Update Saqel Platform: 2026-08-28 15:28:24

docs/SAQEL_ENTERPRISE_ARCHITECTURE.md

@@ -1,5 +1,5 @@
 # وثيقة المعمارية المؤسسية والهندسية لمنصة صَقِل (SAQEL Enterprise Architecture Blueprint)
-**الإصدار:** 3.0.0 (Enterprise Multi-School, National ID, AI Pedagogical Quality & Fair SLA Engine)  
+**الإصدار:** 3.1.0 (Unified Dynamic Multi-Persona App, Guardian Portal, School Admin SaaS & Curriculum Ingestion)  
 **المؤسس والمهندس المعماري للتقنية:** الأستاذ حمزة الغويري (Hamza Ayed)  
 **تاريخ الاعتماد والتحديث:** 2026-08-28  
 
@@ -7,74 +7,52 @@
 
 ## 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)** لضمان مطابقة كل فيديو لنتاجات التعلم المعتمدة لوزارة التربية والتعليم.
+1. **التطبيق الموحد الذكي (Unified Dynamic App Shell):** تطبيق واحد متعدد الهويات يعمل على (Web, Windows, Tablets, Mobile) ويدعم التبديل السلس بين الأدوار (طالب، معلم، ولي أمر).
+2. **التعلم السقراطي النشط وسد الثغرات (Productive Struggle & AI Remediation):** إرجاع الفيديو عند الخطأ وتوليد فحوصات وتلميحات موجهة لمعالجة نقاط ضعف الطالب اللحظية.
+3. **المعمارية المؤسسية الهجينة (B2B2C Multi-School Ecosystem):** ربط مدارس الثقافة العسكرية والمدارس الخاصة عبر كشوفات الأرقام الوطنية (`school_rosters`).
+4. **بوابة ولي الأمر والأبناء المتعددين (Guardian Portal & Multi-Child Graph):** متابعة جاهزية الأبناء وسجل معالجة نقاط الضعف من شاشة واحدة (`/guardian`).
+5. **لوحة إدارة المدارس السحابية (School Admin SaaS):** استيراد كشوفات الطلاب الرقمية ومتابعة تقارير المدرسة (`/school-admin`).
+6. **محرك تحويل المناهج إلى مارك داون (Curriculum PDF to Markdown Engine):** تحويل كتب وزارة التربية والتعليم إلى قاعدة معرفية فائقة السرعة لدعم الذكاء الاصطناعي.
 
 ---
 
-## 2. معمارية الهوية وإدارة الحسابات المتعددة (Identity & Entity Graph)
+## 2. معمارية التطبيق الموحد والبوابات (Unified App Routing)
 
-### 2.1 فصل الهوية عن الأدوار (Identity vs. Role Entities)
-- **جدول الهوية المركزية (`auth_identities`):** يخزن رقم هاتف الأب أو المستخدم بشكل مشفر مع تجريد فريد (`phone_hash`).
-- **جدول الطلاب المستقل (`students`):** يعتمد على **الرقم الوطني** كمعرف أساسي غير قابل للتكرار، ويرتبط بالمدرسة والكشف المعتمد.
-- **جدول أولياء الأمور المستقل (`guardians`):** يرتبط بهوية الأب ويمتلك علاقة متعددة (1:N) مع الأبناء عبر `guardian_students`.
-- **جدول المعلمين المستقل (`teachers`):** يرتبط بالمدرسة والتخصص ونطاق النشر (مدرسي خاص أو سوق عام).
+### 2.1 خريطة البوابات والروابط الرسمية
+- **بوابة الطالب الذكية:** `https://saqel.intaleqapp.com/student`
+- **بوابة استوديو المعلم:** `https://saqel.intaleqapp.com/teacher`
+- **بوابة ولي الأمر التفاعلية:** `https://saqel.intaleqapp.com/guardian`
+- **لوحة إدارة المدارس والمؤسسات:** `https://saqel.intaleqapp.com/school-admin`
 
-### 2.2 دورة الدخول وتجربة المستخدم
-1. **دخول ولي الأمر (OTP Login):**
-   - يدخل ولي الأمر برقم هاتفه، فتظهر له لوحة اختيار: *"متابعة تقارير الأبناء (أحمد، عمر، سارة)"* أو *"دخول ابن محدد لحضور الحصص"*.
-2. **دخول الطالب المباشر (National ID + PIN):**
-   - يستطيع الطالب الدخول اليومي لحصصه عبر (الرقم الوطني + رمز PIN) دون إزعاج ولي الأمر بطلب رمز التحقق في كل مرة.
+### 2.2 دورة الدخول وتعيين كلمة المرور
+1. **المستخدم المسجل مسبقاً:** يسجل دخوله برقم هاتفه وكلمة المرور (أو OTP) ليفتح له حسابه فوراً.
+2. **المستخدم الجديد (Zero-Mock Policy):** يدخل رقم هاتفه، ويطلب منه النظام ملء نموذج التسجيل الحقيقي (الاسم الكامل، التخصص/الرقم الوطني، كلمة المرور) وتفعيل حسابه بدون أي بيانات وهمية.
 
 ---
 
-## 3. منظومة المدارس الشريكة وكشوفات الأرقام الوطنية (B2B School Ingestion)
+## 3. محرك علاج نقاط الضعف السقراطي (AI Diagnostic & Remediation Loop)
 
-### 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 دنانير) مع تقاسم الإيراد بين المنصة والمعلم.
+عندما يجيب الطالب على فحص فهم أثناء الحصة:
+- **في حال الإجابة الصحيحة:** يثني النظام على الطالب، يعزز مؤشر الجاهزية (+0.5%)، ويستأنف الفيديو.
+- **في حال الإجابة الخاطئة:**
+  1. يُرجع المشغل الفيديو $N$ ثوانٍ لإعادة الاستماع للنقطة الجوهرية.
+  2. يُسجل المفهوم المتعثر في سجل التشخيص الجنائي (`exam_attempts.weak_topics_json`).
+  3. يُرسل إشعار مباشر في بوابة ولي الأمر يوضح النقطة التي تعثر فيها الابن وكيف تمت معالجتها.
 
 ---
 
-## 4. محرك تقييم جودة الحصص التعليمية بالذكاء الاصطناعي (Pedagogical Alignment Engine)
+## 4. محرك تحويل وأرشفة المناهج (Curriculum PDF to Markdown Ingestion)
 
-يقوم السيرفر فور رفع أي فيديو بتشغيل نموذج التحليل التربوي المعمق:
-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
+php backend/curriculum_converter.php
 ```
+- تُخزن الملفات في المسار: `backend/storage/curriculum/{subject}/{grade}/`.
+- تُقسم إلى وحدات وفصول ونتاجات تعلم إجرائية وقواعد رياضية لدعم البحث اللحظي وتوليد الأسئلة.
+
+---
+
+## 5. البنية السحابية وهندسة البث (Cloud Infrastructure & Zero-Egress R2)
+- **محرك البث:** تقطيع فيديوهات HLS عبر FFmpeg، والتخزين السحابي على Cloudflare R2 بدون رسوم خروج بيانات.
+- **محرك المحادثات الفورية:** خادم Workerman WebSocket على المنفذ 8080 لتوصيل الرسائل والإشعارات في زمن 0ms.
+- **الأداء العالي:** تشغيل مباشر عبر PHP 8.4 و PHP-FPM دون حاجة لـ Docker.