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

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

---

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

```
                            ┌───────────────────────────────────────────────────┐
                            │               تطبيقات منصة صَقِل                   │
                            │              (Apps Ecosystem - Flutter)           │
                            └─────────────────────────┬─────────────────────────┘
                                                      │
                         ┌────────────────────────────┼────────────────────────────┐
                         │                            │                            │
                ┌────────▼────────┐          ┌────────▼────────┐          ┌────────▼────────┐
                │  student_app    │          │  teacher_app    │          │   admin_app     │
                │ (الطالب + ولي الأمر)│          │ (استوديو المعلم)│          │(الإدارة والمدارس)│
                └────────┬────────┘          └────────┬────────┘          └────────┬────────┘
                         │                            │                            │
                         └────────────────────────────┼────────────────────────────┘
                                                      │ 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)** مع هوية أبل وخطوط San Francisco الرسمية (`SF Pro Display` & `SF Arabic`)؛ الواجهات للعرض والتفاعل، وكافة المعالجات الحسابية والصلاحيات والتحقق تُنفذ في الـ Backend:

| المتطلب التقني | المكتبة / التقنية | الاستخدام والهدف |
|---|---|---|
| **إدارة الحالة (State Management)** | `flutter_bloc` / `Cubit` | بنية برمجية قياسية ونظيفة تفصل منطق العرض عن البيانات. |
| **التخزين الآمن (Secure Storage)** | `flutter_secure_storage` | تخزين الـ JWT Tokens وبصمة الجهاز داخل Keychain / Keystore المشفر. |
| **الاتصال بالشبكة (Networking)** | `http` | عميل شبكة خفيف ومحكم مع Interceptor لحقن الـ JWT وبصمة الجهاز في الـ Headers. |
| **بصمة الجهاز (Device Fingerprint)** | `device_info_plus` + Platform Hash | استخراج معرّف عتادي فريد وثابت للجهاز وإرساله مع كل طلب API لربطه بالـ JWT. |
| **الخطوط الرسمية (Apple Typography)** | `-apple-system` / `SF Pro` / `SF Arabic` | خطوط أبل الرسمية مع تباعد أحرف دقيق وهندسة Cupertino الداكنة. |

---

## 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. **عزل الجلسات النشطة في الذاكرة (Role-Isolated Session Lock):**
   - مفتاح `active_session:{role}:{user_id}` في Redis يعزل جلسة المعلم عن الطالب وولي الأمر لنفس رقم الهاتف، ويبطل أي دخول غير مصرح به من أجهزة أخرى فوراً.

---

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

```
saqel/
├── apps/                        # مجلد تطبيقات Flutter (النموذج الثلاثي المعتمد)
│   ├── student_app/             # تطبيق صَقِل الموحد (الطالب: كويزات وفيديوهات + ولي الأمر: تقارير الأبناء)
│   ├── teacher_app/             # تطبيق المعلم (رفع المواد، كويزات، تقارير المبيعات والأرباح)
│   └── admin_app/               # تطبيق الإدارة ومديري المدارس (B2B Management)
├── backend/                     # مشروع Laravel 11 / Native PHP 8.3 API Gateway
│   ├── app/Controllers/         # وحدات التحكم بالـ APIs
│   ├── app/Services/            # خدمات AI، و Nabeh WhatsApp Gateway، و Curriculum
│   └── database/                # مخطط قاعدة البيانات
├── 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.