# Phase B — SMK Logistics Driver App

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

---

## ملخص

تم إنشاء تطبيق Flutter **`smk_logistics`** (اسم العرض: **SMK Logistics**) وفق معايير `smk_customer` / `smk_merchant` / `smk_shared`، مع:

- مصادقة موحدة + Role Router
- **DriverShell** كامل (100%)
- CentralShell / BranchShell — placeholders فقط (Phase C / D)
- ربط كامل بـ APIs السائق + FCM + Secure Storage

---

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

| # | الشاشة | المسار | الحالة |
|---|--------|--------|--------|
| 1 | Splash | `features/splash/splash_screen.dart` | ✅ |
| 2 | Login (موحد + تذكرني) | `features/driver/auth/logistics_login_screen.dart` | ✅ |
| 3 | Role Router | `core/routing/role_router.dart` | ✅ |
| 4 | Driver Dashboard | `features/driver/dashboard/driver_dashboard_screen.dart` | ✅ |
| 5 | Orders List (نشطة/مسلّمة/فاشلة) | `features/driver/orders/driver_orders_screen.dart` | ✅ |
| 6 | Order Details | `features/driver/orders/order_detail_screen.dart` | ✅ |
| 7 | Call Customer | `url_launcher` tel: | ✅ |
| 8 | Open Map | Google Maps search | ✅ |
| 9 | Start Delivery | API action | ✅ |
| 10 | Deliver Order | API action | ✅ |
| 11 | Upload Proof Photo | camera + gallery | ✅ |
| 12 | Fail Delivery | dialog + API | ✅ |
| 13 | Return Order | API action | ✅ |
| 14 | Notifications | in-app list + FCM | ✅ |
| 15 | Profile + Logout | `features/driver/profile/driver_profile_screen.dart` | ✅ |

### Placeholders (خارج نطاق Phase B)

| الشاشة | الملف | ملاحظة |
|--------|-------|--------|
| CentralShell | `features/central/central_shell.dart` | Phase C |
| BranchShell | `features/branch/branch_shell.dart` | Phase D |

---

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

> **ملاحظة:** يُنصح بتشغيل التطبيق على جهاز حقيقي أو محاكي والتقاط لقطات بعد الاختبار.

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

**حساب اختبار السائق:**

| Email | Password |
|-------|----------|
| driver.dhiqar@smk.iq | 123321001 |

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

1. **Splash + Login** — شاشة البداية ونموذج الدخول
2. **Dashboard** — بطاقات: مسلّم / فاشل / اليوم / الشهر
3. **Orders List** — تبويب نشطة
4. **Order Detail** — أزرار اتصال / خريطة / بدء التوصيل
5. **Deliver Flow** — معاينة صورة الإثبات قبل التسليم
6. **Fail Flow** — حوار سبب التعذر

---

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

| المكوّن | التطبيق |
|---------|---------|
| State | Provider (`LogisticsAuthProvider`, `DriverProvider`) |
| HTTP | Dio + `LogisticsDioClient` (Bearer + 401 session expiry) |
| Token | `SecureStorage` (smk_shared) — Remember login via `SharedPreferences` |
| Token Refresh | `GET /logistics/auth/me` on bootstrap + app resume |
| Auth Guard | `requireAuth()`, session expired → login |
| API Env | `APP_ENV=production` → `https://api.smkiraq.com/api/v1` |
| FCM | `LogisticsPushService` — foreground, background, deep link → order |
| Device | `POST /logistics/devices/register` + unregister on logout |

---

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

| Method | Endpoint | الاستخدام |
|--------|----------|-----------|
| POST | `/logistics/auth/login` | Login |
| POST | `/logistics/auth/logout` | Logout |
| GET | `/logistics/auth/me` | Bootstrap / refresh |
| POST | `/logistics/devices/register` | FCM token |
| POST | `/logistics/devices/unregister` | Logout |
| GET | `/logistics/driver/dashboard` | Dashboard stats |
| GET | `/logistics/driver/orders?tab=` | Orders list |
| GET | `/logistics/driver/orders/{id}` | Detail + timeline |
| POST | `/logistics/driver/orders/{id}/start` | Start delivery |
| POST | `/logistics/driver/orders/{id}/deliver` | Deliver (+ multipart proof) |
| POST | `/logistics/driver/orders/{id}/fail` | Fail delivery |
| POST | `/logistics/driver/orders/{id}/return` | Return order |

---

## الملفات الجديدة (أبرزها)

```
smk_logistics/
├── lib/
│   ├── app.dart
│   ├── main.dart
│   ├── firebase_options.dart
│   ├── core/
│   │   ├── constants/api_config.dart
│   │   ├── constants/api_endpoints.dart
│   │   ├── network/logistics_dio_client.dart
│   │   ├── push/logistics_push_service.dart
│   │   ├── routing/role_router.dart
│   │   └── storage/login_preferences.dart
│   └── features/
│       ├── splash/splash_screen.dart
│       ├── central/central_shell.dart          (placeholder)
│       ├── branch/branch_shell.dart            (placeholder)
│       └── driver/
│           ├── auth/
│           ├── dashboard/
│           ├── orders/
│           ├── notifications/
│           ├── profile/
│           ├── services/
│           ├── models/
│           ├── widgets/driver_bottom_nav.dart
│           └── driver_shell.dart
├── integration_test/driver_flow_test.dart
├── android/ (iq.smk.smk_logistics)
└── config/env/
```

---

## الملفات المعدّلة (monorepo)

| الملف | التغيير |
|-------|---------|
| `melos.yaml` | إضافة `smk_logistics` |
| `scripts/build-logistics-production.bat` | سكربت بناء APK |

---

## اختبار E2E

### Automated

```bash
cd smk_logistics
flutter test integration_test/driver_flow_test.dart
```

يتحقق من: تشغيل التطبيق وظهور Splash.

### Manual (Production API)

**Flow A — Deliver + Proof**

```
Login → Assigned Order → Start Delivery → Upload Proof → Deliver
```

**Flow B — Fail**

```
Login → Assigned Order → Start Delivery → Fail Delivery
```

---

## Firebase

- نفس مشروع Firebase: `smk-platform-595f9`
- Package Android: `iq.smk.smk_logistics`
- Channel: `smk_logistics_default`
- app_role للسائق: `logistics_driver`

**خطوة موصى بها:** تسجيل التطبيق رسمياً في Firebase Console ثم:

```bash
flutterfire configure --project=smk-platform-595f9
```

---

## التحليل الثابت

```
flutter analyze → 0 errors (info warnings only)
```

---

## المشاكل المكتشفة

| المشكلة | الحالة |
|---------|--------|
| Gradle file lock على Windows أثناء build متكرر | بيئة — أعد `flutter build apk` بعد إغلاق عمليات Gradle |
| Firebase app id مؤقت (مشاركة merchant android id) | يُفضّل `flutterfire configure` لتطبيق logistics مستقل |
| Central/Branch UI | متعمد — Phase C/D |

---

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

1. CentralShell كامل: Dashboard + Orders + Transfer
2. ربط APIs المركزي
3. FCM للمركزي (`logistics_central`)

---

## نسبة الإنجاز

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