Initial V2 commit 2

2026-04-22 22:10:19 +03:00
parent 4706404488
commit 9cd7c7a4df
1 changed files with 125 additions and 0 deletions
--- a/README-AR.md
+++ b/README-AR.md
@@ -0,0 +1,125 @@
+# 📖 الدليل الشامل لـ Intaleq V2 (Laravel API)
+
+> **تنبيه:** هذا المستند مكتوب خصيصاً لفريق التطوير والإدارة لشركة انطلق. يوضح كيفية التعامل مع الهيكلية الجديدة، التقييم الأمني، آلية تتبع الأخطاء، وخطوات الرفع الآمنة على السيرفر.
+
+---
+
+## 🏗️ 1. نظرة عامة على التغيير الجذري (Architecture Shift)
+تم الانتقال من بيئة (Procedural PHP) المكونة من أكثر من 300 ملف عشوائي، إلى بيئة عمل (Laravel 11) متماسكة وذات معايير مؤسسية (Enterprise Level). 
+النظام الجديد يعتمد على **MVC** (Model-View-Controller) مع طبقة **Services** مستقلة للعمليات المعقدة، وطبقة **Middleware** للحماية القصوى.
+
+---
+
+## 🛡️ 2. التقييم الشامل (أمنياً وديناميكياً)
+
+### 🔐 أولاً: الأمان (Security)
+تم تطبيق معايير الأمان البنكية على الـ API الجديد لحل كافة ثغرات V1:
+1. **الوقاية من SQL Injection:** جميع الاستعلامات الآن تمر عبر `Eloquent ORM` أو `Query Builder` الخاص بـ Laravel، مما يجعل اختراق قاعدة البيانات عبر الاستعلامات مستحيلاً.
+2. **الوقاية من Replay Attacks:** عبر `HmacAuthMiddleware`، كل طلب يجب أن يحمل طابع زمني (Timestamp) وتوقيع (Signature). لا يمكن لأي مخترق التقاط طلب قديم وإعادة إرساله (مثلاً طلب سحب رصيد).
+3. **تأكيد هوية الأجهزة (Fingerprint):** رمز `JWT` مربوط الآن ببصمة الجهاز. إذا تم سرقة الرمز (Token)، فلن يعمل على جهاز آخر.
+4. **تشفير الحمولات (Payload Encryption):** تم كتابة كلاس `PayloadCrypto` ليقوم بتشفير البيانات الحساسة المتبادلة بين السيرفر وتطبيق Flutter (AES-256-GCM) بمفتاح يتغير مع كل طلب (Dynamic IV).
+5. **جدار الحماية من الهجمات (Rate Limiting):** النظام مربوط بـ Redis، ويمنع أي هجوم (Brute-force) لكسر كلمات المرور أو طلب أرقام OTP بشكل مزعج. (الحد الأقصى لتسجيل الدخول 5 مرات بالدقيقة).
+
+### ⚡ ثانياً: الخفة والأداء (Performance & Dynamics)
+1. **تحسين قواعد البيانات:** تمت إضافة ملف هجرة (Migration) لإنشاء **Indexes** مفقودة في جداول `driver_orders` و `ride` و `tokens`، مما سيسرع الاستعلامات التي كانت تستهلك وقت السيرفر في V1.
+2. **الفصل الذكي (Multi-DB Connection):** النظام مصمم بذكاء للاتصال بـ 3 قواعد بيانات في نفس اللحظة (Primary, Ride, Tracking)، مما يوزع الحمل (Load) بشكل طبيعي.
+
+### ⚖️ ثالثاً: التوازن والثقة (Stability & Reliability)
+1. **العمليات الذرية (Atomic Transactions):** في V1 كان من الممكن خصم الرصيد وعدم تسجيل الرحلة إذا انقطع الإنترنت. في V2، استخدمنا `DB::beginTransaction()`. إما أن تكتمل عملية الرحلة والدفع معاً 100%، أو يتم إلغاؤها بالكامل إذا حدث أي خطأ، مما يمنع أي خلل محاسبي.
+2. **معالجة تضارب البيانات (Race Conditions):** تم استخدام قفل `lockForUpdate()` في قاعدة البيانات عند قبول السائقين للرحلات، لمنع سائقين من قبول نفس الرحلة في نفس اللحظة.
+
+---
+
+## 🐛 3. نظام تتبع وإدارة الأخطاء (Error Tracking & Logging)
+
+التعامل مع الأخطاء في Laravel مختلف كلياً عن V1، وهو أكثر احترافية:
+
+### أين تذهب الأخطاء؟
+لا يتم عرض الأخطاء للمستخدم النهائي (الراكب/السائق) أبداً. بدلاً من ذلك:
+- يحصل المستخدم على رد ثابت: `"message": "Internal server error"`.
+- يتم تسجيل تفاصيل الخطأ (نوع الخطأ، الملف، ورقم السطر) بالكامل داخل ملف واحد وهو:
+  `storage/logs/laravel.log`
+
+### كيف تطبع الأخطاء المخصصة؟
+إذا أردت تتبع شيء معين أو طباعة متغير (للاختبار)، لا تستخدم `echo` أو `print_r`، بل استخدم واجهة `Log`:
+```php
+use Illuminate\Support\Facades\Log;
+
+// سيتم حفظ هذا في ملف السجلات (laravel.log)
+Log::info('تم قبول الرحلة بنجاح', ['ride_id' => $rideId]);
+Log::warning('محاولة تسجيل دخول فاشلة', ['phone' => $phone]);
+Log::error('فشل في الاتصال بخادم اللوكيشن', ['error' => $e->getMessage()]);
+```
+
+### كيف تراقب الأخطاء وقت حدوثها على السيرفر؟
+إذا رفعت المشروع على السيرفر وأردت تتبع الأخطاء لحظة بلحظة، افتح الـ Terminal واكتب:
+```bash
+tail -f storage/logs/laravel.log
+```
+هذا الأمر سيطبع أي خطأ يحدث في التطبيق مباشرة أمامك.
+
+---
+
+## 🚀 4. دليل التثبيت الآمن والرفع على السيرفر (Safe Deployment Guide)
+
+بما أنك تخشى من تأثير التحديثات على النظام الحالي، **أفضل ممارسة هي رفع V2 على Subdomain منفصل** (مثلاً: `api-v2.intaleq.xyz`) وتجربته بالكامل قبل تحويل التطبيق الأساسي عليه.
+
+### الخطوة 1: الرفع والمزامنة
+قمت أنت بالفعل بربط المشروع بـ Git. الآن، ادخل إلى السيرفر الخاص بك واسحب (Pull) المشروع في مجلد جديد، مثلاً `/var/www/intaleq_v2`.
+
+### الخطوة 2: فحص بيئة السيرفر
+لتجنب أخطاء `composer install`، يجب التأكد من:
+1. إصدار PHP يجب أن يكون 8.1 أو أعلى.
+2. الإضافات المطلوبة مفعلة: `php-curl`, `php-mbstring`, `php-xml`, `php-mysql`, `php-bcmath`.
+3. الـ Redis مثبت ويعمل (`sudo apt install redis-server`).
+
+### الخطوة 3: التثبيت (Installation)
+ادخل لمجلد المشروع على السيرفر، ونفذ السكريبت الذي قمنا بإعداده (تمت كتابته بعناية لتجنب تدمير أي شيء):
+```bash
+cd /var/www/intaleq_v2
+chmod +x setup.sh
+./setup.sh
+```
+
+**ماذا سيفعل هذا السكريبت؟**
+1. سيقوم بتثبيت الحزم عبر `composer install`.
+2. سينسخ ملف الإعدادات `.env.example` إلى `.env`.
+3. سينشئ مفتاح التطبيق `php artisan key:generate`.
+4. سيطلب منك الموافقة على تشغيل الـ Migrations. **(هذه الـ Migrations آمنة جداً، فهي تضيف فقط حقول api_key للـ DB وتنشئ الـ Indexes ولا تحذف أي بيانات قديمة).**
+
+### الخطوة 4: إعداد المتغيرات (هام جداً)
+افتح ملف `.env` وقم بتعبئة بيانات السيرفر الحقيقية:
+- الـ IPs الخاصة بقواعد البيانات الثلاث.
+- كلمات المرور لكل قاعدة بيانات.
+- مسار الـ FCM Credentials.
+- مسار الـ Legacy Encrypt Key.
+
+### الخطوة 5: ربط النطاق الفرعي (Subdomain) في Nginx
+قم بإنشاء ملف إعدادات لـ Nginx ليوجه `api-v2.intaleq.xyz` إلى مجلد الـ `public` الخاص بالمشروع:
+```nginx
+server {
+    listen 80;
+    server_name api-v2.intaleq.xyz;
+    root /var/www/intaleq_v2/public;
+    index index.php;
+
+    location / {
+        try_files $uri $uri/ /index.php?$query_string;
+    }
+}
+```
+
+بعدها أعد تشغيل Nginx:
+```bash
+sudo systemctl reload nginx
+```
+
+---
+
+## 🎯 5. الخلاصة
+المشروع الآن عبارة عن **صندوق أسود آمن جداً**. كل ما يدخل له يتم فحصه وتشفيره، وكل ما يخرج منه يكون سريعاً وموثوقاً.
+- **في حال حدوث خطأ:** راجع `storage/logs/laravel.log`.
+- **لتغيير إعداد:** عدل فقط في ملف `.env`.
+- **لمزامنة التغييرات المبرمجة:** استخدم `git pull`.
+
+بهذا تكون قد انتقلت بـ Intaleq إلى مصاف التطبيقات العالمية من ناحية البنية التحتية.