مرجع واجهة API

العنوان الأساسي وصيغة الاستجابة

يُقدَّم كل مسار تحت البادئة /api. محليًا يكون العنوان الأساسي http://localhost:8000/api. وعلى الخادم يكون عنوان واجهة API متبوعًا بـ /api، وهي القيمة نفسها التي تقرؤها لوحة التحكم من NEXT_PUBLIC_API_BASE_URL (متغيرات البيئة).

يستخدم الأعضاء والطاقم تسجيل الدخول نفسه والرمز نفسه؛ والأدوار التي يحملها الحساب تحدد المسارات التي تجيب. محتوى الطلبات بصيغة JSON، باستثناء رفع الملفات. وتأتي كل إجابة في الغلاف نفسه:

{
  "success": true,
  "data": { },
  "message": ""
}

يحتوي data على النتيجة. وmessage جملة قصيرة تملؤها بعض عمليات الكتابة، مترجمة إلى لغة الطلب، وتكون فارغة في غير ذلك.

فحص السلامة هو المسار الوحيد خارج الغلاف. لا يحتاج إلى رمز ولا يخضع لتحديد المعدل:

curl http://localhost:8000/api/health

{"status":"ok"}

يُرجع 503 مع {"status":"unavailable"} ما دام لا يمكن الوصول إلى قاعدة البيانات أو كانت خالية من الجداول، لذا يمكن للمنصة استخدامه كفحص للجاهزية.

الأخطاء

يُجيب الطلب الفاشل برمز حالة HTTP المطابق وبالغلاف نفسه، مع success: false وdata: null، ومع المشكلات لكل حقل عند فشل التحقق:

{
  "success": false,
  "data": null,
  "message": "<the first field's problem>",
  "errors": {
    "email": ["<the problem with email>"]
  }
}

تحمل أخطاء كثيرة مفتاحًا تترجمه لوحة التحكم، مثل member_not_found أو event_full، في message.

التقسيم إلى صفحات

تأخذ القوائم page، بدءًا من 1، وpage_count، وهو حجم الصفحة. تحتوي الصفحة على 100 صف كحد أقصى: الحجم الأكبر يُقرأ 100، والأصغر يُقرأ 1، والحجم المفقود أو غير المقروء يعود إلى القيمة الافتراضية للقائمة. وتجيب القائمة بشكل واحد:

{
  "success": true,
  "data": { "data": [ ], "page": 1, "limit": 15, "total": 35, "totalPages": 3 },
  "message": ""
}

تُرتَّب قوائم المحتوى حسب updated_at، الأحدث أولًا افتراضيًا (order=asc أو desc)، مع المعرّف كمعيار ترجيح، وتقبل search وفلاترها الخاصة.

اللغة

أرسل لغة القارئ في الترويسة Accept-Language: en أو ar كما في الإصدار المرفق. تُعدّ ar-SA عربية، وأي لغة لا تملكها واجهة API يُجاب عنها بالإنجليزية. تُترجم رسائل الخطأ وmessage لعملية الكتابة الناجحة؛ ويعود المحتوى المخزّن باللغتين بالشكل { "en": "...", "ar": "..." }.

المصادقة

• سجّل الدخول عبر POST /api/auth/login. تحتوي الإجابة على access_token، وهو JWT موقّع بـ JWT_SECRET، والحساب مع أدواره وصلاحياته. أرسله بالشكل Authorization: Bearer <token>.
• يدوم الرمز طوال JWT_EXPIRATION، و7d افتراضيًا. لا يوجد مسار للتجديد: عندما تنتهي صلاحية الرمز، يُرجع الطلب التالي 401 ويسجّل العميل الدخول من جديد.
• يقبل تسجيل الدخول والتسجيل وحذف الحساب 10 محاولات في الدقيقة من عنوان واحد، تُعدّ لكل مسار على حدة، ثم تُرجع 429. يُحفظ العدد في ذاكرة واجهة API، لذا يبدأ من جديد عند إعادة التشغيل. خلف خادم وكيل، راجع TRUST_PROXY (حل المشكلات).

1. 01

   سجّل الدخول بصفتك المدرب الرئيسي المزروع

   الطرفيةنسخ

   curl -X POST http://localhost:8000/api/auth/login \
     -H "Content-Type: application/json" \
     -d '{"email":"headcoach@example.com","password":"Coach@123"}'

   الاستجابةنسخ

   {
     "success": true,
     "data": {
       "access_token": "eyJhbGciOiJIUzI1NiIs...",
       "token_type": "Bearer",
       "expires_in": "7d",
       "account": { "email": "headcoach@example.com", "roles": [ ], "permissions": [ ] }
     },
     "message": "..."
   }
2. 02

   استدعِ مسارًا محميًا بالرمز

   الطرفيةنسخ

   curl "http://localhost:8000/api/users?page=1&page_count=5" \
     -H "Authorization: Bearer <access_token>"

   النتيجة المتوقعة: أول خمسة أعضاء، بشكل القائمة.

لا يوجد مسار لإعادة تعيين كلمة المرور. صفحتا نسيان كلمة المرور وإعادة تعيينها في لوحة التحكم واجهتان فقط: لا يُرسَل أي رابط لإعادة التعيين. يعيّن حساب طاقم يملك members.update كلمة مرور العضو عبر PATCH /api/users/:username/change-password.

الصلاحيات

يتحقق المسار من الرمز أولًا، ثم من الصلاحية التي يحددها. يملك الحساب كل صلاحيات كل دور لديه؛ وحيث يحدد المسار عدة صلاحيات، تكفي أي واحدة منها. في الجداول أدناه، اسم الصلاحية في من يحق له استدعاؤه يعني حسابًا تمنحه أدواره تلك الصلاحية.

• الأدوار وصلاحياتها

الأعضاء

المدربون والأدوار

إعدادات التطبيق

بيانات العضو الخاصة

كل مسار هنا يجيب عن الحساب صاحب الرمز ولا أحد غيره. رمز الطاقم يُرجع 403، لأن دور العضو وحده يملك fitness.view وfitness.edit. وتجيب كل عملية كتابة بالصفحة كاملة بعد تحديثها.

• التقدم والتسجيل
• الأجهزة ومفاتيح الإدخال

التمارين والحركات والجلسة

التدريب

تجيب مسارات قائمة العملاء عن المدرب الذي يرسل الطلب: عميل مدرب آخر يُرجع 404.

كتالوجات المحتوى

يجيب كل كتالوج عن المسارات الخمسة نفسها تحت /api/fitness/manage/<catalogue>، ويحتاج كل منها إلى fitness.manage. الكتالوجات هي exercises وworkouts وprograms وdishes وgroups وevents وchallenges وachievements وbadges.

المعرّف غير المعروف يُرجع 404 record_not_found. تُرسل الأسماء والنصوص بالشكل { "en": "…", "ar": "…" }؛ ولا تُرسل سعرات الطبق أبدًا، بل تُحسب من غراماته.

الإدخال

الباب المخصص للأجهزة والمجمّعات. تأخذ هذه المسارات مفتاح إدخال في X-Api-Key، لا رمز bearer أبدًا، وتكتب لحساب المفتاح فقط.

• الأجهزة ومفاتيح الإدخال

البحث، والرفع، والإشعارات، والدول

يدفع مجالا Socket.IO على الخادم نفسه التحديثات المباشرة: يوصل /notifications كل إشعار جديد، ويخبر /auth لوحة التحكم المسجّل دخولها بأن صلاحياتها تغيّرت. يقبلان المصادر الموجودة في FRONTEND_URL، أو CORS_ORIGIN إذا لم يُضبط.

• كيف يرتّب البحث نتائجه

المساعد الذكي

خادم MCP

مسارات وضع العرض التجريبي