Initial V2 commit 4

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
 {