# SMK Logistics — معمارية تطبيق `smk_logistics`

> **الحالة:** مسودة للمراجعة والموافقة — **لا يبدأ التنفيذ البرمجي قبل الموافقة.**  
> **التاريخ:** 2025-06-05  
> **Backend:** Laravel الحالي (`https://api.smkiraq.com/api/v1`)  
> **قاعدة البيانات:** نفس DB الحالية (بدون fork)  
> **Firebase:** نفس مشروع FCM المستخدم في `smk_customer` و `smk_merchant`

---

## 1. ملخص تنفيذي

تطبيق **`smk_logistics`** تطبيق Flutter **واحد** يحتوي على **3 أدوار** (Central / Branch / Driver). بعد تسجيل الدخول، يُحدَّد الدور من الـ Backend ويُوجَّه المستخدم إلى واجهة مناسبة (Role-Based Shell).

| الدور | التعريف في النظام الحالي | آلية التحقق |
|--------|---------------------------|-------------|
| **Central Logistics Admin** | مستخدم Platform بصلاحية `logistics.central.manage` | Permission + `User::canAccessCentralLogistics()` |
| **Branch Logistics Manager** | `user_type = branch_manager` + فرع نشط (`managedBranch`) | `User::canAccessBranchLogistics()` |
| **Delivery Driver** | `user_type = driver` + سجل `drivers` نشط | `User::canAccessDriverLogistics()` |

**الوضع الحالي:** منطق اللوجستك **موجود ويعمل** في Laravel (Livewire Web + `VendorOrderWorkflowService`). واجهة API للموبايل **جزئية** (السائق فقط). التطبيق الجديد يعيد استخدام الـ Workflow الحالي ويُكمّل الـ API الناقص.

**مرجع Flutter قديم:** مجلد `smk_app/lib/features/logistics/` (نموذج سائق مبكر) — **لا يُستخدم كمنتج نهائي**، بل كمرجع فقط. المنتج الجديد: `smk_logistics/` بنفس بنية `smk_merchant`.

---

## 2. تحليل Routes الحالية

### 2.1 Web — لوحة Laravel Livewire (`routes/web.php`)

| Prefix | Middleware | المسارات | الوظيفة |
|--------|------------|----------|---------|
| `/logistics/login` | — | GET/POST login, logout | دخول موحّد لكل الأدوار |
| `/logistics/central/*` | `auth` + `logistics.central` | dashboard, orders | المركزي: استلام، تحويل، متابعة |
| `/logistics/branch/*` | `auth` + `logistics.branch` | dashboard, orders | الفرع: استلام، إسناد سائق |
| `/logistics/driver/*` | `auth` + `logistics.driver` | dashboard, orders | السائق: توصيل (ويب) |

**ملاحظة:** إدارة المحافظات، الفروع، السائقين، ومستخدمي الفروع تتم اليوم من **لوحة Admin** (`/admin/branches`, `/admin/drivers`, `/admin/users`) وليس من لوحة اللوجستك Web.

### 2.2 API — Mobile (`routes/api.php`)

| Prefix | Middleware | Endpoints | الحالة |
|--------|------------|-----------|--------|
| `/api/v1/logistics/driver/auth/*` | throttle / sanctum + `logistics.driver.api` | login, logout, profile | ✅ موجود |
| `/api/v1/logistics/driver/orders/*` | sanctum + driver | list, show, start, deliver, fail | ✅ موجود |
| `/api/v1/logistics/central/*` | — | — | ❌ غير موجود |
| `/api/v1/logistics/branch/*` | — | — | ❌ غير موجود |

### 2.3 API مرتبطة (عامة)

| Endpoint | الاستخدام المحتمل |
|----------|-------------------|
| `GET /api/v1/governorates` | قوائم المحافظات (Central / Transfer) |
| `GET /api/v1/app-info` | إصدار التطبيق |

---

## 3. تحليل Models الحالية

### 3.1 النواة — الطلبات

| Model | الجدول | الغرض |
|-------|--------|--------|
| `VendorOrder` | `vendor_orders` | الطلب الرئيسي (merchant → customer) |
| `VendorOrderItem` | `vendor_order_items` | بنود الطلب |
| `VendorOrderStatusLog` | `vendor_order_status_logs` | Timeline / سجل الحالات |
| `VendorOrderCentralIntake` | `vendor_order_central_intakes` | استلام المركزي (sent/received) |
| `VendorOrderTransfer` | `vendor_order_transfers` | تحويل إلى فرع المحافظة |

**حقول مهمة على `vendor_orders`:**  
`vendor_id`, `customer_id`, `governorate_id`, `branch_id`, `driver_id`, `status`,  
`shipping_address`, `customer_area`, `customer_phone`, `customer_name`,  
`subtotal`, `shipping_fee`, `total`, `total_weight`,  
`sent_to_central_logistics_at`, `received_by_central_logistics_at`,  
`sent_to_branch_at`, `arrived_to_branch_at`, `assigned_to_driver_at`,  
`out_for_delivery_at`, `delivered_at`, `failed_delivery_at`, `failed_delivery_reason`, `returned_at`

**غير موجود حالياً:** `delivery_proof_photo`, إحداثيات GPS للعميل.

### 3.2 المستخدمون والصلاحيات

| Model | الغرض |
|-------|--------|
| `User` | حساب موحّد (Sanctum tokens) |
| `Role` | أدوار RBAC |
| `Permission` | صلاحيات (انظر `config/permissions.php`) |
| `Branch` | مكتب محافظة (`manager_user_id`, `governorate_id`, `is_central_hub`) |
| `Driver` | سجل السائق (`user_id`, `branch_id`, `vehicle_*`, `is_active`) |
| `Governorate` | المحافظات |
| `DeviceToken` | FCM (morph owner — حالياً Customer/Vendor فقط) |

### 3.3 Services

| Service | الدور |
|---------|--------|
| `VendorOrderWorkflowService` | **مصدر الحقيقة** لانتقالات الحالة (central / branch / driver) |
| `LogisticsNotificationService` | إشعار DB للمركزي عند طلب وارد (`CentralLogisticsIncomingOrderNotification`) |
| `FcmService` | إرسال Push (يُ reused للوجستك) |

---

## 4. Order Status Workflow

### 4.1 مخطط سير الطلب (من التاجر إلى السائق)

```mermaid
flowchart LR
    subgraph Merchant["التاجر"]
        A[new] --> B[accepted]
        B --> C[preparing]
        C --> D[ready_for_pickup]
        D --> E[sent_to_central_logistics]
    end

    subgraph Central["المركزي"]
        E --> F[received_by_central_logistics]
        F --> G[sent_to_branch]
    end

    subgraph Branch["مدير الفرع"]
        G --> H[arrived_to_branch]
        H --> I[assigned_to_driver]
    end

    subgraph Driver["السائق"]
        I --> J[out_for_delivery]
        J --> K[delivered]
        J --> L[failed_delivery]
        L --> M[returned]
    end
```

### 4.2 مطابقة أسماء الحالات (مواصفاتك ↔ Backend)

| في المواصفات | في Backend (`VendorOrderStatus`) | الملاحظة |
|--------------|----------------------------------|----------|
| `sent_to_central_logistics` | `sent_to_central_logistics` | ✅ متطابق |
| `received_by_central_logistics` | `received_by_central_logistics` | ✅ متطابق |
| `sent_to_branch` | `sent_to_branch` | ✅ متطابق |
| `received_by_branch` | **`arrived_to_branch`** | ⚠️ اسم مختلف — نستخدم Backend في API |
| `assigned_to_driver` | `assigned_to_driver` | ✅ متطابق |
| `out_for_delivery` | `out_for_delivery` | ✅ متطابق |
| `delivered` | `delivered` | ✅ متطابق |
| `delivery_failed` | **`failed_delivery`** | ⚠️ اسم مختلف — نستخدم Backend في API |

### 4.3 انتقالات مسموحة (`canTransitionTo`)

| من | إلى | الفاعل (`actor`) | Method في Workflow |
|----|-----|------------------|-------------------|
| `sent_to_central_logistics` | `received_by_central_logistics` | `central` | `centralReceiveFromMerchant()` |
| `received_by_central_logistics` | `sent_to_branch` | `central` | `transferToBranch()` |
| `sent_to_branch` | `arrived_to_branch` | `branch` | `branchReceive()` |
| `arrived_to_branch` | `assigned_to_driver` | `branch` | `assignDriver()` |
| `assigned_to_driver` | `out_for_delivery` | `driver` | `driverStartDelivery()` |
| `out_for_delivery` | `delivered` | `driver` | `driverDeliver()` |
| `out_for_delivery` | `failed_delivery` | `driver` | `driverFailDelivery()` |
| `failed_delivery` | `returned` / `assigned_to_driver` | `driver` | `driverReturn()` / إعادة إسناد |

### 4.4 فجوات مقارنة بالمواصفات

| المطلوب | Backend حالياً |
|---------|--------------|
| سحب الطلب من السائق (unassign) | ❌ لا يوجد method/API |
| صورة إثبات التسليم | ❌ لا يوجد حقل/endpoint |
| فتح موقع العميل على الخريطة | ⚠️ عنوان نصي فقط (`shipping_address`, `customer_area`) — لا lat/lng للعميل |
| إشعار الفرع عند التحويل | ❌ غير مُنفَّذ (المركزي فقط) |
| إشعار السائق عند الإسناد | ❌ غير مُنفَّذ عبر FCM |

---

## 5. RBAC — الصلاحيات والأدوار

### 5.1 صلاحيات Laravel (`config/permissions.php`)

```
logistics.central.view
logistics.central.manage      ← Central Admin (إلزامي للمركزي)
logistics.branch.view
logistics.branch.manage       ← Branch Manager (مستقبلياً)
logistics.driver.view
logistics.driver.manage
```

### 5.2 قواعد الدخول للتطبيق

```
POST /api/v1/logistics/auth/login
→ يرجع: token + role: central | branch | driver + profile
```

| الدور | شروط الدخول | Scope البيانات |
|-------|-------------|----------------|
| Central | `hasPermission('logistics.central.manage')` | كل الطلبات / كل المحافظات |
| Branch | `user_type=branch_manager` + `managedBranch.is_active` | `vendor_orders.branch_id = managedBranch.id` |
| Driver | `user_type=driver` + `driver.is_active` | `vendor_orders.driver_id = driver.id` |

**أولوية التوجيه** (نفس `Logistics\AuthController`): Central → Branch → Driver.

### 5.3 إدارة المستخدمين

| العملية | من ينفّذها اليوم | المطلوب في التطبيق |
|---------|------------------|-------------------|
| إضافة/تعديل/تعطيل مدير فرع | Admin Web | Central عبر API جديد |
| إضافة/تعديل/تعطيل سائق | Admin Web (عرض فقط) | Branch Manager عبر API جديد |
| إنشاء مستخدم من السائق | — | ❌ ممنوع (حسب المواصفات) |

---

## 6. قاعدة البيانات المستخدمة (بدون جداول جديدة إلزامية)

### جداول أساسية (read/write)

- `users`, `roles`, `role_permission`, `permissions`
- `governorates`, `branches`, `drivers`, `branch_staff`
- `vendor_orders`, `vendor_order_items`, `vendor_order_status_logs`
- `vendor_order_central_intakes`, `vendor_order_transfers`
- `vendors`, `customers` (قراءة بيانات الطلب)
- `device_tokens` (توسيع `app_role`: `logistics_central`, `logistics_branch`, `logistics_driver`)
- `notifications` (Laravel DB notifications — اختياري للتطبيق)

### جداول مقترحة (Phase B — اختيارية)

| جدول/عمود | السبب |
|-----------|--------|
| `vendor_orders.delivery_proof_path` | صورة إثبات التسليم |
| `vendor_orders.customer_lat`, `customer_lng` | خريطة دقيقة (أو geocoding لاحقاً) |
| `logistics_push_logs` | تتبع FCM (debug) |

---

## 7. API الحالية vs API المطلوبة

### 7.1 موجودة — تُ reused

#### Driver (`/api/v1/logistics/driver/...`)

| Method | Path | الوظيفة |
|--------|------|---------|
| POST | `/auth/login` | دخول |
| POST | `/auth/logout` | خروج |
| GET | `/auth/profile` | ملف السائق |
| GET | `/orders?tab=` | قائمة |
| GET | `/orders/{id}` | تفاصيل + timeline |
| POST | `/orders/{id}/start` | `out_for_delivery` |
| POST | `/orders/{id}/deliver` | `delivered` |
| POST | `/orders/{id}/fail` | `failed_delivery` |

### 7.2 مطلوبة — Auth موحّد

| Method | Path | الوظيفة |
|--------|------|---------|
| POST | `/api/v1/logistics/auth/login` | دخول موحّد (email/password) → role + token |
| POST | `/api/v1/logistics/auth/logout` | خروج |
| GET | `/api/v1/logistics/auth/me` | الملف + الدور + branch/governorate |
| POST | `/api/v1/logistics/device/register` | FCM token |
| POST | `/api/v1/logistics/device/unregister` | إلغاء FCM |

**Middleware مقترح:**  
`logistics.central.api`, `logistics.branch.api`, `logistics.driver.api` (أو middleware واحد `logistics.api` + policy داخل Controller).

### 7.3 مطلوبة — Central API

| Method | Path | الوظيفة |
|--------|------|---------|
| GET | `/logistics/central/dashboard` | إحصائيات (incoming, received, transit, by governorate) |
| GET | `/logistics/central/orders` | قائمة + filters (status, governorate, search) |
| GET | `/logistics/central/orders/{id}` | تفاصيل + timeline + intake + transfers |
| POST | `/logistics/central/orders/{id}/receive` | `centralReceiveFromMerchant` |
| POST | `/logistics/central/orders/{id}/transfer` | `transferToBranch` (governorate_id, branch_id, notes) |
| POST | `/logistics/central/orders/{id}/reject-transfer` | `rejectTransfer` (optional) |
| GET | `/logistics/central/governorates` | محافظات + عدد الطلبات |
| GET | `/logistics/central/branches` | فروع نشطة |
| GET | `/logistics/central/drivers` | كل السائقين (read-only monitoring) |
| GET | `/logistics/central/branch-managers` | قائمة مديري الفروع |
| POST | `/logistics/central/branch-managers` | إنشاء مدير + ربط branch |
| PUT | `/logistics/central/branch-managers/{id}` | تعديل |
| PATCH | `/logistics/central/branch-managers/{id}/toggle` | تفعيل/تعطيل |

> **إدارة المحافظات (CRUD)** تبقى في Admin Web في Phase 1؛ Central يرى ويُ filter فقط. CRUD محافظات عبر API = Phase 2 إن طُلب.

### 7.4 مطلوبة — Branch API

| Method | Path | الوظيفة |
|--------|------|---------|
| GET | `/logistics/branch/dashboard` | إحصائيات فرع المستخدم |
| GET | `/logistics/branch/orders` | طلبات `branch_id` فقط |
| GET | `/logistics/branch/orders/{id}` | تفاصيل |
| POST | `/logistics/branch/orders/{id}/receive` | `branchReceive` |
| POST | `/logistics/branch/orders/{id}/assign-driver` | `assignDriver` |
| POST | `/logistics/branch/orders/{id}/unassign-driver` | **جديد** — إرجاع إلى `arrived_to_branch` |
| GET | `/logistics/branch/drivers` | سائقو الفرع |
| POST | `/logistics/branch/drivers` | إنشاء سائق (user + driver) |
| PUT | `/logistics/branch/drivers/{id}` | تعديل |
| PATCH | `/logistics/branch/drivers/{id}/toggle` | تفعيل/تعطيل |

### 7.5 مطلوبة — Driver API (توسيع الموجود)

| Method | Path | الوظيفة |
|--------|------|---------|
| POST | `/logistics/driver/orders/{id}/deliver` | + **`proof_photo`** (multipart) |
| POST | `/logistics/driver/orders/{id}/return` | `driverReturn` (موجود في Web، ناقص API) |
| GET | `/logistics/driver/orders/{id}/map` | deep link / coords (address string + optional geocode) |

**Migration:** `delivery_proof_path` nullable on `vendor_orders`.

### 7.6 Notifications API (مشترك)

| Method | Path | الوظيفة |
|--------|------|---------|
| GET | `/logistics/notifications` | قائمة |
| PATCH | `/logistics/notifications/{id}/read` | قراءة |
| POST | `/logistics/notifications/read-all` | قراءة الكل |

---

## 8. Push Notifications

### 8.1 الوضع الحالي

| الحدث | التنفيذ |
|-------|---------|
| طلب جديد للمركزي | ✅ `LogisticsNotificationService` → Laravel Notification (DB) |
| FCM للتجار/العملاء | ✅ `DeviceToken` + `FcmService` |
| FCM للوجستك | ❌ غير مربوط |

### 8.2 المطلوب

| الدور | الحدث | Payload type |
|-------|-------|--------------|
| Central | `sent_to_central_logistics` | `logistics_new_incoming_order` |
| Branch | `sent_to_branch` (branch_id match) | `logistics_branch_incoming` |
| Driver | `assigned_to_driver` | `logistics_driver_assigned` |

**التنفيذ:** توسيع `LogisticsNotificationService` + `DeviceToken.app_role` + استدعاء `FcmService` من `VendorOrderWorkflowService` بعد كل transition ذي صلة.

---

## 9. تطبيق Flutter — `smk_logistics`

### 9.1 Stack (مطابق للتطبيقات الحالية)

| العنصر | القرار |
|--------|--------|
| Package | `smk_logistics/` (monorepo — يُضاف إلى `melos.yaml`) |
| Shared | `packages/smk_shared` (DioClient, SmkApiConfig, theme helpers) |
| State | Provider |
| Auth | Sanctum token في `SecureStorage` |
| Push | Firebase Messaging + `logistics/device/register` |
| Env | `--dart-define=APP_ENV=production` → `api.smkiraq.com` |
| Design | `AppColors` / `google_fonts` / نفس patterns من `smk_merchant` |

### 9.2 هيكل المجلدات المقترح

```
smk_logistics/
  lib/
    main.dart
    app.dart
    core/
      constants/   api_config, api_endpoints, app_colors
      push/        push_service.dart
    features/
      splash/
      auth/        login, auth_provider, role_router
      central/     dashboard, orders, order_detail, transfer, branch_managers
      branch/      dashboard, orders, order_detail, assign_driver, drivers
      driver/      dashboard, orders, order_detail, delivery_actions
      notifications/
    shared/widgets/
```

### 9.3 Role Router (بعد Login)

```
login success
  → if role == central  → CentralShell
  → if role == branch   → BranchShell
  → if role == driver   → DriverShell
  → else                → error "لا صلاحية لوجستك"
```

---

## 10. الشاشات المطلوبة

### 10.1 مشتركة

| الشاشة | Central | Branch | Driver |
|--------|:-------:|:------:|:------:|
| Splash | ✅ | ✅ | ✅ |
| Login | ✅ | ✅ | ✅ |
| Notifications | ✅ | ✅ | ✅ |
| Profile / Logout | ✅ | ✅ | ✅ |

### 10.2 Central Logistics Admin

| # | الشاشة | الوظيفة |
|---|--------|---------|
| C1 | Dashboard | incoming / received / in-transit / delivered today / by governorate |
| C2 | Orders List | tabs: وارد، مستلم، في الطريق، مكتمل |
| C3 | Order Detail | vendor, customer, items, timeline, intake |
| C4 | Receive Order | تأكيد استلام (`received_by_central_logistics`) |
| C5 | Transfer Order | اختيار محافظة + فرع + ملاحظات |
| C6 | Orders by Governorate | filter |
| C7 | Branch Managers List | CRUD |
| C8 | Branch Manager Form | create/edit/toggle |
| C9 | All Drivers (monitor) | read-only |
| C10 | Governorates Overview | read-only (Phase 1) |

**حالات التعامل:** `sent_to_central_logistics`, `received_by_central_logistics`, `sent_to_branch` (+ متابعة لاحقة read-only).

### 10.3 Branch Logistics Manager

| # | الشاشة | الوظيفة |
|---|--------|---------|
| B1 | Dashboard | incoming / active / completed |
| B2 | Orders List | tabs: وارد من المركزي، نشط، منتهي |
| B3 | Order Detail | + السائق الحالي |
| B4 | Receive at Branch | `arrived_to_branch` |
| B5 | Assign Driver | picker من سائقي الفرع |
| B6 | Unassign Driver | **جديد** |
| B7 | Drivers List | CRUD |
| B8 | Driver Form | create/edit/toggle |

**حالات التعامل:** `sent_to_branch`, `arrived_to_branch`, `assigned_to_driver` (+ متابعة read-only).

### 10.4 Delivery Driver

| # | الشاشة | الوظيفة |
|---|--------|---------|
| D1 | Dashboard | today's count / active |
| D2 | My Orders | assigned + out_for_delivery |
| D3 | Order Detail | customer, phone, address, items |
| D4 | Call Customer | `url_launcher` tel: |
| D5 | Open Map | Google Maps / Waze deep link من العنوان |
| D6 | Start Delivery | `out_for_delivery` |
| D7 | Confirm Delivery | + camera/gallery proof photo |
| D8 | Delivery Failed | reason text |
| D9 | Return Order | optional |
| D10 | Completed History | delivered / failed |

**حالات التعامل:** `assigned_to_driver`, `out_for_delivery`, `delivered`, `failed_delivery`.

---

## 11. خطة التنفيذ المقترحة (بعد الموافقة)

### Phase A — Backend API (أسبوع 1)

1. Auth موحّد + middlewares  
2. Central orders API (dashboard, list, receive, transfer)  
3. Branch orders API (list, receive, assign)  
4. توسيع Driver API (return, proof photo + migration)  
5. Device tokens للوجستك  
6. FCM triggers (central, branch, driver)  
7. PHPUnit: lifecycle central → branch → driver  

### Phase B — Flutter Shell (أسبوع 2)

1. Scaffold `smk_logistics` + melos  
2. Firebase (نفس project، flavor `logistics`)  
3. Auth + Role Router  
4. Driver flow (أكثر API جاهزاً) — E2E على جهاز حقيقي  

### Phase C — Central + Branch (أسبوع 3)

1. Central screens C1–C6  
2. Branch screens B1–B6  
3. Branch manager + driver management APIs & UI  

### Phase D — Polish (أسبوع 4)

1. Push notifications كاملة  
2. Unassign driver  
3. Beta checklist + production signing  
4. توثيق `docs/BETA_TESTING_CHECKLIST_LOGISTICS.md`  

---

## 12. حسابات اختبار (من Seeder)

| الدور | Email | Password |
|-------|-------|----------|
| Central | `central@smk.iq` | `123321001` |
| Branch (ذي قار) | `branch.dhiqar@smk.iq` | `123321001` |
| Driver (ذي قار) | `driver.dhiqar@smk.iq` | `123321001` |

> Central يحتاج role بصلاحية `logistics.central.manage` (super-admin/admin).

---

## 13. قرارات تحتاج موافقتك

1. **أسماء الحالات:** نستخدم Backend (`arrived_to_branch`, `failed_delivery`) في API والتطبيق — أم نضيف aliases في JSON؟  
2. **إدارة المحافظات:** من Admin Web فقط (Phase 1) أم CRUD من تطبيق المركزي؟  
3. **Unassign driver:** إرجاع إلى `arrived_to_branch` فقط — أم حالة وسيطة جديدة؟  
4. **Firebase:** نفس `google-services.json` مع `app_role` مختلف — أم Firebase app منفصل في Console؟  
5. **اسم التطبيق على الهاتف:** `smk اللوجستك` / `smk التوصيل`؟  

---

## 14. الخلاصة

| البند | الحالة |
|-------|--------|
| Workflow الطلبات | ✅ جاهز في Laravel |
| Web Logistics | ✅ Central / Branch / Driver |
| API Mobile | ⚠️ Driver جزئي — Central/Branch مفقود |
| FCM Logistics | ❌ يحتاج بناء |
| Flutter App | ❌ لم يُنشأ — `smk_logistics` مقترح |

**التوصية:** الموافقة على هذا المستند → البدء بـ **Phase A (Backend API)** ثم **Flutter Driver** كأسرع مسار لاختبار حقيقي، يليه Central و Branch.

---

*آخر تحديث: تحليل codebase SMK — Laravel 11 + Livewire 4 + Flutter monorepo.*