# راهنمای تنظیم Social Login

این راهنما نحوه پیکربندی ثبت‌نام و ورود با شبکه‌های اجتماعی را توضیح می‌دهد.

## ویژگی‌های پیاده‌سازی شده

✅ ثبت‌نام و ورود با Google, GitHub, Facebook, Microsoft, Apple, LinkedIn, Twitter
✅ خواندن اطلاعات کاربر از شبکه اجتماعی
✅ تشخیص اطلاعات گمشده (ایمیل، نام کاربری، شماره تلفن)
✅ نمایش فرم تکمیل پروفایل برای جمع‌آوری اطلاعات گمشده
✅ اتصال حساب‌های اجتماعی به حساب موجود
✅ ذخیره اطلاعات Social Identity در دیتابیس

## پیش‌نیازها

پکیج Laravel Socialite قبلاً در پروژه شما نصب شده است:

```bash
composer require laravel/socialite
```

برای پروایدرهای اضافی:

```bash
composer require socialiteproviders/apple
composer require socialiteproviders/linkedin
composer require socialiteproviders/microsoft
composer require socialiteproviders/twitter
```

## تنظیمات

### 1. افزودن کانفیگ پروایدرها به `.env`

```env
# Google OAuth
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=<GOOGLE_CLIENT_SECRET>
GOOGLE_REDIRECT_URI=${APP_URL}/auth/social/google/callback

# GitHub OAuth
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=<GITHUB_CLIENT_SECRET>
GITHUB_REDIRECT_URI=${APP_URL}/auth/social/github/callback

# Facebook OAuth
FACEBOOK_CLIENT_ID=your-facebook-app-id
FACEBOOK_CLIENT_SECRET=<FACEBOOK_CLIENT_SECRET>
FACEBOOK_REDIRECT_URI=${APP_URL}/auth/social/facebook/callback

# Microsoft OAuth
MICROSOFT_CLIENT_ID=your-microsoft-client-id
MICROSOFT_CLIENT_SECRET=<MICROSOFT_CLIENT_SECRET>
MICROSOFT_REDIRECT_URI=${APP_URL}/auth/social/microsoft/callback

# Apple OAuth (اختیاری)
APPLE_CLIENT_ID=your-apple-service-id
APPLE_CLIENT_SECRET=<APPLE_CLIENT_SECRET>
APPLE_REDIRECT_URI=${APP_URL}/auth/social/apple/callback

# LinkedIn OAuth (اختیاری)
LINKEDIN_CLIENT_ID=your-linkedin-client-id
LINKEDIN_CLIENT_SECRET=<LINKEDIN_CLIENT_SECRET>
LINKEDIN_REDIRECT_URI=${APP_URL}/auth/social/linkedin/callback

# Twitter OAuth (اختیاری)
TWITTER_CLIENT_ID=your-twitter-client-id
TWITTER_CLIENT_SECRET=<TWITTER_CLIENT_SECRET>
TWITTER_REDIRECT_URI=${APP_URL}/auth/social/twitter/callback

# Fallback domain for users without email
SOCIAL_FALLBACK_DOMAIN=social.local
```

### 2. اضافه کردن به `config/services.php`

فایل `config/services.php` را باز کنید و تنظیمات زیر را اضافه کنید:

```php
return [
    // ... سایر سرویس‌ها

    'google' => [
        'client_id' => env('GOOGLE_CLIENT_ID'),
        'client_secret' => env('GOOGLE_CLIENT_SECRET'),
        'redirect' => env('GOOGLE_REDIRECT_URI'),
    ],

    'github' => [
        'client_id' => env('GITHUB_CLIENT_ID'),
        'client_secret' => env('GITHUB_CLIENT_SECRET'),
        'redirect' => env('GITHUB_REDIRECT_URI'),
    ],

    'facebook' => [
        'client_id' => env('FACEBOOK_CLIENT_ID'),
        'client_secret' => env('FACEBOOK_CLIENT_SECRET'),
        'redirect' => env('FACEBOOK_REDIRECT_URI'),
    ],

    'microsoft' => [
        'client_id' => env('MICROSOFT_CLIENT_ID'),
        'client_secret' => env('MICROSOFT_CLIENT_SECRET'),
        'redirect' => env('MICROSOFT_REDIRECT_URI'),
    ],

    'apple' => [
        'client_id' => env('APPLE_CLIENT_ID'),
        'client_secret' => env('APPLE_CLIENT_SECRET'),
        'redirect' => env('APPLE_REDIRECT_URI'),
    ],

    'linkedin' => [
        'client_id' => env('LINKEDIN_CLIENT_ID'),
        'client_secret' => env('LINKEDIN_CLIENT_SECRET'),
        'redirect' => env('LINKEDIN_REDIRECT_URI'),
    ],

    'twitter' => [
        'client_id' => env('TWITTER_CLIENT_ID'),
        'client_secret' => env('TWITTER_CLIENT_SECRET'),
        'redirect' => env('TWITTER_REDIRECT_URI'),
    ],

    'social_fallback_domain' => env('SOCIAL_FALLBACK_DOMAIN', 'social.local'),
];
```

### 3. افزودن Event Listeners (برای پروایدرهای غیرمعمول)

اگر از Apple, LinkedIn, Microsoft یا Twitter استفاده می‌کنید، به `app/Providers/AppServiceProvider.php` اضافه کنید:

```php
use SocialiteProviders\Apple\AppleExtendSocialite;
use SocialiteProviders\LinkedIn\LinkedInExtendSocialite;
use SocialiteProviders\Microsoft\MicrosoftExtendSocialite;
use SocialiteProviders\Twitter\TwitterExtendSocialite;
use SocialiteProviders\Manager\SocialiteWasCalled;

public function boot(): void
{
    Event::listen(function (SocialiteWasCalled $event) {
        $event->extendSocialite('apple', AppleExtendSocialite::class);
        $event->extendSocialite('linkedin', LinkedInExtendSocialite::class);
        $event->extendSocialite('microsoft', MicrosoftExtendSocialite::class);
        $event->extendSocialite('twitter', TwitterExtendSocialite::class);
    });
}
```

## دریافت Client ID و Secret

### Google OAuth

1. به [Google Cloud Console](https://console.cloud.google.com/) بروید
2. یک پروژه جدید بسازید یا پروژه موجود را انتخاب کنید
3. به "APIs & Services" > "Credentials" بروید
4. "Create Credentials" > "OAuth client ID" را انتخاب کنید
5. نوع برنامه را "Web application" انتخاب کنید
6. Redirect URI را اضافه کنید: `https://yourdomain.com/auth/social/google/callback`

### GitHub OAuth

1. به [GitHub Developer Settings](https://github.com/settings/developers) بروید
2. "New OAuth App" را کلیک کنید
3. اطلاعات را پر کنید
4. Callback URL: `https://yourdomain.com/auth/social/github/callback`

### Facebook OAuth

1. به [Facebook Developers](https://developers.facebook.com/) بروید
2. یک اپلیکیشن جدید بسازید
3. به "Settings" > "Basic" بروید
4. App ID و App Secret را کپی کنید
5. Valid OAuth Redirect URIs: `https://yourdomain.com/auth/social/facebook/callback`

### Microsoft OAuth

1. به [Azure Portal](https://portal.azure.com/) بروید
2. "Azure Active Directory" > "App registrations" > "New registration"
3. نام و Redirect URI را وارد کنید
4. پس از ساخت، Application (client) ID را کپی کنید
5. "Certificates & secrets" > "New client secret" برای ساخت Secret

## نحوه کارکرد

### فرآیند Login/Register:

1. **کاربر روی دکمه Social کلیک می‌کند**
   - مثلاً "Continue with Google"
   - به `/auth/social/google/redirect` ریدایرکت می‌شود

2. **هدایت به Provider**
   - کاربر به سایت Google/Facebook/... هدایت می‌شود
   - اجازه دسترسی به اطلاعات را می‌دهد

3. **برگشت به Callback**
   - Provider به `/auth/social/google/callback` برمی‌گردد
   - سیستم اطلاعات کاربر را دریافت می‌کند

4. **بررسی اطلاعات**
   - اگر کاربر قبلاً ثبت‌نام کرده: Login
   - اگر ایمیل موجود است: اتصال Social Account
   - اگر اطلاعات کامل است: ثبت‌نام خودکار
   - **اگر اطلاعات ناقص است: هدایت به صفحه تکمیل پروفایل**

5. **تکمیل پروفایل** (در صورت نیاز)
   - کاربر به `/auth/social/complete-profile` هدایت می‌شود
   - فرم با فیلدهای گمشده نمایش داده می‌شود
   - پس از ارسال، ثبت‌نام کامل می‌شود

## فیلدهای مورد نیاز

سیستم به طور خودکار این فیلدها را بررسی می‌کند:

- ✅ **Email**: اگر provider ایمیل ندهد، از کاربر می‌پرسد
- ⚠️ **Username**: به صورت خودکار از name یا email تولید می‌شود
- ⚠️ **Phone**: اختیاری (می‌توانید در Controller آن را الزامی کنید)

### سفارشی‌سازی فیلدهای الزامی

در فایل `app/Http/Controllers/Auth/SocialAuthController.php`، متد `getMissingFields`:

```php
private function getMissingFields(SocialiteUser $socialiteUser, string $provider): array
{
    $missing = [];

    // بررسی ایمیل
    $email = $this->resolveSocialEmail($provider, $socialiteUser);
    if (!$email || $this->isSyntheticEmail($email)) {
        $missing[] = 'email';
    }

    // اگر می‌خواهید شماره تلفن الزامی باشد:
    // $missing[] = 'phone';

    // اگر می‌خواهید username الزامی باشد:
    // if (!$socialiteUser->getNickname() && !$socialiteUser->getName()) {
    //     $missing[] = 'username';
    // }

    return $missing;
}
```

## اطلاعات ذخیره شده

اطلاعات Social در جدول `oauth_identities` ذخیره می‌شود:

```sql
CREATE TABLE oauth_identities (
    id BIGINT PRIMARY KEY,
    user_id BIGINT,
    provider VARCHAR(50),          -- 'google', 'github', etc.
    provider_user_id VARCHAR(255), -- ID کاربر در provider
    provider_email VARCHAR(255),   -- ایمیل از provider
    metadata JSON,                 -- کل اطلاعات خام از provider
    created_at TIMESTAMP,
    updated_at TIMESTAMP
);
```

## Customization

### تغییر ظاهر دکمه‌های Social

در `resources/views/auth/register.blade.php` و `login.blade.php`:

```html
<div class="social-login">
    <a href="{{ route('social.redirect', ['provider' => 'google', 'intent' => 'register']) }}" 
       class="btn btn-social">
        <i class="bi bi-google"></i> Google
    </a>
    <!-- سایر دکمه‌ها -->
</div>
```

### افزودن Provider جدید

1. نصب پکیج مربوطه
2. اضافه به `SUPPORTED_PROVIDERS` در `SocialAuthController`
3. اضافه کردن کانفیگ به `config/services.php`
4. اضافه دکمه در view

## مشکلات رایج

### خطای "Invalid redirect URI"

- مطمئن شوید redirect URI در تنظیمات Provider با `.env` شما مطابقت دارد
- دقت کنید که `https://` یا `http://` درست باشد

### کاربر ایمیل ندارد

- سیستم به صورت خودکار ایمیل synthetic تولید می‌کند
- یا کاربر را به صفحه complete-profile می‌فرستد

### خطای "Session expired"

- Session باید فعال باشد
- مطمئن شوید که `SESSION_DRIVER` در `.env` به درستی تنظیم شده

## تست

برای تست در محیط لوکال:

```bash
# استفاده از ngrok برای دریافت HTTPS URL
ngrok http 8000

# سپس URL را در تنظیمات Provider و .env قرار دهید
```

## امنیت

✅ تمام رمزهای عبور کاربران Social به صورت رندوم و هش شده ذخیره می‌شوند
✅ اطلاعات خام Provider در فیلد `metadata` ذخیره می‌شود
✅ ایمیل‌های verified به صورت خودکار تأیید می‌شوند
✅ Session برای انتقال اطلاعات بین صفحات استفاده می‌شود

## پشتیبانی

اگر مشکلی دارید:

1. لاگ‌های Laravel را چک کنید: `storage/logs/laravel.log`
2. Browser console را برای خطاهای JavaScript بررسی کنید
3. مطمئن شوید تمام credentials درست هستند

---

**توسعه‌دهنده**: این سیستم با استفاده از Laravel Socialite و پترن Repository پیاده‌سازی شده است.