HamzaandClaude Opus 4.8
95fea546f5
- docs/00-15: دراسة، بنية، محرك تعرفة، تسعير، نموذج استئجار، تكاملات، بيانات، realtime، خطة، devops، لاندنج، مخاطر، اصطلاحات سيرفر، تدفق نشر - backend/: NestJS 11 على Docker (health + tenants + عزل tenant_id + بادئة tripz_ + Redis DB 3) - apps/rider, apps/driver, dashboards/admin-web, dashboards/superadmin-web (هياكل) - sync-to-server.sh + .gitignore Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
62 lines
5.6 KiB
Markdown
62 lines
5.6 KiB
Markdown
# 01 — البنية العامة
|
|
|
|
## المخطط العلوي
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ عملاء التطبيق (Flutter) │
|
|
│ راكب سائق مشغّل (Dispatch) إدارة (Web/Admin) │
|
|
└──────┬──────────┬──────────────┬────────────────────┬────────────┘
|
|
│ REST │ REST + WS │ REST + WS │ REST
|
|
▼ ▼ ▼ ▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ API Gateway / NestJS │
|
|
│ Guards (Auth, Tenant, Roles) → Interceptors (Usage, Logging) │
|
|
│ ┌──────────┬──────────┬──────────┬──────────┬──────────────┐ │
|
|
│ │ auth │ trips │ tariff │ dispatch │ billing │ │
|
|
│ │ tenants │ drivers │ payments │ maps │ notifications│ │
|
|
│ └──────────┴──────────┴──────────┴──────────┴──────────────┘ │
|
|
│ WebSocket Gateway (Socket.IO) │
|
|
└──────┬─────────────────┬────────────────┬───────────────┬────────┘
|
|
▼ ▼ ▼ ▼
|
|
┌────────────┐ ┌──────────────┐ ┌──────────┐ ┌──────────────┐
|
|
│ PostgreSQL │ │ Redis │ │ انطلق │ │ BullMQ │
|
|
│ + PostGIS │ │ presence/ │ │ Maps: │ │ (jobs queue) │
|
|
│ tenant_id │ │ matching/ │ │ Martin/ │ │ إشعارات/تقارير│
|
|
│ everywhere │ │ pub-sub │ │ geocode/ │ │ /تسويات │
|
|
└────────────┘ └──────────────┘ │ routing │ └──────────────┘
|
|
└──────────┘
|
|
▲
|
|
│ Adapters (country pack يفعّلها)
|
|
┌──────┴───────────────────────────────────────────────────────────┐
|
|
│ الدفع (كاش/CliQ/زين/سيرياتيل/MTN/Binance) · SMS/OTP · واجهة المنظّم │
|
|
└──────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## الطبقات (من الخارج للداخل)
|
|
1. **العملاء (Flutter):** 4 واجهات من كود موحّد + flavor لكل مستأجر. تفاصيل: [03-mobile-plan](03-mobile-plan.md).
|
|
2. **API Gateway (NestJS):** كل طلب يمر بـ Guards ثم Interceptors. تفاصيل: [02-backend-plan](02-backend-plan.md).
|
|
3. **الطبقة الحية (Socket.IO):** موقع السائق، العروض، التتبع، لوحة dispatch. تفاصيل: [09-realtime](09-realtime.md).
|
|
4. **التخزين:** PostgreSQL/PostGIS (مصدر الحقيقة) + Redis (حالة لحظية) + BullMQ (مهام غير متزامنة).
|
|
5. **الخرائط:** انطلق ذاتي (بلاطات/ترميز/توجيه). طبقة تجريد تسمح بتبديل المزوّد.
|
|
6. **التكاملات:** محوّلات (Adapters) يفعّلها الـ country pack. تفاصيل: [07-integrations](07-integrations.md).
|
|
|
|
## تدفق نموذجي — «طلب رحلة»
|
|
```
|
|
1. الراكب يطلب → POST /trips (Guard: Auth+Tenant → Interceptor: Usage++)
|
|
2. الباك إند → tariff.quote() يحسب السعر المقفول
|
|
3. الباك إند → matching (Redis GEO) يجد أقرب سائقين مؤهلين
|
|
4. Socket → يبث العرض للسائقين المرشحين (Bloc عرض السائق)
|
|
5. سائق يقبل → trip.assign() → Postgres + Socket للراكب (Bloc دورة الرحلة)
|
|
6. تتبع حي → Socket كل 3–5 ثوانٍ (موقع السائق مجمّع)
|
|
7. إنهاء → tariff.finalize() → دفع كاش → تقييم
|
|
8. BullMQ → تسوية GMV + قياس usage للفوترة الشهرية
|
|
```
|
|
|
|
## حدود المسؤولية
|
|
- **مصدر الحقيقة الدائم:** PostgreSQL فقط. Redis حالة عابرة قابلة لإعادة البناء.
|
|
- **قياس الاستخدام (Usage):** Interceptor يسجّل كل رحلة مكتملة → يغذّي [الفوترة](05-pricing-billing.md).
|
|
- **العزل بين المستأجرين:** `tenant_id` إلزامي في كل استعلام عبر نطاق على مستوى الـ Repository. تفاصيل: [06-tenant-model](06-tenant-model.md).
|
|
|
|
← السابق: [00-overview](00-overview.md) · التالي: [02-backend-plan](02-backend-plan.md)
|