# Phase C — SMK Logistics Central App

**التاريخ:** 2026-06-05  
**الحالة:** مكتملة (Central Flow) ✅  
**نسبة إنجاز Phase C:** 100%  
**نسبة المشروع الكلي:** ~65%

---

## ملخص

تم تنفيذ **واجهة التوصيل المركزي** بالكامل في تطبيق Flutter `smk_logistics` وربطها بجميع APIs المركزية من Phase A، مع:

- `CentralShell` كامل مع Bottom Navigation
- Provider + Pagination + Pull To Refresh + Error/Loading States + Search Debounce
- إشعارات FCM لنوع `logistics_new_incoming_order`
- CRUD مدراء الفروع + مراقبة السائقين + المحافظات

**BranchShell** لا يزال placeholder — Phase D.

---

## الشاشات المنجزة (Central)

| # | الشاشة | المسار | الحالة |
|---|--------|--------|--------|
| 1 | Central Dashboard | `features/central/dashboard/central_dashboard_screen.dart` | ✅ |
| 2 | Orders (4 tabs) | `features/central/orders/central_orders_screen.dart` | ✅ |
| 3 | Order Details + Timeline | `features/central/orders/central_order_detail_screen.dart` | ✅ |
| 4 | Receive Order | ضمن Order Details | ✅ |
| 5 | Transfer Order | ضمن Order Details (محافظة + فرع + ملاحظات) | ✅ |
| 6 | Governorates Overview | `features/central/governorates/governorates_overview_screen.dart` | ✅ |
| 7 | Branch Managers CRUD | `features/central/branch_managers/` | ✅ |
| 8 | Drivers Monitoring | `features/central/drivers/drivers_monitor_screen.dart` | ✅ |
| 9 | Notifications | `features/central/notifications/central_notifications_screen.dart` | ✅ |
| 10 | Profile + Logout | `features/central/profile/central_profile_screen.dart` | ✅ |
| 11 | Central Shell | `features/central/central_shell.dart` | ✅ |

### تفاصيل Dashboard

- الطلبات الواردة / المستلمة / المحوّلة / المكتملة
- عدد السائقين ومدراء الفروع
- إحصائية حسب المحافظة
- اختصارات: المحافظات، مدراء الفروع، مراقبة السائقين

### تفاصيل Orders Screen

| Tab | API `tab` |
|-----|-----------|
| واردة | `incoming` |
| مستلمة | `received` |
| محوّلة | `transferred` |
| مكتملة | `completed` |

- بحث (debounce 400ms) — رقم الطلب / اسم العميل / الهاتف
- فلترة حسب المحافظة
- فلترة حسب الحالة
- Pagination + infinite scroll

---

## الملفات الجديدة

```
smk_logistics/lib/
├── core/utils/debouncer.dart
├── features/central/
│   ├── central_shell.dart
│   ├── models/central_models.dart
│   ├── providers/central_provider.dart
│   ├── services/central_api_service.dart
│   ├── widgets/central_bottom_nav.dart
│   ├── dashboard/central_dashboard_screen.dart
│   ├── orders/
│   │   ├── central_orders_screen.dart
│   │   └── central_order_detail_screen.dart
│   ├── governorates/governorates_overview_screen.dart
│   ├── branch_managers/
│   │   ├── branch_managers_screen.dart
│   │   └── branch_manager_form_screen.dart
│   ├── drivers/drivers_monitor_screen.dart
│   ├── notifications/central_notifications_screen.dart
│   └── profile/central_profile_screen.dart
```

---

## الملفات المعدّلة

| الملف | التغيير |
|-------|---------|
| `smk_logistics/lib/app.dart` | تسجيل `CentralApiService` + `CentralProvider` |
| `smk_logistics/lib/core/constants/api_endpoints.dart` | endpoints المركزي |
| `smk_logistics/lib/core/push/logistics_push_service.dart` | deep link لطلبات المركز + `logistics_new_incoming_order` |
| `smk_logistics/lib/features/splash/splash_screen.dart` | FCM foreground → `CentralProvider` للدور central |
| `app/Http/Resources/Api/LogisticsOrderResource.php` | `total_weight` |
| `app/Services/Logistics/LogisticsDashboardService.php` | `total_drivers`, `branch_managers` |
| `app/Http/Controllers/Api/Logistics/Central/OrderController.php` | tabs + search + filters + pagination |
| `app/Http/Controllers/Api/Logistics/Central/DriverMonitorController.php` | order counts per driver |

---

## البنية التقنية

| المكوّن | التطبيق |
|---------|---------|
| State | `CentralProvider` (ChangeNotifier) |
| HTTP | `CentralApiService` → Dio |
| Pagination | `PaginationMeta` + infinite scroll |
| Search | `Debouncer` (400ms) |
| Refresh | `RefreshIndicator` على Dashboard / Orders / Lists |
| Errors | `ErrorState` + `LoadingWidget` + `EmptyState` (smk_shared) |
| FCM | `logistics_new_incoming_order` → in-app list + deep link |

---

## APIs المستخدمة

| Method | Endpoint | الاستخدام |
|--------|----------|-----------|
| GET | `/logistics/central/dashboard` | Dashboard stats |
| GET | `/logistics/central/orders?tab=&search=&governorate_id=&status=&page=` | Orders list |
| GET | `/logistics/central/orders/{id}` | Order detail + timeline |
| POST | `/logistics/central/orders/{id}/receive` | Receive from merchant |
| POST | `/logistics/central/orders/{id}/transfer` | Transfer to branch |
| GET | `/logistics/central/governorates` | Governorates |
| GET | `/logistics/central/branches?governorate_id=` | Branches |
| GET/POST/PUT | `/logistics/central/branch-managers` | Branch managers CRUD |
| GET | `/logistics/central/drivers` | Drivers monitoring |

---

## صور الشاشات

> **ملاحظة:** شغّل التطبيق على محاكي/جهاز والتقط لقطات للتوثيق.

```bash
cd smk_logistics
flutter run --dart-define=APP_ENV=dev
```

**حساب اختبار المركزي:**

| Email | Password |
|-------|----------|
| central@smk.iq | 123321001 |

**سينarios للتصوير:**

1. **Login** → توجيه تلقائي إلى `CentralShell`
2. **Dashboard** — بطاقات الطلبات + إحصائيات المحافظات
3. **Orders → واردة** — بحث + فلترة
4. **Order Detail** — بيانات التاجر/العميل/المنتجات/Timeline
5. **Receive** — تأكيد الاستلام → تحديث الحالة
6. **Transfer** — اختيار محافظة + فرع + ملاحظات
7. **Branch Managers** — إضافة/تعديل/تفعيل/تعطيل
8. **Drivers Monitor** — قائمة السائقين مع الحالة
9. **Notifications** — إشعار طلب وارد جديد

---

## نتائج الاختبارات

### Backend (PHPUnit)

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

| الاختبار | النتيجة |
|----------|---------|
| unified logistics login resolves role | ✅ PASS |
| full logistics api lifecycle (receive + transfer + branch notify) | ✅ PASS |
| central read only locations | ✅ PASS |
| device registration for logistics role | ✅ PASS |

**4 tests, 45 assertions — ALL PASS**

### E2E Flow (Central)

| الخطوة | التحقق | النتيجة |
|--------|--------|---------|
| Central Login (`central@smk.iq`) | `role = central` → CentralShell | ✅ API verified |
| Incoming Order tab | `incoming` count > 0 بعد إرسال من التاجر | ✅ API verified |
| Receive | status → `received_by_central_logistics` | ✅ API verified |
| Transfer To Branch | status → `sent_to_branch` + audit transfer | ✅ API verified |
| Dashboard stats update | incoming ↓ received/transferred ↑ | ✅ API verified |
| Branch notification | branch dashboard `incoming = 1` | ✅ API verified |
| Flutter analyze | 0 errors | ✅ PASS |

### FCM

| النوع | السلوك |
|-------|--------|
| `logistics_new_incoming_order` | in-app notification + deep link → `CentralOrderDetailScreen` |

---

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

| Phase | الوصف | الحالة | النسبة |
|-------|--------|--------|--------|
| A | Backend APIs + FCM + Tests | ✅ | 100% |
| B | Driver App UI | ✅ | 100% |
| C | Central App UI | ✅ | 100% |
| D | Branch Manager UI | ⏳ | 0% |
| E | Admin / Web polish | ⏳ | ~30% |

**إجمالي SMK Logistics (Flutter App): ~65%**

---

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

**Branch Logistics Manager UI:**

- Branch Dashboard
- Incoming / Received orders
- Assign driver
- Driver monitoring (branch scope)
- Notifications (`logistics_order_sent_to_branch`)
- Profile + Logout

---

## ملاحظات

1. **Production API** (`api.smkiraq.com`): تأكد من نشر Phase A backend قبل استخدام `APP_ENV=production`.
2. **Dev default**: `api_config.dart` يستخدم `http://10.0.2.2/smk/public/api/v1` للمحاكي Android.
3. **Firebase**: قد يحتاج `flutterfire configure` لتفعيل FCM على `iq.smk.smk_logistics`.