الاتفاقيات

غلاف الاستجابة

كل نجاح أو خطأ JSON يبدو هكذا:

{
  "success": true,
  "statusCode": 200,
  "statusMessage": "SUCCESS",
  "results": {},
  "error": null
}

عند الفشل يكون results هو null ويحمل error الحمولة (رسالة وأخطاء حقول اختيارية):

{
  "success": false,
  "statusCode": 401,
  "statusMessage": "AUTHENTICATION_REQUIRED",
  "results": null,
  "error": {
    "message": "يلزم تسجيل الدخول"
  }
}

statusMessage تعداد ثابت. راجع الأخطاء. لا تتفرع على نص message المترجم.

فئات المصادقة

التسمية	المعنى
عامة	بلا JWT مطلوب. الضيوف مسموحون.
عميل	Authorization: Bearer <accessToken> من التحقق من OTP أو التحديث. الغياب / الانتهاء → 401. حدّث مرة ثم عامل كخروج.
موظف	Authorization: Bearer <accessToken> من دخول الموظف أو التحديث. الغياب / الانتهاء → 401.
موظف + orders:read	GET للتجهيز
موظف + orders:update	POST لإجراءات التجهيز

إرفاق العميل اختياري على مسارات الكتالوج: إن وُجد JWT يُحمَّل، لكن الضيوف يتصفحون ويستخدمون السلة.

المعرّفات والاختصارات

• معرّفات Mongo سلسلة hex من 24 حرفاً.
• قراءات الكتالوج بـ slug (GET /v1/products/:slug).
• التعديلات التي تستهدف منتجاً تأخذ عادة productId.
• مسارات الطلب تستخدم :orderId.

كائنات ثنائية اللغة

وثائق شكل الإدارة تستخدم:

{ "en": "Milk", "ar": "حليب" }

بطاقات الكتالوج العامة تعرض عادة اسم name واحد محلولاً للغة الطلب.

استثناءات SSE

هذه النقاط ليست غلاف JSON:

• GET /v1/notifications/sse — text/event-stream
• POST /v1/assistant/messages — text/event-stream

حد المعدل

الواجهة العامة تطبّق حدود Redis. قائمة المساعد محدودة (60/دقيقة) وإرسال الرسالة (20/دقيقة). عالج 429 + RATE_LIMITED / TOO_MANY_ATTEMPTS بالتراجع.

التكرار

طلبات POST للتجهيز غير معلنة كمتكررة بأمان. إعادة مسح سطر ملتقط أو ready ثانية تفشل بخطأ مجالي. أعد تحميل الطلب بعد كل إجراء.