إليك التقرير الفني الشامل لمشروع **Intaleq Passenger App**، مكتوباً بصيغة توثيق تقني (Technical Documentation) موجهة لفريق التطوير، بناءً على تحليل الكود المصدري.

---

# 📘 Intaleq Passenger App - Technical Documentation Report

**Prepared by:** CTO Office
**Target Audience:** Mobile Engineering Team
**Version:** 1.0

---

## 1. 🚀 بداية التشغيل (Initialization & Startup)

تعتمد مرحلة الإقلاع على تهيئة الخدمات الأساسية قبل عرض واجهة المستخدم لضمان استقرار التطبيق.

### أ. نقطة الدخول (`main.dart`)

- **المسار:** `lib/main.dart`
- **الوظيفة:**
  - يستخدم `runZonedGuarded` لالتقاط الأخطاء العامة (Global Error Handling) وإرسالها للسيرفر عبر `CRUD.addError`.
  - **تهيئة الخدمات:** يتم تهيئة `GetStorage` (للتخزين المحلي)، `WakelockPlus` (لمنع انطفاء الشاشة)، و `Firebase` (للإشعارات) قبل استدعاء `runApp`.
  - **إعدادات التوجيه:** يتم تحديد الاتجاه العمودي فقط (`portraitUp`) للجهاز.
  - **حقن التبعيات (DI):** يتم استدعاء `AppBindings` كـ `initialBinding` لتهيئة المتحكمات الأساسية.

### ب. إدارة التبعيات (`AppBindings`)

- **المسار:** `lib/app_bindings.dart`
- **الآلية:**
  - يتم حقن `LocaleController` و `DeepLinkController` بشكل دائم (`permanent: true`) لضمان تواجدهم طوال دورة حياة التطبيق.
  - يتم استخدام `Get.lazyPut` مع `fenix: true` للمتحكمات الأخرى (مثل `LoginController`) ليتم إنشاؤها عند الحاجة وإعادة إنشائها إذا تم التخلص منها.

### ج. شاشة البداية (`Splash Screen`)

- **المسار:** `lib/splash_screen_page.dart` و `lib/controller/home/splash_screen_controlle.dart`
- **المنطق:**
  - يتم عرض انيميشن باستخدام `AnimatedTextKit` و `FadeTransition`.
  - **العمليات الخلفية:** يقوم `SplashScreenController` بتنفيذ `_initializeBackgroundServices` لتهيئة خدمات التشفير (`EncryptionHelper`) والإشعارات.
  - **التوجيه الذكي:** تتحقق الدالة `_performNavigationLogic` من وجود بيانات المستخدم في `BoxName`. إذا كان المستخدم مسجلاً ومفعلاً (`isVerified == '1'`)، يتم توجيهه تلقائياً للصفحة الرئيسية، وإلا يتم توجيهه لصفحة الدخول أو الترحيب (`OnBoarding`).

---

## 2. 🔐 دورة المصادقة (Authentication Cycle)

يعتمد النظام على مصادقة هجينة (Token-based + Social Auth) مع تخزين آمن.

### أ. التسجيل والدخول (`Sign Up & Login`)

- **المسار:** `lib/controller/auth/login_controller.dart` و `register_controller.dart`
- **الآلية:**
  - **Social Login:** يتم استخدام `GoogleSignInHelper` أو `AuthController` (Apple). عند النجاح، يتم إرسال التوكن للسيرفر للتحقق.
  - **Credentials:** في حالة الدخول التقليدي، يتم استدعاء `loginUsingCredentials` التي تتحقق من البيانات عبر API.
  - **التحقق (Verification):** إذا رد السيرفر بأن الحساب غير مفعل، يتم تحويل المستخدم لصفحة `PhoneNumberScreen` للتحقق عبر OTP.

### ب. التحقق عبر الهاتف (OTP)

- **المسار:** `lib/controller/auth/otp_controller.dart`
- **المنطق:** يستخدم كلاس `PhoneAuthHelper` لإرسال OTP (غالباً عبر WhatsApp أو SMS حسب الدولة) ثم التحقق منه عبر الـ Endpoint `verifyOtp.php`.

### ج. إدارة الجلسة والتوكن

- **المخزن:** يتم تخزين الـ JWT في `GetStorage` تحت مفتاح `BoxName.jwt`.
- **التشفير:** يتم استخدام `EncryptionHelper` لتشفير البيانات الحساسة محلياً.
- **التجديد التلقائي:** في كلاس `CRUD`، إذا رد السيرفر بـ `401 Token expired`، يتم استدعاء `getJWT` تلقائياً لتجديد التوكن دون تسجيل خروج المستخدم.

---

## 3. 🗺️ الشاشة الرئيسية والخريطة (Home & Map Logic)

تعتبر `MapPagePassenger` هي الواجهة المركزية التي تديرها `MapPassengerController`.

### أ. تحميل الخريطة والموقع

- **المسار:** `lib/controller/home/map_passenger_controller.dart`
- **المتحكم:** `MapPassengerController`
- **المنطق:**
  - يتم استخدام `location.getLocation()` لجلب موقع الراكب الحالي عند البدء.
  - يتم تحديد المنطقة الجغرافية (سوريا، مصر، الأردن) عبر دالة `getLocationArea` التي تفحص وقوع الإحداثيات داخل مضلعات (Polygons) محددة مسبقاً.

### ب. السيارات القريبة (Real-time Updates)

- **الدالة:** `getCarsLocationByPassengerAndReloadMarker`.
- **الآلية:** تقوم بطلب API (مثل `getSpeed.php`) بناءً على نوع السيارة المختار (Speed, Comfort, Lady). يتم تحديث الـ `markers` على الخريطة، ويتم استخدام دالة `_smoothlyUpdateMarker` لتحريك أيقونة السيارة بسلاسة بدلاً من القفز المفاجئ.

### ج. القائمة الجانبية (Drawer)

- **المسار:** `lib/views/home/map_widget.dart/map_menu_widget.dart`
- **المتحكم:** `MyMenuController`
- **الوظيفة:** تدير حالة القائمة (مفتوحة/مغلقة) وتوفر روابط لصفحات الملف الشخصي، المحفظة، والسجل.

---

## 4. 🚕 دورة طلب الرحلة (Ride Request Flow)

هذا هو الجزء الأكثر تعقيداً في التطبيق، حيث يدار عبر آلة حالة (State Machine).

### أ. اختيار الوجهة ورسم المسار

- **المسار:** `lib/controller/home/map_passenger_controller.dart`
- **الوظيفة:** `getDirectionMap`.
- **المنطق:**
  - يتم إرسال نقطة البداية والنهاية إلى خدمة التوجيه (OSRM/Google).
  - يتم استلام نقاط المسار (Polyline Points) وفك تشفيرها في `Isolate` منفصل (`decodePolylineIsolate`) لتحسين الأداء.
  - يتم رسم المسار على الخريطة وضبط الكاميرا لتشمل النقطتين.

### ب. اختيار نوع السيارة والسعر

- **المسار:** `lib/views/home/map_widget.dart/car_details_widget_to_go.dart`
- **الآلية:** يتم عرض قائمة أنواع السيارات (Fixed Price, Comfort, etc.). عند الاختيار، يتم حساب السعر المتوقع بناءً على المسافة والوقت والتعرفة الخاصة بكل نوع والمخزنة في المتحكم (`totalPassengerSpeed`, `totalPassengerComfort`).

### ج. إرسال الطلب (البحث عن سائق)

- **الدالة:** `startSearchingForDriver`.
- **العمليات:**
  1.  تغيير الحالة إلى `RideState.searching`.
  2.  استدعاء `postRideDetailsToServer` لإنشاء سجل الرحلة في قاعدة البيانات.
  3.  تشغيل المؤقت `_startMasterTimer` الذي يدير دورة البحث.
  4.  يتم توسيع نطاق البحث (Radius) تدريجياً (مراحل: 2400م -> 3000م -> 3100م) عبر `_findAndNotifyNearestDrivers`.

### د. انتظار السائق

- **الواجهة:** `SearchingCaptainWindow`.
- **المنطق:** يظهر رادار بحث. يتم التحقق دورياً (`Polling`) من حالة الرحلة في السيرفر. إذا مر الوقت المحدد (90 ثانية) دون قبول، يظهر خيار "زيادة السعر" (`_showIncreaseFeeDialog`).

---

## 5. 🚘 أثناء الرحلة (Active Ride)

يتم إدارة هذه المرحلة عبر تحديثات الحالة في `_handleRideState`.

### أ. قبول السائق

- **الحدث:** وصول إشعار FCM أو تغيير الحالة في السيرفر إلى `Apply`.
- **الإجراء:** يتم استدعاء `processRideAcceptance`.
  - يتم جلب بيانات السائق وموقعه.
  - يتم تفعيل تتبع السائق `startTimerFromDriverToPassengerAfterApplied`.
  - تتغير الواجهة لعرض معلومات السائق والوقت المقدر للوصول.

### ب. بدء الرحلة وميزات الأمان

- **بدء الرحلة:** عند وصول حالة `Begin`، يتم استدعاء `processRideBegin`.
- **SOS:** زر الاستغاثة يستدعي `makePhoneCall` مع رقم الشرطة أو جهة اتصال الطوارئ المخزنة.
- **مشاركة الرحلة:** الدالة `shareTripWithFamily` تولد رابط تتبع مشفر وترسله عبر واتساب.
- **تسجيل الصوت:** يتم استخدام `AudioRecorderController` لتسجيل ما يدور في الرحلة لأغراض الأمان.

### ج. إلغاء الرحلة

- **الدالة:** `cancelRide`.
- **المنطق:**
  - يتم إرسال طلب `cancel` للسيرفر لتحديث حالة الرحلة.
  - يتم إرسال إشعار للسائق بالإلغاء.
  - يتم تصفير الواجهة والعودة للخريطة.

---

## 6. 🏁 ما بعد الرحلة (Post-Ride)

### أ. شاشة الدفع

- **المسار:** `lib/controller/payment/payment_controller.dart`
- **المنطق:**
  - يتم الخصم من المحفظة (`addPassengerWallet`) أو الدفع النقدي.
  - يتم التعامل مع بوابات الدفع الخارجية (مثل Paymob, Stripe) إذا اختار العميل الدفع الإلكتروني.

### ب. التقييم

- **المسار:** `lib/views/Rate/rate_captain.dart` و `RateController`.
- **الآلية:** يقوم الراكب باختيار عدد النجوم وإضافة تعليق. يتم إرسال البيانات عبر `addRateToDriver`.

### ج. تقديم الشكاوى

- **المسار:** `lib/views/home/profile/complaint_page.dart`
- **المتحكم:** `ComplaintController`.
- **الميزة:** يمكن للراكب تسجيل رسالة صوتية وإرفاقها مع الشكوى، ثم يتم إرسالها للسيرفر عبر `submitComplaintToServer`.

---

## 7. ⚙️ الإعدادات والملف الشخصي

### أ. تعديل البيانات

- **المسار:** `lib/views/home/profile/passenger_profile_page.dart`.
- **المتحكم:** `ProfileController`.
- يسمح بتعديل الاسم، الجنس، ورقم الطوارئ.

### ب. المحفظة

- **المسار:** `lib/views/home/my_wallet/passenger_wallet.dart`.
- يعرض الرصيد الحالي وسجل المعاملات (`PassengerWalletHistoryController`).

### ج. اللغة

- **المتحكم:** `LocaleController`.
- يقوم بتغيير لغة التطبيق وتحديث `Get.updateLocale` وحفظ التفضيل في التخزين المحلي.