المنسقون والمدراء

المنسّق ومدير المدرسة دوران قياديان مختلفان يعملان على مستويين مختلفين.

مساران للإنشاء

ثمّة طريقتان لإدخال قيادي إلى النظام، وهما عمليتان مختلفتان:

1. إنشاء المستخدم عبر POST /api/users مع primaryPersona: MANAGER (أو PRINCIPAL)، مما يُنشئ حساب الدخول وملف الدور معًا.
2. إسناد الدور/الملف لمستخدم قائم عبر POST /api/managers أو POST /api/principals.

استخدم المسار 1 لشخص جديد تمامًا؛ والمسار 2 لمنح الدور لمستخدم موجود سلفًا.

إنشاء منسّق

curl -X POST https://localhost:3000/api/managers \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{ "userId": 1, "scopedSchoolIds": ["clx4z2k0u0000xyz1234abcde"] }'

يتطلّب MANAGE_MANAGERS (للمسؤول فقط). scopedSchoolIds فارغة تجعل المنسّق على مستوى المؤسسة.

تُعيد 409 (CONFLICT، “User is already a Manager”) إذا كان المستخدم منسّقًا بالفعل، بما في ذلك حين يتسابق طلبان متزامنان على نفس userId.

إنشاء مدير مدرسة

curl -X POST https://localhost:3000/api/principals \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{ "userId": 1, "schoolId": "clx4z2k0u0000xyz1234abcde", "tier": "STANDARD" }'

يعيد 201 PrincipalDetailResponse. MANAGE_PRINCIPALS: يملكها المسؤول بأي نطاق؛ ويملكها المنسّق حين تكون schoolId المستهدفة ضمن scopedSchoolIds خاصته (أو كان على مستوى المؤسسة).

التجميع المؤسسي (أداة مسؤول)

GET /api/organizations/{id}/rollup (VIEW_ORG، للمسؤول أو لمنسّق على مؤسسته) يعيد قائمة المدارس وtotalStudents. حقل byMacroDomain يكون دائمًا كائنًا فارغًا {} في هذه النقطة النهائية. بيانات المجالات الكبرى تُقدّمها ثلاثة مسارات مخصّصة للمنسّق موضّحة أدناه.

واجهة برمجة تطبيقات المنسّق على مستوى المؤسسة

لوحة المنسّق مدعومة بثلاثة مسارات مجمِّعة للقراءة فقط، جميعها مقيَّدة بـVIEW_ORG (منسّق أو مسؤول). المنسّق ذو scopedSchoolIds غير الفارغة يرى مدارسه المحدّدة فقط (تطبيق الكل أو لا شيء). orgId من مؤسسة أخرى يُعيد 404 دون الكشف عن وجودها.

نظرة عامة

GET /api/orgs/{orgId}/overview يُعيد OrgOverviewDTO: بطاقات تجميع لكل مدرسة تحتوي على schoolNameAr وtotalStudents وclassCount وneedsSupportCount وlastUpdatedAt. هذه هي الشاشة الرئيسية للمنسّق.

المقارنات

GET /api/orgs/{orgId}/comparisons يُعيد OrgComparisonDTO: توزيعات أعداد الحالات عبر جميع المجالات الكبيرة الستة لكل مدرسة في المؤسسة، مرتَّبةً أبجديًا. لا يوجد ترتيب تفضيلي بين المدارس. كل مدخل هو توزيع حالات، لا متوسّط عددي ولا نسبة مئوية إجمالية واحدة.

الاتجاهات

GET /api/orgs/{orgId}/trends يُعيد OrgTrendsDTO: سلسلة زمنية لكل مدرسة ولكل مجال كبير. يُجمِّع المحور الأفقي اللقطات حسب الشهر التقويمي (YYYY-MM مشتقّة من computedAt) بترتيب تصاعدي. هذا التجميع حسب الشهر التقويمي، لا حسب نوافذ التقييم (بداية العام أو منتصفه أو نهايته).

وللاطّلاع على القراءة على مستوى المدرسة خلف لوحة مدير المدرسة، انظر المعايير والمحكات (نظرة المدرسة العامة + الخريطة الحرارية) و التقارير وملف ولي الأمر.

صلاحية الموافقة

موافقة تفعيل المستوى الثالث للمسؤول في الموجة الأولى (APPROVE_TIER_3_ACTIVATION)، وأخصائي القراءة يُسنَد للمسؤول عبر specialistRole. انظر المفاهيم الأساسية.