تطوير API

سجل تصحيحات المشارك

تقبل تفاصيل التقويم في الخادم المحدث معرّف الموعد id وview=trainer وhistoryOnly=true وhistoryMember وhistoryKind=attendance|results وhistoryOffset. يعاد items بحد أقصى ٢٥ إدخالاً وnext، مع نسبة التسجيل إلى الموظف وتوقيته والحضور الأصلي والمعدل أو نسخة النتائج. يُتحقق من تعيين موظفي الموعد وحدود المشارك في كل قراءة. توضح مواصفة OpenAPI المرجعية المعاملات وبنية الرد. لا تتغير دلالات الكتابة وإعادة المحاولة.

مواصفة OpenAPI

يصدّر الخادم وثيقة JSON متوافقة مع OpenAPI 3.1 وSwagger من كل نسخة جامعية محدّثة عبر GET /v1/openapi.json. تصف الوثيقة، دون مصادقة، مجموعة واجهات تطبيق المدرب الميداني المدعومة. ولا تتضمن حسابات أو قوائم رياضيين أو بياناتهم.

فتح Swagger UI

عند تشغيل نسخة خادم تتضمن العارض، افتح /v1/docs على عنوان API مباشرة، أو /api/v1/docs على نسخة مستضافة عبر Compose. للتطوير المحلي الافتراضي، افتح http://127.0.0.1:55331/v1/docs بعد تشغيل الخادم المحدّث أو إعادة تشغيله. موقع Rafik يشرح العارض؛ خادم جامعتك هو الذي يقدّمه.

1. في بيئة التطوير المحلية، وسّع POST /v1/mobile/auth/login واختر Try it out. استخدم حساب مدرب ببيانات تجريبية.
2. انسخ access_token من الرد إلى Authorize.
3. استكشف واجهات المدرب المدعومة. يضيف العارض X-Rafik-Client: android، ولا يرسل ملفات تعريف ارتباط المتصفح، ويوجّه الطلبات إلى النسخة الحالية.

تُمسح المصادقة عند تحديث الصفحة. ملفات العارض مضمّنة محلياً، والتحقق الخارجي معطّل، ولا تُحفظ الرموز بشكل دائم. عند ضبط NODE_ENV=production يصبح العارض مرجعاً فقط وتُعطّل Try it out. تبقى صلاحيات API مفروضة بشكل مستقل. لا تستخدم بيانات رياضيين أو معلومات صحية حقيقية في الأمثلة.

الواجهات المدعومة

تغطي المواصفة الحالية تسجيل الدخول الأصلي والتحقق من الجلسة وتجديدها وتسجيل الخروج، وقراءة السياقات حسب الدور، وقراءات تقويم المدرب المحدودة، وأشكال أوامر الحضور والنتائج وإنهاء الحدث. وهي لا تسرد جميع واجهات الويب أو الواجهات القديمة. راجع مرجع المسارات الأوسع في مستودع Rafik.

المصادقة

يستخدم التطبيق الأصلي X-Rafik-Client: android مع رمز وصول Bearer معتم. تنتهي رموز الوصول سريعاً وتتجدد رموز التحديث بالتناوب. لا تستخدم طلبات التطبيق ملفات تعريف ارتباط المتصفح. استخدم HTTPS للنسخ البعيدة؛ وتظل ملفات المتصفح وقواعد المصدر منفصلة.

الكتابة وإعادة المحاولة والأخطاء

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

النطاق والخصوصية

تخدم هذه المواصفة تنفيذ Stage 7 الموجّه للمدرب أولاً. نُفّذت محلياً وظائف الحضور ومسودات التقييم ونتائجه وإنهاء الحدث وإعادة إرسال الأوامر دون اتصال؛ ولا يزال التحقق من التكامل مع API والقبول على أجهزة فعلية مفتوحين. لا تثبت وثيقة API اجتياز بوابات القبول هذه. لا تُخزَّن الردود والملفات الخاصة في مخابئ عامة. لا تضع أسرار API مشتركة أو بيانات مشغل أو معلومات صحية في أمثلة الطلبات.

المصدر والحالة

رُوجعت وفق فرع التطوير الجامعي في 18 أكتوبر 2026. تتطلب المواصفة والعارض نشر تغييرات الخادم المناسبة وتثبيتها. قد تتضمن النسخ الأقدم ملف JSON دون العارض. هذه إرشادات لفرع التطوير وليست إعلان إصدار. راجع نطاق تطبيق الهاتف ومرجع تنفيذ API.