مرجع واجهة API

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

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

تخدم واجهة API جمهورين لا يتشاركان رمزًا أبدًا. يستخدم الطلاب المسارات تحت /api/users/<area> و/api/shop، المذكورة في أقسام الطلاب أدناه. وتستخدم لوحة الإدارة كل المسارات الأخرى، بما فيها /api/users نفسه و/api/users/<username>، اللذان يديران حسابات الطلاب.

أجسام الطلبات بصيغة JSON، باستثناء رفع الملفات. وتأتي كل إجابة في الغلاف نفسه:

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

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

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

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

يجيب بـ 503 ما دام الوصول إلى قاعدة البيانات متعذرًا أو كانت خالية من الجداول، لذا يمكن لموازن الأحمال استخدامه كفحص للجاهزية.

الأخطاء

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

curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"not-an-email","password":"x"}'

{
  "success": false,
  "data": null,
  "message": "Enter a valid email address (example@domain.com).",
  "errors": {
    "email": ["Enter a valid email address (example@domain.com)."]
  }
}

تجيب عمليات الكتابة الناجحة بـ 201 مع POST وبـ 200 مع الطرق الأخرى.

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

تأتي القوائم بشكلين، واحد لكل جمهور. تجيب مسارات الطلاب بالشكل الذي يقرؤه موقع الطلاب؛ وتجيب مسارات الإدارة بالشكل الذي تقرؤه لوحة الإدارة.

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

لا يقبل sort إلا الأعمدة التي تسمح بها كل قائمة. ويعود المفتاح غير المعروف إلى الترتيب الافتراضي بدلًا من الفشل، فتظل الإشارة المرجعية القديمة تعمل.

ترتَّب قائمة الدورات العامة حسب id أو price أو discount_percentage أو rating أو duration أو level أو language أو created_at أو updated_at، وتُرشَّح حسب title وcategory_id وinstructor_id وtype (live أو recorded).

اللغة

أرسل لغة القارئ في ترويسة Accept-Language. تتحدث واجهة API اللغات المسرودة في back-end/src/i18n/locales.ts، وهي en وar كما تُشحن. تقرأ الوسم الأول، فيكون ar-SA عربية، والطلب الذي لا يحدد لغة مدعومة يُجاب بلغة الإعداد default_locale. لا يوجد معامل استعلام للغة.

• تُترجم رسائل الخطأ وmessage الخاصة بعمليات الكتابة الناجحة.
• النص المخزّن باللغتين، مثل عناوين الدورات وأوصافها، يُعاد بالشكل { "en": "...", "ar": "..." } ويختار العميل أحدهما.
• تجيب بعض مسارات الطلاب باللغة المطلوبة فقط: قائمة التسجيلات، ومحتوى الدورة، والبحث.
• يأخذ الدفع اللغة من جسم الطلب (locale، إحدى اللغات المدعومة)، فيطابق الإيصال الصفحة التي اشترى منها الطالب.

المصادقة

يسجّل الطلاب والمسؤولون الدخول عبر نقاط نهاية مختلفة، ومقابل جداول مختلفة، ويحصلون على رموز لا تقبلها إلا مساراتهم الخاصة.

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

1. 01

   سجّل الدخول بحساب المدير العام التجريبي

   الطرفيةنسخ

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

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

   {
     "success": true,
     "data": {
       "access_token": "eyJhbGciOiJIUzI1NiIs...",
       "token_type": "Bearer",
       "expires_in": "7d",
       "admin": {
         "id": 1,
         "email": "admin@learnio.com",
         "instructor_id": null,
         "roles": [{ "id": 1, "name": "Super Admin", "guard_name": "web" }],
         "permissions": ["admins.view", "admins.create", "..."]
       }
     },
     "message": "Signed in successfully."
   }
2. 02

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

   الطرفيةنسخ

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

   النتيجة المتوقعة: أول خمس دورات، بشكل قائمة الإدارة.
3. 03

   سجّل الدخول بحساب الطالب التجريبي

   تحتوي البيانات النموذجية أيضًا على طالب، demo@learnio.com بكلمة المرور Demo@123:

   الطرفيةنسخ

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

   ثم مرّر data.token بالطريقة نفسها، على سبيل المثال إلى GET /api/users/enrollments.

الصلاحيات

يتحقق كل مسار إداري من الرمز أولًا، ثم من الصلاحية التي يحددها. تُسمّى الصلاحيات بالشكل <module>.<action>، ويملك المسؤول كل صلاحيات كل دور لديه. وحيث يحدد المسار عدة صلاحيات، تكفي أي واحدة منها. في جداول الإدارة أدناه، يعني اسم الصلاحية في عمود من يحق له استدعاؤه مسؤولًا تمنحه أدواره تلك الصلاحية.

تشغيل أداة البذر مجددًا ينشئ الأدوار الناقصة ويترك صلاحيات الأدوار الموجودة كما هي، فتبقى التغييرات التي أجريتها في لوحة الإدارة. والاستثناء هو المدير العام: يحصل على أي صلاحية لا يملكها بعد.

كل صلاحية قراءة تنتهي بـ .view ولا تنتهي بها أي صلاحية أخرى: دور المشاهد (Viewer) التجريبي مبني على هذه القاعدة. الأدوار التي تنشئها البيانات النموذجية:

يحمل حساب المسؤول المرتبط بمدرّس الحقل instructor_id في إجابة تسجيل الدخول، ويُقيَّد بدوراته الخاصة إضافة إلى صلاحياته: لا تعرض القوائم إلا تلك الدورات وطلابها، وأي عملية كتابة خارجها تجيب بـ 403.

عندما تتغير أدوار مسؤول، تُبلَّغ لوحة الإدارة عبر مقبس /auth (الحدث permissions-updated) لتعيد تحميل GET /api/auth/me. ولا يقبل هذا المقبس إلا رموز المسؤولين.

الكتالوج العام

لا حاجة إلى رمز. هذه هي المسارات التي تستدعيها الصفحات العامة في موقع الطلاب.

الحرف الكبير I في /api/users/Instructors هو المسار الذي يستدعيه موقع الطلاب؛ والمطابقة لا تميّز بين الأحرف الكبيرة والصغيرة.

تسجيل الطلاب وتسجيل دخولهم

يستخدم موقع الطلاب المسارات تحت /api/users/auth. يسجّل إنشاء الحساب دخول الطالب مباشرة ويرسل إليه رابط تأكيد بالبريد؛ ويظل بإمكان الحساب غير المؤكد التصفح والشراء.

يُجيب resend وforgot-password بالطريقة نفسها سواء كان للعنوان حساب أم لا، فلا يمكن استخدامهما لمعرفة من المسجّل. وتسجيل الدخول وإنشاء الحساب وresend وforgot-password وreset-password محدودة المعدّل (المصادقة).

تعمل مجموعة ثانية من مسارات الطلاب تحت /api/students/auth على الحسابات نفسها، وتجيب أيضًا بـ token وuser. لا يستخدمها موقع الطلاب؛ فضّل /api/users/auth.

الملف الشخصي للطالب ودوراته وتقدّمه

تحتاج كل المسارات هنا إلى رمز طالب. يُشار إلى الدورات والدروس بقيمة code الخاصة بها، لا بمعرّفها الرقمي.

تأخذ مسارات التقييم المعرّف الرقمي للدورة، ولكل طالب تقييم واحد لكل دورة. ولا يكتبه إلا طالب مسجّل في الدورة؛ والتسجيل الملغى يُجاب بالرمز 403.

• يكون التقييم published فورًا، أو pending إلى أن يعتمده مشرف عندما تكون قيمة الإعداد reviews_require_approval هي true. وتعديل تقييم أخفاه مشرف يعيده إلى pending.
• التقييم الذي حذفه مشرف يعود بالحالة status: removed ولا يمكن تعديله ولا سحبه (403).
• كل كتابة تعيد حساب تقييم الدورة وعدد تقييماتها، وكذلك تقييم مدرّسها وعدده.
• التقييم الجديد، والتعديل الذي ينتظر الموافقة، يُشعِران الطاقم الذي يملك reviews.view.

الاختبارات والواجبات والتقويم

مسارات الحصص المباشرة في التقويم موصوفة في الحصص المباشرة.

رسائل الطلاب وإشعاراتهم

تُدفع الإشعارات الجديدة أيضًا عبر Socket.IO، على مساحة الأسماء /notifications على عنوان واجهة API من دون /api. مرّر الرمز المميز في auth.token أثناء المصافحة واستمع إلى notification:created. يستخدم المسؤولون المقبس نفسه برموزهم الخاصة.

الدفع والمدفوعات

عندما تجيب صفحة الدفع بـ redirect_url، وجّه المشتري إليه واعتبر الطلب pending: يُمنح المقعد عندما يؤكد الـ webhook الخاص بمعالج الدفع العملية، لا عند العودة. يتحقق كل webhook من توقيع معالج الدفع ويجيب بـ 401 عند عدم التطابق. تُطبَّق الأحداث مرة واحدة، مهما كرّر معالج الدفع المحاولة.

تمر الدورة المجانية (السعر 0) عبر المسار نفسه ولا تصل إلى أي معالج دفع، فتعمل دون أي مفاتيح دفع. يُكتب الطلب بالحالة paid مع gateway: "free" وredirect_url: null، ويُمنح المقعد فورًا، ويتلقى الطالب رسالة التسجيل دون إيصال. وتُحسب الطلبات المجانية تسجيلات لا مبيعات: فهي مستبعدة من متوسط قيمة الطلب.

إعداد معالجات الدفع واشتراكات الـ webhook الخاصة بها: المدفوعات.

تسجيل دخول المسؤولين وحسابات الطاقم

عنوان البريد يخص مسؤولًا واحدًا، حتى لو كان محذوفًا: إنشاء مسؤول، أو تغيير بريد إلى عنوان مستخدم، يُجاب بالرمز 409.

الأدوار

الطلاب

يُشار إلى حسابات الطلاب بقيمة username. حذف أحدها حذف مؤقت يمكن التراجع عنه.

المدرّسون

يراسل حساب المدرّس طلابه عبر هذه المسارات، التي تجيب بـ 403 للمسؤول غير المرتبط بمدرّس:

الفئات

القراءات متاحة للجميع ومدرجة مع الكتالوج العام. أما الكتابة فتحتاج إلى صلاحية:

الدورات

المنهج: الأقسام والدروس والموارد

الاختبارات والواجبات

التسجيلات والطلبات

حالة الطلب status هي pending أو paid أو failed أو refunded. ويذكر gateway معالج الدفع الذي حصّل المبلغ، أو demo للمحاكي المدمج، أو free لدورة لم تكلّف شيئًا.

التقييمات

يكتب الطلاب تقييماتهم عبر مسارات الطالب، وتقرأ صفحة الدورة المنشور منها من الكتالوج العام. كل تغيير إشرافي يعيد حساب تقييم الدورة وتقييم المدرّس.

المدونة

الإعدادات

تُخزَّن إعدادات المنصة كأزواج من المفاتيح والقيم، ويُشار إليها بقيمة key.

تنشئ أداة البذر هذه الإعدادات الستة، ويقرأ كلًّا منها واجهة API أو لوحة الطالب:

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

رفع الوسائط

أرسل multipart/form-data مع الملف في file، بحجم يصل إلى 150 ميغابايت، واختياريًا path (المجلد، وهو uploads افتراضيًا)، وfor (إعداد مسبق لحجم الصورة)، وtype (القيمة video لتخطي معالجة الصور). يُعاد تحجيم الصور إلى عدة نسخ؛ أما الفيديو (mp4، webm، mov، m4v) فيُخزَّن كما هو. يحتاج إلى إعدادات المخزن في تخزين الوسائط.

يحتاج المسار إلى رمز مسؤول أو طالب، ويُتحقق منه قبل قراءة الملف. ويجب أن تكون path أحد المجلدات المسرودة في back-end/src/modules/helpers/upload/upload-folders.constants.ts؛ وأي مجلد آخر يُجاب بالرمز 400. يستطيع المسؤول الرفع إلى uploads وadmins/profile وadmins/profiles وusers/profiles وblog وcategories وcourses وinstructors وmessages وai-chat. ولا يستطيع الطالب الرفع إلا إلى messages، للصور التي يرفقها بمحادثة. والشاشة الجديدة التي ترفع إلى مجلد خاص بها تحتاج إلى إضافة ذلك المجلد إلى القائمة.

curl -X POST http://localhost:8000/api/helpers/upload \
  -H "Authorization: Bearer <access_token>" \
  -F "file=@cover.jpg" -F "path=courses"

الإشعارات والبحث والإحصاءات

لا يقرأ المسؤول ولا يغيّر إلا إشعاراته: تأخذ المسارات المسؤولَ من الرمز. وتكتب واجهة API إشعارًا لكل حدث من هذه الأحداث، لكل مسؤول يملك الصلاحية التي تحتاجها الشاشة المرتبطة:

حساب المسؤول المرتبط بمدرّس لا يُشعَر إلا بما يخص دورات ذلك المدرّس، ولا يُشعَر بالحسابات الجديدة. ويُدفع كل إشعار أيضًا عبر مقبس /notifications لحظة حفظه.

الحصص المباشرة

الشهادات

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

سجل محادثات المساعد

خادم MCP

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

بوابات دفع مخصّصة