Initial V2 commit 4

app/Helpers/LegacyEncryption.php

@@ -3,13 +3,15 @@
 namespace App\Helpers;
 
 /**
- * Legacy Encryption Helper
+ * مساعد التشفير القديم (Legacy Encryption Helper)
  * 
- * Backward-compatible encryption for data stored in the database.
- * Uses AES-256-CBC with static IV (same as V1) to read existing encrypted data.
+ * الغرض من الملف:
+ * الحفاظ على التوافق مع الإصدار الأول (V1) للنظام من خلال القدرة على قراءة البيانات التي تم تشفيرها قديماً في قاعدة البيانات.
  * 
- * WARNING: This class uses a static IV for backward compatibility only.
- * For new payload encryption between Flutter and server, use PayloadCrypto service.
+ * كيفية العمل:
+ * 1. يستخدم خوارزمية AES-256-CBC مع مفتاح تشفير ثابت (IV) مماثل للمستخدم في النسخة القديمة.
+ * 2. يقوم بفك تشفير الحقول الحساسة مثل (رقم الهاتف، الاسم، العنوان) المحفوظة في قاعدة البيانات الأساسية.
+ * 3. يضمن أن البيانات المنتقلة من النظام القديم للنظام الجديد تظل قابلة للقراءة والاستخدام.
  */
 class LegacyEncryption
 {

app/Http/Controllers/Admin/DriverManagementController.php

@@ -9,10 +9,15 @@ use Illuminate\Http\JsonResponse;
 use Illuminate\Support\Facades\DB;
 
 /**
- * Admin Driver Management Controller
- * Replaces: serviceapp/getDriverByPhone.php, getDriverByNational.php,
- * getDriversWaitingActive.php, getDriverDetailsForActivate.php,
- * updateDriverToActive.php, registerDriverAndCarService.php, etc.
+ * متحكم إدارة السائقين للمسؤولين (Admin Driver Management Controller)
+ * 
+ * الغرض من الملف:
+ * إدارة حسابات السائقين من قبل طاقم الإدارة، بما في ذلك تفعيل السائقين الجدد، البحث عنهم، وإضافتهم للنظام.
+ * 
+ * كيفية العمل:
+ * 1. يسمح بالبحث عن السائقين برقم الهاتف أو الرقم الوطني.
+ * 2. يتيح للمسؤول تفعيل أو إلغاء تفعيل حساب السائق.
+ * 3. يدير إضافة السيارات للسائقين والملاحظات الإدارية عليهم.
  */
 class DriverManagementController extends Controller
 {

app/Http/Controllers/Admin/PassengerManagementController.php

@@ -10,7 +10,14 @@ use Illuminate\Http\JsonResponse;
 use Illuminate\Support\Facades\DB;
 
 /**
- * Admin Passenger Management Controller
+ * متحكم إدارة الركاب للمسؤولين (Admin Passenger Management Controller)
+ * 
+ * الغرض من الملف:
+ * السماح للمسؤولين بالبحث عن الركاب المسجلين في النظام وإدارة حساباتهم.
+ * 
+ * كيفية العمل:
+ * 1. يوفر ميزة البحث عن الركاب حسب رقم الهاتف.
+ * 2. يعرض قائمة الركاب للمسؤول مع إمكانية التصفية (Pagination).
  */
 class PassengerManagementController extends Controller
 {

app/Http/Controllers/Admin/RideManagementController.php

@@ -8,7 +8,14 @@ use Illuminate\Http\JsonResponse;
 use Illuminate\Support\Facades\DB;
 
 /**
- * Admin Ride Management Controller
+ * متحكم إدارة الرحلات للمسؤولين (Admin Ride Management Controller)
+ * 
+ * الغرض من الملف:
+ * منح المسؤولين رؤية شاملة لجميع الرحلات التي تتم عبر المنصة.
+ * 
+ * كيفية العمل:
+ * 1. يعرض قائمة بجميع الرحلات مع تفاصيلها (الموقع، السعر، السائق، الراكب).
+ * 2. يسمح للمسؤول بمتابعة حالة الرحلات الحالية أو مراجعة الرحلات السابقة.
  */
 class RideManagementController extends Controller
 {

app/Http/Controllers/Admin/StatsController.php

@@ -11,6 +11,16 @@ use Illuminate\Support\Facades\DB;
  * Admin Stats Controller
  * Replaces: serviceapp/getRidesStatic.php, getPassengersStatic.php,
  * getEmployeeStatic.php, getdriverstotalMonthly.php, getEditorStatsCalls.php
+ *
+ * متحكم الإحصائيات (Stats Controller)
+ * 
+ * الغرض من الملف:
+ * توليد تقارير وإحصائيات حول أداء المنصة للمسؤولين.
+ * 
+ * كيفية العمل:
+ * 1. يحسب إجمالي عدد الرحلات، السائقين النشطين، والركاب.
+ * 2. يحلل البيانات المالية والنمو الشهري للسائقين.
+ * 3. يعرض ملخصاً سريعاً (Overview) لمؤشرات الأداء الرئيسية.
  */
 class StatsController extends Controller
 {

app/Http/Controllers/AuthController.php

@@ -15,16 +15,16 @@ use Illuminate\Support\Facades\Cache;
 use Illuminate\Support\Str;
 
 /**
- * Authentication Controller
+ * متحكم الهوية والوصول (Authentication Controller)
  * 
- * Unifies all V1 login flows:
- *   login.php → passengerLogin
- *   loginFirstTime.php → passengerRegister
- *   loginJwtDriver.php → driverLogin
- *   loginFirstTimeDriver.php → driverRegister
- *   loginWallet.php → passengerWalletLogin
- *   loginJwtWalletDriver.php → driverWalletLogin
- *   loginAdmin.php → adminLogin
+ * الغرض من الملف:
+ * إدارة عمليات تسجيل الدخول وإنشاء الحسابات لجميع أنواع المستخدمين (ركاب، سائقين، مدراء).
+ * 
+ * كيفية العمل:
+ * 1. يستقبل بيانات الاعتماد (مثل الهاتف وكلمة المرور).
+ * 2. يتحقق من صحة البيانات بمقارنتها بما هو موجود في قاعدة البيانات.
+ * 3. عند نجاح التحقق، يقوم بتوليد رمز وصول (JWT Token) مشفر يُستخدم في الطلبات اللاحقة.
+ * 4. يدير أيضاً تسجيل "بصمة الجهاز" لإرسال التنبيهات لاحقاً.
  */
 class AuthController extends Controller
 {

app/Http/Controllers/Controller.php

@@ -4,6 +4,16 @@ namespace App\Http\Controllers;
 
 use Illuminate\Routing\Controller as BaseController;
 
+/**
+ * المتحكم الأساسي (Base Controller)
+ * 
+ * الغرض من الملف:
+ * هذا هو الملف "الأب" لجميع المتحكمات (Controllers) في المشروع.
+ * 
+ * كيفية العمل:
+ * 1. يرث الخصائص الأساسية من Laravel.
+ * 2. يستخدم لتعريف الدوال أو الخصائص المشتركة التي تحتاجها جميع المتحكمات الأخرى.
+ */
 abstract class Controller extends BaseController
 {
     //

app/Http/Controllers/NotificationController.php

@@ -7,8 +7,14 @@ use Illuminate\Http\JsonResponse;
 use Illuminate\Support\Facades\DB;
 
 /**
- * Notification Controller
- * Replaces: ride/notification/*.php
+ * متحكم الإشعارات (Notification Controller)
+ * 
+ * الغرض من الملف:
+ * عرض وإدارة التنبيهات التاريخية التي وصلت للمستخدم (سائق أو راكب).
+ * 
+ * كيفية العمل:
+ * 1. يجلب قائمة الإشعارات من جداول (notifications) أو (notificationCaptain).
+ * 2. يسمح بتحديد الإشعارات كـ "مقروءة".
  */
 class NotificationController extends Controller
 {

app/Http/Controllers/OtpController.php

@@ -9,8 +9,15 @@ use Illuminate\Support\Facades\Cache;
 use Illuminate\Support\Str;
 
 /**
- * OTP Controller
- * Replaces: auth/otpmessage.php, verifyOtpMessage.php, sendVerifyEmail.php, etc.
+ * متحكم رموز التحقق (OTP Controller)
+ * 
+ * الغرض من الملف:
+ * إدارة إرسال والتحقق من رموز الـ OTP (التي تصل عبر SMS أو البريد الإلكتروني) لضمان ملكية المستخدم للحساب.
+ * 
+ * كيفية العمل:
+ * 1. يستقبل رقم الهاتف أو البريد الإلكتروني.
+ * 2. يولد رمزاً عشوائياً ويرسله عبر الخدمة المناسبة.
+ * 3. يخزن الرمز مؤقتاً للتحقق منه لاحقاً عند إدخاله من قبل المستخدم.
  */
 class OtpController extends Controller
 {

app/Http/Controllers/PlaceController.php

@@ -7,8 +7,14 @@ use Illuminate\Http\JsonResponse;
 use Illuminate\Support\Facades\DB;
 
 /**
- * Place Controller
- * Replaces: ride/places/add.php, ride/places_syria/*.php
+ * متحكم الأماكن (Place Controller)
+ * 
+ * الغرض من الملف:
+ * البحث عن العناوين والأماكن المشهورة، والسماح للمستخدمين بإضافة أماكن جديدة للخريطة.
+ * 
+ * كيفية العمل:
+ * 1. يتواصل مع خدمات الخرائط للبحث عن العناوين.
+ * 2. يتيح إضافة "أماكن مفضلة" (مثل المنزل أو العمل).
  */
 class PlaceController extends Controller
 {

app/Http/Controllers/ProfileController.php

@@ -12,8 +12,14 @@ use Illuminate\Http\JsonResponse;
 use Illuminate\Support\Facades\DB;
 
 /**
- * Profile Controller
- * Replaces: ride/profile/get.php, getCaptainProfile.php, update.php, updateDriverEmail.php
+ * متحكم الملف الشخصي (Profile Controller)
+ * 
+ * الغرض من الملف:
+ * إدارة البيانات الشخصية للمستخدمين (سائقين وركاب).
+ * 
+ * كيفية العمل:
+ * 1. يعرض بيانات المستخدم الحالية بعد فك تشفير الحقول الحساسة.
+ * 2. يسمح للمستخدم بتحديث بياناته مثل الاسم أو البريد الإلكتروني.
  */
 class ProfileController extends Controller
 {

app/Http/Controllers/PromoController.php

@@ -7,8 +7,14 @@ use Illuminate\Http\JsonResponse;
 use Illuminate\Support\Facades\DB;
 
 /**
- * Promo Controller
- * Replaces: ride/promo/*.php
+ * متحكم الأكواد الترويجية (Promo Controller)
+ * 
+ * الغرض من الملف:
+ * إدارة أكواد الخصم (Promo Codes) التي يستخدمها الركاب للحصول على تخفيضات.
+ * 
+ * كيفية العمل:
+ * 1. يتحقق من صحة الكود المدخل وصلاحيته التاريخية.
+ * 2. يطبق الخصم على سعر الرحلة إذا كان الكود صحيحاً.
  */
 class PromoController extends Controller
 {

app/Http/Controllers/RatingController.php

@@ -7,8 +7,15 @@ use Illuminate\Http\JsonResponse;
 use Illuminate\Support\Facades\DB;
 
 /**
- * Rating Controller
- * Replaces: ride/rate/*.php
+ * متحكم التقييمات (Rating Controller)
+ * 
+ * الغرض من الملف:
+ * إدارة عمليات التقييم المتبادل بين السائقين والركاب، بالإضافة لتقييم التطبيق نفسه.
+ * 
+ * كيفية العمل:
+ * 1. يستقبل التقييم (من 1 إلى 5) والتعليق من المستخدم.
+ * 2. يتحقق من عدم وجود تقييم مسبق لنفس الرحلة لمنع التكرار.
+ * 3. يحفظ التقييم في الجداول المناسبة (ratingDriver أو ratingPassenger).
  */
 class RatingController extends Controller
 {

app/Http/Controllers/RideController.php

@@ -16,10 +16,16 @@ use Illuminate\Http\JsonResponse;
 use Illuminate\Support\Facades\DB;
 
 /**
- * Ride Controller
+ * متحكم الرحلات (Ride Controller)
  * 
- * Handles the complete ride lifecycle:
- * create → search drivers → accept → arrive → start → finish/cancel
+ * الغرض من الملف:
+ * إدارة دورة حياة الرحلة بالكامل؛ بدءاً من طلب الراكب للرحلة حتى وصوله ودفعه للأجرة.
+ * 
+ * كيفية العمل:
+ * 1. يستقبل طلبات الرحلات الجديدة ويحفظها في جدول (waitingRides).
+ * 2. يسمح للسائقين بقبول الرحلات المتاحة وتحديث حالتهم.
+ * 3. يدير حالات الرحلة المختلفة: (انتظار، قبول، وصول السائق، بدء الرحلة، انتهاء الرحلة).
+ * 4. يرسل إشعارات فورية للركاب والسائقين عند أي تغيير في حالة الرحلة.
  */
 class RideController extends Controller
 {

app/Http/Controllers/TrackingController.php

@@ -10,6 +10,18 @@ use Illuminate\Support\Facades\DB;
  * Tracking Controller
  * Replaces: ride/rides/get_driver_location.php, public_track_location.php, getRealTimeHeatmap.php
  */
+
+/**
+ * متحكم التتبع (Tracking Controller)
+ * 
+ * الغرض من الملف:
+ * توفير بيانات المواقع الجغرافية الحية للسائقين والركاب.
+ * 
+ * كيفية العمل:
+ * 1. يجلب إحداثيات السائق من قاعدة بيانات التتبع (tracking) لعرضها للراكب.
+ * 2. يوفر بيانات "خريطة الحرارة" (Heatmap) لمعرفة أماكن تركز الطلبات.
+ * 3. يتيح تتبع الرحلة بشكل علني (Public Tracking) عبر رابط خارجي.
+ */
 class TrackingController extends Controller
 {
     /** GET /v2/tracking/driver/{rideId} */

app/Http/Controllers/UploadController.php

@@ -16,6 +16,16 @@ use Illuminate\Support\Str;
  * - Randomized filenames (prevents path traversal)
  * - Max file size enforcement
  * - No directory traversal possible
+ * 
+ * متحكم الرفع (Upload Controller)
+ * 
+ * الغرض من الملف:
+ * التعامل مع رفع الملفات والصور (مثل صور الهوية، رخصة القيادة، الصور الشخصية، والملفات الصوتية).
+ * 
+ * كيفية العمل:
+ * 1. يستقبل الملفات المرفوعة من التطبيق.
+ * 2. يقوم بتخزين الملفات في المجلدات المخصصة لها على الخادم مع تسميتها بشكل فريد.
+ * 3. يرجع رابط الملف المرفوع ليتم تخزينه في قاعدة البيانات.
  */
 class UploadController extends Controller
 {

app/Http/Controllers/WalletController.php

@@ -9,7 +9,16 @@ use Illuminate\Support\Str;
 
 /**
  * Wallet Controller
- * Replaces: ride/passengerWallet/*.php, ride/driverWallet/*.php
+ * Replaces: ride/passenger/**
+ * متحكم المحفظة (Wallet Controller)
+ * 
+ * الغرض من الملف:
+ * إدارة العمليات المالية للركاب، بما في ذلك عرض الرصيد، شحن المحفظة، وعرض سجل العمليات.
+ * 
+ * كيفية العمل:
+ * 1. يتواصل مع جداول (passengerWallet) و (payments) لجلب البيانات المالية.
+ * 2. يسمح للركاب بإضافة أموال لمحفظتهم وتحديث رصيدهم.
+ * 3. يعرض قائمة بالمعاملات المالية السابقة (Transactions).
  */
 class WalletController extends Controller
 {

app/Http/Middleware/AdminMiddleware.php

@@ -6,8 +6,15 @@ use Closure;
 use Illuminate\Http\Request;
 
 /**
- * Admin Role Middleware
- * Ensures the authenticated user has admin privileges
+ * وسيط التحقق من صلاحيات المدير (Admin Role Middleware)
+ * 
+ * الغرض من الملف:
+ * حماية المسارات (Routes) التي لا يسمح بالدخول إليها إلا للمدراء فقط.
+ * 
+ * كيفية العمل:
+ * 1. يفحص نوع المستخدم المخزن في رمز الـ JWT.
+ * 2. إذا كان نوع المستخدم ليس "admin"، يرفض الطلب ويرجع خطأ (403 Unauthorized).
+ * 3. إذا كان مديراً، يسمح للطلب بالمرور للمتحكم (Controller) المعني.
  */
 class AdminMiddleware
 {

app/Http/Middleware/HmacAuthMiddleware.php

@@ -8,16 +8,16 @@ use Illuminate\Support\Facades\DB;
 use Illuminate\Support\Facades\Cache;
 
 /**
- * HMAC Signature Validation Middleware
+ * وسيط التحقق من التوقيع الرقمي (HMAC Validation Middleware)
  * 
- * Validates every API request using HMAC-SHA256 signatures.
- * Prevents: Replay attacks, Man-in-the-Middle, Tampering.
+ * الغرض من الملف:
+ * توفير طبقة أمان إضافية لجميع الطلبات لضمان عدم التلاعب بالبيانات أثناء انتقالها بين التطبيق والخادم.
  * 
- * Required Headers:
- *   X-API-Key: unique per user (stored in DB)
- *   X-Timestamp: Unix timestamp (must be within TOLERANCE window)
- *   X-Signature: HMAC-SHA256(timestamp|api_key|request_body, api_secret)
- *   X-Nonce: unique per request (prevents replay attacks)
+ * كيفية العمل:
+ * 1. يتطلب وجود "توقيع" (Signature) في رأس الطلب (Headers).
+ * 2. يقوم الخادم بإعادة حساب التوقيع باستخدام مفتاح سري (API Secret) ومقارنته بالتوقيع المرسل.
+ * 3. يحمي من هجمات "إعادة الإرسال" (Replay Attacks) عن طريق التحقق من الـ Nonce والـ Timestamp.
+ * 4. يضمن أن البيانات لم تتغير في الطريق (Data Integrity).
  */
 class HmacAuthMiddleware
 {

app/Http/Middleware/JwtAuthMiddleware.php

@@ -9,10 +9,16 @@ use Firebase\JWT\Key;
 use Firebase\JWT\ExpiredException;
 
 /**
- * JWT Authentication Middleware
+ * وسيط التحقق من الهوية (JWT Authentication Middleware)
  * 
- * Validates JWT tokens from the Authorization header.
- * Works in conjunction with HMAC middleware for double-layer security.
+ * الغرض من الملف:
+ * التحقق من "رمز الوصول" (Access Token) الذي يحمله المستخدم بعد تسجيل الدخول للتأكد من هويته.
+ * 
+ * كيفية العمل:
+ * 1. يستخرج الرمز من رأس الطلب (Authorization Header).
+ * 2. يقوم بفك تشفير الرمز (Decode) باستخدام مفتاح سري (JWT Secret).
+ * 3. يستخرج بيانات المستخدم (مثل المعرف والنوع) ويضيفها للطلب ليسهل الوصول إليها في المتحكمات.
+ * 4. يمنع الطلب إذا كان الرمز منتهي الصلاحية أو غير صحيح.
  */
 class JwtAuthMiddleware
 {

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';

app/Services/FcmService.php

@@ -5,10 +5,15 @@ namespace App\Services;
 use Illuminate\Support\Facades\Log;
 
 /**
- * FCM Notification Service
+ * خدمة إشعارات Firebase (FCM Service)
  * 
- * Sends push notifications via Firebase Cloud Messaging (HTTP v1 API).
- * Replaces the scattered sendFCM_Internal() calls from V1.
+ * الغرض من الملف:
+ * إرسال التنبيهات (Push Notifications) للهواتف الذكية عبر خدمة Google Firebase.
+ * 
+ * كيفية العمل:
+ * 1. يتصل بخوادم Google باستخدام مفاتيح الوصول (API Keys).
+ * 2. يرسل التنبيه للراكب أو السائق بناءً على الرمز (Token) الخاص بجهازه.
+ * 3. يدير إرسال البيانات الإضافية (مثل معرف الرحلة) داخل التنبيه لتسهيل التفاعل معه داخل التطبيق.
  */
 class FcmService
 {

app/Services/PayloadCrypto.php

@@ -3,14 +3,15 @@
 namespace App\Services;
 
 /**
- * Payload Crypto Service — AES-256-GCM
+ * خدمة تشفير حمولة البيانات (Payload Crypto Service)
  * 
- * Dynamic encryption for all payloads between Flutter apps and the API.
- * Unlike LegacyEncryption which uses static IV, this generates a unique IV per request.
+ * الغرض من الملف:
+ * تشفير وفك تشفير البيانات المتبادلة بين التطبيق (Flutter) والخادم (API) باستخدام تقنية AES-256-GCM.
  * 
- * Format: base64(IV + ciphertext + tag)
- * - IV: 12 bytes (random per encryption)
- * - Tag: 16 bytes (integrity verification)
+ * كيفية العمل:
+ * 1. يولد مفتاح تشفير ديناميكي وفريد لكل طلب (IV).
+ * 2. يضمن خصوصية البيانات (تشفير) وسلامتها (منع التلاعب عبر الـ Authentication Tag).
+ * 3. يختلف عن التشفير القديم (Legacy) بأنه أكثر أماناً ويستخدم معايير تشفير حديثة.
  */
 class PayloadCrypto
 {

app/Services/SocketService.php

@@ -5,10 +5,15 @@ namespace App\Services;
 use Illuminate\Support\Facades\Log;
 
 /**
- * Socket Communication Service
+ * خدمة التواصل اللحظي (Socket Communication Service)
  * 
- * Communicates with Node.js socket servers for real-time events.
- * Replaces hardcoded IPs in V1 with .env configuration.
+ * الغرض من الملف:
+ * التنسيق بين الخادم (PHP) وخوادم الـ Sockets (التي تعمل بـ Node.js) لتحديث التطبيقات فوراً عند وقوع حدث معين.
+ * 
+ * كيفية العمل:
+ * 1. عندما يتم قبول رحلة أو تحديث موقع، يرسل هذا الملف طلباً سريعاً (Async) لخادم السوكت.
+ * 2. يقوم خادم السوكت بدوره بتوصيل هذه المعلومة لتطبيق الراكب أو السائق في نفس اللحظة بدون تأخير.
+ * 3. يستخدم مفاتيح أمان داخلية (Internal Key) لضمان أن الطلبات قادمة من الخادم الموثوق فقط.
  */
 class SocketService
 {

artisan

@@ -1,6 +1,18 @@
 #!/usr/bin/env php
 <?php
 
+/**
+ * ملف Artisan (أداة سطر الأوامر في Laravel)
+ * 
+ * الغرض من الملف:
+ * هو المحرك الأساسي للأوامر التي تنفذها في "Terminal" مثل (php artisan migrate) أو (php artisan make:controller).
+ * 
+ * كيفية العمل:
+ * 1. يقوم بتحميل ملفات المشروع الأساسية (autoload.php).
+ * 2. يستدعي بيئة العمل (Bootstrap) لتجهيز التطبيق.
+ * 3. يستقبل الأمر الذي كتبته في سطر الأوامر ويقوم بتنفيذه داخل إطار عمل Laravel.
+ */
+
 define('LARAVEL_START', microtime(true));
 
 require __DIR__.'/vendor/autoload.php';

config/app.php

@@ -1,5 +1,16 @@
 <?php
 
+/**
+ * إعدادات التطبيق العامة (App Configuration)
+ * 
+ * الغرض من الملف:
+ * ضبط الإعدادات الأساسية للمشروع مثل الاسم، البيئة (إنتاج أم تطوير)، اللغة الافتراضية، ومفاتيح التشفير.
+ * 
+ * كيفية العمل:
+ * 1. يقرأ القيم من ملف الـ (.env) لسهولة التغيير بين السيرفرات المختلفة.
+ * 2. يحدد المناطق الزمنية واللغات التي يدعمها التطبيق.
+ */
+
 return [
     'name' => env('APP_NAME', 'IntaleqV2'),
     'env' => env('APP_ENV', 'production'),

config/database.php

@@ -1,5 +1,17 @@
 <?php
 
+/**
+ * إعدادات قواعد البيانات (Database Configuration)
+ * 
+ * الغرض من الملف:
+ * تعريف جميع الاتصالات بقواعد البيانات التي يستخدمها المشروع. في هذا المشروع، نستخدم 3 قواعد بيانات مختلفة.
+ * 
+ * كيفية العمل:
+ * 1. (primary): قاعدة البيانات الأساسية لبيانات المستخدمين والسيارات.
+ * 2. (ride): قاعدة بيانات مخصصة لعمليات الرحلات السريعة.
+ * 3. (tracking): قاعدة بيانات تتبع المواقع الجغرافية للسائقين.
+ */
+
 return [
 
     'default' => env('DB_CONNECTION', 'primary'),

config/intaleq.php

@@ -1,8 +1,15 @@
 <?php
 
 /**
- * Intaleq V2 — Custom configuration
- * All secrets and paths are externalized to .env
+ * إعدادات مشروع "انطلق" الخاصة (Intaleq Custom Configuration)
+ * 
+ * الغرض من الملف:
+ * تجميع كل الإعدادات الخاصة بمشروع "انطلق" في مكان واحد، مثل مفاتيح الـ JWT، مسارات التشفير، وإعدادات خدمة Firebase.
+ * 
+ * كيفية العمل:
+ * 1. يحدد المسارات للملفات السرية (Keys) الموجودة على الخادم.
+ * 2. يضبط روابط خوادم الـ Sockets والتتبع.
+ * 3. يحدد القيود الخاصة برفع الملفات (الحجم والأنواع المسموحة).
  */
 return [
     // JWT

database/migrations/2026_04_22_000001_add_api_keys_and_missing_indexes.php

@@ -6,9 +6,15 @@ use Illuminate\Support\Facades\Schema;
 use Illuminate\Support\Facades\DB;
 
 /**
- * Add missing indexes + api_key/api_secret columns for HMAC auth
+ * ملف تحديث قاعدة البيانات (Database Migration)
  * 
- * SAFE: Only adds columns/indexes — does NOT modify existing data
+ * الغرض من الملف:
+ * إضافة أعمدة جديدة (api_key و api_secret) وتعديل هيكلية الجداول الحالية لتدعم ميزات الأمان الجديدة وتحسين الأداء.
+ * 
+ * كيفية العمل:
+ * 1. يضيف حقول الأمان لجداول السائقين والركاب والمدراء.
+ * 2. ينشئ "فهارس" (Indexes) لتحسين سرعة البحث في قاعدة البيانات، مما يجعل التطبيق أسرع في الاستجابة.
+ * 3. يضمن تحديث هيكلية الجداول في جميع قواعد البيانات المستخدمة (primary و ride).
  */
 return new class extends Migration
 {

public/index.php

@@ -1,5 +1,19 @@
 <?php
 
+/**
+ * ملف المدخل الرئيسي (Public Entry Point)
+ * 
+ * الغرض من الملف:
+ * هذا هو أول ملف يتم تنفيذه عندما يقوم شخص ما بطلب الرابط الخاص بموقعك أو تطبيقك.
+ * يعمل كبوابة دخول لجميع الطلبات القادمة من المتصفح أو التطبيقات.
+ * 
+ * كيفية العمل:
+ * 1. يتحقق مما إذا كان الموقع في وضع الصيانة (Maintenance Mode).
+ * 2. يقوم بتحميل "الملقم الآلي" (Composer Autoloader) للوصول لكل ملفات المشروع.
+ * 3. يستدعي بيئة Laravel (Bootstrap) لتشغيل النظام.
+ * 4. يستقبل الطلب (Request)، يرسله للمسار الصحيح، ثم يرسل الرد (Response) للمستخدم.
+ */
+
 use Illuminate\Http\Request;
 
 define('LARAVEL_START', microtime(true));

routes/api.php

@@ -1,5 +1,19 @@
 <?php
 
+/**
+ * ملف مسارات الـ API (API Routes)
+ * 
+ * الغرض من الملف:
+ * تعريف جميع "العناوين" (Endpoints) التي يمكن للتطبيقات (راكب، سائق، لوحة تحكم) التواصل معها.
+ * يعمل كخريطة تدل النظام على أي "Controller" يجب استدعاؤه لكل طلب.
+ * 
+ * كيفية العمل:
+ * 1. المسارات العامة (Public): مثل تسجيل الدخول وإنشاء الحساب، لا تحتاج لتشفير مسبق.
+ * 2. المسارات المحمية (Protected): تتطلب وجود رمز التحقق (JWT) وتوقيع (HMAC) لضمان الأمان.
+ * 3. المسارات مقسمة لمجموعات (Prefixes) مثل /v2/auth و /v2/rides لتسهيل التنظيم.
+ * 4. يستخدم الوسيط (Middleware) للتحقق من هوية المستخدم وصلاحياته قبل تنفيذ الطلب.
+ */
+
 use Illuminate\Support\Facades\Route;
 use App\Http\Controllers\AuthController;
 use App\Http\Controllers\RideController;

setup.sh

@@ -2,6 +2,18 @@
 
 ###############################################
 # Intaleq V2 — Server Setup Script (CloudPanel Optimized)
+#
+# الغرض من الملف:
+# هذا الملف عبارة عن "سكربت" (Script) لأتمتة عملية إعداد المشروع على الخادم (Server).
+# بدلاً من تنفيذ الأوامر يدوياً واحد تلو الآخر، يقوم هذا الملف بتجهيز كل شيء بضغطة واحدة.
+#
+# كيفية العمل:
+# 1. يقوم بتثبيت المكتبات المطلوبة (Composer dependencies).
+# 2. ينشئ ملف الإعدادات (.env) إذا لم يكن موجوداً.
+# 3. يولد مفتاح التشفير الخاص بالتطبيق (App Key).
+# 4. يقوم بعمل "Cache" للإعدادات والمسارات لتحسين الأداء.
+# 5. يضبط صلاحيات المجلدات (Permissions) لضمان قدرة التطبيق على الكتابة في مجلد التخزين.
+# 6. ينفذ عمليات تحديث قاعدة البيانات (Migrations).
 ###############################################
 
 set -e