From 3f4afd0f5cc11958046411b561bf1345e4061465 Mon Sep 17 00:00:00 2001 From: Hamza-Ayed Date: Wed, 22 Apr 2026 23:16:23 +0300 Subject: [PATCH] Initial V2 commit 4 --- app/Helpers/LegacyEncryption.php | 12 +++++++----- .../Admin/DriverManagementController.php | 13 +++++++++---- .../Admin/PassengerManagementController.php | 9 ++++++++- .../Admin/RideManagementController.php | 9 ++++++++- app/Http/Controllers/Admin/StatsController.php | 10 ++++++++++ app/Http/Controllers/AuthController.php | 18 +++++++++--------- app/Http/Controllers/Controller.php | 10 ++++++++++ .../Controllers/NotificationController.php | 10 ++++++++-- app/Http/Controllers/OtpController.php | 11 +++++++++-- app/Http/Controllers/PlaceController.php | 10 ++++++++-- app/Http/Controllers/ProfileController.php | 10 ++++++++-- app/Http/Controllers/PromoController.php | 10 ++++++++-- app/Http/Controllers/RatingController.php | 11 +++++++++-- app/Http/Controllers/RideController.php | 12 +++++++++--- app/Http/Controllers/TrackingController.php | 12 ++++++++++++ app/Http/Controllers/UploadController.php | 10 ++++++++++ app/Http/Controllers/WalletController.php | 11 ++++++++++- app/Http/Middleware/AdminMiddleware.php | 11 +++++++++-- app/Http/Middleware/HmacAuthMiddleware.php | 16 ++++++++-------- app/Http/Middleware/JwtAuthMiddleware.php | 12 +++++++++--- app/Models/CarLocation.php | 11 +++++++++++ app/Models/CarRegistration.php | 11 +++++++++++ app/Models/Driver.php | 12 +++++++++--- app/Models/DriverDocument.php | 10 ++++++++++ app/Models/DriverGift.php | 10 ++++++++++ app/Models/DriverHealthAssurance.php | 10 ++++++++++ app/Models/DriverOrder.php | 10 ++++++++++ app/Models/DriverToken.php | 10 ++++++++++ app/Models/ImageProfileCaptain.php | 10 ++++++++++ app/Models/Passenger.php | 12 ++++++++++++ app/Models/PassengerToken.php | 10 ++++++++++ app/Models/PassengerWallet.php | 10 ++++++++++ app/Models/RatingDriver.php | 10 ++++++++++ app/Models/RatingPassenger.php | 10 ++++++++++ app/Models/Ride.php | 13 +++++++++---- app/Models/WaitingRide.php | 11 +++++++++++ app/Services/FcmService.php | 11 ++++++++--- app/Services/PayloadCrypto.php | 13 +++++++------ app/Services/SocketService.php | 11 ++++++++--- artisan | 12 ++++++++++++ config/app.php | 11 +++++++++++ config/database.php | 12 ++++++++++++ config/intaleq.php | 11 +++++++++-- ...000001_add_api_keys_and_missing_indexes.php | 10 ++++++++-- public/index.php | 14 ++++++++++++++ routes/api.php | 14 ++++++++++++++ setup.sh | 12 ++++++++++++ 47 files changed, 456 insertions(+), 72 deletions(-) diff --git a/app/Helpers/LegacyEncryption.php b/app/Helpers/LegacyEncryption.php index 82dc3fb..91d62e3 100644 --- a/app/Helpers/LegacyEncryption.php +++ b/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 { diff --git a/app/Http/Controllers/Admin/DriverManagementController.php b/app/Http/Controllers/Admin/DriverManagementController.php index da82330..31f5df2 100644 --- a/app/Http/Controllers/Admin/DriverManagementController.php +++ b/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 { diff --git a/app/Http/Controllers/Admin/PassengerManagementController.php b/app/Http/Controllers/Admin/PassengerManagementController.php index 83da607..ec5d7d7 100644 --- a/app/Http/Controllers/Admin/PassengerManagementController.php +++ b/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 { diff --git a/app/Http/Controllers/Admin/RideManagementController.php b/app/Http/Controllers/Admin/RideManagementController.php index 41701d8..b71f0a5 100644 --- a/app/Http/Controllers/Admin/RideManagementController.php +++ b/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 { diff --git a/app/Http/Controllers/Admin/StatsController.php b/app/Http/Controllers/Admin/StatsController.php index 43374b0..da8bc27 100644 --- a/app/Http/Controllers/Admin/StatsController.php +++ b/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 { diff --git a/app/Http/Controllers/AuthController.php b/app/Http/Controllers/AuthController.php index 468ec88..218bfdc 100644 --- a/app/Http/Controllers/AuthController.php +++ b/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 { diff --git a/app/Http/Controllers/Controller.php b/app/Http/Controllers/Controller.php index e1fc5de..6997630 100644 --- a/app/Http/Controllers/Controller.php +++ b/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 { // diff --git a/app/Http/Controllers/NotificationController.php b/app/Http/Controllers/NotificationController.php index 178457d..3546777 100644 --- a/app/Http/Controllers/NotificationController.php +++ b/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 { diff --git a/app/Http/Controllers/OtpController.php b/app/Http/Controllers/OtpController.php index efb0c0b..d1554c8 100644 --- a/app/Http/Controllers/OtpController.php +++ b/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 { diff --git a/app/Http/Controllers/PlaceController.php b/app/Http/Controllers/PlaceController.php index 282a6db..a5c2073 100644 --- a/app/Http/Controllers/PlaceController.php +++ b/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 { diff --git a/app/Http/Controllers/ProfileController.php b/app/Http/Controllers/ProfileController.php index 63890aa..c58bce2 100644 --- a/app/Http/Controllers/ProfileController.php +++ b/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 { diff --git a/app/Http/Controllers/PromoController.php b/app/Http/Controllers/PromoController.php index 12a44c1..1d9d799 100644 --- a/app/Http/Controllers/PromoController.php +++ b/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 { diff --git a/app/Http/Controllers/RatingController.php b/app/Http/Controllers/RatingController.php index 729637b..8960fff 100644 --- a/app/Http/Controllers/RatingController.php +++ b/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 { diff --git a/app/Http/Controllers/RideController.php b/app/Http/Controllers/RideController.php index 7084f4a..34a0796 100644 --- a/app/Http/Controllers/RideController.php +++ b/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 { diff --git a/app/Http/Controllers/TrackingController.php b/app/Http/Controllers/TrackingController.php index 22ddb6a..c5b064a 100644 --- a/app/Http/Controllers/TrackingController.php +++ b/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} */ diff --git a/app/Http/Controllers/UploadController.php b/app/Http/Controllers/UploadController.php index 41858f7..68568ac 100644 --- a/app/Http/Controllers/UploadController.php +++ b/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 { diff --git a/app/Http/Controllers/WalletController.php b/app/Http/Controllers/WalletController.php index be18649..592ae55 100644 --- a/app/Http/Controllers/WalletController.php +++ b/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 { diff --git a/app/Http/Middleware/AdminMiddleware.php b/app/Http/Middleware/AdminMiddleware.php index f15dfb7..14f1d8b 100644 --- a/app/Http/Middleware/AdminMiddleware.php +++ b/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 { diff --git a/app/Http/Middleware/HmacAuthMiddleware.php b/app/Http/Middleware/HmacAuthMiddleware.php index c06e91e..af6e341 100644 --- a/app/Http/Middleware/HmacAuthMiddleware.php +++ b/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 { diff --git a/app/Http/Middleware/JwtAuthMiddleware.php b/app/Http/Middleware/JwtAuthMiddleware.php index 8347383..751e044 100644 --- a/app/Http/Middleware/JwtAuthMiddleware.php +++ b/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 { diff --git a/app/Models/CarLocation.php b/app/Models/CarLocation.php index 68680a9..6679f20 100644 --- a/app/Models/CarLocation.php +++ b/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'; diff --git a/app/Models/CarRegistration.php b/app/Models/CarRegistration.php index 4d626a6..a3799bb 100644 --- a/app/Models/CarRegistration.php +++ b/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'; diff --git a/app/Models/Driver.php b/app/Models/Driver.php index d38adbd..e29594e 100644 --- a/app/Models/Driver.php +++ b/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 { diff --git a/app/Models/DriverDocument.php b/app/Models/DriverDocument.php index 30d64eb..3dea7bb 100644 --- a/app/Models/DriverDocument.php +++ b/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'; diff --git a/app/Models/DriverGift.php b/app/Models/DriverGift.php index 3f26c13..36955b1 100644 --- a/app/Models/DriverGift.php +++ b/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'; diff --git a/app/Models/DriverHealthAssurance.php b/app/Models/DriverHealthAssurance.php index 398b15a..d493558 100644 --- a/app/Models/DriverHealthAssurance.php +++ b/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'; diff --git a/app/Models/DriverOrder.php b/app/Models/DriverOrder.php index cbadc29..1cb7ce2 100644 --- a/app/Models/DriverOrder.php +++ b/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'; diff --git a/app/Models/DriverToken.php b/app/Models/DriverToken.php index b64ca8b..451f699 100644 --- a/app/Models/DriverToken.php +++ b/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'; diff --git a/app/Models/ImageProfileCaptain.php b/app/Models/ImageProfileCaptain.php index 12086e7..26601ad 100644 --- a/app/Models/ImageProfileCaptain.php +++ b/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'; diff --git a/app/Models/Passenger.php b/app/Models/Passenger.php index ee57837..492f3f2 100644 --- a/app/Models/Passenger.php +++ b/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'; diff --git a/app/Models/PassengerToken.php b/app/Models/PassengerToken.php index 53d13fc..c6504ee 100644 --- a/app/Models/PassengerToken.php +++ b/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'; diff --git a/app/Models/PassengerWallet.php b/app/Models/PassengerWallet.php index df0ea06..4f00671 100644 --- a/app/Models/PassengerWallet.php +++ b/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'; diff --git a/app/Models/RatingDriver.php b/app/Models/RatingDriver.php index 1eae024..d8789c2 100644 --- a/app/Models/RatingDriver.php +++ b/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'; diff --git a/app/Models/RatingPassenger.php b/app/Models/RatingPassenger.php index 09b7042..4ec4f96 100644 --- a/app/Models/RatingPassenger.php +++ b/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'; diff --git a/app/Models/Ride.php b/app/Models/Ride.php index a72a74c..5886e73 100644 --- a/app/Models/Ride.php +++ b/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 { diff --git a/app/Models/WaitingRide.php b/app/Models/WaitingRide.php index c075772..67ea052 100644 --- a/app/Models/WaitingRide.php +++ b/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'; diff --git a/app/Services/FcmService.php b/app/Services/FcmService.php index b3883e5..34bbe7c 100644 --- a/app/Services/FcmService.php +++ b/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 { diff --git a/app/Services/PayloadCrypto.php b/app/Services/PayloadCrypto.php index adc4e9e..5541813 100644 --- a/app/Services/PayloadCrypto.php +++ b/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 { diff --git a/app/Services/SocketService.php b/app/Services/SocketService.php index 8094d66..ae99759 100644 --- a/app/Services/SocketService.php +++ b/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 { diff --git a/artisan b/artisan index 954a58b..98f02b9 100644 --- a/artisan +++ b/artisan @@ -1,6 +1,18 @@ #!/usr/bin/env php env('APP_NAME', 'IntaleqV2'), 'env' => env('APP_ENV', 'production'), diff --git a/config/database.php b/config/database.php index d6c8036..0b1faf9 100644 --- a/config/database.php +++ b/config/database.php @@ -1,5 +1,17 @@ env('DB_CONNECTION', 'primary'), diff --git a/config/intaleq.php b/config/intaleq.php index e6c4c46..3c72409 100644 --- a/config/intaleq.php +++ b/config/intaleq.php @@ -1,8 +1,15 @@