المفاهيم الأساسية

التسلسل: المؤسسة ← المدرسة ← الصف

بنية أمل المستأجِرة شجرة من ثلاثة مستويات:

المؤسسة تملك عدّة مدارس (دعم السلاسل).
المدرسة تتبع مؤسسة واحدة بالضبط.
الصف يتبع مدرسة واحدة بالضبط، وله grade (1-4 في الموجة الأولى)، وacademicYear (YYYY-YYYY)، واسم عرض name.

معرّفات المؤسسة والمدرسة والصف هي نصوص cuid (^c[a-z0-9]{24}$).

العزل المستأجِر

organizationId هو مفتاح العزل المعتمد. يُخزَّن مكرّرًا على كل صفّ ضمن نطاق المستأجِر، وتُرشِّح الوسيطة كل استعلام به تلقائيًا. ويفرض نمطا استجابة الخصوصيةَ:

الحالة	الاستجابة	السبب
مورد في مؤسسة أخرى	`404`	لا يُكشف الوجود أبدًا عبر حدود المؤسسات
مورد في مؤسستك لكن دورك لا يصله	`403`	المورد موجود؛ لكن صلاحياتك لا تصله

404 لا تعني «غير موجود». عبر المؤسسات، يُبلَّغ عن مورد حقيقي بـ 404 عمدًا. وداخل مؤسستك، المورد خارج المتناول يكون 403. ابنِ معالجة الأخطاء حول هذا النمط المزدوج.

لا `teacherId` على الصف

ليس للصف مفتاح أجنبي للمعلّم. علاقة المعلّم بالصف كثير-إلى-كثير عبر وصلة ClassTeacher. يمكن للمعلّم أن يدرّس عدّة صفوف، والتفويض يسأل دائمًا «هل يوجد صفّ ClassTeacher فعّال؟» لا «هل يطابق teacherId الصف؟». انظر إدارة الصفوف والقوائم.

الأدوار الستة

لتعداد PersonaKey ست قيم:

الدور	المستوى	الوظيفة
`STUDENT`	—	يتدرّب، يجيب على التشخيصات؛ يدخل بالرمز السريع
`TEACHER`	الصف	يقرّر في كل توصية؛ يدرّس صفًّا أو أكثر
`PARENT`	—	يرى نموّ طفله
`PRINCIPAL`	المدرسة	يقود مدرسة واحدة بالضبط؛ يراجع صحة المدرسة
`MANAGER`	المؤسسة	دور على مستوى المؤسسة، مقيَّد بمدارس محدّدة (أو على مستوى المؤسسة)
`ADMIN`	المشغِّل	يزوّد المؤسسات والمدارس والصفوف والمستخدمين

التحكم بالصلاحيات: الصلاحيات تحكم نقاط النهاية، لا الأدوار

المصادقة (من أنت) منفصلة عن التفويض (ما يمكنك فعله). الهوية من requireAuth؛ والقدرة من requirePermission(code). رموز الصلاحيات تعداد مغلق من 25 قيمة. أكثرها صلةً بالمطوّر:

الصلاحية	تتيح
`VIEW_ORG`	قراءة مؤسسة وتجميعها
`MANAGE_ORG`	إنشاء/تحديث المؤسسات
`MANAGE_SCHOOLS`	إنشاء/تحديث المدارس والصفوف
`MANAGE_TEACHERS`	إسناد المعلّمين للصفوف (ClassTeacher)
`MANAGE_PRINCIPALS`	إنشاء/إسناد المدراء
`MANAGE_MANAGERS`	إنشاء/إسناد المنسقين
`MANAGE_CLASS_STUDENTS`	إدارة قوائم الصفوف
`SUPER_ADMIN`	قدرة مشغِّل عبر المؤسسات (يملكها المسؤول الأول)

يسرد مرجع الواجهة البرمجية متطلّب security الدقيق لكل عملية.

بوّابات الموافقة

تتطلّب بعض الإجراءات الحسّاسة دور موافقة (قواعد APP_*). في الموجة الأولى، موافقة تفعيل المستوى الثالث للمسؤول (APPROVE_TIER_3_ACTIVATION)، ودور أخصائي القراءة يُسنَد للمسؤول عبر علامة specialistRole. هذا داخلي للمنتج غالبًا؛ ويُذكر هنا لتلمس أن المنصّة تحمل نموذج موافقة حقيقيًا.