intaleq_driver/lib/readme.md

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