feat: Initial commit for Saqel Platform architecture, backend, Docker, and documentation

2026-08-26 15:45:55 +03:00
commit d53b64500a
177 changed files with 19909 additions and 0 deletions
@@ -0,0 +1,113 @@
+# 📘 وثيقة المخطط المعماري والاستراتيجي الشامل — منصة "صَقِل" (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.