# Phase A — SMK Logistics Backend APIs

**التاريخ:** 2026-06-05  
**الحالة:** مكتملة ✅  
**نسبة الإنجاز:** 100% (Backend APIs — Phase A)

---

## ملخص

تم تنفيذ **Phase A** بالكامل: واجهات REST API للتطبيق الموحد **SMK Logistics** (مركزي / فرع / سائق) على نفس Laravel Backend وقاعدة البيانات الحالية، مع توسيع سير العمل، FCM، واختبارات E2E.

**لم يبدأ Flutter (`smk_logistics`)** — كما طُلب.

---

## ما تم إنجازه

### 1. قاعدة البيانات (Migration)
- `vendor_orders.delivery_proof_photo` — إثبات التسليم (صورة)
- `vendor_order_transfers.received_by_user_id` — من استلم في الفرع
- `vendor_order_transfers.received_at` — وقت الاستلام
- `vendor_order_transfers.receive_notes` — ملاحظات الاستلام

**Migration:** `database/migrations/2026_06_05_100001_add_logistics_mobile_fields.php`

### 2. سير العمل (Workflow)
توسيع `VendorOrderWorkflowService`:
- `branchReceive()` — تسجيل audit الاستلام في `vendor_order_transfers`
- `branchUnassignDriver()` — إرجاع الحالة إلى `arrived_to_branch` (بدون حالة جديدة)
- `driverDeliver()` — قبول مسار `delivery_proof_photo`
- `driverReturn()` — إرجاع الطلب
- FCM hooks عند: تحويل للفرع، إسناد سائق، سحب إسناد

### 3. المصادقة الموحدة
تطبيق واحد — تحديد الواجهة حسب الصلاحية بعد Login:
- `POST /api/v1/logistics/auth/login`
- `POST /api/v1/logistics/auth/logout`
- `GET /api/v1/logistics/auth/me`

يرجع: `token`, `role` (`central`|`branch`|`driver`), `app_role` (`logistics_central`|`logistics_branch`|`logistics_driver`)

### 4. FCM Devices
- `POST /api/v1/logistics/devices/register`
- `POST /api/v1/logistics/devices/unregister`

### 5. APIs المركزي (`logistics.central.api`)
| Method | Endpoint | الوصف |
|--------|----------|--------|
| GET | `/logistics/central/dashboard` | إحصائيات: وارد، قيد التوصيل، مكتمل، سائقين نشطين، حسب المحافظة، أفضل المحافظات |
| GET | `/logistics/central/orders?tab=` | قائمة الطلبات (incoming/received/in_transit/all) |
| GET | `/logistics/central/orders/{id}` | تفاصيل + timeline + سجل التحويل |
| POST | `/logistics/central/orders/{id}/receive` | استلام من التاجر |
| POST | `/logistics/central/orders/{id}/transfer` | تحويل للفرع (branch_id, shipping_notes) |
| POST | `/logistics/central/orders/{id}/reject-transfer` | رفض التحويل |
| GET | `/logistics/central/governorates` | **قراءة فقط** |
| GET | `/logistics/central/branches` | **قراءة فقط** |
| GET | `/logistics/central/branch-managers` | قائمة مديري الفروع |
| POST | `/logistics/central/branch-managers` | إنشاء مدير فرع |
| PUT | `/logistics/central/branch-managers/{user}` | تحديث مدير فرع |
| GET | `/logistics/central/drivers` | مراقبة السائقين |

### 6. APIs الفرع (`logistics.branch.api`)
| Method | Endpoint | الوصف |
|--------|----------|--------|
| GET | `/logistics/branch/dashboard` | وارد، نشط، مسلّم، متأخر، أداء السائقين |
| GET | `/logistics/branch/orders?tab=` | incoming/active/done |
| GET | `/logistics/branch/orders/{id}` | تفاصيل + timeline |
| POST | `/logistics/branch/orders/{id}/receive` | استلام (notes) |
| POST | `/logistics/branch/orders/{id}/assign` | إسناد سائق |
| POST | `/logistics/branch/orders/{id}/unassign` | سحب → `arrived_to_branch` |
| GET | `/logistics/branch/drivers` | قائمة السائقين |
| POST | `/logistics/branch/drivers` | إنشاء سائق |
| PUT | `/logistics/branch/drivers/{driver}` | تحديث سائق |

### 7. APIs السائق (`logistics.driver.api`)
| Method | Endpoint | الوصف |
|--------|----------|--------|
| GET | `/logistics/driver/dashboard` | مسلّم، فاشل، اليوم، الشهر، نشط |
| GET | `/logistics/driver/orders?tab=` | active/completed/failed |
| GET | `/logistics/driver/orders/{id}` | تفاصيل + timeline |
| POST | `/logistics/driver/orders/{id}/start` | بدء التوصيل |
| POST | `/logistics/driver/orders/{id}/deliver` | تسليم + `delivery_proof_photo` (multipart) |
| POST | `/logistics/driver/orders/{id}/fail` | `failed_delivery` |
| POST | `/logistics/driver/orders/{id}/return` | إرجاع |

### 8. FCM Notifications (`LogisticsNotificationService`)
| الحدث | المستلم | app_role |
|-------|---------|----------|
| طلب جديد من التاجر | المركزي | `logistics_central` |
| تحويل طلب للفرع | مدير الفرع | `logistics_branch` |
| إسناد طلب | السائق | `logistics_driver` |
| سحب إسناد | السائق السابق | `logistics_driver` |

### 9. اختبارات PHPUnit
`tests/Feature/LogisticsApiE2ETest.php` — **4 tests, 45 assertions — PASS**

يغطي: login لكل الأدوار، دورة حياة كاملة (مركز → فرع → سائق → unassign → deliver + proof)، مواقع read-only، تسجيل FCM.

---

## الملفات المعدّلة / الجديدة

### جديد
```
app/Http/Controllers/Api/Logistics/AuthController.php
app/Http/Controllers/Api/Logistics/DeviceController.php
app/Http/Controllers/Api/Logistics/Central/DashboardController.php
app/Http/Controllers/Api/Logistics/Central/OrderController.php
app/Http/Controllers/Api/Logistics/Central/LocationController.php
app/Http/Controllers/Api/Logistics/Central/BranchManagerController.php
app/Http/Controllers/Api/Logistics/Central/DriverMonitorController.php
app/Http/Controllers/Api/Logistics/Branch/DashboardController.php
app/Http/Controllers/Api/Logistics/Branch/OrderController.php
app/Http/Controllers/Api/Logistics/Branch/DriverController.php
app/Http/Controllers/Api/Logistics/Driver/DashboardController.php
app/Http/Middleware/EnsureCentralLogisticsApi.php
app/Http/Middleware/EnsureBranchLogisticsApi.php
app/Http/Resources/Api/LogisticsOrderResource.php
app/Services/Logistics/LogisticsDashboardService.php
app/Services/Logistics/LogisticsUserManagementService.php
app/Support/LogisticsRole.php
database/migrations/2026_06_05_100001_add_logistics_mobile_fields.php
tests/Feature/LogisticsApiE2ETest.php
docs/reports/PHASE_A_LOGISTICS_BACKEND.md
```

### معدّل
```
app/Services/VendorOrderWorkflowService.php
app/Services/LogisticsNotificationService.php
app/Http/Controllers/Api/Logistics/DriverOrderController.php
app/Models/VendorOrder.php
app/Models/VendorOrderTransfer.php
app/Models/DeviceToken.php
routes/api.php
bootstrap/app.php
config/marketplace.php (+ logistics_delayed_hours)
database/seeders/LogisticsSeeder.php (UserType::Platform fix)
```

### محذوف
```
app/Http/Controllers/Api/Logistics/DriverAuthController.php (استُبدل بـ AuthController الموحد)
```

---

## قرارات معمارية مُطبّقة

| # | القرار | التطبيق |
|---|--------|---------|
| 1 | تطبيق واحد SMK Logistics | Auth موحد + `LogisticsRole` |
| 2 | نفس Backend/DB/Firebase | لا backend جديد |
| 3 | أسماء الحالات كما هي | `arrived_to_branch`, `failed_delivery` |
| 4 | المحافظات Admin Web فقط | Central: GET governorates/branches فقط |
| 5 | Unassign → `arrived_to_branch` | `branchUnassignDriver()` |
| 11 | audit التحويل | `vendor_order_transfers` (sent_by, notes, governorate, branch) |
| 12 | audit الاستلام | received_by, received_at, receive_notes |
| 13 | delivery_proof_photo | multipart upload → `storage/delivery-proofs` |

---

## المشاكل المكتشفة والإصلاحات

| المشكلة | الإصلاح |
|---------|---------|
| `UserType::Staff` غير موجود في Seeder | → `UserType::Platform` |
| `token_digest` غير fillable في DeviceToken | أُضيف للـ fillable + values في register |
| مسارات driver القديمة `/logistics/driver/auth/*` | استُبدلت بالمسارات الموحدة |

---

## تشغيل Migration

```bash
php artisan migrate
```

---

## اختبار محلي

```bash
php artisan test --filter=LogisticsApiE2ETest
```

**حسابات الاختبار (LogisticsSeeder):**
| الدور | Email | Password |
|-------|-------|----------|
| مركزي | central@smk.iq | 123321001 |
| فرع | branch.dhiqar@smk.iq | 123321001 |
| سائق | driver.dhiqar@smk.iq | 123321001 |

---

## الخطوات التالية — Phase B

1. إنشاء مشروع Flutter `smk_logistics` (اسم التطبيق: **SMK Logistics**)
2. Auth + routing حسب `role` من `/logistics/auth/login`
3. Driver Flow: dashboard, orders, start/deliver/fail/return + camera/gallery proof
4. ربط `smk_shared` + Firebase الحالي
5. تسجيل FCM عبر `/logistics/devices/register`

**Phase C:** Central Dashboard + Orders  
**Phase D:** Branch Dashboard + Driver Management  
**Phase E:** Push Notifications QA + Beta Testing

---

## نسبة الإنجاز الإجمالي للمشروع

| Phase | الحالة | النسبة |
|-------|--------|--------|
| A — Backend APIs | ✅ مكتمل | 100% |
| B — Auth + Driver Flutter | ⏳ لم يبدأ | 0% |
| C — Central Flutter | ⏳ | 0% |
| D — Branch Flutter | ⏳ | 0% |
| E — Push + QA | ⏳ | 0% |
| **الإجمالي** | | **~20%** |