واجهات برمجة لوحة التحكم

Base URL: https://dashboard.shambus.com/api | http://localhost:3001/api

جميع الطلبات تتطلب مصادقة مستخدم الشركة.

نطاق الصفحة

هذه الصفحة تركز على عائلات العقود الأعلى أهمية تشغيلياً في لوحة الشركات، لا كل endpoint منخفض الخطورة بالتفصيل نفسه.

قواعد الوصول العامة

• عمليات القراءة تتحقق من عضوية المستخدم في الشركة المالكة للبيانات
• عمليات الكتابة تتحقق من أن الشركة نشطة وغير موقوفة
• بعض العمليات تتطلب شركة موثقة قبل السماح بالتعديل
• العمليات الحساسة قد تتطلب أدواراً مثل OWNER أو ADMIN أو ACCOUNTANT

عائلات العقود عالية الأولوية

العائلة	لماذا هي مهمة
settings/team	الصلاحيات وهوية الشركة
payments	التحصيل والحالة المالية التشغيلية
reports/analytics	التصدير وثقة الأرقام
tracking	مباشر/متأخر/غير متاح
trips/bookings	قلب التشغيل اليومي
cities/routes	تعريف المدن ومسارات الشركة
buses/layouts	تخطيط المقاعد مصدره حاسم للحجز

المصادقة

POST /auth/login

يعتمد المسار على جلسة مستخدم الشركة، وليس على عقد العملاء.

الرحلات والحجوزات

GET /trips
POST /trips
GET /trips/{id}/dispatch
POST /trips/{id}/dispatch
POST /trips/bulk
GET /trip-schedules
POST /trip-schedules
GET /bookings
GET /bookings/{id}
PATCH /bookings/{id}/status

هذه العائلة تغطي الإدارة اليومية للرحلات والحجوزات وتبقى مرتبطة بصلاحيات الشركة النشطة.

GET /trips يقبل date كتاريخ تشغيل بتوقيت دمشق ويرتب ذلك اليوم تصاعدياً. عند غياب التاريخ يعمل كسجل كامل مرتب تنازلياً. تعيد اللقطة عدادات كل حالات الرحلة ومعلومات السائق والتأخير والأوقات الفعلية مع pagination من الخادم.

يعيد GET /trips/{id}/dispatch الرحلة وتجهيز الباص والسائق وكشفاً على مستوى المسافر من get_company_trip_dispatch_v2 وعدادات الحضور وعوائق الجاهزية والإجراءات المسموحة وآخر 25 حدثاً تشغيلياً.

يقبل POST /trips/{id}/dispatch إجراءً واحداً من:

• START_BOARDING, MARK_DELAYED, DEPART, ARRIVE, COMPLETE, CANCEL
• CHECK_IN, MARK_NO_SHOW, RESTORE

تتطلب إجراءات الحضور manifest_item_id وmanifest_item_type، وتستخدم JOURNEY_TICKET لكل مسافر حديث أو BOOKING فقط للتوافق مع الحجز القديم. يقبل MARK_NO_SHOW سبباً تشغيلياً اختيارياً ويعيد RESTORE المسافر نفسه. يتطلب التأخير reason وdelay_minutes، ويتطلب الإلغاء reason. تمر كل كتابة عبر RPC مقيد بالشركة يقفل الرحلة وهوية المسافر ويفحص التسلسل والجاهزية ويزامن التكليف والحجز ويكتب سجل التشغيل في المعاملة نفسها.

برنامج ولاء الشركة

GET /loyalty?search=&limit=50&offset=0
PUT /loyalty
POST /loyalty/rewards
PUT /loyalty/rewards/{id}
DELETE /loyalty/rewards/{id}
POST /loyalty/tiers
PUT /loyalty/tiers/{id}
POST /loyalty/accounts/{id}/adjust

تتطلب هذه المسارات عضوية شركة موثقة بدور OWNER أو ADMIN. لا تقبل company_id من جسم العميل؛ تستمد النطاق من العضوية الفعالة وتضيفه إلى كل قراءة أو كتابة. تتطلب الكتابات CSRF، ويمنع العقد رصيداً سالباً أو مسار مكافأة لا تملكه الشركة.

يقبل PATCH /bookings/{id}/status قرار الشركة على طلب Journey بحالة PENDING_CONFIRMATION. يقرأ الخادم طلب الشركة من النطاق الموثق ثم يستدعي decide_company_booking_confirmation بمفتاح idempotency ثابت. لا يسمح fallback إلى تحديث الحجز القديم إذا كان طلب Journey مفقوداً أو مغلقاً؛ يعيد 409 JOURNEY_CONFIRMATION_STATE_CONFLICT حتى لا تُؤكد قطعة واحدة أو تُصدر تذكرة قبل بقية الشركات المشغلة. تبقى حالات الحضور وعدم الحضور والإكمال ضمن غرفة التشغيل.

بعد التأكيد لا يسمح المسار نفسه بإلغاء صف bookings التوافقي وحده؛ يعيد 409 JOURNEY_AGGREGATE_OPERATION_REQUIRED. تعرض مساحة العمل رابط غرفة تشغيل الرحلة بدلاً من زر إلغاء مضلل، لأن الإلغاء التشغيلي أو إعادة التسكين يجب أن يحدثا عبر أمر aggregate-aware يحافظ على Journey وOrder والتذاكر والمخزون والاتصالات كحقيقة واحدة.

يقبل POST /trips/bulk الأوامر المقابلة بأسماء صغيرة على قائمة لا تتجاوز 50 معرفاً. يزيل التكرار ويعيد نتيجة مستقلة لكل رحلة وملخصاً صريحاً للناجح والفاشل؛ لا ينفذ تحديثاً مباشراً على جدول الرحلات. مسار PATCH /trips/{id} القديم باقٍ للتوافق لكنه يستخدم معاملة الانتقال نفسها ويتطلب سبب التأخير أو الإلغاء.

POST /trips يتطلب أن يكون للباص المختار تخطيط مقاعد صالح ونشط. التخطيطات الجديدة يجب أن تكون layout_document فعالة ومتحققاً منها؛ يسمح fallback القديم فقط للباصات المرحّلة قبل التخطيط القانوني.

يتطلب إنشاء الرحلة أيضاً pickup_stop_id. يجلب GET /pickup-locations?city_id={originCityId} النقاط العامة ونقاط الشركة المفعلة في مدينة المنشأ، وينشئ POST /pickup-locations نقطة شركة جديدة بعد CSRF وصلاحية التشغيل والتحقق من الاسم والعنوان والإحداثيات. تستخدم كتابة الرحلة RPC مقفلاً يمرر النقطة داخل المعاملة؛ وتعيد غرفة التشغيل snapshot النقطة نفسها مع حالة تأكيدها. يرفض الخادم نقطة من مدينة أخرى أو شركة أخرى، ويرفض تغيير نقطة رحلة لديها حجوزات.

يستخدم POST /trip-schedules عقداً واحداً للمعاينة والإنشاء. الحقول الأساسية هي route_id, pickup_stop_id, bus_id, driver_id, start_date, end_date, departure_time, days_of_week, duration_minutes, price_base, price_vip, وnotes. يحدد commit=false معاينة بلا كتابة، بينما يعيد commit=true فحص التعارضات داخل المعاملة قبل إنشاء الرحلات. لا يتجاوز النطاق 180 يوماً. عند وجود تعارضات يجب أن يكون قرار skip_conflicts صريحاً، ولا يُنشأ جدول فارغ إذا لم يبق أي موعد صالح. GET /trip-schedules يعيد أحدث السلاسل المقيدة بالشركة للمستخدمين ذوي صلاحية التشغيل.

الباصات وتخطيط المقاعد

GET /bus-templates
GET /buses/{id}/layout
PUT /buses/{id}/layout
DELETE /buses/{id}/layout

قواعد العقد:

• PUT /buses/{id}/layout يقبل layoutDocument أو layout_document فقط، مع saveMode بقيمة draft أو active.
• التخطيط القانوني يحتوي schemaVersion, grid, وelements بإحداثيات x, y, width, height, rotation, وdeck.
• كل مقعد يحتوي seatId ثابت وseatNumber ظاهر للراكب. تغيير رقم المقعد لا يغير seatId.
• الحفظ يتم عبر RPC قاعدة البيانات save_bus_layout_document لتحديث bus_layouts, bus_layout_positions, وbuses.capacity في معاملة واحدة.
• bus_layout_positions لا يكتب مباشرة في ميزات جديدة؛ هو إسقاط توافق مشتق.
• التخطيط النشط المستخدم في حجز العميل يجب أن يكون status=active وvalidation_status=valid.
• DELETE /buses/{id}/layout يؤرشف التخطيط بدلاً من حذفه، ويرفض العملية إذا كان الباص مستخدماً في رحلات لديها حجوزات.
• استجابة العميل تعرض نسخة آمنة من التخطيط وتحذف الحقول الداخلية مثل ملاحظات الإدارة.

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

GET /cities
POST /cities
GET /routes
POST /routes

يسمح POST /cities لمستخدم شركة مصادق ومتحقق من شركته بإضافة مدينة غير موجودة أثناء إنشاء مسار جديد. إذا كان الاسم موجوداً مسبقاً، يعيد المسار المدينة الحالية بدلاً من إنشاء نسخة مكررة. كل عمليات الكتابة تستخدم CSRF وجلسة لوحة الشركة.

الإعدادات والفريق

GET /settings
PATCH /settings
PUT /settings/booking-confirmation
GET /team

يقتصر PUT /settings/booking-confirmation على OWNER وADMIN في شركة موثقة، ويحتاج CSRF. يقبل وضع AUTO_CONFIRM أو MANUAL_CONFIRM، نافذة قرار من 15 إلى 1,440 دقيقة، ومجموعة غير فارغة من CUSTOMER_WEB, CUSTOMER_MOBILE, وRESELLER. يحل الخادم Company والفاعل من الجلسة ولا يقبلهما من جسم الطلب.

ملاحظات:

• من أعلى العائلات حساسية من ناحية الصلاحيات
• عند غياب الصلاحية أو تعليق الشركة يجب أن تكون النتيجة صريحة

المدفوعات

GET /payments
GET /payments/{id}
PATCH /payments/{id}
POST /payments/{id}/verify
POST /payments/{id}/refund
POST /payments/{id}/cancel
GET /payments/receipts/{source}/{id}?locale=ar
GET /payments/cash-shifts
POST /payments/cash-shifts
GET /payment-settings

GET /payments يعيد دفتر تحصيل موحداً مع pagination وإحصاءات، ويقبل مرشحات status, provider, source, date, وsearch. تجمع النتيجة سجلات عمليات الدفع، تحصيل السائق، حجوزات المكتب، وحقيقة دفع الحجز من دون عد المبلغ مرتين.

تعمل إجراءات verify, refund, وcancel عبر معاملات PostgreSQL تقفل العملية والحجز وتثبت المستخدم الذي اتخذ القرار وتزامن حقيقة دفع الحجز. الاسترداد الحالي كامل فقط؛ لا يقبل المسار مبلغاً جزئياً كي لا يوسم الحجز كله كمسترد مقابل إعادة جزء من المبلغ. يقتصر الإلغاء على العملية غير المكتملة، بينما يسمح PATCH بتعديل الملاحظة فقط قبل وصول العملية إلى حالة نهائية.

يتطلب اعتماد تحصيل نقدي صندوقاً مفتوحاً ويربط العملية به. يدعم مسار cash-shifts إجراءات OPEN, ADJUST, وCLOSE لصندوق واحد مفتوح لكل شركة، مع رصيد بداية وحركات موثقة ومبلغ متوقع ومعلن وفارق الإغلاق. هذه العقود متاحة لمالك الشركة ومديرها النشط فقط.

لا يملك دور authenticated حق الكتابة المباشرة إلى bookings أو payment_transactions. يجب أن تمر الكتابة من عقود المجال المصرح بها. الدفع الإلكتروني غير متاح في الإنتاج، ومسار webhook لا يقرأ payload ولا يغير البيانات: يعيد 404 عند التعطيل و501 OFFICIAL_CONTRACT_REQUIRED في وضع التطوير. لا يوجد توقيع HMAC مفترض قبل وصول عقد رسمي من المزود.

المرجع هنا تشغيلي، ويجب عدم افتراض دفع إلكتروني عام لمجرد وجود حالة دفع في الواجهة.

GET /payments/receipts/{source}/{id} يقبل source بقيمة transaction, driver, office, أو booking. يتطلب دوراً مالياً صالحاً وtenant مطابقاً، ولا يصدر إيصالاً لسجل غير مكتمل. الإيصال وإشعار الاسترداد مستندان مختلفان برقم ثابت وsnapshot غير قابل للتعديل؛ يسجل API checksum قبل إعادة PDF خاص بـno-store.

التقارير والتحليلات

GET /reports?type=revenue&fromDate=2026-08-01&toDate=2026-08-31&format=pdf&locale=ar
GET /analytics?period=monthly
GET /analytics?period=weekly
GET /analytics?period=daily
GET /analytics/advanced?days=14

يجب فهم النتيجة ضمن واحدة من الحالات المرجعية: بيانات جاهزة، لا توجد بيانات، غير مصرح، أو فشل التصدير.

يدعم GET /reports أنواع revenue, bookings, trips, وoccupancy، وصيغ csv, json, وpdf. يجب أن تكون اللغة ar أو en. CSV يحمل BOM لتوافق Excel، وPDF يستخدم هوية الشركة وتقرير A4 أفقي tagged مع رأس جدول متكرر. تصدر الفترة التي لا تحتوي بيانات ملفاً صالحاً بحالة no_data بدلاً من خطأ متناقض. كل PDF يسجل checksum وrow count وحالة التقرير في document_render_events.

مسار GET /analytics متاح لدوري OWNER وADMIN فقط. يعيد لقطة واحدة تشمل المؤشرات والإيراد اليومي والشهري واتجاهات الحجز وأداء المسارات وتكرار سفر العملاء. تُجمع النتائج داخل PostgreSQL عبر get_dashboard_analytics_snapshot(company_id)؛ لا تُرسل الواجهة قوائم معرفات الرحلات داخل URL، ولا تعتمد الأعداد على حد صفوف PostgREST. القيم الجغرافية والعمرية تبقى مصفوفات فارغة إلى أن يخزن ملف الراكب هذه البيانات فعلياً، بدلاً من استنتاجها من رقم الهاتف.

تعيد لقطة النظرة العامة السلاسل اليومية والأسبوعية والشهرية معاً، لذلك يبدّل المتصفح الفترة من البيانات المحملة من دون طلب جديد. يحمّل مسار GET /analytics/advanced التحليلات الثقيلة عند فتح تبويبها فقط، في استدعاء RPC واحد مقيد بالشركة. يقبل days عدداً صحيحاً من 7 إلى 30 لتحديد أفق توقع الإيراد. تشمل النتيجة الإلغاءات والاحتفاظ وتوقع الإيراد وترتيب المسارات ووقت الحجز المسبق. لا تنزّل هذه الواجهة صفوف الحجوزات الخام ولا تعتمد على حد PostgREST.

التتبع

GET /tracking/active-trips

هذه العائلة تقرأ حالة الرحلات النشطة ومصدر البيانات وآخر تحديث معروف.

source of truth

المرجع النهائي هو route handlers تحت apps/dashboard/src/app/api.