إنشاء المستخدمين

يُنشأ كل مستخدم بعد المسؤول الأول عبر POST /api/users، وجسمها اتحاد مُميَّز مفتاحه primaryPersona. يربط المُميِّز (CreateUserBody) كل دور بمخطّط جسمه الخاص:


primaryPersona  →  body schema
STUDENT         →  CreateStudentUserBody
TEACHER         →  CreateTeacherUserBody
PARENT          →  CreateParentUserBody
PRINCIPAL       →  CreatePrincipalUserBody
MANAGER         →  CreateManagerUserBody
ADMIN           →  CreateAdminUserBody

حدّد primaryPersona فيتحقّق الخادم من بقية الجسم مقابل مخطّط ذلك الدور.

حقول كل دور

الدور	المطلوب (إضافةً للمشترك)	الاختياري
المشترك	`email`، `password` (8–72 محرفًا)، `fullNameAr`، `primaryPersona`	`fullNameEn`، وغالبًا `organizationId`
`STUDENT`	`gradeLevel` (1–4)	`homeDialect` (`MSA` \| `LEV`، الافتراضي `MSA`)، `classId`
`TEACHER`	—	`tier` (`STANDARD` \| `SENIOR` \| `HEAD`)، `arabicLiteracyTraining`
`PARENT`	—	`phoneE164`، `preferredLanguage` (`ar` \| `en`)
`PRINCIPAL`	`schoolId`	`tier` (`STANDARD` \| `HEAD`)
`MANAGER`	—	`scopedSchoolIds[]` (`[]` = على مستوى المؤسسة)
`ADMIN`	`scope` (`SUPER` \| `ORG` \| `SCHOOL`)	`specialistRole`

مثال: إنشاء طالب في الصف الثاني مسجَّل في صف بالفعل:


curl -X POST https://localhost:3000/api/users \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "primaryPersona": "STUDENT",
    "email": "student@school.edu.jo",
    "password": "student-strong-password",
    "fullNameAr": "ليان حسن",
    "organizationId": "clx4z2k0u0000xyz1234abcde",
    "gradeLevel": 2,
    "classId": "clx4z2k0u0000xyz1234abcde"
  }'

تسجيل طالب في صف. حدّد classId في جسم الطالب عند الإنشاء. لا توجد نقطة نهاية تسجيل منفصلة في 1.0.0-phase0؛ يظهر الطالب بعدها في GET /api/classes/{classId}/students. انظر إدارة الصفوف والقوائم.

من يمكنه الاستدعاء

POST /api/users يتطلّب صلاحية MANAGE_ORG، التي يملكها المسؤولون فقط. لإنشاء مدير مدرسة أو منسّق نطاق بصفة منسّق، استخدم نقطتَي النهاية المخصَّصتين POST /api/principals (تتطلّب MANAGE_PRINCIPALS) وPOST /api/managers (تتطلّب MANAGE_MANAGERS) بدلًا من ذلك. لا يمكن للمنسّقين استدعاء POST /api/users مباشرةً.

ما الذي تستردّه

201 UserCreatedResponse (id، email، primaryPersona، organizationId، createdAt). ويُنشأ صفّ ملف الدور المطابق في الجلسة نفسها.

قراءة الملفات والقوائم

GET /api/users/me/profile ← PersonaProfileResponse للمستدعي بحسب دوره (مُميَّز).
GET /api/users ← المستخدمون ضمن نطاقك، مُصفّحون بمؤشّر nextCursor.
GET /api/users/me/preferences ← UserPreferencesResponse (يُنشأ عند القراءة بقيم افتراضية). PATCH /api/users/me/preferences ← تحديث جزئي. الحقول: highContrast، captionsDefault، transcriptOpensInPanel، reducedMotionOverride، fontScalePreference (100 | 125 | 150 | 200)، dyslexiaFontEnabled. لا قيد على الصلاحية سوى المصادقة.

الأخطاء

الحالة	متى
`422`	تحقّق: كلمة مرور قصيرة، أو تركيبة دور/حقل خاطئة (`VALIDATION_ERROR`)
`403`	غياب صلاحية `MANAGE_*` المطلوبة (`PERMISSION_DENIED`)
`409`	تعارض: مثل تصادم رمز سريع (يُعاد تلقائيًا حتى 10 مرات، ثم يُظهَر كـ`QUICKCODE_COLLISION_EXHAUSTED`)

انظر الأخطاء لكامل الدليل.