feat: N1d/N2/N3 + قانون فلاتر وإعادة ضبط تطبيق السائق

الباك إند: - تعيين أول أدمن صار يُنشئ المستخدم إن لم يوجد — كان يشترط دخولاً سابقاً، وهي بيضة ودجاجة تمنع الدخول إلى لوحة أي مستأجر جديد أصلاً. - OTP_DEV_MODE كان يفشل مفتوحاً (`!== 'false'`): غياب المتغيّر أو خطأ مطبعي يترك الإنتاج برمز ثابت يفتح كل حساب، ويحرس السحب المالي كذلك. صار `=== 'true'` في الإعداد وفي قارئَيه، مع تحذير عند الإقلاع. - N2: التحقّق من اللوغو عند الرفع (PNG/JPEG · 512+ · مربّع · سقف 5MB) عبر قراءة الترويسة بلا اعتمادية — بدل اكتشاف أيقونة ممطوطة بعد النشر. N3: السكربت يولّد build_config.dart بأعلام const (طبقات docs/22 §1.5)، ويضبط bundle IDs واسم التطبيق والأيقونات/splash، و--build يشغّل Shorebird. فلاتر: - docs/23: قانون مُلزِم للتطبيقين (البنية · Cubit · طبقة الشبكة · الأعلام). - السائق: أُزيل Dart القديم (GetX) مع الإبقاء على الأصيل والإضافات وشهادات التوقيع وShorebird وFirebase الخاص به، وأُعيد هيكلته مطابقاً للراكب. - طبقة الشبكة ترسل x-device-id وتجدّد التوكن عند 401 مرة واحدة فقط. - الحزم موحّدة بين التطبيقين، والـAPI https حصراً في الاثنين. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-18 13:06:46 +03:00
parent 3ab74a13a8
commit de4bbd00ac
271 changed files with 1333 additions and 81068 deletions
@@ -1,133 +0,0 @@
-إليك التوثيق التقني العميق (Deep Technical Documentation) لتطبيق السائق (Driver App) في منصة **انطلق (Intaleq)**. تم إعداد هذا التقرير بناءً على تحليل الكود المصدري، مع التركيز على البنية التحتية، تدفق البيانات، والخدمات الخلفية.
-
---
-
-# 📘 Intaleq Driver App - Technical Documentation
-
-**الإصدار:** 1.0
-**المعمارية:** MVC using GetX
-**اللغة:** Dart (Flutter)
-**إدارة الحالة:** GetX (Reactive State Management)
-
---
-
-## 1. 🔐 التسجيل والتحقق (Onboarding & KYC)
-
-نظام التسجيل في تطبيق السائق معقد لأنه يتطلب التحقق من الهوية والأهلية قبل السماح للسائق بالعمل.
-
-### أ. دورة تسجيل السائق (`Driver Registration Flow`)
-
- **المسار:** `lib/controller/auth/captin/register_captin_controller.dart`
- **الآلية:**
-  1.  **التحقق من الهاتف:** يتم استخدام `SmsEgyptController` أو `PhoneAuthHelper` لإرسال OTP. يتم التحقق مما إذا كان الرقم مسجلاً مسبقاً عبر `checkPhoneNumberISVerfiedDriver`.
-  2.  **إدخال البيانات الأساسية:** (الاسم، البريد، تاريخ الميلاد) يتم جمعها في `RegistrationView`.
-  3.  **إنشاء الحساب:** يتم استدعاء `signUpCaptin.php` لإنشاء سجل أولي للسائق بحالة `yet` (بانتظار التوثيق).
-
-### ب. نظام رفع الوثائق والمعالجة بالذكاء الاصطناعي (AI & OCR)
-
- **المسؤوليـة:** `lib/controller/functions/gemeni.dart` (الكلاس `AI`).
- **العملية التقنية:**
-  1.  **التقاط الصورة:** يتم استخدام `ImagePicker` و `ImageCropper` لضمان جودة الصورة.
-  2.  **الضغط:** يتم ضغط الصورة باستخدام `FlutterImageCompress` لتقليل استهلاك البيانات.
-  3.  **التحليل (AI Extraction):**
-      - يتم رفع الصورة إلى `uploadImageToAi`.
-      - يتم تمرير `prompt` هندسي دقيق لنموذج الذكاء الاصطناعي (مثل Gemini أو نماذج OCR مخصصة) لاستخراج البيانات كـ JSON (مثل: `vin`, `make`, `model`, `plate_number`).
-  4.  **التعبئة التلقائية:** البيانات المستخرجة تُعبأ تلقائياً في `RegisterCaptainController` ليقوم السائق بمراجعتها فقط، مما يقلل أخطاء الإدخال اليدوي.
-
-### ج. حالة "بانتظار الموافقة" (`Pending Approval`)
-
- **المسؤوليـة:** `LoginDriverController` و `DriverVerificationScreen`.
- **المنطق:**
-  - عند تسجيل الدخول، يتحقق النظام من الحقل `status` و `is_verified` في استجابة الـ login.
-  - إذا كانت الحالة `yet`، يتم توجيه السائق إجبارياً إلى شاشة `DriverVerificationScreen` التي تعرض رسالة "Your Application is Under Review" وتمنع الوصول للخريطة.
-
---
-
-## 2. 📡 الخدمات الخلفية والتتبع (Background Services & Tracking)
-
-يعتمد التطبيق على نظام تتبع ذكي (Batch Tracking) لتقليل استهلاك البطارية والبيانات مع الحفاظ على الدقة.
-
-### أ. محرك الموقع (`LocationController`)
-
- **المسار:** `lib/controller/functions/location_controller.dart`.
- **آلية العمل في الخلفية:**
-  1.  **التهيئة:** يتم تفعيل `location.enableBackgroundMode(enable: true)` لضمان استمرار الخدمة عند إغلاق الشاشة.
-  2.  **التخزين المؤقت (Buffering):** بدلاً من إرسال كل نقطة GPS للسيرفر، يتم تخزين النقاط في قائمة محلية `_trackBuffer`.
-  3.  **التصفية الذكية (Smart Filtering):** لا يتم تسجيل النقطة إلا إذا تحرك السائق مسافة معينة (`onMoveMetersNormal = 15m`) أو مرّ وقت محدد (`30 ثانية`) لضمان تسجيل التوقفات.
-
-### ب. إرسال البيانات (Batch Upload)
-
- يوجد مؤقت `_uploadTimer` يعمل كل **دقيقتين** (في الوضع العادي).
- يقوم هذا المؤقت بجمع كل النقاط في `_trackBuffer`، تحويلها لـ JSON، وإرسالها بطلب واحد `POST` إلى `add_batch.php`. هذا يقلل الحمل على السيرفر بنسبة كبيرة جداً.
-
-### ج. وضع توفير الطاقة (Power Saving Mode)
-
- يراقب التطبيق حالة البطارية عبر `BatteryNotifier`. إذا انخفضت عن 20%، يتم تقليل معدل التحديث (تسجيل كل 6 ثواني ورفع كل 4 دقائق).
-
---
-
-## 3. 🔔 استقبال الطلبات (Request Handling)
-
-### أ. النافذة العائمة (`Overlay Window`)
-
- **التقنية:** `flutter_overlay_window`.
- **المسار:** `lib/main.dart` (Background Handler) و `lib/views/home/Captin/orderCaptin/order_over_lay.dart`.
- **كيفية العمل:**
-  1.  عند وصول إشعار FCM من نوع `Order` والتطبيق في الخلفية، يتم استدعاء `backgroundMessageHandler`.
-  2.  يتم التحقق من إذن الرسم فوق التطبيقات. إذا مُنح، يتم استدعاء `FlutterOverlayWindow.showOverlay` وتمرير بيانات الطلب (`DriverList`).
-  3.  ملف `order_over_lay.dart` هو تطبيق Flutter مصغر يعمل بشكل مستقل فوق التطبيقات الأخرى. يحتوي على منطق قبول/رفض خاص به ويتصل بالسيرفر مباشرة.
-
-### ب. منطق القبول والرفض (`OrderRequestController`)
-
- **المسار:** `lib/controller/home/captin/order_request_controller.dart`.
- **العداد التنازلي:** يتم تشغيل `startTimer` لمدة 15-20 ثانية. إذا انتهى الوقت، يتم رفض الطلب تلقائياً.
- **القبول:** عند الضغط على "قبول"، يتم استدعاء `updateStausFromSpeed.php` لحجز الطلب ومنع تضارب السائقين (Race Condition).
-
---
-
-## 4. 🚗 تنفيذ الرحلة (Trip Execution Workflow)
-
-يدير `MapDriverController` دورة حياة الرحلة بالكامل.
-
-### أ. الذهاب للراكب (`Going to Passenger`)
-
- عند قبول الطلب، تتغير الحالة إلى `Apply`.
- يتم عرض موقع الراكب على الخريطة ورسم المسار باستخدام `getRoute` (يعتمد على OSRM أو Google Directions).
- يمكن للسائق فتح خرائط جوجل الخارجية عبر `openGoogleMapFromDriverToPassenger`.
-
-### ب. الوصول (`Arrived`)
-
- **الزر:** `I Arrive`.
- **المنطق البرمجي:** يتحقق الكود أولاً من المسافة بين السائق والراكب. إذا كانت أقل من **140 متر** (`distance < 140`)، يتم إرسال إشعار `Hi ,I Arrive your site` للراكب وتفعيل عداد الانتظار.
-
-### ج. بدء وإنهاء الرحلة
-
- **البدء (`Begin`):** يطلب النظام تأكيداً "Is the Passenger in your Car?". عند الموافقة، يتم إرسال `status: Begin` للسيرفر ويبدأ عداد الرحلة الفعلي `rideIsBeginPassengerTimer`.
- **الإنهاء (`Finish`):**
-  - يتم حساب المسافة المقطوعة والوقت.
-  - يتم استدعاء `finishRideFromDriver1` التي تقوم بإرسال طلبين متزامنين: تحديث حالة الرحلة وتنفيذ عملية الدفع `process_ride_payments.php`.
-  - يتم تحويل السائق لصفحة تقييم الراكب `RatePassenger`.
-
---
-
-## 5. 💰 المحفظة والأرباح (Wallet & Earnings)
-
- **المسار:** `lib/controller/home/payment/captain_wallet_controller.dart`.
-
-### أ. عرض الرصيد والديون
-
- يتم جلب البيانات المالية عبر `getCaptainWalletFromRide` (للأرباح من الرحلات) و `getCaptainWalletFromBuyPoints` (للنقاط المشتراة).
- **الحظر المالي:** إذا انخفض رصيد النقاط عن حد معين (مثل -300)، يتم منع السائق من استقبال الطلبات ويظهر زر `Charge your Account`.
-
-### ب. آلية الشحن
-
- يتم دعم بوابات دفع متعددة مثل **Syriatel Cash** و **MTN Cash**.
- عند الشحن، يتم إنشاء `Invoice` وانتظار الـ Callback أو التحقق الدوري (`polling`) من حالة الدفع.
-
---
-
-## 6. ⚙️ الإعدادات والميزات الإضافية
-
- **إعدادات السيارة:** تدار عبر `DriverCarController` و `CarsInsertingPage`، حيث يمكن إضافة سيارات جديدة ورفع وثائقها.
- **اللغة:** `LocaleController` يدير التبديل بين العربية والإنجليزية ويحفظ التفضيل في `GetStorage`.
- **التقييم:** يتم جلب تقييم السائق عبر `getDriverRate` وعرضه في القائمة الجانبية أو الرأسية.