الاصطلاحات

مغلّف الأخطاء#

كل استجابة خطأ — أيًّا كانت حالة HTTP — تتبع نفس الشكل:

{
  "error": {
    "code": "STUDENT_NOT_FOUND",
    "message": "Student not found.",
    "details": {
      "studentId": "0190a1b2-..."
    },
    "requestId": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b"
  }
}

message دائمًا بالإنجليزية ومخصّصة للسجلّات لا للمستخدم النهائي — تَرجِم حسب code في واجهتك أنت. details تظهر فقط حين تضيف شيئًا يمكن للعميل التصرّف بناءً عليه (أي حقل فشل التحقّق منه، أي معرّف لم يُعثر عليه). requestId يطابق القيمة التي تسجّلها الواجهة أيضًا من جهة الخادم — أرفقه عند الإبلاغ عن مشكلة.

رموز الأخطاء#

كل رمز يمكن أن تُعيده الواجهة، مُولَّد مباشرة من packages/shared/src/errors.ts — المصدر الوحيد الذي تُبنى منه كل دالة إنشاء خطأ في قاعدة الشيفرة، لذا لا يمكن لهذا الجدول أن ينحرف أبدًا عمّا ترسله الواجهة فعليًا.

400 مقابل 422#

التحقّق من الصحّة يكون دائمًا 422. كل ما تقرأه الواجهة ولا تقبله — جسم الطلب أو سلسلة الاستعلام أو معامل المسار أو ترويسة تفشل في مخطّطها، أو قاعدة عمل ترفض قيمة سليمة الشكل — يعود بـ 422 VALIDATION_ERROR، وفشل المخطّط يحمل الحقول التي فشلت في details.issues:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input: expected string, received undefined",
    "details": {
      "issues": [
        {
          "path": [
            "branchId"
          ],
          "message": "Invalid input"
        }
      ]
    },
    "requestId": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b"
  }
}

أمّا 400 MALFORMED_REQUEST فيعني فقط أنّ الطلب تعذّرت قراءته أصلًا: JSON غير قابل للتحليل، أو Content-Type غير صالح، أو حمولة تتجاوز الحدّ. باختصار: 400 خلل في طريقة تسلسل الطلب، و422 خلل في محتواه. وتستخدم بضع نقاط نهاية 400 أيضًا لرفض محدّد باسمه (INVITATION_INVALID، LICENSE_INVALID، OAUTH_INVALID_REDIRECT_URI) — ولهذا تُفرّع على error.code لا على رمز الحالة.

التصفّح بالمؤشّر (Cursor)#

كل نقطة نهاية لعرض قوائم تستخدم تصفّحًا بالمؤشّر — لا بالإزاحة أو رقم الصفحة أبدًا — لتبقى النتائج صحيحة حتى أثناء إدراج صفوف جديدة في الوقت نفسه. مرّر limit (بحدّ أقصى 100، والقيمة الافتراضية تختلف حسب نقطة النهاية)، ولكل صفحة بعد الأولى، cursor من استجابة الصفحة السابقة:

{
  "data": [
    "…"
  ],
  "nextCursor": "eyJpZCI6IjAxOTAwMDAwLTAwMDAtNzAwMC04MDAwLTAwMDAwMDAwMDAwMSJ9"
}

nextCursor من نوع string | null — null تعني أنك وصلت إلى الصفحة الأخيرة. تعامل مع المؤشّر كقيمة معتمة: هو مؤشّر مُرمَّز بـ base64url، وليس إزاحة صف، وقد يتغيّر شكله الداخلي.

المبالغ المالية#

كل قيمة مالية هي كائن متداخل — { amountMinor, currency } — عدد صحيح بالوحدة الصغرى للعملة (سنتات، أغورات، فلوس) إلى جانب حقل currency خاص به على نفس ذلك الكائن، مثل total.amountMinor + total.currency للفاتورة، أو amountMinor + currency للدفعة. وهي ليست أبدًا رقمًا مجردًا مع وجود حقل العملة في مكان آخر على الكائن الأصل. لا تُستخدم الأعداد العشرية (float) أبدًا. القيمة { amountMinor: 1250, currency: "USD" } تعني 12.50 دولارًا.

الطوابع الزمنية#

كل طابع زمني بصيغة ISO-8601 بتوقيت UTC (2026-03-02T09:00:00.000Z). التواريخ بلا مكوّن وقت (تاريخ استحقاق، تاريخ ميلاد) بصيغة YYYY-MM-DD بسيطة. حوِّل الأوقات إلى المنطقة الزمنية للمستأجر (افتراضيًا Asia/Jerusalem) عند العرض — الواجهة لا تفعل ذلك نيابة عنك.

تعدّد المستأجرين#

لا تمرّر معرّف مستأجر بنفسك أبدًا. رمز JWT للتطبيق الأوّل يحمل المستأجر المُختار وقت select-tenant؛ ومفتاح API مرتبط بشكل دائم بالمستأجر الذي أُنشئ فيه. كل استعلام تُجريه الواجهة مُقيَّد بذلك المستأجر على مستوى طبقة التطبيق وعلى مستوى أمان الصفوف (Row-Level Security) في قاعدة البيانات معًا — لا توجد طريقة للوصول إلى بيانات مستأجر آخر بتخمين معرّف.