# تسجيل دخول العملاء للموبايل: Apple وGoogle وFacebook

هذه إضافة إلى Laravel API فقط. الموبايل ينفذ شاشة موافقة المزوّد باستخدام SDK، ثم يرسل توكن المزوّد إلى الخادم ليستبدله بتوكن Sanctum المعتاد. لا توجد redirects أو جلسات متصفح، ولا يعتمد الخادم على البريد أو معرّف المستخدم الذي يرسله الموبايل.

## التفعيل على الخادم

1. ثبّت الاعتمادات من `composer.lock`؛ الإضافة تستخدم `firebase/php-jwt` للتحقق من التوقيع.
2. طبّق migration `2026_10_17_180000_create_customer_social_auth_tables.php` على قاعدة التينانت المقصود عبر مسار ترحيل العملاء المعتمد عند النشر. لا يلزم تغيير جدول المستخدمين أو تشغيل seed. الاختبارات تنفذها داخل SQLite مؤقتة فقط.
3. أضف إعدادات كل عميل تحت **كوده المطابق لـ X-Client-Id** في متغير الخادم `SOCIAL_AUTH_TENANTS_JSON`، ثم حدّث config cache حسب إجراءات النشر. لا تضع Facebook app secret داخل تطبيق الموبايل أو Git أو collection منشورة.

مثال بقيم بديلة؛ كل مزوّد يظل متوقفًا حتى تفعيل إعداداته صراحةً:

```dotenv
SOCIAL_AUTH_TENANTS_JSON='{"client-code":{"google":{"enabled":true,"client_ids":["SERVER_WEB_CLIENT_ID.apps.googleusercontent.com"]},"apple":{"enabled":true,"client_ids":["com.example.iosapp","com.example.apple.service"]},"facebook":{"enabled":true,"app_id":"123456789","app_secret":"SERVER_ONLY_APP_SECRET"}}}'
SOCIAL_AUTH_FACEBOOK_GRAPH_VERSION=v25.0
```

Google: استخدم audience الخاص بتوكن تسجيل الدخول المطلوب للخادم، عادةً **Server Web Client ID**، وأضف audiences المسموح بها فقط في `client_ids`. Apple: ضع Bundle ID أو Service ID المطابق للتدفق. Facebook: تطبيق واحد لكل تينانت؛ `app_secret` لازم لتوكن الدخول العادي، بينما Limited Login يعمل بـ `app_id` وحده. لا يوجد fallback لإعدادات عميل آخر. بيانات التطبيقات الأصلية وشهاداتها وإعداد SDK للموبايل تُجهّز في حساب المزوّد.

## الهيدرز والقدرات

المسارات بالنسبة إلى `http://127.0.0.1:8010/api/v1` محليًا، وHTTPS عند النشر:

```http
Accept: application/json
Content-Type: application/json
X-Client-Id: client-code
X-Store-Code: kw
X-Client: ios
```

`X-Client` يقبل `ios` أو `android` لتسجيل مصدر العميل. مسارات هذه الإضافة تحتاج `X-Store-Code`؛ يمكن إرسال `X-Store-ID` المطابق معه. استخدم `GET /auth/capabilities` لعرض أزرار المزوّدين المفعّلين من `data.social`:

```json
{
  "google": {"enabled": true, "token_types": ["id_token"]},
  "apple": {"enabled": true, "token_types": ["id_token"]},
  "facebook": {"enabled": true, "token_types": ["id_token", "access_token"]}
}
```

القسم مضاف إلى capabilities الحالية، ولا يكشف أسرار التطبيقات.

## تسلسل تسجيل الدخول

استبدل `{provider}` بأحد `google` أو `apple` أو `facebook`.

1. قبل بدء SDK، أرسل `POST /auth/customer/social/{provider}/challenge` بجسم فارغ. الرد `201`:

   ```json
   {
     "success": true,
     "message": "Sign-in challenge created.",
     "data": {
       "challenge_id": "UUID",
       "nonce": "NONCE_TO_SEND_TO_PROVIDER",
       "raw_nonce": "RAW_NONCE_FOR_SDKS_THAT_HASH_IT",
       "expires_in": 300
     }
   }
   ```

2. شغّل SDK بالمزوّد المختار. **قيمة nonce في ID token الموقّع يجب أن تساوي `data.nonce` حرفيًا**. مرّر `nonce` كما هي إلى SDK الذي لا يجري hashing، أو `raw_nonce` فقط إذا كان SDK يجري SHA-256 تلقائيًا؛ `nonce = SHA256(raw_nonce)`. اطلب هوية جديدة لهذه المحاولة بدل silent token قديم. Apple وGoogle وFacebook Limited Login تتطلب nonce. Facebook العادي يستخدم access token ولا يحمل nonce موقّعًا، لكنه يحتاج challenge أيضًا.
3. أرسل التوكن إلى `POST /auth/customer/social/{provider}/login`:

   ```json
   {"challenge_id": "UUID", "id_token": "PROVIDER_SIGNED_ID_TOKEN"}
   ```

   مع Facebook العادي فقط، أرسل `access_token` بدل `id_token`. لا ترسل الاثنين معًا. توكن Facebook Limited Login من نوع JWT يُرسل في `id_token`، ولا يُرسل إلى Graph API كـ access token. توكنات Firebase Auth ليست بديلًا لتوكن المزوّد المباشر في هذا العقد.

   يمكن إرسال `name` اختياريًا مع Apple عند الموافقة الأولى؛ يُستخدم اسمًا للعرض فقط. لا ترسل `email` أو `provider_user_id` أو `user_id` أو nonce داخل جسم طلب الدخول؛ الهوية تأتي من التوكن المتحقق منه.

4. الرد `200`:

   ```json
   {
     "success": true,
     "message": "Login successful.",
     "data": {
       "user": {"id": 123, "name": "Customer", "email": null, "phone": null, "roles": ["Customer"]},
       "token": "SANCTUM_BEARER_TOKEN",
       "is_new_customer": true
     }
   }
   ```

   `user` يتبع `CustomerProfileResource` الحالي، وفيه بقية حقول الملف الشخصي أيضًا. احفظ `data.token` في التخزين الآمن للموبايل وأرسله `Authorization: Bearer ...` للمسارات المحمية. انتهاء الصلاحية يتبع `CUSTOMER_API_TOKEN_TTL_MINUTES`، والافتراضي 43200 دقيقة. لا تحفظ أو تطبع توكن المزوّد في logs؛ الخادم لا يخزنه.

المحاولة مرتبطة بالتينانت والمتجر والمزوّد، وتُستهلك مرة واحدة عند بدء التحقق. بعد الفشل أو timeout أو انتهاء المهلة، ابدأ challenge وتسجيل دخول جديدين. تسجيل الدخول التالي بنفس هوية المزوّد يعيد العميل نفسه داخل التينانت، دون إعادة كتابة بيانات ملفه الشخصي. الحساب مشترك بين متاجر التينانت نفسه، ويظل منفصلًا عن حسابات التينانت الآخرين.

## ربط عميل موجود

لا ندمج الحسابات تلقائيًا بمجرد تطابق البريد. إذا عاد `409` بالكود `social_account_link_required`:

1. سجّل دخول الحساب الموجود بكلمة المرور أو OTP واحصل على توكن Sanctum.
2. ابدأ challenge جديدًا وSDK جديدًا للمزوّد.
3. أرسل جسم الدخول نفسه إلى `POST /auth/customer/social/{provider}/link` مع توكن Sanctum في Authorization.

الرد `200` يحتوي `data.linked = true` و`data.provider` وبيانات العميل، ولا يصدر توكنًا جديدًا. بعد الربط يمكن استخدام `/login` مباشرةً. لا يمكن ربط نفس الهوية بعميل ثانٍ أو استبدال هوية مربوطة للمزوّد نفسه بهذه العملية. لا توجد عملية فك ربط ضمن هذه الإضافة.

الحسابات الجديدة تأخذ دور Customer فقط. الحساب المعطّل أو المحذوف أو صاحب صلاحية إدارة لا يحصل على جلسة عميل عبر هذه الإضافة. حذف الحساب هو Soft Delete دائم بعد إعادة التحقق: تُلغى الجلسات وروابط المزوّد، ويظل الحساب القديم مؤرشفًا للإدارة ولا يُسترجع. تسجيل الدخول الاجتماعي لاحقًا بهوية متحقق منها ينشئ حسابًا جديدًا منفصلًا، أو يطلب ربطه بحساب حالي عند تطابق البريد. راجع [عقد حذف الحساب](CUSTOMER_ACCOUNT_DELETION.md) لتفاصيل إعادة التحقق والتأكيد.

البريد قد يكون `null`: Facebook لا يقدّم إثباتًا كافيًا لملكية البريد هنا. Google يُستخدم بريده فقط إذا كان موثّقًا ومستضافًا على Gmail أو Workspace، وApple إذا حمل التوكن `email_verified` الصحيح. لا نخترع بريدًا، ولا نقبل بريدًا يدويًا لتحديد الحساب. إذا كان للعميل حساب هاتف/بريد موجود، يمكنه تسجيل دخوله المعتاد ثم ربط المزوّد به.

## الأخطاء والتحقق

| HTTP | code | التصرف في الموبايل |
| --- | --- | --- |
| 401 | `invalid_social_token` | أعد تدفق المزوّد بتوكن وnonce جديدين |
| 422 | `invalid_social_challenge` | ابدأ محاولة جديدة؛ القديمة مفقودة أو مستخدمة أو منتهية أو تخص سياقًا آخر |
| 422 | أخطاء validation في `errors` | صحّح الحقول والهيدرز |
| 409 | `social_account_link_required` | سجّل دخول الحساب الموجود ثم اربط المزوّد |
| 409 | `social_identity_conflict` | الهوية مربوطة بالفعل؛ لا تنشئ حسابًا بديلًا تلقائيًا |
| 403 | `social_account_unavailable` | الحساب لا يسمح بدخول العميل بهذه الطريقة |
| 503 | `social_provider_disabled` | أخفِ الزر حتى تكتمل إعدادات الخادم |
| 503 | `social_provider_unavailable` | أعد المحاولة لاحقًا بتدفق جديد |
| 429 | — | احترم `Retry-After`؛ حدود auth تشمل challenge والدخول والربط |

اختبارات API في `tests/Feature/Api/V1/Customer/CustomerSocialAuthTest.php` تستخدم توقيعات RSA حقيقية بمفاتيح اختبار وHTTP وهمي للمزوّدين، وتشمل الجمهور والمصدر والتوقيع وnonce والصلاحية وإعادة الاستخدام والربط وعزل التينانت وحالة الحساب. الاختبار مع تطبيقات المزوّدين الحقيقية يحتاج إعدادات التطبيقات وتوكنات SDK؛ لا توجد بيانات اعتماد حقيقية داخل المستودع.

## مراجع عقد المزوّدين

- [Google: التحقق من ID token على الخادم](https://developers.google.com/identity/sign-in/android/backend-auth).
- [Apple: التحقق من المستخدم](https://developer.apple.com/documentation/signinwithapple/verifying-a-user)، و[بدء المصادقة باستخدام nonce](https://developer.apple.com/documentation/signinwithapple/authenticating-users-with-sign-in-with-apple).
- [Meta: التحقق من access token](https://developers.facebook.com/docs/facebook-login/guides/access-tokens/debugging-and-error-handling/)، و[Limited Login token](https://developers.facebook.com/docs/facebook-login/limited-login/token/)، و[OIDC discovery](https://www.facebook.com/.well-known/openid-configuration/).
