---
title: "المفاهيم الأساسية"
url: https://docs.growamal.com/ar/core-concepts/
language: ar
---

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

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

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

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

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

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

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

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

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

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

ليس للصف مفتاح أجنبي للمعلّم. علاقة المعلّم بالصف كثير-إلى-كثير عبر وصلة **ClassTeacher**. يمكن للمعلّم
أن يدرّس عدّة صفوف، والتفويض يسأل دائمًا «هل يوجد صفّ ClassTeacher فعّال؟» لا «هل يطابق `teacherId`
الصف؟». انظر [إدارة الصفوف والقوائم](https://docs.growamal.com/ar/guides/classes-and-rosters/).

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

لتعداد `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` | قدرة مشغِّل عبر المؤسسات (يملكها المسؤول الأول) |

يسرد [مرجع الواجهة البرمجية](https://docs.growamal.com/ar/api-reference/) متطلّب `security` الدقيق لكل عملية.

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

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