126 lines
8.6 KiB
Markdown
126 lines
8.6 KiB
Markdown
# 📖 الدليل الشامل لـ 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 إلى مصاف التطبيقات العالمية من ناحية البنية التحتية.
|