المصادقة والتفويض

نظرة عامة

تستخدم شام باص أكثر من مسار مصادقة بحسب السطح:

التطبيق	طريقة المصادقة	ملاحظات
بوابة العملاء	OTP عبر الهاتف	جلسة cookies + refresh
لوحة الشركات	بريد إلكتروني + كلمة مرور	حسب صلاحيات الشركة والجلسة الحالية
لوحة الإدارة	بريد إلكتروني + كلمة مرور + 2FA عند الحاجة	RBAC وتدقيق أمني
تطبيق السائق	تدفق تشغيلي مرتبط بحساب السائق	يعتمد على الإعداد الحالي للتطبيق

أين يظهر هذا العقد؟

• بوابة العملاء
• تطبيق العملاء
• لوحة الشركات
• لوحة الإدارة

ملاحظة

هذا المرجع يركز على العقود الحالية وخصوصاً مصادقة العملاء. إذا تغيّر عقد route handler فعلياً، فالأولوية للتنفيذ في المستودع.

مصادقة العملاء (OTP)

التدفق الكامل

1. يرسل العميل رقم الهاتف
2. يطلب القناة عبر الحقل method
3. ترسل المنصة رمز OTP عبر القناة المطلوبة أو تستخدم fallback عند الحاجة
4. يتحقق الخادم من الرمز
5. يضبط الخادم جلسة عبر HttpOnly cookies
6. تستخدم الواجهة مسار refresh لتجديد الجلسة عند الحاجة

إرسال OTP

POST /api/auth/customer/send-otp
Content-Type: application/json

{
  "phone": "+963912345678",
  "method": "sms"
}

ملاحظات العقد الحالي:

• الحقل المعتمد هو method وليس channel
• القنوات الجديدة في الواجهات: sms و telegram
• sms هو الافتراضي ويستخدم مزود Verify يملك توليد الرمز وصلاحيته ومحاولات التحقق
• قيمة whatsapp مقبولة مؤقتاً للتوافق مع إصدارات قديمة، لكنها تتحول إلى SMS ولا تتصل بأي خدمة من Meta
• telegram يستخدم Chat ID يدوي أو رابط رقم محفوظ من خدمة بوت تيليجرام

إعداد مزود SMS:

OTP_PROVIDER=twilio
TWILIO_ACCOUNT_SID=<account-sid>
TWILIO_AUTH_TOKEN=<auth-token>
TWILIO_VERIFY_SERVICE_SID=<verify-service-sid>

أو مزود خارجي معتمد يطبق عقد Sham Bus Verify:

OTP_PROVIDER=external
OTP_EXTERNAL_PROVIDER_NAME=<vendor-name>
OTP_EXTERNAL_BASE_URL=https://verify.vendor.example
OTP_EXTERNAL_API_KEY=<server-only-key>

قبل الإطلاق فقط، يمكن استخدام OTP_PROVIDER=disabled مع PUBLIC_SITE_MODE=coming-soon. يسمح هذا بالرمز المحلي لهويات العرض المحجوزة +963900... فقط، ويعيد 503 لأي رقم حقيقي من دون الاتصال بـMeta أو أي مزود آخر. يرفض النشر هذا الوضع عند تحويل الموقع إلى live.

العقد الكامل موثق في عقد مزود OTP الخارجي. لا تعرض مفاتيح المزود أو رسائل الخطأ الخام للعميل.

مثال تيليجرام:

{
  "phone": "+963912345678",
  "method": "telegram",
  "telegramChatId": "123456789"
}

يتطلب تيليجرام إعداد TELEGRAM_BOT_TOKEN في بيئة الخادم. الطريقة المفضلة هي تشغيل خدمة telegram-bot في Docker وطلب مشاركة رقم الهاتف من المستخدم عبر البوت، ثم يستطيع مسار OTP حل chat_id تلقائياً من الرقم. إذا لم يكن الرقم مربوطاً، يمكن للعميل إرسال telegramChatId يدوياً.

استجابة نموذجية:

{
  "success": true,
  "message": "تم إرسال رمز التحقق عبر رسالة نصية SMS",
  "fallbackToSms": false,
  "actualChannel": "sms"
}

في بيئات التطوير فقط قد تظهر حقول إضافية مثل devMode أو otpCode عندما يفعّل ذلك صراحة لأغراض التطوير المحلي.

التحقق من OTP

POST /api/auth/customer/verify-otp
Content-Type: application/json

{
  "phone": "+963912345678",
  "code": "123456",
  "method": "telegram",
  "name": "أحمد محمد",
  "email": "ahmed@example.com"
}

استجابة نموذجية:

{
  "success": true,
  "data": {
    "user": {
      "id": "uuid",
      "phone": "+963912345678",
      "name": "أحمد محمد",
      "email": "ahmed@example.com"
    },
    "isNewUser": false,
    "emailVerificationPending": false
  }
}

ملاحظات مهمة:

• الجلسة تضبط في cookies آمنة من نوع HttpOnly
• لا تعتمد على body token كعقد رئيسي للعميل الحديث
• قد يعيد المسار معلومات عن emailVerificationPending
• عند عدم إرسال method في الإرسال أو التحقق، يعامل الطلب كـ whatsapp

تحديث الجلسة

POST /api/auth/customer/refresh

السلوك الحالي:

• يقرأ refresh token من cookie أولاً
• ما زال يقبل refreshToken في body كتوافق خلفي

استجابة نموذجية:

{
  "success": true,
  "data": {
    "token": "new_jwt_token",
    "refreshToken": "new_refresh_token",
    "expiresAt": 1713176400
  }
}

بيانات المستخدم الحالي

GET /api/auth/customer/me

استجابة نموذجية:

عند عدم وجود جلسة زائر، يرجع المسار:

{
  "data": null
}

إذا وُجدت جلسة أو ترويسة تفويض غير صالحة، يرجع 401.

{
  "data": {
    "id": "uuid",
    "phone": "+963912345678",
    "name": "أحمد محمد",
    "email": "ahmed@example.com",
    "gender": "",
    "nationalId": "",
    "created_at": "2026-04-11T10:00:00.000Z"
  }
}

تسجيل الخروج

POST /api/auth/customer/logout

يقوم هذا المسار بإنهاء الجلسة الحالية، تنظيف cookies ذات الصلة، ومنع إعادة استخدام التوكنات وفق السلوك الأمني الحالي.

مصادقة لوحات التشغيل

هذه الصفحة تعطي مرجعاً عالياً فقط لسطحي الشركة والإدارة. التوثيق الدقيق للعقود يجب أن يراجع من route handlers الفعلية عند أي تغيير مهم.

أدوار الشركة الشائعة

الدور	الاستخدام
OWNER	إدارة الحساب والصلاحيات العليا
ADMIN	تشغيل يومي وصلاحيات واسعة
DISPATCHER	تشغيل الرحلات والحجوزات
STAFF	مهام تشغيلية أو مكتبية بحسب التفعيل

الإدارة وRBAC

أمثلة على صلاحيات الإدارة:

• companies.view
• companies.manage
• tickets.view
• tickets.manage
• admins.view
• admins.manage
• analytics.view
• audit.view

وقد يتبع تسجيل الدخول خطوة 2FA بحسب حالة الحساب الإداري.

ملاحظات تنفيذية

• مصادقة العملاء الآن cookie-first
• لا تنشر أي توكنات أو أسرار فعلية داخل الوثائق
• عند أي تغيير عقدي مهم، حدّث هذه الصفحة مع واجهات العملاء