tripz-llc/docs/08-data-model.md

08 — نموذج البيانات

PostgreSQL 16 + PostGIS. كل جدول عملياتي فيه tenant_id (عدا الجداول العالمية المعلّمة 🌐). فهارس مكانية للسائقين القريبين ومناطق التعرفة.

الجداول الأساسية

الاستئجار

🌐 tenants        id, name, slug, country_pack, plan, mode(shared|sovereign),
                  branding jsonb, features jsonb, status, created_at
🌐 country_packs  code, config jsonb          (أو ملفات في المستودع)
   tenant_config  tenant_id, key, value       (تجاوزات ديناميكية)

المستخدمون والأدوار

users     id, tenant_id, phone, name, role(rider|driver|dispatcher|admin),
          status, created_at
drivers   id, tenant_id, user_id, vehicle_id, docs jsonb, verification_status,
          rating, is_online, last_location geography(Point)   ← فهرس GIST
vehicles  id, tenant_id, driver_id, plate, model, service_class, color, docs

الرحلات

trips        id, tenant_id, rider_id, driver_id, service_class,
             origin geography(Point), destination geography(Point),
             status, tariff_version, quoted_fare, final_fare, currency,
             payment_method, requested_at, assigned_at, completed_at
trip_events  id, trip_id, tenant_id, from_status, to_status, source,
             payload jsonb, created_at          ← سجل الانتقالات (تشخيص + منظّم)
ratings      id, tenant_id, trip_id, by_role, stars, comment
chat_messages id, tenant_id, trip_id, sender_id, body, created_at

التعرفة والمناطق

tariffs        id, tenant_id, city, service_class, definition jsonb,
               version, active_from, active
pricing_zones  id, tenant_id, name, area geography(Polygon)   ← فهرس GIST
zone_matrix    id, tenant_id, from_zone, to_zone, price

الدفع والفوترة

payments   id, tenant_id, trip_id, provider, amount, currency, status, tx_ref
payouts    id, tenant_id, driver_id, amount, period, status
usage      id, tenant_id, period, completed_trips, gmv, currency   ← يغذّي الفوترة
invoices   id, tenant_id, period, base_fee, gmv_fee, min_applied,
           total, status, pdf_url                                  ← فاتورتنا للمستأجر

الإشعارات والتكامل

device_tokens  id, tenant_id, user_id, fcm_token, platform
webhooks       id, tenant_id, url, events[], secret, active

العلاقات (مبسّطة)

tenant 1─* users 1─1 drivers 1─* vehicles
tenant 1─* trips *─1 rider(users)  trips *─1 driver(drivers)
trip 1─* trip_events   trip 1─1 payment   trip 1─* chat_messages
tenant 1─* tariffs   tenant 1─* pricing_zones
tenant 1─* usage 1─1 invoice(period)

قواعد

• الهجرات فقط (migrations)؛ لا synchronize في الإنتاج.
• فهارس GIST على كل عمود geography.
• فهرس مركّب يبدأ بـ tenant_id على الجداول عالية الاستعلام (trips, users, drivers).
• soft-delete (deleted_at) لا حذف صلب — بيانات المنظّم والتدقيق.
• الحضور اللحظي وموقع السائق الجاري في Redis (لا Postgres) — راجع 09-realtime.

← السابق: 07-integrations · التالي: 09-realtime