# Session Handoff — base → new project

> **كيف تستخدمه:** افتح تاب المشروع الجديد، وأول رسالة قول: «اقرأ `docs/SESSION-HANDOFF.md` كاملاً قبل ما تبدأ».
> (أو الصق محتواه كأول رسالة.) ده الـ compact للمحادثة اللي بنينا فيها النظام — يدّي التاب الجديد كل السياق.
> احذف الملف ده بعد ما المشروع الجديد يبدأ فعلياً (مش جزء من الـ base الدائم).

---

## 1) إيه هو الـ base دلوقتي
- Laravel **12.62** (PHP 8.3) · أدمن (Blade, `auth:admin`) + API مُصدَّر (`/api/v1`, Sanctum) · عربي+إنجليزي (افتراضي `ar`).
- باكدجات: Sanctum · Astrotomic Translatable · Spatie Media · Maatwebsite Excel · PHPWord.
- **اتقرر Laravel 12 مش 13** لأن باكدجات أساسية (translatable/medialibrary/excel/sanctum) لسه مالهاش نسخة مستقرة تدعم 13.

## 2) نظام البناء بالـ AI (الخطة اللي نبدأ بيها كل مشروع)
- **نقطة البداية:** `docs/project-init/START.md` — تملا فيه رابط Figma + مسار ملف التحليل PDF، وتقول «نفّذ START».
- **الـ pipeline:** `build-schema → 🛑 GATE → build-database → build-api/dashboard → build-tests → build-postman → ✅ DoD(verify §B) → commit`. (لا سايكل تصليح base في الأول.)
- **المخ (الإجراءات):** `docs/build/*` (README + build-schema/database/dashboard-crud/api/postman + **build-tests** + **verify**). الطبقتان `.cursor` و`.claude` رفيعتان ويأشّران عليه (صفر تكرار).
- **بوابتان توقّف:** (1) مراجعة الـ schema قبل أي كود، (2) موافقة الـ design-pattern وقت تنفيذ كل sprint. وبوابة آلية ثالثة = **Definition of Done** (`verify.md` §B) قبل أي commit.
- **القواعد:** اقرأ كل الفيجما شاشة-شاشة · reuse/alter/new + تأكّد من الـ DB الفعلية · مثّل كل الملفات · think-first · Laravel-first (events/jobs/notifications/policies/observers) · بدون انحراف عن ستايل base · seed عربي حقيقي.
- **قواعد قراءة الشاشات:** شاشات بنفس الاسم **تتقارن مش تتدمج**؛ الشاشة الواحدة = أكشنز كتير = endpoints متعددة + نموذج حالات (Enum + انتقالات).
- **أداة:** `php artisan schema:check` تكشف drift بين `database/schema/*.json` والـ DB.

## 3) ⚠️ باگات معروفة في الـ base (للعلم — **لا تصلّحها من جوه مشروعك**)
مراجعة شاملة (4 وكلاء) لقت الباگات دي في الـ base. **مهم:** ما تدخلش في سايكل تصليح للـ base وأنت بتبدأ مشروعك —
ابدأ مشروعك عادي. لو عايز تصلّحها، اعملها **مرة واحدة في الـ base repo** وأعد النسخ. القائمة (أولوية أعلى أولاً):

**Critical:**
- **AuthService binding مكسور** → `AppServiceProvider` يربط `AuthServiceInterface` بـ `\App\Services\AuthService` (مش موجود)؛ الحقيقي `Services/Auth/AuthService` مش بيـ implement الـ interface. النتيجة: `/api/v1/auth/login-code` و`/request-code` **endpoints ميتة**.
- **Slider seeder/factory بتقع على DB نضيفة** → `BaseFilesTrait::handleFileAssignment` بيتجاهل قيمة string (مايكتبش `attributes`)، و`sliders.image` NOT NULL بدون default. (أضف فرع `is_string` + خلّي العمود nullable.)

**High:**
- **OTP plaintext في اللوج** (`LogCodeSender`). · **guard غلط** في `ProfileController::updatePassword` (`auth()` بدل `auth('admin')`).
- **`lang/ar/response.php` مقابل `lang/en/responses.php`** → الترجمة بترجّع المفتاح حرفياً (يكسر `ar` الافتراضي). وحّد على `responses.php`.
- **PSR-4** في `app/Http/Requests/Api/Auth/CodeLoginRequest.php` + `RequestCodeRequest.php` (namespace غلط) → يكسر مع `dump-autoload -o`.
- **رسائل إنجليزي hardcoded + تسريب `$e->getMessage()`** في geo controllers. · **`notifications.php` على `auth`** بدل `auth:sanctum`.
- **`respondWithPaginated()` مش موجودة** رغم إن CLAUDE.md بيفرضها.
- **drift:** `cms.json` فاضي (11 جدول CMS) + `otps` أعمدة في JSON مش في DB. · **`*~` (33 ملف) + `.DS_Store`** متسجّلين. · `diagram.json` orphan.

**بيئي:** داتابيز `base` متلوّثة بجداول عشرات المشاريع التانية (816 جدول) — استخدم DB نضيفة للمشروع الجديد.

> التقرير الكامل (Critical→Low) موجود في history الجلسة السابقة؛ ابدأ بالـ Critical+High.

## 4) كيف تبدأ المشروع الجديد عملياً
1. clone الـ base لفولدر جديد + DB **فاضية** + `.env` (APP_NAME/URL/DB).
2. املا `docs/project-init/START.md` (Figma + analysis PDF) وقول «نفّذ START» — **مباشرة، بدون تصليح للـ base**.
3. النظام يمشي لوحده ويقف عند بوابة الـ schema للمراجعة، وبوابة كل sprint.
4. (اختياري ومنفصل) لو حبيت تصلّح باگات §3، اعملها في الـ base repo نفسه — مش من جوه مشروعك.

## 5) ملفات مهمة
```
README.md                      نظرة عامة + المعمارية + الهيكلة
docs/project-init/START.md     نقطة إقلاع المشروع
docs/build/README.md           تنسيق الـ pipeline + البوابات + القواعد الذهبية
docs/build/verify.md           §A base readiness (one-time) + §B Definition of Done
CLAUDE.md                      قواعد المشروع للمساعد
```