# برومبت بناء منصّة "مندوب" — لاستخدامه مع Claude Code

> **طريقة الاستخدام:** انسخ هذا الملف كاملاً إلى Claude Code، وأرفق معه ملفات التصاميم (mandoub-user-app.html, mandoub-driver-app.html, mandoub-company-dashboard.html, mandoub-company-web.html, mandoub-super-admin.html). نفّذ **مرحلة مرحلة** — لا تطلب بناء كل شيء دفعة واحدة.

---

## 1) نظرة عامة على المشروع

اسم المشروع: **مندوب (Mandoub)** — منصّة SaaS لتوصيل الطرود بين المحافظات في العراق.

الفكرة الأساسية: المستخدم ينشئ طلب توصيل (من محافظة إلى محافظة)، وشركات التوصيل ترد بعروض (سعر + مدة) أو يبحث المستخدم مباشرةً عن الشركات التي تخدم مساره ويختار. بعد القبول، الشركة تعيّن سائقاً، والسائق يستلم الطرد ويحدّث حالته عبر مراحل (استُلم ← الفرع ← في الطريق ← الوجهة ← سُلّم) مع تتبّع مباشر على الخريطة، وتأكيد تسليم برمز من المستلِم.

المنصّة SaaS متعدّدة المستأجرين (multi-tenant): كل شركة "مستأجر" مستقل ببياناته، ومالك المنصّة (سوبر أدمن) يشرف على الكل.

اللغة الأساسية للواجهات: **العربية (RTL)**. العملة: **الدينار العراقي (IQD)**.

---

## 2) الحزمة التقنية (Tech Stack) — التزم بها بدقّة

- **الباك-إند:** Laravel 11 (PHP 8.3)
- **قاعدة البيانات:** MySQL 8
- **الكاش والطوابير والبثّ اللحظي:** Redis
- **لوحات الويب (لوحة الشركة + السوبر أدمن):** Vue.js 3 + Inertia.js + Vite (داخل نفس مشروع Laravel)
- **تطبيقات الموبايل (المستخدم + السائق):** Flutter (Dart) — منفصلة، تتصل بالـ API
- **المصادقة:** Laravel Sanctum (توكن للموبايل + جلسات للويب)
- **الخرائط والتتبّع:** Google Maps SDK (Flutter) + Directions API. **مهم:** قلّل استهلاك الـ API — ابثّ موقع السائق كل ٥–١٠ ثوانٍ أو كل ١٠٠ متر حركة فقط، وخزّن مسار الرحلة (cache) بدل إعادة طلبه.
- **الإشعارات:** Firebase Cloud Messaging (FCM)
- **البثّ اللحظي للتتبّع:** Laravel Echo + Redis + (Pusher أو Soketi)

ابدأ بالباك-إند أولاً. لا تكتب أي واجهة قبل اكتمال قاعدة البيانات والمصادقة والـ API الأساسية.

---

## 3) الهوية البصرية (مأخوذة من التصاميم المرفقة)

- خلفية بيضاء نظيفة.
- لون أساسي: بنفسجي–فيوزي متدرّج `linear-gradient(135deg,#7C3AED,#D946EF)`.
- لون ثانوي: سمائي `#38BDF8` (متدرّج `#7C3AED → #38BDF8`).
- نص داكن `#1A1230`، نص ثانوي `#7A7391`، حدود `#ECE8F4`، خلفية ناعمة `#F7F5FC`.
- نجاح `#22C55E`، تحذير `#F59E0B`، خطر `#DC2626`.
- الخطوط: Cairo (للعناوين) + IBM Plex Sans Arabic (للنصوص).
- كل الواجهات RTL. حوافّ دائرية واضحة (radius ١٢–٢٢px)، ظلال ناعمة.

**التزم بهذه الألوان والخطوط في كل الواجهات، وطابق التخطيط الموجود في ملفات HTML المرفقة قدر الإمكان.**

---

## 4) الأدوار (Roles)

1. **المستخدم (User/Sender):** ينشئ طلبات، يستقبل عروضاً أو يبحث حسب الوجهة، يتتبّع، يقيّم الشركات، محفظة إلكترونية.
2. **السائق (Driver):** تابع لشركة، يستقبل مهام، يحدّث الحالة، يؤكّد التسليم بالرمز/الصورة.
3. **مدير الشركة (Company Admin/Tenant):** يدير طلبات شركته، يعيّن السائقين، يدير سائقيه ومساراته وتقاريره واشتراكه.
4. **السوبر أدمن (Platform Owner):** يدير كل الشركات، الباقات، الاشتراكات، صحّة النظام، والصلاحيات.

---

## 5) مخطّط قاعدة البيانات (الجداول الأساسية)

صمّم الهجرات (migrations) لهذه الجداول. راعِ فصل المستأجرين عبر `company_id` على البيانات التابعة للشركة.

- `governorates` — محافظات العراق (id, name_ar).
- `users` — المستخدمون النهائيون (id, name, phone, password, wallet_balance, rating, status).
- `companies` (المستأجرون) — (id, name, logo, governorate_id, phone, rating, status[active/pending/suspended], subscription_plan_id, trial_ends_at, verified_at).
- `company_admins` — حسابات مديري الشركات (id, company_id, name, email, password, role).
- `drivers` — (id, company_id, name, phone, vehicle_type, vehicle_plate, rating, status[available/busy/offline], current_lat, current_lng, last_location_at).
- `company_routes` — المسارات التي تخدمها الشركة (id, company_id, from_governorate_id, to_governorate_id, price, duration_hours, is_active).
- `orders` — الطلبات (id, code[MND-xxxx], user_id, company_id, driver_id, from_governorate_id, to_governorate_id, pickup_address, dropoff_address, package_type[normal/documents/fragile/large], notes, price, status, delivery_code[4 أرقام], created_at).
  - حالات الطلب: `pending_offers, offer_accepted, driver_assigned, picked_up, at_branch, in_transit, arrived_dest, delivered, cancelled`.
- `order_offers` — عروض الشركات على الطلبات المفتوحة (id, order_id, company_id, price, duration_hours, status).
- `order_tracking` — سجلّ مراحل التتبّع (id, order_id, status, note, lat, lng, created_at).
- `reviews` — تقييمات المستخدمين للشركات (id, user_id, company_id, order_id, rating, comment, tags).
- `wallet_transactions` — عمليات محفظة المستخدم (id, user_id, type[credit/debit], amount, reference, description).
- `chat_messages` — رسائل المستخدم/السائق (id, order_id, sender_type, sender_id, message, read_at).
- `subscription_plans` — الباقات (id, name, price_monthly, features_json, trial_days).
- `company_subscriptions` — اشتراكات الشركات (id, company_id, plan_id, started_at, ends_at, status[trial/active/expired], amount).
- `platform_settings` — إعدادات وميزات المنصّة القابلة للتفعيل (key, value).
- `notifications` — إشعارات (قياسي Laravel).

أضف الفهارس (indexes) المناسبة، خصوصاً على `orders(from_governorate_id, to_governorate_id, status)` و`company_routes(from_governorate_id, to_governorate_id, is_active)` و`orders(company_id, status)`.

---

## 6) واجهات API الأساسية (REST, مع Sanctum)

نظّمها بمجموعات. أعطِ كل مجموعة موارد RESTful قياسية حيثما أمكن.

**المصادقة:** تسجيل/دخول بالهاتف + OTP، دخول مديري الشركات والسوبر أدمن.

**للمستخدم:**
- `GET /governorates`
- `POST /orders` (إنشاء طلب مفتوح للعروض)
- `GET /companies?from=&to=&type=` (بحث الشركات حسب المسار — استعلام على company_routes)
- `GET /companies/{id}` + `GET /companies/{id}/reviews`
- `GET /orders/{id}/offers` + `POST /offers/{id}/accept`
- `GET /orders/{id}/tracking` (+ قناة بثّ لحظي)
- `POST /orders/{id}/rate`
- `GET /wallet` + `POST /wallet/topup`
- دردشة: `GET/POST /orders/{id}/messages`

**للسائق:**
- `GET /driver/jobs` (المهام المتاحة/المعيّنة)
- `POST /driver/jobs/{id}/accept`
- `POST /driver/orders/{id}/status` (تحديث المرحلة)
- `POST /driver/location` (بثّ الموقع — مقنّن)
- `POST /driver/orders/{id}/deliver` (تأكيد بالرمز + صورة)
- `GET /driver/earnings`

**لمدير الشركة:**
- CRUD: `company/routes`, `company/drivers`
- `GET company/orders` + `POST company/orders/{id}/assign` (تعيين سائق)
- `GET company/reports`, `GET company/subscription`
- إدارة تغطية المحافظات

**للسوبر أدمن:**
- CRUD: `admin/companies`, `admin/plans`
- `GET admin/overview` (MRR/ARR/churn), `admin/subscriptions`, `admin/users`, `admin/drivers`
- `GET admin/system-health`, إدارة `admin/features`

وثّق الـ endpoints (استخدم Scribe أو ملف OpenAPI).

---

## 7) منطق أعمال مهم (Business Logic) لا تنساه

- **البحث حسب المسار:** يعتمد على `company_routes` — فقط الشركات التي فعّلت المسار (from/to, is_active) تظهر، مرتّبة بالسعر افتراضياً.
- **رمز التسليم:** يُولَّد ٤ أرقام عند تعيين السائق، يظهر للمستلِم في تطبيقه، ويُطلب من السائق إدخاله عند التسليم النهائي (حماية من نزاعات "لم أستلم").
- **البثّ اللحظي المُقنّن:** موقع السائق يُحدّث كل ٥–١٠ ثوانٍ أو ١٠٠ متر فقط، ويُبثّ عبر قناة Echo خاصة بالطلب.
- **الاشتراك التجريبي:** كل شركة جديدة تبدأ بباقة تجريبية مجانية مدّتها ٦ أشهر (`trial_ends_at`). عند الانتهاء تتحوّل الحالة إلى expired وتحتاج ترقية. أضف Job مجدول يفحص انتهاء التجارب يومياً.
- **الإشعارات:** كل تغيير حالة طلب يرسل إشعار FCM للمستخدم، وكل مهمة جديدة تُشعر السائق.
- **العزل بين المستأجرين:** مدير الشركة لا يرى إلا بيانات شركته (Global Scope على company_id). السوبر أدمن يرى الكل.

---

## 8) خطة التنفيذ المرحلية — نفّذها بالترتيب

**المرحلة ١ — الأساس:** إعداد مشروع Laravel 11 + Sanctum + Redis، كل الهجرات والـ Models والعلاقات، بيانات أولية (seeders) للمحافظات والباقات وحساب سوبر أدمن.

**المرحلة ٢ — المصادقة والـ API الأساسية:** تسجيل/دخول لكل الأدوار، وendpoints المستخدم (إنشاء طلب، بحث الشركات، العروض).

**المرحلة ٣ — دورة الطلب الكاملة:** العروض والقبول، تعيين السائق، تحديث الحالات، التتبّع، رمز التسليم، الإشعارات، الدردشة، المحفظة، التقييم.

**المرحلة ٤ — لوحة الشركة (Vue + Inertia):** طابق `mandoub-company-web.html` — النظرة العامة، الطلبات، تعيين السائق، السائقون، المسارات، التقارير، الاشتراك.

**المرحلة ٥ — لوحة السوبر أدمن (Vue + Inertia):** طابق `mandoub-super-admin.html` — MRR/الباقات/المستأجرين/صحّة النظام/الصلاحيات.

**المرحلة ٦ — تطبيقات Flutter:** المستخدم ثم السائق، طابق `mandoub-user-app.html` و`mandoub-driver-app.html`، مع Google Maps والتتبّع اللحظي.

بعد كل مرحلة: أوقف، لخّص ما بنيته، وانتظر مراجعتي قبل المتابعة.

---

## 9) تعليمات جودة

- كود نظيف، أسماء واضحة، Form Requests للتحقّق، Resources لتنسيق مخرجات API، Policies للصلاحيات.
- اكتب اختبارات (Feature tests) للمسارات الحرجة: إنشاء الطلب، البحث حسب المسار، تعيين السائق، تأكيد التسليم بالرمز.
- كل النصوص الظاهرة بالعربي. رسائل الأخطاء واضحة وبالعربي.
- التزم بالهوية البصرية أعلاه في كل واجهات Vue.
- استخدم متغيّرات بيئة (.env) لكل المفاتيح (Google Maps, FCM, Pusher). لا تضع مفاتيح في الكود.

---

**ابدأ الآن بالمرحلة ١ فقط: أنشئ مشروع Laravel 11، اكتب كل الهجرات والـ Models والعلاقات والـ seeders. اعرض عليّ الملفات ثم توقّف للمراجعة قبل المرحلة ٢.**