134 lines
9.1 KiB
Markdown
134 lines
9.1 KiB
Markdown
إليك التوثيق التقني العميق (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` وعرضه في القائمة الجانبية أو الرأسية.
|