Initial V2 commit 4

app/Models/CarLocation.php

@@ -2,6 +2,17 @@
 namespace App\Models;
 use Illuminate\Database\Eloquent\Model;
 
+/**
+ * نموذج موقع السيارة (CarLocation Model)
+ * 
+ * الغرض من الملف:
+ * تتبع الموقع الجغرافي الحي للسائقين على الخريطة.
+ * 
+ * كيفية العمل:
+ * 1. يرتبط بجدول (car_locations) في قاعدة بيانات التتبع (tracking).
+ * 2. يخزن خطوط الطول والعرض (Latitude & Longitude) والسرعة والاتجاه.
+ * 3. يستخدم لتحديث خريطة الراكب بمكان السائق في الوقت الفعلي.
+ */
 class CarLocation extends Model
 {
     protected $connection = 'tracking';

app/Models/CarRegistration.php

@@ -2,6 +2,17 @@
 namespace App\Models;
 use Illuminate\Database\Eloquent\Model;
 
+/**
+ * نموذج تسجيل السيارة (CarRegistration Model)
+ * 
+ * الغرض من الملف:
+ * إدارة بيانات المركبات المسجلة في النظام والتابعة للسائقين.
+ * 
+ * كيفية العمل:
+ * 1. يرتبط بجدول (CarRegistration) في قاعدة البيانات الأساسية.
+ * 2. يخزن تفاصيل السيارة مثل: رقم اللوحة، الموديل، السنة، واللون.
+ * 3. يحتوي على حقول مشفرة مثل رقم اللوحة لحمايتها من الوصول غير المصرح به.
+ */
 class CarRegistration extends Model
 {
     protected $connection = 'primary';

app/Models/Driver.php

@@ -5,10 +5,16 @@ namespace App\Models;
 use Illuminate\Database\Eloquent\Model;
 
 /**
- * Driver Model (Primary DB)
+ * نموذج السائق (Driver Model)
  * 
- * Note: Primary key is `idn` (auto-increment), but the business ID is `id` (varchar).
- * All endpoints use `id` (varchar) for lookups, not `idn`.
+ * الغرض من الملف:
+ * إدارة بيانات السائقين (الكباتن) في النظام.
+ * 
+ * كيفية العمل:
+ * 1. يرتبط بجدول (driver) في قاعدة البيانات الأساسية (primary).
+ * 2. يحتوي على قائمة بالحقول المشفرة (ENCRYPTED_FIELDS) التي يتم تخزينها بشكل آمن وتحتاج لفك تشفير عند العرض.
+ * 3. يدير العلاقات الكثيرة للسائق مثل: السيارة، المستندات، التقييمات، الموقع الحالي، والصورة الشخصية.
+ * 4. يوفر دوال مساعدة مثل حساب متوسط التقييم (getAverageRating).
  */
 class Driver extends Model
 {

app/Models/DriverDocument.php

@@ -2,6 +2,16 @@
 namespace App\Models;
 use Illuminate\Database\Eloquent\Model;
 
+/**
+ * نموذج مستندات السائق (DriverDocument Model)
+ * 
+ * الغرض من الملف:
+ * إدارة الملفات والمستندات الورقية التي يرفعها السائقون (مثل رخصة القيادة، الهوية).
+ * 
+ * كيفية العمل:
+ * 1. يرتبط بجدول (driver_documents) في قاعدة البيانات الأساسية.
+ * 2. يخزن نوع المستند ورابط الصورة أو الملف وتاريخ الرفع.
+ */
 class DriverDocument extends Model {
     protected $connection = 'primary';
     protected $table = 'driver_documents';

app/Models/DriverGift.php

@@ -2,6 +2,16 @@
 namespace App\Models;
 use Illuminate\Database\Eloquent\Model;
 
+/**
+ * نموذج هدايا السائق (DriverGift Model)
+ * 
+ * الغرض من الملف:
+ * تتبع الهدايا أو المكافآت التي يحصل عليها السائقون.
+ * 
+ * كيفية العمل:
+ * 1. يرتبط بجدول (driver_gifts) في قاعدة البيانات الأساسية.
+ * 2. يخزن وصف الهدية، تاريخها، وما إذا تم استلامها أم لا.
+ */
 class DriverGift extends Model {
     protected $connection = 'primary';
     protected $table = 'driver_gifts';

app/Models/DriverHealthAssurance.php

@@ -2,6 +2,16 @@
 namespace App\Models;
 use Illuminate\Database\Eloquent\Model;
 
+/**
+ * نموذج التأمين الصحي للسائق (DriverHealthAssurance Model)
+ * 
+ * الغرض من الملف:
+ * إدارة معلومات التأمين الصحي الخاصة بالسائقين.
+ * 
+ * كيفية العمل:
+ * 1. يرتبط بجدول (driver_health_assurance) في قاعدة البيانات الأساسية.
+ * 2. يخزن ما إذا كان السائق مؤمناً عليه واسم شركة التأمين.
+ */
 class DriverHealthAssurance extends Model {
     protected $connection = 'primary';
     protected $table = 'driver_health_assurance';

app/Models/DriverOrder.php

@@ -2,6 +2,16 @@
 namespace App\Models;
 use Illuminate\Database\Eloquent\Model;
 
+/**
+ * نموذج طلبات السائق (DriverOrder Model)
+ * 
+ * الغرض من الملف:
+ * تسجيل الطلبات (الرحلات) التي تم إرسالها لسائق معين وحالتها (قبول/رفض).
+ * 
+ * كيفية العمل:
+ * 1. يرتبط بجدول (driver_orders) في قاعدة البيانات الأساسية.
+ * 2. يربط بين السائق (driver_id) ومعرف الرحلة (order_id).
+ */
 class DriverOrder extends Model {
     protected $connection = 'primary';
     protected $table = 'driver_orders';

app/Models/DriverToken.php

@@ -2,6 +2,16 @@
 namespace App\Models;
 use Illuminate\Database\Eloquent\Model;
 
+/**
+ * نموذج رمز السائق (DriverToken Model)
+ * 
+ * الغرض من الملف:
+ * تخزين رموز التنبيهات (FCM Tokens) الخاصة بالسائقين لإرسال الإشعارات لهواتفهم.
+ * 
+ * كيفية العمل:
+ * 1. يرتبط بجدول (driverToken) في قاعدة البيانات الأساسية.
+ * 2. يخزن الرمز المشفر (Token) ومعرف السائق وبصمة الجهاز (Fingerprint).
+ */
 class DriverToken extends Model
 {
     protected $connection = 'primary';

app/Models/ImageProfileCaptain.php

@@ -2,6 +2,16 @@
 namespace App\Models;
 use Illuminate\Database\Eloquent\Model;
 
+/**
+ * نموذج الصورة الشخصية للسائق (ImageProfileCaptain Model)
+ * 
+ * الغرض من الملف:
+ * إدارة الصور الشخصية (Profile Pictures) الخاصة بالسائقين.
+ * 
+ * كيفية العمل:
+ * 1. يرتبط بجدول (imageProfileCaptain) في قاعدة البيانات الأساسية.
+ * 2. يخزن اسم ملف الصورة ورابط الوصول إليها وتاريخ الرفع.
+ */
 class ImageProfileCaptain extends Model {
     protected $connection = 'primary';
     protected $table = 'imageProfileCaptain';

app/Models/Passenger.php

@@ -4,6 +4,18 @@ namespace App\Models;
 
 use Illuminate\Database\Eloquent\Model;
 
+/**
+ * نموذج الراكب (Passenger Model)
+ * 
+ * الغرض من الملف:
+ * إدارة بيانات الركاب المستخدمين للتطبيق.
+ * 
+ * كيفية العمل:
+ * 1. يرتبط بجدول (passengers) في قاعدة البيانات الأساسية.
+ * 2. يستخدم معرّفاً نصياً (String ID) كمفتاح أساسي بدلاً من الأرقام المتسلسلة.
+ * 3. يحتوي على قائمة بالحقول المشفرة لضمان خصوصية بيانات الركاب.
+ * 4. يدير علاقات الراكب مع: المحفظة المباشرة، الرحلات، والتقييمات.
+ */
 class Passenger extends Model
 {
     protected $connection = 'primary';

app/Models/PassengerToken.php

@@ -2,6 +2,16 @@
 namespace App\Models;
 use Illuminate\Database\Eloquent\Model;
 
+/**
+ * نموذج رمز الراكب (PassengerToken Model)
+ * 
+ * الغرض من الملف:
+ * تخزين رموز التنبيهات (FCM Tokens) الخاصة بالركاب لإرسال الإشعارات لهواتفهم.
+ * 
+ * كيفية العمل:
+ * 1. يرتبط بجدول (tokens) في قاعدة البيانات الأساسية.
+ * 2. يخزن الرمز المشفر وبصمة الجهاز لضمان وصول التنبيهات للجهاز الصحيح.
+ */
 class PassengerToken extends Model
 {
     protected $connection = 'primary';

app/Models/PassengerWallet.php

@@ -2,6 +2,16 @@
 namespace App\Models;
 use Illuminate\Database\Eloquent\Model;
 
+/**
+ * نموذج محفظة الراكب (PassengerWallet Model)
+ * 
+ * الغرض من الملف:
+ * إدارة الرصيد المالي للركاب داخل التطبيق.
+ * 
+ * كيفية العمل:
+ * 1. يرتبط بجدول (passengerWallet) في قاعدة البيانات الأساسية.
+ * 2. يتبع الرصيد الحالي للراكب ويسمح بعمليات الشحن أو الخصم.
+ */
 class PassengerWallet extends Model {
     protected $connection = 'primary';
     protected $table = 'passengerWallet';

app/Models/RatingDriver.php

@@ -2,6 +2,16 @@
 namespace App\Models;
 use Illuminate\Database\Eloquent\Model;
 
+/**
+ * نموذج تقييم السائق (RatingDriver Model)
+ * 
+ * الغرض من الملف:
+ * تخزين التقييمات والتعليقات التي يتركها الركاب للسائقين بعد انتهاء الرحلة.
+ * 
+ * كيفية العمل:
+ * 1. يرتبط بجدول (ratingDriver) في قاعدة البيانات الأساسية.
+ * 2. يربط التقييم بالراكب والسائق والرحلة المعنية.
+ */
 class RatingDriver extends Model {
     protected $connection = 'primary';
     protected $table = 'ratingDriver';

app/Models/RatingPassenger.php

@@ -2,6 +2,16 @@
 namespace App\Models;
 use Illuminate\Database\Eloquent\Model;
 
+/**
+ * نموذج تقييم الراكب (RatingPassenger Model)
+ * 
+ * الغرض من الملف:
+ * تخزين التقييمات التي يتركها السائقون للركاب.
+ * 
+ * كيفية العمل:
+ * 1. يرتبط بجدول (ratingPassenger) في قاعدة البيانات الأساسية.
+ * 2. يربط التقييم بالراكب والسائق والرحلة.
+ */
 class RatingPassenger extends Model {
     protected $connection = 'primary';
     protected $table = 'ratingPassenger';

app/Models/Ride.php

@@ -5,11 +5,16 @@ namespace App\Models;
 use Illuminate\Database\Eloquent\Model;
 
 /**
- * Ride Model
+ * نموذج الرحلة (Ride Model)
  * 
- * Exists on BOTH Primary and Ride databases.
- * Default connection is 'ride' (for real-time operations).
- * Use Ride::on('primary') when querying the primary DB copy.
+ * الغرض من الملف:
+ * تمثيل بيانات "الرحلة" في قاعدة البيانات. هذا الملف هو المسؤول عن التعامل مع جدول (ride).
+ * 
+ * كيفية العمل:
+ * 1. يربط الكود بجدول الرحلات ويحدد الحقول التي يمكن كتابتها (fillable).
+ * 2. يحدد قاعدة البيانات المستخدمة؛ حيث أن الرحلات موجودة في قاعدة بيانات منفصلة (ride connection) لسرعة الأداء.
+ * 3. يحتوي على علاقات (Relationships) مع السائق والراكب.
+ * 4. يحتوي على "Scopes" وهي اختصارات لعمليات البحث المتكررة (مثل البحث عن الرحلات النشطة فقط).
  */
 class Ride extends Model
 {

app/Models/WaitingRide.php

@@ -2,6 +2,17 @@
 namespace App\Models;
 use Illuminate\Database\Eloquent\Model;
 
+/**
+ * نموذج الرحلات المنتظرة (WaitingRide Model)
+ * 
+ * الغرض من الملف:
+ * إدارة الرحلات التي لم يقبلها سائق بعد وهي في حالة "انتظار".
+ * 
+ * كيفية العمل:
+ * 1. يرتبط بجدول (waitingRides) في قاعدة البيانات الأساسية.
+ * 2. يستخدم هذا الجدول بشكل أساسي لمحرك البحث عن السائقين القريبين.
+ * 3. يحتوي على تفاصيل المواقع (بداية ونهاية) والأسعار ونوع السيارة المطلوب.
+ */
 class WaitingRide extends Model {
     protected $connection = 'primary';
     protected $table = 'waitingRides';