Update: 2026-07-07 04:57:50

docs/siro_comprehensive_report.md

@@ -0,0 +1,67 @@
+<div dir="rtl" align="right">
+
+# تقرير المراجعة الشاملة لمشروع Siro
+
+## 1. مقدمة ونظرة عامة
+يُظهر مشروع Siro معمارية متطورة جداً تعتمد على فصل الخدمات (Microservices) والتسعير الديناميكي الذكي. النظام لا يعتمد على الطرق التقليدية في حساب التكلفة، بل يستخدم خوارزميات ذكاء اصطناعي لتحليل السوق وتعديل الأسعار.
+
+## 2. نظام التسجيل والمصادقة (التطبيقات الأربعة)
+النظام يدعم 4 تطبيقات رئيسية (Siro Rider, Siro Driver, Siro Admin, Siro Service).
+- **أمان عالي**: تم استخدام `Rate Limiter` لمنع هجمات الـ Brute-Force.
+- **التوكن المؤقت (One-Time Token)**: في تسجيل السائقين (`loginFirstTimeDriver.php`)، يتم استخدام توكن لمرة واحدة مخزن في Redis، مما يمنع استخدام كلمات مرور ثابتة قابلة للاختراق.
+- **توثيق البصمة**: يتم دمج البصمة (Fingerprint) مع (Pepper) لتوليد JWT آمن وصلاحية قصيرة (150 ثانية للراكب، و 3600 للسائق) كتوكن تسجيل مبدئي.
+
+## 3. دورة حياة الرحلة (Trip Lifecycle)
+دورة الرحلة مكتوبة بطريقة احترافية تعتمد على (Transactions) لضمان عدم فقدان البيانات:
+- **بدء الرحلة (`start_ride.php`)**:
+  - يتم قفل السعر للرحلات الثابتة (Immutable Fare Lock) وحفظه في Redis لمدة 24 ساعة، مما يمنع أي تلاعب من جهة العميل.
+  - يتم تصفير ديون الراكب من Redis ومعالجة المحفظة.
+  - إشعارات فورية عبر (Sockets) و (FCM).
+- **إنهاء الرحلة وحساب السعر (`finish_ride_updates.php`)**:
+  - **حساب السعر على الخادم (Server-Side)**: التطبيق لا يرسل السعر، بل يرسل المسافة والوقت، ويقوم الخادم بحساب السعر بناءً على تسعيرة الدولة في جدول `kazan`.
+  - **التزامن الذري (Atomic Transaction)**: يتم تحديث قواعد البيانات (Local & Remote) بشكل ذري، وإذا فشلت خطوة، يتم التراجع عن الكل (Rollback).
+  - **الاتصال بخادم الدفع (S2S)**: يتم الاتصال بمخدم الدفع الخارجي (`walletintaleq`) باستخدام `cURL` ومفاتيح سرية (`X-S2S-Api-Key`).
+  - **المكافآت (Streaks)**: النظام يتحقق من تتابع قبول الطلبات للسائق، ويعطيه رحلة بدون عمولة (Zero Commission) إذا كان مؤهلاً.
+
+## 4. التسعير الذكي ومهام الـ Cron
+هذا الجزء هو الأكثر تعقيداً وذكاءً في المشروع:
+- **محرك التسعير (Pricing Engine - Node.js)**: 
+  - يقرأ أسعار المنافسين.
+  - يزيل الشذوذ في البيانات باستخدام (MAD).
+  - يصنف الأسعار لثلاث مستويات (Economy, Standard, Premium) باستخدام (K-Means).
+  - يستخرج معادلة التسعير (Base + KM + Min) باستخدام الانحدار الخطي (Multiple Linear Regression).
+- **محرك الذكاء الاصطناعي (`cron_ai_engine.php`)**:
+  - يقرأ المعادلات الناتجة ويطبق خصم 6.5% ليظل السعر تنافسياً.
+  - يحدد المناطق الساخنة (Hotzones) والـ (Surge) ويصدرها إلى Redis.
+- **التسويق الآلي (Smart Retention)**: يستهدف الركاب الخاملين الذين فتحوا التطبيق ولم يطلبوا.
+
+## 5. نظام Redis والأداء
+تم استخدام Redis ببراعة لتقليل الضغط على قاعدة البيانات:
+- تخزين قفل الأسعار (Fare Locks).
+- إدارة التوكنات المؤقتة.
+- تخزين الديون المؤقتة (Debt caching).
+- تخزين المناطق الساخنة والـ Surge بمدة صلاحية قصيرة (TTL) لضمان تحديثها.
+- تقييد الطلبات (Rate Limiting) على الـ APIs.
+
+## 6. معمارية الخوادم
+- **قواعد بيانات منفصلة**: النظام يستخدم `con` للمحلي و `con_ride` لخادم الرحلات، مما يعكس توزيعاً للحمل.
+- **خادم المحفظة (Wallet Server)**: مفصول بالكامل عن النظام الأساسي ويتواصل عبر S2S.
+- **خادم الموقع (Location Server)**: يتم الاتصال به لتحديث حالة السائق والرحلة.
+
+## 7. جاهزية واجهة المستخدم (UI Readiness)
+التطبيقات الأربعة مبنية باستخدام Flutter (بناءً على ملفات `pubspec.yaml`).
+- **الهيكلة**: التطبيقات مفصولة بوضوح وتم استخدام حزم متنوعة.
+- **الإشعارات**: دمج كامل مع Firebase (FCM).
+- **الخريطة والتتبع**: تم استخدام إضافات مثل `trip_overlay_plugin` في تطبيق السائق للرسم على الشاشة وفوق التطبيقات الأخرى.
+
+## 8. الخلاصة والتوصيات
+المشروع متقدم جداً ومبني على أسس قوية. نظام الأمان ممتاز ومعمارية الخوادم تدعم التوسع (Scalability).
+
+**ملاحظات لتحسين الأداء:**
+1. التأكد من وجود فهارس (Indexes) على الجداول الكبيرة مثل `ride` و `scraped_competitor_prices` لتسريع القراءة في محرك التسعير.
+2. مراقبة استهلاك الذاكرة في Redis خصوصاً مع استخدامات הـ Hotzones والـ Fare Locks بشكل مكثف.
+3. التأكد من وجود نظام لمراقبة الأخطاء (مثل Sentry) في نظام S2S Payment للتعامل السريع مع أي فشل في الدفع.
+4. مراجعة كود Flutter للتأكد من عدم وجود State Management ثقيل يؤثر على بطارية هاتف السائق أثناء التتبع الطويل.
+
+جهد جبار وعمل متقن جداً!
+</div>