# وثيقة المعمارية المؤسسية والهندسية لمنصة صَقِل (SAQEL Enterprise Architecture Blueprint)
**الإصدار:** 3.0.0 (Enterprise Multi-School, National ID, AI Pedagogical Quality & Fair SLA Engine)  
**المؤسس والمهندس المعماري للتقنية:** الأستاذ حمزة الغويري (Hamza Ayed)  
**تاريخ الاعتماد والتحديث:** 2026-08-28  

---

## 1. الملخص التنفيذي والرؤية الاستثمارية (Executive Summary & Moat)
منصة **صَقِل (Saqel)** هي البنية التحتية التعليمية الذكية الأحدث في المملكة الأردنية الهاشمية والشرق الأوسط (MENA). تجمع المنصة بين:
1. **التعلم السقراطي النشط (Active Recall Socratic Engine)** المدمج لحظياً بالفيديو لمنع المشاهدة السلبية.
2. **المعمارية المؤسسية الهجينة (B2B2C Multi-School Ecosystem)** لربط مدارس الثقافة العسكرية والمدارس الخاصة عبر كشوفات الأرقام الوطنية.
3. **نموذج الهوية المركزية والأبناء المتعددين (Parent-Multi-Child Graph)** الذي يتيح لولي الأمر إدارة ومتابعة أبنائه المتعددين من رقم هاتف واحد.
4. **سوق المعلمين المتعدد ومحرك الجدارة المحصن ضد الكيد (Anti-Brigading Meritocracy Engine)** القائم على مؤشرات السيرفر الصلبة وتيليمتري الاستجابة الحقيقية.
5. **محرك الذكاء الاصطناعي لتقييم جودة الحصص (Pedagogical Quality & Curriculum Alignment)** لضمان مطابقة كل فيديو لنتاجات التعلم المعتمدة لوزارة التربية والتعليم.

---

## 2. معمارية الهوية وإدارة الحسابات المتعددة (Identity & Entity Graph)

### 2.1 فصل الهوية عن الأدوار (Identity vs. Role Entities)
- **جدول الهوية المركزية (`auth_identities`):** يخزن رقم هاتف الأب أو المستخدم بشكل مشفر مع تجريد فريد (`phone_hash`).
- **جدول الطلاب المستقل (`students`):** يعتمد على **الرقم الوطني** كمعرف أساسي غير قابل للتكرار، ويرتبط بالمدرسة والكشف المعتمد.
- **جدول أولياء الأمور المستقل (`guardians`):** يرتبط بهوية الأب ويمتلك علاقة متعددة (1:N) مع الأبناء عبر `guardian_students`.
- **جدول المعلمين المستقل (`teachers`):** يرتبط بالمدرسة والتخصص ونطاق النشر (مدرسي خاص أو سوق عام).

### 2.2 دورة الدخول وتجربة المستخدم
1. **دخول ولي الأمر (OTP Login):**
   - يدخل ولي الأمر برقم هاتفه، فتظهر له لوحة اختيار: *"متابعة تقارير الأبناء (أحمد، عمر، سارة)"* أو *"دخول ابن محدد لحضور الحصص"*.
2. **دخول الطالب المباشر (National ID + PIN):**
   - يستطيع الطالب الدخول اليومي لحصصه عبر (الرقم الوطني + رمز PIN) دون إزعاج ولي الأمر بطلب رمز التحقق في كل مرة.

---

## 3. منظومة المدارس الشريكة وكشوفات الأرقام الوطنية (B2B School Ingestion)

### 3.1 معالجة كشوفات المدارس (School Rosters)
- تزود المدارس الخاصة ومدارس الثقافة العسكرية المنصة بكشوفات رقمية للطلاب (National ID, Full Name, Grade).
- تُخزن في جدول `school_rosters`.
- عند تسجيل الطالب وإدخال رقمه الوطني، يطابق النظام الكشف فوراً ويمنحه صفة **"طالب مدعوم مدرسيًا (School Sponsored)"**.

### 3.2 نموذج الاشتراكات المزدوج (Tiered Passes)
1. **المحتوى المدرسي الأساسي (Included Pass):** مجاني ومفتوح لحصص وامتحانات معلمي مدرسة الطالب المعتمدين.
2. **المحتوى النخبوي الخارجي (Micro-Pass Marketplace):** يتيح لطالب المدرسة الاشتراك بحصص نخبة معلمي المملكة باشتراك رمزي مخفض (5 - 10 دنانير) مع تقاسم الإيراد بين المنصة والمعلم.

---

## 4. محرك تقييم جودة الحصص التعليمية بالذكاء الاصطناعي (Pedagogical Alignment Engine)

يقوم السيرفر فور رفع أي فيديو بتشغيل نموذج التحليل التربوي المعمق:
1. **مطابقة المنهاج الرسمي (Curriculum Alignment Score):** مقارنة محاور الفيديو مع الكتاب الوزاري المعتمد ووحدة المبحث.
2. **استخراج نتاجات التعلم المستهدفة (Learning Outcomes Extraction):** صياغة أهداف إجرائية واضحة للطالب وولي الأمر.
3. **تغطية هرمية بلوم المعرفية (Bloom Taxonomy Coverage):** (التذكر، الفهم، التطبيق، التحليل).
4. **الاعتماد التربوي التلقائي (Quality Approval Status):** اعتماد الحصة كـ `approved_official` أو توجيه تنبيه للمعلم لإعادة التنسيق.

---

## 5. خوارزمية الجدارة وسرعة الاستجابة في الطابور (Dynamic Fair Queue SLA)

تضمن الخوارزمية عدم ظلم المعلم أثناء معالجة المسائل العلمية المعقدة:
$$\text{المؤشر الكلي} = (0.25 \times \text{سرعة الرد}) + (0.25 \times \text{تفاعل الحصص}) + (0.25 \times \text{تحصيل الطلاب}) + (0.25 \times \text{التقييم الموزون})$$

- **جلسة الحل النشطة (Active Solving State):** إذا كان المعلم يرد على أي طالب، تُعفى المحادثات المعلقة في الطابور من أي خصم زمني.
- **مهلة الطابور العادل (Fair Queue Allowance):**
$$\text{المهلة العادلة} = 15 \text{ دقيقة} + (\text{عدد الرسائل المعلقة} \times 6 \text{ دقائق لكل مسألة})$$
- **الحصانة من التقييم الكيدي (Anti-Brigading):** تخفيض وزن تقييم الحسابات غير المتفاعلة إلى $\le 0.10$ وعزل الهجمات المنسقة إحصائياً.

---

## 6. البنية السحابية وهندسة البث (Cloud Infrastructure & Zero-Egress R2)
- **محرك البث:** تقطيع فيديوهات HLS عبر FFmpeg، والتخزين السحابي على Cloudflare R2 بدون أي رسوم خروج بيانات (Zero Egress Fees).
- **محرك المحادثات الفورية:** خادم Workerman WebSocket على المنفذ 8080 لتوصيل الرسائل والإشعارات في زمن وصول 0ms.
- **الأداء العالي والتنفيذ:** تشغيل مباشر عبر PHP 8.4 و PHP-FPM المدمج مع CloudPanel دون حاجة لحاويات دوكر الثقيلة.

---

## 7. أمر التصفير والتهيئة البرمجية (Migration CLI)
لتطبيق الهيكلية الصفرية النظيفة بالكامل والخالية من أي بيانات ديمو:
```bash
php backend/migrate.php --fresh
```