saqel/docs/SAQEL_ENTERPRISE_ARCHITECTURE.md

وثيقة المعمارية المؤسسية والهندسية لمنصة صَقِل (SAQEL Enterprise Architecture Blueprint)

مرجع تاريخي؛ وصف الجاهزية والأرقام الثابتة للتقدم/الأداء أدناه ليس دليلاً تشغيلياً. يرجع العمل الجديد إلى مواصفات 2026-09-09 وتدقيق الكود. الإتقان لا يزداد بمقدار ثابت لمجرد جواب صحيح، ولا يعتمد زمن أداء غير مقاس.

الإصدار: 3.1.0 (Unified Dynamic Multi-Persona App, Guardian Portal, School Admin SaaS & Curriculum Ingestion)
المؤسس والمهندس المعماري للتقنية: الأستاذ حمزة الغويري (Hamza Ayed)
تاريخ الاعتماد والتحديث: 2026-08-28

---

1. الملخص التنفيذي والرؤية الاستثمارية (Executive Summary & Moat)

منصة صَقِل (Saqel) هي البنية التحتية التعليمية الذكية الأحدث في المملكة الأردنية الهاشمية والشرق الأوسط (MENA). تجمع المنصة بين:

1. التطبيق الموحد الذكي للطالب والأسرة: تطبيق واحد يعمل على (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. معمارية التطبيق الموحد والبوابات (Unified App Routing)

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) ليفتح له حسابه فوراً.
2. المستخدم الجديد (Zero-Mock Policy): يدخل رقم هاتفه، ويطلب منه النظام ملء نموذج التسجيل الحقيقي (الاسم الكامل، التخصص/الرقم الوطني، كلمة المرور) وتفعيل حسابه بدون أي بيانات وهمية.

---

3. محرك علاج نقاط الضعف السقراطي (AI Diagnostic & Remediation Loop)

عندما يجيب الطالب على فحص فهم أثناء الحصة:

• في حال الإجابة الصحيحة: يثني النظام على الطالب، يعزز مؤشر الجاهزية (+0.5%)، ويستأنف الفيديو.
• في حال الإجابة الخاطئة:
  1. يُرجع المشغل الفيديو N ثوانٍ لإعادة الاستماع للنقطة الجوهرية.
  2. يُسجل المفهوم المتعثر في سجل التشخيص الجنائي (exam_attempts.weak_topics_json).
  3. يُرسل إشعار مباشر في بوابة ولي الأمر يوضح النقطة التي تعثر فيها الابن وكيف تمت معالجتها.

---

4. محرك تحويل وأرشفة المناهج (Curriculum PDF to Markdown Ingestion)

أداة سطر أوامر لتحويل وتفصيص كتب المناهج الرسمية:

php backend/curriculum_converter.php

• تُخزن الملفات في المسار: backend/storage/curriculum/{subject}/{grade}/.
• تُقسم إلى وحدات وفصول ونتاجات تعلم إجرائية وقواعد رياضية لدعم البحث اللحظي وتوليد الأسئلة.

---

5. البنية السحابية وهندسة البث (Cloud Infrastructure & Zero-Egress R2)

• محرك البث: تقطيع فيديوهات HLS عبر FFmpeg، والتخزين السحابي على Cloudflare R2 بدون رسوم خروج بيانات.
• محرك المحادثات الفورية: خادم Workerman WebSocket على المنفذ 8080 لتوصيل الرسائل والإشعارات في زمن 0ms.