saqel/docs/PLATFORM_MASTER_PLAN.md

📘 وثيقة المخطط المعماري والاستراتيجي الشامل — منصة "صَقِل" (Saqel Platform)

الرؤية: بناء الجيل الثاني من المنصات التعليمية (EdTech 2.0) لطلبة الثانوية العامة (التوجيهي) في الأردن والمنطقة، بالاعتماد على الفهم التفاعلي، مكافحة القرصنة الشاملة، والذكاء الاصطناعي التكيفي.

---

1. الهيكل المعماري والتقني (Architecture & Multi-App Ecosystem)

                            ┌───────────────────────────────────────────────────┐
                            │               تطبيقات منصة صَقِل                   │
                            │              (Apps Ecosystem - Flutter)           │
                            └─────────────────────────┬─────────────────────────┘
                                                      │
         ┌───────────────────┬────────────────────────┼────────────────────────┬───────────────────┐
         │                   │                        │                        │                   │
┌────────▼────────┐ ┌────────▼────────┐      ┌────────▼────────┐      ┌────────▼────────┐ ┌────────▼────────┐
│  student_app    │ │  teacher_app    │      │  guardian_app   │      │   admin_app     │ │   Web Portal    │
│ (تطبيق الطالب)   │ │ (تطبيق المعلم)  │      │ (تطبيق ولي الأمر)│      │(الإدارة والمدارس)│ │ (بوابة الويب)   │
└────────┬────────┘ └────────┬────────┘      └────────┬────────┘      └────────┬────────┘ └────────┬────────┘
         │                   │                        │                        │                   │
         └───────────────────┴────────────────────────┼────────────────────────┴───────────────────┘
                                                      │ HTTPS / REST API / JWT + Device Fingerprint
                                                      │
                                 ┌────────────────────▼────────────────────┐
                                 │    Laravel 11 API Gateway (PHP 8.3)     │
                                 │  (Zero-Trust Auth / Queues / Logic)     │
                                 └────────┬───────────────┬────────────────┘
                                          │               │
                       ┌──────────────────┴──┐         ┌──┴──────────────────┐
                       │                     │         │                     │
           ┌───────────▼───────────┐ ┌───────▼───────┐ │ ┌───────────────────▼───────────────────┐
           │ MySQL 8 (Master Data) │ │ Redis Cluster │ │ │ Bunny Stream CDN + MediaCage DRM      │
           │ (Users, PII Encrypted)│ │ (Cache/Locking│ │ │ (Encrypted HLS + Watermark Engine)    │
           └───────────────────────┘ └───────────────┘ │ └───────────────────────────────────────┘
                                                       │
                                             ┌─────────▼─────────┐
                                             │ AI & Speech Layer │
                                             │ Gemini / Whisper  │
                                             └───────────────────┘

---

2. المعايير الهندسية لتطبيقات Flutter (/apps)

تعتمد جميع التطبيقات الأربعة مبدأ (Thin Client)؛ الواجهات للعرض فقط، وكافة المعالجات الحسابية والصلاحيات والتحقق تُنفذ في الـ Backend:

المتطلب التقني	المكتبة / التقنية	الاستخدام والهدف
إدارة الحالة (State Management)	flutter_bloc / Cubit	بنية برمجية قياسية ونظيفة تفصل منطق العرض عن البيانات.
التخزين الآمن (Secure Storage)	flutter_secure_storage	تخزين الـ JWT Tokens وبصمة الجهاز داخل Keychain / Keystore المشفر.
الاتصال بالشبكة (Networking)	http	عميل شبكة خفيف ومحكم مع Interceptor لحقن الـ JWT وبصمة الجهاز في الـ Headers.
إدارة المتغيرات والبيئات	envied	تشفير وتوليد مفاتيح الـ API في كود الفلاتر أثناء الـ Compile time لمنع الهندسة العكسية.
أيقونات وهوية التطبيقات	flutter_launcher_icons	توليد أيقونات المنصة المعتمدة لكافة مقاسات iOS, Android, Desktop.
بصمة الجهاز (Device Fingerprint)	device_info_plus + Platform Hash	استخراج معرّف عتادي فريد وثابت للجهاز وإرساله مع كل طلب API لربطه بالـ JWT.
الإشعارات اللحظية (Push Notifications)	firebase_messaging	استقبال تنبيهات الكويزات، تقارير الأهل، وتحديثات الدروس.

---

3. المصادقة وأمن البيانات الحساسة (Zero-Trust & PII Security)

1. المصادقة عبر الواتساب و OTP فقط (No Social Login):
   • إلغاء التسجيل عبر جوجل/فيسبوك حالياً والاعتماد الحصري على رقم الهاتف.
   • إرسال رموز التحقق (OTP) عبر منصة تنبيه (Tanbih API) على الواتساب والـ SMS (نفس نمط منصة سيرو المعتمد).
2. استخراج الهوية الحصري من الـ JWT:
   • التوكن يحتوي على: { user_id, role, school_id, device_fingerprint, token_version }.
   • لا يُقبل أي user_id في مسارات الـ API (Body أو Query) لمنع ثغرات IDOR.
3. تشفير البيانات الحساسة (PII Encryption):
   • تشفير رقم الهاتف والاسم بـ AES-256-GCM مع Nonce عشوائي.
   • إنشاء حقل phone_hash مفهرس أعمى (Blind Index) عبر HMAC-SHA256 للبحث والتحقق اللحظي في قاعدة البيانات.
4. حظر تعدد الأجهزة الفوري (Redis Active Session Lock):
   • مفتاح active_session:{user_id} في Redis يسجل بصمة الجهاز الحالية؛ أي دخول من جهاز آخر يبطل الجلسة فوراً.

---

4. شجرة المشروع وهيكلية المجلدات

saqel/
├── apps/                        # مجلد تطبيقات Flutter
│   ├── student_app/             # تطبيق الطالب (كويزات، مشغل فيديو، ملاحظات صوتية)
│   ├── teacher_app/             # تطبيق المعلم (رفع المواد، كويزات، تقارير المبيعات)
│   ├── guardian_app/            # تطبيق ولي الأمر (متابعة الأبناء، التقارير الذكية)
│   └── admin_app/               # تطبيق الإدارة ومديري المدارس (B2B)
├── backend/                     # مشروع Laravel 11 API Gateway
│   ├── app/Http/Controllers/Api # وحدات التحكم بالـ APIs
│   ├── app/Services/            # خدمات AI (Gemini)، OTP (Tanbih)، و Bunny Stream
│   └── database/migrations/     # مخطط قاعدة البيانات
├── docker/                      # إعدادات الحاويات والإنتاج
│   ├── nginx/                   # إعدادات الويب سيرفر
│   ├── php/                     # Dockerfile الخاص بـ PHP-FPM 8.3
│   └── .env.docker.example      # قالب المتغيرات الإنتاجية للـ Docker
├── docs/                        # وثائق التخطيط والتحليل
│   └── PLATFORM_MASTER_PLAN.md  # هذا المرجع المعماري الشامل
├── docker-compose.yml           # حاويات: saqel_app, saqel_nginx, saqel_mysql, saqel_queue
└── README.md                    # دليل التشغيل السريع

---

5. ميزات الجيل الثاني (EdTech 2.0 Feature Set)

1. الملاحظات الصوتية والتفريغ الآلي (Voice Notes & Whisper/Gemini):
   • تسجيل الملاحظة الصوتية المربوطة بلحظة الفيديو وتفريغها لنص عربي فوري عبر Whisper / Groq API.
2. الكويز الصدمي مع الإرجاع العلاجي (In-Video Socratic Gatekeeping):
   • إيقاف الفيديو عند الدقيقة المحددة، وإرجاع الطالب تلقائياً 45 ثانية في حال الخطأ.
3. مؤشر الجاهزية للوزاري (Exam Readiness Score 0-100%):
   • خوارزمية ذكية تقيس مدى تمكن الطالب من نواتج التعلم الوزارية.
4. بطاقات التكرار المتباعد (Spaced Repetition Flashcards):
   • جلسة يومية (3 دقائق) لمراجعة المفاهيم السابقة ونقاط الضعف.
5. منع القرصنة الجنائي (4-Tier Anti-Piracy):
   • تشفير HLS + DRM، علامة مائية باسم ورقم هاتف والـ IP الخاص بالطالب، وحظر تسجيل الشاشة Native.