intaleq_v2/README-AR.md

📖 الدليل الشامل لـ 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:

use Illuminate\Support\Facades\Log;

// سيتم حفظ هذا في ملف السجلات (laravel.log)
Log::info('تم قبول الرحلة بنجاح', ['ride_id' => $rideId]);
Log::warning('محاولة تسجيل دخول فاشلة', ['phone' => $phone]);
Log::error('فشل في الاتصال بخادم اللوكيشن', ['error' => $e->getMessage()]);

كيف تراقب الأخطاء وقت حدوثها على السيرفر؟

إذا رفعت المشروع على السيرفر وأردت تتبع الأخطاء لحظة بلحظة، افتح الـ Terminal واكتب:

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)

ادخل لمجلد المشروع على السيرفر، ونفذ السكريبت الذي قمنا بإعداده (تمت كتابته بعناية لتجنب تدمير أي شيء):

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 الخاص بالمشروع:

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:

sudo systemctl reload nginx

---

🎯 5. الخلاصة

المشروع الآن عبارة عن صندوق أسود آمن جداً. كل ما يدخل له يتم فحصه وتشفيره، وكل ما يخرج منه يكون سريعاً وموثوقاً.

• في حال حدوث خطأ: راجع storage/logs/laravel.log.
• لتغيير إعداد: عدل فقط في ملف .env.
• لمزامنة التغييرات المبرمجة: استخدم git pull.

بهذا تكون قد انتقلت بـ Intaleq إلى مصاف التطبيقات العالمية من ناحية البنية التحتية.