# حذف حساب العميل — أرشفة دائمة (Soft Delete)

السياسة المعتمدة: الحذف يتم فورًا حتى مع وجود طلبات مفتوحة أو رصيد/مبالغ محجوزة في المحفظة. الحساب القديم لا يمكن استرجاعه أو إعادة تفعيله. يحتفظ النظام بسجله وطلباته وعناوينه ومعاملاته ورصيده للمراجعة والتسوية من الإدارة. هذه أرشفة للحساب وليست محوًا لكل بياناته الشخصية؛ يجب أن يشرح تطبيق الموبايل هذه السياسة بدقة للمستخدم.

## الهيدرز

كل المسارات التالية تتطلب `Authorization: Bearer <customer-token>` و`X-Client-Id: <tenant-code>` و`X-Store-Code: <store-code>`. يلزم توكن Sanctum فعلي؛ جلسة الويب وحدها لا تكفي. الحذف يشمل حساب العميل في كل متاجر التينانت، وليس المتجر الحالي فقط. لا يجوز حساب موظف أو حساب مختلط مع صلاحيات إدارة استخدام هذه المسارات.

## 1. إعادة التحقق من الهوية

`POST /api/v1/auth/customer/account-deletion/verify`

بكلمة المرور الحالية:

```json
{"method":"password","current_password":"<current-password>"}
```

أو بهوية اجتماعية مرتبطة بالفعل بالحساب: اطلب challenge جديدًا من `POST /auth/customer/social/{provider}/challenge` واستخدم الـ SDK حسب [توثيق الدخول الاجتماعي](MOBILE_SOCIAL_AUTH.md)، ثم:

```json
{"method":"social","provider":"apple","challenge_id":"<uuid>","id_token":"<fresh-sdk-id-token>"}
```

المزوّد `google` أو `apple` أو `facebook`. Facebook يقبل `id_token` الخاص بـ Limited Login أو `access_token` الموثّق من الخادم. لا يتم إنشاء أو ربط حساب جديد أثناء إعادة التحقق، ولا تكفي مطابقة البريد. الـ challenge يُستهلك مرة واحدة.

للحسابات التي تستخدم OTP:

1. `POST /api/v1/auth/customer/account-deletion/otp` بالجسم `{"channel":"email"}` أو `{"channel":"whatsapp"}`.
2. الكود يُرسل إلى البريد/الهاتف المسجل في الحساب الحالي فقط؛ إرسال بريد أو هاتف بديل مرفوض. الاستجابة `201` تحمل `challenge_id` و`masked_destination` و`expires_in: 300` و`resend_after: 60`.
3. أرسل `{"method":"otp","challenge_id":"<uuid>","code":"<6-digits>"}` إلى مسار verify.

أكواد الحذف عشوائية دائمًا، ولا يُقبل `OTP_DEFAULT_CODE` أو challenge تسجيل الدخول. خمس محاولات خاطئة تقفل الكود، وطلب كود جديد مسموح بعد دقيقة، مع حد الإرسال الخاص بالمتجر (افتراضيًا خمسة أكواد في الساعة). يلزم إعداد قناة الإرسال في المتجر؛ فشل الإرسال يرجع `503`.

استجابة verify الناجحة:

```json
{"success":true,"data":{"deletion_token":"<uuid>.<opaque-secret>","expires_in":300}}
```

هذا التوكن مستقل عن توكن الدخول، يستخدم مرة واحدة فقط، ويرتبط بالعميل والتينانت والمتجر وجلسة Sanctum الحالية وبيانات الدخول الحالية. تغيير البريد أو الهاتف أو كلمة المرور يُبطل التأكيد السابق. لا تسجّل التوكن أو أكواد التحقق في logs/analytics، ولا تحفظها في تخزين دائم بالموبايل.

## 2. تأكيد الحذف

اعرض تأكيدًا واضحًا بأن الحساب القديم لن يعود وأن التسجيل مجددًا يبدأ بحساب جديد دون طلبات أو رصيد قديم، ثم نفّذ:

`DELETE /api/v1/auth/customer/account`

```json
{"confirmation":"DELETE","deletion_token":"<token-from-verify>"}
```

`POST /api/v1/auth/customer/delete-request` موجود للتوافق، لكنه يتطلب **نفس** إعادة التحقق والهيدرز والتأكيد. الطلب القديم بدون دليل هوية يرجع `422` ولا يحذف الحساب.

النجاح `200`: امسح بيانات الجلسة المحلية وانتقل لشاشة الدخول. الخادم يُلغي كل توكنات Sanctum وتوكنات الأجهزة وروابط الدخول الاجتماعي ويعطّل تحديات OTP وروابط إعادة تعيين كلمة المرور القديمة. تُفرَّغ أعمدة الدخول `email` و`phone` بعد نسخها إلى `deleted_email` و`deleted_phone`، ويُسجل `deleted_at` وتتعطل كلمة المرور. الطلبات والأرصدة لا تُمسح ولا تُنقل. يُسجل حدث تدقيق `customer.account_deleted` بمعرّف العميل والمتجر والسياسة دون حفظ كلمة المرور أو كود التحقق أو توكن التأكيد.

التسجيل بالبريد/الهاتف نفسيهما، أو تسجيل اجتماعي متحقق منه بعد الحذف، ينشئ **User ID جديدًا**؛ لا يصل لأي طلب أو عنوان أو محفظة تخص الحساب المؤرشف. في حالة وجود حساب حالي بنفس بريد الهوية الاجتماعية تظل قاعدة الربط الصريح مطبقة.

## الإدارة

صفحة «العملاء» تحتوي فلتر الحسابات الحالية/المحذوفة/الكل. API:

- `GET /api/v1/admin/customers`: يستبعد المحذوف افتراضيًا.
- `?deleted=only` للمحذوف فقط؛ `?deleted=with` للكل. صيغة `filters[deleted]` متاحة أيضًا.
- البحث بالبريد أو الهاتف يجد بيانات الأرشيف عند اختيار فلتر المحذوف/الكل.
- `GET /api/v1/admin/customers/{id}` يعرض السجل المؤرشف و`is_deleted` و`deleted_at` والبريد/الهاتف الأصليين والإحصائيات، ضمن نطاق المتجر وصلاحية `customers.view`.
- السجل المؤرشف يرجع `editable_fields: []`؛ تعديل الملف أو الحالة أو إضافة عنوان مرفوض، ولا يوجد endpoint للاسترجاع. استرجاع User عبر Eloquent محظور كذلك.
- تظل التسويات المالية للطلبات القديمة متاحة للموظفين المخولين؛ علاقات الطلبات والمحفظة والسجل المالي تستمر في الإشارة للعميل القديم حتى بعد حذفه.

حد الحذف وإعادة التحقق: خمس طلبات في الدقيقة للحساب وعشرون للـ IP داخل التينانت، بالإضافة للحد العام. `401` لجلسة غير صالحة، `403` لحساب غير مسموح، `422` لدليل/تأكيد غير صالح أو منتهي، و`429` لتجاوز الحد.

## النشر والتحقق

طبّق migration `2026_10_17_190000_add_irreversible_customer_soft_deletion.php` على قواعد العملاء المطلوبة قبل تشغيل الإصدار الجديد. يلزم أيضًا migration الدخول الاجتماعي `2026_10_17_180000_create_customer_social_auth_tables.php`. اختَر قاعدة التينانت والمسار صراحةً وفق إجراءات النشر؛ لا تستخدم migrate عامًا أو fresh أو seed يمسح البيانات. الـ migration تقبل إعادة المحاولة بعد فشل DDL جزئي دون حذف بيانات؛ التراجع لا يزيل علامات الحذف أو بيانات الأرشيف حتى لا يعيد تفعيل حسابات قديمة. تُحوَّل علامات الحذف القديمة المطابقة تمامًا (`Deleted customer` مع `deleted-{id}@invalid.local` وحساب معطّل بلا هاتف) إلى أرشيف دائم وتُلغى جلساتها وروابطها الاجتماعية. البريد الأصلي لهذه السجلات كان قد فُقد بالحذف القديم ولا يمكن إعادة بنائه؛ الحسابات المعطلة العادية لا تتأثر.

اختبارات الانحدار: `CustomerAccountDeletionTest`, `CustomerAuthTest`, `CustomerSocialAuthTest`, `AdminDeletedCustomerTest`, ومجموعات العملاء والمحفظة و`AdminWalletPaymentRefundTest`، واختبارات صفحات العملاء في admin. تغطي الحسابات الجديدة المنفصلة، إبطال الجلسات والاسترجاع، التحقق الاجتماعي/OTP وكلمة المرور، عزل الجلسة والمتجر والتينانت، عرض الأرشيف، واستمرار رد المدفوعات لحساب محذوف.

## سجل التنفيذ — 17 أكتوبر 2026

- نُفذت الأرشفة الدائمة وإعادة التحقق والتأكيد وسجل التدقيق وإلغاء الجلسات، مع فصل أي تسجيل جديد عن السجل القديم.
- نجحت مجموعة مركزة من 194 اختبار Backend (1132 assertion)، ومجموعة 88 اختبارًا بعد إضافات حد إرسال OTP والتدقيق (657 assertion). شُغِّل اختبار منفصل أيضًا للتأكد من رفض قراءة طلب قديم بتوكن الحساب الجديد.
- نجحت إعادة تشغيل آخر اختبارات الحذف والأرشيف والتوافق بعد كل التعديلات: **20 اختبارًا و125 assertion**.
- نجحت اختبارات الواجهة ذات الصلة: 15 اختبارًا، وفحص ESLint للصفحات المعدلة، وبناء Vite.
- طُبقت migrations المحددة على `3lcost` المحلي فقط. تم إصلاح حد طول أسماء قيود MySQL والتحقق من استئناف migration بعد فشل DDL جزئي دون حذف بيانات.
- نجح سيناريو MySQL للحذف وإلغاء التوكنات وبقاء الرصيد والمبلغ المحجوز والتسجيل بنفس البريد بحساب مختلف؛ استُخدمت transaction مؤقتة وتم التراجع عنها بالكامل.
- نجحت تجربة المتصفح على متجر الكويت المحلي: اختيار فلتر المحذوف، فتح التفاصيل، ظهور تاريخ الحذف والبريد المؤرشف، تعطيل الحقول واختفاء إعادة التفعيل والحفظ. سجل التجربة منفصل وتم تنظيفه بعد التحقق؛ لم يُحذف أي حساب عميل حقيقي.
- اكتملت مجموعة Backend الكاملة: **1755 اختبارًا إجمالًا، 1753 ناجحًا، اختباران متخطّيان خاصان بـ MySQL، و9014 assertion**، خلال نحو 19 دقيقة و33 ثانية. اختبارات التوافق الجديدة الخاصة بإعادة migration والعلامة القديمة شُغلت منفصلة بعد آخر تعديل أيضًا.
