إدارة الصفوف والقوائم

إنشاء صف

POST /api/classes بجسم { schoolId, name, grade, academicYear } (يتطلّب MANAGE_SCHOOLS). grade بين 1 و4؛ وacademicYear يطابق ^\d{4}-\d{4}$.

curl -X POST https://localhost:3000/api/classes \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "schoolId": "clx4z2k0u0000xyz1234abcde",
    "name": "صف ثاني — أ",
    "grade": 2,
    "academicYear": "2026-2027"
  }'

السرد والقراءة

• GET /api/classes: الصفوف ضمن نطاقك (يرى المعلّم صفوف ClassTeacher الخاصة به؛ ويرى المنسّق صفوف مدارسه المحدّدة).
• GET /api/classes/{id}: صفّ واحد.

إسناد معلّم (وصلة ClassTeacher)

ليس للصف مفتاح أجنبي للمعلّم. يرتبط المعلّمون عبر وصلة ClassTeacher بدور:

curl -X POST https://localhost:3000/api/classes/{classId}/teachers \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{ "teacherUserId": 1, "role": "PRIMARY" }'

role يكون PRIMARY (الافتراضي) أو SECONDARY أو SUPPORT. يعيد الاستدعاء 201 ClassTeacherRowResponse؛ وإسناد معلّم مُسنَد سلفًا يعيد 409. أزِل الإسناد بـ DELETE /api/classes/{classId}/teachers/{teacherUserId} (إلغاء إسناد ناعم).

سرد معلّمي صف وطلابه

• GET /api/classes/{classId}/teachers ← ClassTeacherListResponse.
• GET /api/classes/{classId}/students ← StudentListResponse.

نموذج التسجيل

يُربط الطلاب بالصفوف عبر وصلة ClassStudent. الطالب في نسخة فعّالة واحدة من الصف في الوقت ذاته؛ وتُحفظ الصفوف التاريخية.

إعادة توليد الرمز السريع للطالب

POST /api/students/{id}/quickcode/regen يصدر رمزًا جديدًا من رقمين (01–99) لدخول الطالب الصفّي. رموز الطلاب لا تنتهي، وتتغيّر فقط عند إعادة توليد أحدها. أما رمز الصف نفسه فمنفصل: صالح سنة كاملة (365 يومًا) ويُجدَّد عبر POST /api/classes/{classId}/login-code/rotate (لوحة رابط الصف في صفحتَي التقييمات وبطاقات الدخول عند المعلّم). أما تدفّق دخول الطالب نفسه فموجود في المصادقة ← دخول الطالب بالرمز السريع.

حذف صف

DELETE /api/classes/{id}. صفّ ما زال به طلاب يعيد 409؛ أزِل القائمة أو أعِد إسنادها أولًا.