Enrich full codebase with architectural Arabic docblocks and synchronize database_schema.sql with live database

apps/student_app/lib/logic/cubits/exam_cubit.dart

@@ -1,15 +1,31 @@
+/// ==============================================================================
+/// SAQEL ENTERPRISE (EDTECH 2.0) - ADAPTIVE EXAM STATE MANAGEMENT (CUBIT)
+/// ==============================================================================
+/// 
+/// ملف: exam_cubit.dart
+/// الهدف المعماري:
+/// إدارة حالة دورة حياة الامتحانات التكيفية والتشخيص الذكي في تطبيق الطالب:
+/// 1. جلب الامتحانات مباشرة من واجهات السيرفر (Pure API-Driven) دون أي بيانات أو أسئلة محلية ثابتة.
+/// 2. إدارة المؤقت التنازلي الذكي ومزامنة الوقت المتبقي.
+/// 3. إدارة التنقل بين الأسئلة وحفظ اختيارات الطالب وتحديد البدائل المحددة.
+/// 4. إرسال الإجابات إلى السيرفر لتصحيحها واستلام تقرير التشخيص السقراطي ومؤشر الجاهزية للتوجيهي.
+library;
+
 import 'dart:async';
 import 'package:flutter_bloc/flutter_bloc.dart';
 import '../../data/models/exam_model.dart';
 import '../../data/repositories/app_repositories.dart';
 
+/// الحالات العامة للامتحان
 abstract class ExamState {}
 
+/// الحالة المبدئية قبل بدء التحميل
 class ExamInitial extends ExamState {}
 
+/// حالة انتظار جلب الأسئلة من السيرفر
 class ExamLoading extends ExamState {
   final String message;
-  ExamLoading({this.message = 'جاري تحضير الامتحان والأسئلة التكيفية...'});
+  ExamLoading({this.message = 'جاري تحضير الامتحان والأسئلة التكيفية من السيرفر...'});
 }
 
 class ExamLoaded extends ExamState {

apps/student_app/lib/main.dart

@@ -1,3 +1,16 @@
+/// ==============================================================================
+/// SAQEL ENTERPRISE (EDTECH 2.0) - FLUTTER APPLICATION ENTRY POINT
+/// ==============================================================================
+/// 
+/// ملف: main.dart
+/// الهدف المعماري:
+/// نقطة الدخول الرئيسية لتطبيق الطالب الموحد لمنصة صَقِل.
+/// يتولى هذا الملف:
+/// 1. تهيئة بيئة تشغيل فلاتر وتثبيت معايير التصميم العالمي (Cupertino Dark Aesthetic).
+/// 2. حقن وإدارة كافة الـ BLoC/Cubit Providers (المصادقة، المنهاج، المشغل، لوحة الطالب وولي الأمر).
+/// 3. التوجيه التلقائي بين شاشة تسجيل الدخول والشاشة الموحدة وفق حالة الجلسة.
+library;
+
 import 'package:flutter/material.dart';
 import 'package:flutter_bloc/flutter_bloc.dart';
 import 'core/config/app_config.dart';
@@ -10,11 +23,13 @@ import 'logic/cubits/video_playback_cubit.dart';
 import 'presentation/screens/auth/auth_screen.dart';
 import 'presentation/screens/home/unified_home_screen.dart';
 
+/// نقطة انطلاق التطبيق الرئيسية
 void main() {
   WidgetsFlutterBinding.ensureInitialized();
   runApp(const SaqelAppRoot());
 }
 
+/// الودجت الجذرية للتطبيق (Root Widget) المحتوية على المزودات وإعدادات الثيم والاتجاه العربي
 class SaqelAppRoot extends StatefulWidget {
   const SaqelAppRoot({super.key});
 

apps/student_app/lib/presentation/screens/curriculum/curriculum_document_viewer_screen.dart

@@ -1,9 +1,23 @@
+/// ==============================================================================
+/// SAQEL ENTERPRISE (EDTECH 2.0) - IN-APP CURRICULUM DOCUMENT & TEXTBOOK READER
+/// ==============================================================================
+/// 
+/// ملف: curriculum_document_viewer_screen.dart
+/// الهدف المعماري:
+/// عارض وقارئ المستندات وأوراق العمل والكتب المدرسية المقررة داخل التطبيق مباشرة:
+/// 1. قراءة سلسة ومريحة للمحتوى دون الحاجة للتحميل والتطبيقات الخارجية.
+/// 2. التحكم اللحظي بحجم الخط (Font Zoom Control +/-).
+/// 3. عرض مهيكل للنتاجات، القواعد الذهبية، الأمثلة الوزارية المحلولة خطوة بخطوة.
+/// 4. تمارين تفاعلية للتقييم الذاتي مع زر لمسي لإظهار وإخفاء الحل النموذجي.
+library;
+
 import 'package:flutter/cupertino.dart';
 import 'package:flutter/material.dart';
 import '../../../core/theme/app_colors.dart';
 import '../../../core/utils/saqel_toast.dart';
 import '../../widgets/luxury_widgets.dart';
 
+/// شاشة عارض أوراق العمل والملخصات والكتب الوزارية التفاعلية
 class CurriculumDocumentViewerScreen extends StatefulWidget {
   final String title;
   final String documentType; // 'worksheet', 'summary', 'textbook'

apps/student_app/lib/presentation/screens/curriculum/subject_hub_screen.dart

@@ -1,3 +1,16 @@
+/// ==============================================================================
+/// SAQEL ENTERPRISE (EDTECH 2.0) - SUBJECT HUB & MULTI-TEACHER CURRICULUM SCREEN
+/// ==============================================================================
+/// 
+/// ملف: subject_hub_screen.dart
+/// الهدف المعماري:
+/// المركز الشامل للمادة الدراسية (Subject Hub):
+/// 1. فهرسة وحدات ودروس المنهاج الوزاري وشروحات المعلمين والذكاء الاصطناعي.
+/// 2. بطاقة اختيار الشرح متعدد المعلمين (Multi-Teacher & Saqel AI Video Selector Modal).
+/// 3. مركز بنك الأسئلة والامتحانات التكيفية لبدء الاختبارات الشاملة (Adaptive Exams).
+/// 4. تبويب المذكرات وأوراق العمل والكتب المدرسية المقررة للقراءة والتصفح المباشر.
+library;
+
 import 'package:flutter/cupertino.dart';
 import 'package:flutter/material.dart';
 import '../../../core/theme/app_colors.dart';
@@ -9,6 +22,7 @@ import '../player/socratic_video_player_screen.dart';
 import '../exams/adaptive_exam_screen.dart';
 import 'curriculum_document_viewer_screen.dart';
 
+/// الشاشة المركزية للمادة الدراسية وبوابات الدروس والامتحانات والمصادر
 class SubjectHubScreen extends StatefulWidget {
   final SubjectModel subject;
 

apps/student_app/lib/presentation/screens/exams/adaptive_exam_screen.dart

@@ -1,3 +1,17 @@
+/// ==============================================================================
+/// SAQEL ENTERPRISE (EDTECH 2.0) - ADAPTIVE EXAM SCREEN (CUPERTINO LUXURY UI)
+/// ==============================================================================
+/// 
+/// ملف: adaptive_exam_screen.dart
+/// الهدف المعماري:
+/// شاشة تقديم الامتحانات التكيفية بتصميم أبل كوبرتينو المظلم (Dark OLED Aesthetic):
+/// 1. مؤشر تقدم تفاعلي متزامن مع نسبة الإجابات المكتملة.
+/// 2. مؤقت تنازلي ذكي يتغير لونه إلى الأحمر عند اقتراب انتهاء الوقت.
+/// 3. بطاقات أسئلة لمسية فاخرة مع أزرار اختيار مشعة (Glowing Glassmorphic Radios).
+/// 4. شاشة عرض نتائج متقدمة تحتوي على: نسبة الإتقان، وسام الاجتياز، تقرير التشخيص بالذكاء الاصطناعي،
+///    وسوم نقاط الضعف، ومؤشر الجاهزية لامتحان التوجيهي.
+library;
+
 import 'package:flutter/cupertino.dart';
 import 'package:flutter/material.dart';
 import 'package:flutter_bloc/flutter_bloc.dart';
@@ -7,6 +21,7 @@ import '../../../core/utils/saqel_toast.dart';
 import '../../../logic/cubits/exam_cubit.dart';
 import '../../widgets/luxury_widgets.dart';
 
+/// الشاشة التكيفية لتقديم الامتحان واستقبال نتائج التصحيح اللحظية
 class AdaptiveExamScreen extends StatelessWidget {
   final int examId;
   final String title;

apps/student_app/lib/presentation/screens/player/socratic_video_player_screen.dart

@@ -1,3 +1,18 @@
+/// ==============================================================================
+/// SAQEL ENTERPRISE (EDTECH 2.0) - SOCRATIC VIDEO PLAYER SCREEN
+/// ==============================================================================
+/// 
+/// ملف: socratic_video_player_screen.dart
+/// الهدف المعماري:
+/// مشغل الفيديو السقراطي الذكي والمحمي في تطبيق صَقِل:
+/// 1. تشغيل الفيديو الرقمي وبث HLS عبر مشغل مخصص عالي الأداء.
+/// 2. حماية الملكية الفكرية بعلامة مائية متحركة ديناميكية (Dynamic Anti-Piracy Watermark).
+/// 3. محاذاة نقاط التقدم اللمسية مع نقاط الفحص السقراطي الزمني (Socratic Checkpoints).
+/// 4. تجميد الفيديو وإظهار نافذة الفحص السقراطي عند وصول المؤشر لنقطة الفحص.
+/// 5. تفعيل الإرجاع العلاجي (Rewind Remediation) عند الإجابة الخاطئة لترسيخ الفهم.
+/// 6. إبراز شارة المعلم المختار (شرح الذكاء الاصطناعي أو المعلم المعتمد).
+library;
+
 import 'dart:async';
 import 'package:flutter/cupertino.dart';
 import 'package:flutter/material.dart';
@@ -12,6 +27,7 @@ import '../../widgets/luxury_widgets.dart';
 import '../../widgets/socratic_dialog.dart';
 import 'package:video_player/video_player.dart';
 
+/// مشغل الفيديو السقراطي الذكي ونقاط الفحص والإرجاع العلاجي
 class SocraticVideoPlayerScreen extends StatefulWidget {
   final CurriculumLessonItemModel lesson;
   final SubjectModel? subject;

backend/app/Controllers/AuthController.php

@@ -1,4 +1,19 @@
 <?php
+/**
+ * ==============================================================================
+ * SAQEL ENTERPRISE (EDTECH 2.0) - AUTHENTICATION & IDENTITY CONTROLLER
+ * ==============================================================================
+ * 
+ * ملف: AuthController.php
+ * الهدف المعماري:
+ * إدارة منظومة الهوية الرقمية والدخول الآمن والتحقق عبر الواتساب (OTP) في منصة صَقِل.
+ * يتولى هذا الملف المهام التالية:
+ * 1. إرسال رموز التحقق لمرة واحدة (OTP) عبر الواتساب بواسطة بوابة نبّه الرسمية (Nabeh Gateway).
+ * 2. التحقق من صحة الرمز وتوليد رموز JWT المشفرة بصلاحيات محددة (طالب، معلم، ولي أمر، مدير).
+ * 3. حماية الحسابات من هجمات الاختراق عبر بصمة الجهاز الرقمية (Device Fingerprinting).
+ * 4. إدارة جلسات تسجيل الدخول والخروج والتحقق من صلاحية التوكن (Token Introspection).
+ * 5. التحقق عبر الرقم الوطني لطلاب مديرية الثقافة العسكرية والمدارس الحكومية.
+ */
 
 namespace App\Controllers;
 
@@ -13,8 +28,11 @@ use App\Services\NabehService;
 class AuthController
 {
     /**
-     * Request OTP via WhatsApp (Nabeh Gateway)
+     * طلب رمز تحقق OTP جديد وإرساله عبر الواتساب بواسطة بوابة نبّه
      * POST /api/auth/otp/request
+     * 
+     * @param Request  $request  طلب الـ HTTP المحتوي على رقم الهاتف بصيغة دولية أو محلية
+     * @param Response $response كائن الاستجابة بحالة الإرسال وزمن انتهاء الصلاحية
      */
     public function requestOtp(Request $request, Response $response): void
     {

backend/app/Controllers/CurriculumController.php

@@ -1,4 +1,21 @@
 <?php
+/**
+ * ==============================================================================
+ * SAQEL ENTERPRISE (EDTECH 2.0) - CURRICULUM & STUDIO CONTROLLER
+ * ==============================================================================
+ * 
+ * ملف: CurriculumController.php
+ * الهدف المعماري:
+ * إدارة منظومة تفريغ وفهرسة كتب المناهج الوزارية واستوديو المناهج (Curriculum Studio).
+ * يتولى هذا الملف المهام التالية:
+ * 1. استلام كتب الـ PDF الوزارية المرفوعة وتمريرها لعمال الخلفية لاستخراج شجرة الماركداون.
+ * 2. متابعة حالة مهام المعالجة والتفريغ التلقائي وإرجاع سجلات التشغيل الحية (Live Logs).
+ * 3. استرجاع الشجرة الهرمية للمنهاج (المرحلة، المادة، الفصل، الوحدة، الدرس).
+ * 4. حفظ وتحديث محتوى ملفات الماركداون للدروس وربطها مع قاعدة البيانات.
+ * 5. توليد الملخصات الذكية (Cheat Sheets) والفحوصات السقراطية عبر Gemini.
+ * 6. توليد وتحديث بنوك الأسئلة (50 سؤالاً للوحدة) بالذكاء الاصطناعي بنقرة واحدة من الاستوديو.
+ * 7. استضافة ورفع ملفات الفيديو مباشرة وربطها بالدروس.
+ */
 
 namespace App\Controllers;
 
@@ -10,7 +27,11 @@ use App\Services\CurriculumExtractorService;
 class CurriculumController
 {
     /**
-     * Upload and Queue Real Ministry PDF Document for Deep Extraction
+     * استلام ورفع كتاب المنهاج الوزاري بصيغة PDF وجدولته في طابور المعالجة المعمقة
+     * POST /api/curriculum/upload-pdf
+     * 
+     * @param Request  $request  طلب الـ HTTP المحتوي على ملف الـ PDF المرفوع
+     * @param Response $response كائن الاستجابة بمعرف المهمة ومسار المتابعة
      */
     public function uploadPdf(Request $request, Response $response): void
     {

backend/app/Controllers/ExamController.php

@@ -1,4 +1,20 @@
 <?php
+/**
+ * ==============================================================================
+ * SAQEL ENTERPRISE (EDTECH 2.0) - EXAM & ADAPTIVE ASSESSMENT CONTROLLER
+ * ==============================================================================
+ * 
+ * ملف: ExamController.php
+ * الهدف المعماري:
+ * إدارة منظومة القياس والتقويم والامتحانات التكيفية في منصة صَقِل.
+ * يقوم هذا الملف بالوظائف الجوهرية التالية:
+ * 1. استرجاع قائمة الامتحانات والفحوصات السقراطية (in_video_checkpoint, lesson_exam, unit_exam).
+ * 2. محرك الاختيار التكيفي (Adaptive 60/40 Engine): فحص نقاط ضعف الطالب وسحب 60% من أسئلة الامتحان
+ *    من المفاهيم التي تعثر فيها الطالب سابقاً لسد الثغرات وتحقيق الإتقان، و 40% من باقي مفاهيم الوحدة.
+ * 3. استلام وتصحيح إجابات الامتحانات لحظياً وحساب نسبة الإتقان وتوليد تقرير التشخيص الذكي (AI Diagnostic Report).
+ * 4. إطلاق إشعار الواتساب التوجيهي الهادئ لولي الأمر عبر بوابة "نبّه" عند رصد حاجة الطالب للمعالجة.
+ * 5. حساب مؤشرات الجاهزية للتوجيهي ونقاط الإتقان لكل مادة دراسية.
+ */
 
 namespace App\Controllers;
 
@@ -10,8 +26,11 @@ use App\Core\Validator;
 class ExamController
 {
     /**
-     * List exams for a specific course/lesson/scope
+     * جلب قائمة الامتحانات المتاحة لمادة أو درس معين مع عدد الأسئلة
      * GET /api/exams?course_id=1&lesson_id=2&scope=in_video_checkpoint
+     * 
+     * @param Request  $request  طلب الـ HTTP المحتوي على معاملات التصفية (course_id, lesson_id, scope)
+     * @param Response $response كائن الاستجابة لإرجاع مصفوفة الامتحانات بصيغة JSON
      */
     public function getExams(Request $request, Response $response): void
     {
@@ -50,8 +69,17 @@ class ExamController
     }
 
     /**
-     * Get single exam with questions and sanitized options
+     * استرجاع تفاصيل الامتحان مع الأسئلة والخيارات المنقحة (ومحرك الاختيار التكيفي 60/40)
      * GET /api/exams/{id}
+     * 
+     * آلية العمل:
+     * 1. التحقق من وجود الامتحان، وإذا كان غير مفهرس يتم استدعاء باني الأسئلة التلقائي للوحدة الأولى.
+     * 2. تطبيق خوارزمية التعلم التكيفي (Adaptive Sampling): إذا كان بنك الأسئلة يحتوي على أكثر من 15 سؤالاً،
+     *    يتم فحص تاريخ الطالب واستخراج المفاهيم التي أخطأ فيها سابقاً وسحب 60% من أسئلة الامتحان منها.
+     * 3. تنقيح خيارات الإجابة وحجب حقل (is_correct) عن الطالب منعاً للغش وإظهاره فقط للمعلم أو الأدمن.
+     * 
+     * @param Request  $request  طلب الـ HTTP المحتوي على معرف الامتحان في المسار ومعرف الطالب المصادق عليه
+     * @param Response $response كائن الاستجابة لإرجاع كائن الامتحان بأسئلته الـ 15 التكيفية
      */
     public function getExamDetails(Request $request, Response $response): void
     {
@@ -141,8 +169,19 @@ class ExamController
     }
 
     /**
-     * Submit Exam Attempt & Calculate Instant AI Diagnostic Evaluation
+     * تصحيح الامتحان لحظياً بالذكاء الاصطناعي وتوليد التقرير التشخيصي وإشعار ولي الأمر
      * POST /api/exams/{id}/submit
+     * 
+     * الوظائف المنجزة:
+     * 1. التحقق من إجابات الطالب ومقارنتها بالخيارات الصحيحة وحساب مجموع النقاط ونسبة الإتقان المئوية.
+     * 2. تسجيل كل إجابة في جدول (student_question_answers) لبناء ملف الضعف والقوة للتعلم التكيفي المستقبلي.
+     * 3. توليد تقرير تشخيصي ذكي (AI Diagnostic Report) يبرز المفاهيم المتقنة والمفاهيم المتعثر فيها بدقة.
+     * 4. فحص شرط النجاح: إذا كانت النتيجة أقل من نسبة النجاح، يتم ضبط الحالة على needs_remediation
+     *    وإطلاق رسالة توجيهية هادئة عبر الواتساب لولي الأمر عبر بوابة نبّه (Nabeh Gateway).
+     * 5. تحديث جدول إتقان الطالب (student_course_mastery) ونقاط جاهزية التوجيهي.
+     * 
+     * @param Request  $request  طلب الـ HTTP المحتوي على الإجابات ووقت المحاولة
+     * @param Response $response كائن الاستجابة بالنتيجة والتقرير وتفاصيل الحل النموذجي
      */
     public function submitExam(Request $request, Response $response): void
     {
@@ -350,8 +389,11 @@ class ExamController
     }
 
     /**
-     * Get Student Mastery & Tawjihi Readiness Analytics
+     * استرجاع مقاييس إتقان الطالب ومؤشر الجاهزية لامتحان التوجيهي
      * GET /api/student/progress/mastery?course_id=1
+     * 
+     * @param Request  $request  طلب الـ HTTP المحتوي على معرف الطالب ومعرف المادة
+     * @param Response $response كائن الاستجابة بنسبة الإتقان والمحاولات الأخيرة
      */
     public function getMastery(Request $request, Response $response): void
     {
@@ -386,6 +428,10 @@ class ExamController
         ]);
     }
 
+    /**
+     * فحص التوافقية الذاتية وترقية جداول الامتحانات والتقييم في قاعدة البيانات
+     * تقوم بإنشاء جدول (student_question_answers) والتأكد من وجود عمود (completed_at) وتوسيع الـ ENUM
+     */
     public static function ensureSchema(): void
     {
         try {
@@ -424,6 +470,11 @@ class ExamController
         }
     }
 
+    /**
+     * التهيئة والتوليد الذاتي لامتحان الوحدة الأولى الشامل وحقن الأسئلة من بنك الذكاء الاصطناعي
+     * 
+     * @return int معرف الامتحان في قاعدة البيانات
+     */
     public static function seedUnit1ComprehensiveExam(): int
     {
         self::ensureSchema();

backend/app/Controllers/VideoController.php

@@ -1,4 +1,19 @@
 <?php
+/**
+ * ==============================================================================
+ * SAQEL ENTERPRISE (EDTECH 2.0) - VIDEO STREAMING & SOCRATIC PLAYBACK CONTROLLER
+ * ==============================================================================
+ * 
+ * ملف: VideoController.php
+ * الهدف المعماري:
+ * إدارة منظومة بث الفيديو الرقمي، وتوليد الفحوصات السقراطية، وبث HLS المجزأ عبر Cloudflare R2.
+ * يتولى هذا الملف المهام التالية:
+ * 1. رفع ملفات الفيديو المباشرة وتحويلها وتجزئتها إلى مقاطع HLS مشفرة لحماية الملكية الفكرية.
+ * 2. تشغيل التحليل السمعي-البصري بالذكاء الاصطناعي (AiVideoAnalyzerService) لتوليد الفصول الزمنية ونقاط الفحص السقراطي.
+ * 3. بث الفيديو عبر روابط مؤقتة آمنة (Byte-Range Streaming و HLS Playlists).
+ * 4. تزويد مشغل الفيديو في فلاتر ببيانات التشغيل (الروابط، الفصول، المعلم المعتمد، ونقاط التوقف السقراطية).
+ * 5. حفظ تقدم المشاهدة اللحظي لكل طالب في جدول (lesson_progress) وإدارة الاستئناف التلقائي.
+ */
 
 namespace App\Controllers;
 
@@ -13,8 +28,11 @@ use App\Services\CurriculumService;
 class VideoController
 {
     /**
-     * Upload Video directly via API, transcode HLS, and trigger Autonomous Gemini AI Analysis
+     * رفع فيديو الشرح مباشرة عبر واجهة البرمجة وتوليد HLS وبدء التحليل السقراطي بالذكاء الاصطناعي
      * POST /api/teacher/videos/upload-direct
+     * 
+     * @param Request  $request  طلب الـ HTTP المحتوي على ملف الفيديو والبيانات الوصفية
+     * @param Response $response كائن الاستجابة بحالة الرفع ومعرف الدرس ورابط المشاهدة
      */
     public function uploadDirect(Request $request, Response $response): void
     {

backend/app/Services/AiLessonEnhancerService.php

@@ -1,4 +1,18 @@
 <?php
+/**
+ * ==============================================================================
+ * SAQEL ENTERPRISE (EDTECH 2.0) - AI LESSON ASSETS ENHANCER SERVICE
+ * ==============================================================================
+ * 
+ * ملف: AiLessonEnhancerService.php
+ * الهدف المعماري:
+ * توليد وتطوير الأصول التعليمية الذكية للدروس والمناهج:
+ * 1. تحويل نص الماركداون للدرس إلى ملخص مركز (Cheat Sheet) وقواعد ذهبية.
+ * 2. صياغة سيناريو حواري لشرح الدرس (Video Script).
+ * 3. توليد سؤال فحص سقراطي ذكي مع خيارات وشرح علمي.
+ * 4. توليد برومبتات المحاكيات الفيزيائية والمعامل التفاعلية (HTML5 Canvas Interactive Lab Simulations).
+ * 5. يوفر آلية توليد احتياطية حتمية تضمن الاستقرار الدائم.
+ */
 
 namespace App\Services;
 
@@ -8,7 +22,11 @@ use App\Core\Env;
 class AiLessonEnhancerService
 {
     /**
-     * Extracts the lively script, cheat sheet, and Socratic quiz using Gemini or Intelligent Synthesis Fallback.
+     * استخراج المخرجات الذكية (الملخص، الفحص السقراطي، والسيناريو) من نص الدرس
+     * 
+     * @param string $title   عنوان الدرس
+     * @param string $content محتوى الدرس بصيغة الماركداون
+     * @return array مصفوفة تحتوي على cheat_sheet, socratic_quiz, video_script
      */
     public static function generateFromText(string $title, string $content): array
     {

backend/app/Services/AiQuestionBankGeneratorService.php

@@ -1,20 +1,36 @@
 <?php
+/**
+ * ==============================================================================
+ * SAQEL ENTERPRISE (EDTECH 2.0) - AI QUESTION BANK GENERATOR SERVICE
+ * ==============================================================================
+ * 
+ * ملف: AiQuestionBankGeneratorService.php
+ * الهدف المعماري:
+ * المحرك المركزي العام لتوليد وفهرسة بنوك الأسئلة الوزارية والتكيفية بالذكاء الاصطناعي.
+ * مصمم ليكون مستقلاً تماماً عن الصف أو المادة:
+ * 1. يقرأ ملفات المناهج بصيغة Markdown المرفوعة على السيرفر لأي كتاب أو وحدة أو درس.
+ * 2. يحلل المحتوى والنتاجات والمعادلات عبر Gemini API بواسطة برومبت قياس وتقويم وزاري محكم.
+ * 3. يولد 50 سؤالاً مصنفاً لكل وحدة، و 15-20 سؤالاً لكل درس، مصنفة حسب هرمية بلوم (تذكر، فهم، تطبيق، تحليل).
+ * 4. يربط كل سؤال بوسمه الموضوعي (topic_tag) والشرح العلمي والخيارات والتغذية الراجعة.
+ * 5. يوفر محرك توليد احتياطي حتمي (Deterministic Curriculum Synthesis) مبني على نصوص وتمارين الكتاب
+ *    ليعمل النظام بكفاءة 100% حتى في حال غياب أو تعطل مفتاح Gemini الخارجي.
+ * 6. يحقن الأسئلة مباشرة في جدولي (questions) و (question_options) في قاعدة بيانات صَقِل.
+ */
 
 namespace App\Services;
 
 use App\Core\Database;
 use App\Core\Env;
 
-/**
- * Universal Server-Side AI Question Bank Generator Service
- * Ingests Curriculum Markdown Files (for any Grade / Subject) and generates:
- * 1. 15-20 Questions per Lesson (tagged with bloom_taxonomy, topic_tag, and difficulty)
- * 2. 50 Comprehensive Questions per Unit (seeded into Question Bank for Adaptive Testing)
- */
 class AiQuestionBankGeneratorService
 {
     /**
-     * Generate 50 Comprehensive Questions for a Unit from its Markdown files
+     * توليد وحقن بنك الـ 50 سؤالاً الشامل للوحدة الدراسية من ملفات الماركداون
+     * 
+     * @param string $unitRelativePath المسار النسبي لمجلد الوحدة داخل storage/curriculum
+     * @param int    $courseId         معرّف المادة الدراسية
+     * @param int    $targetCount      العدد المستهدف من الأسئلة في البنك (افتراضياً 50)
+     * @return array مصفوفة تحتوي على معرف الامتحان وعنوان الوحدة وإجمالي الأسئلة المحقونة
      */
     public static function generateUnitQuestionBank(string $unitRelativePath, int $courseId = 1, int $targetCount = 50): array
     {

backend/app/Services/AiVideoAnalyzerService.php

@@ -1,21 +1,31 @@
 <?php
+/**
+ * ==============================================================================
+ * SAQEL ENTERPRISE (EDTECH 2.0) - AI VIDEO & SOCRATIC CHECKPOINT ANALYZER
+ * ==============================================================================
+ * 
+ * ملف: AiVideoAnalyzerService.php
+ * الهدف المعماري:
+ * التحليل الذكي المستقل للفيديوهات التعليمية وتوليد الفحوصات السقراطية والفصول الزمنية:
+ * 1. فهرسة الفصول الزمنية الذكية للدرس (Timeline Chapters) بدقة الثواني والدقائق.
+ * 2. توليد نقاط الفحص السقراطي الزمنية (Chronological Socratic Checkpoints) التي تقطع المشاهدة
+ *    وتلزم الطالب بالإجابة للتأكد من اليقظة والفهم، وتحدد زمن الإرجاع العلاجي (rewind_seconds) عند الخطأ.
+ * 3. توليد بنك أسئلة إتقان الدرس الختامي مستنداً حرفياً إلى كتاب المنهاج الوزاري المعتمد.
+ * 4. ربط كل فحص سقراطي بنتاجات التعلم المحددة في شجرة المنهاج.
+ */
 
 namespace App\Services;
 
 use App\Core\Database;
 use App\Core\Security;
 
-/**
- * Autonomous AI Forensic Video & Curriculum Analyzer Service (Gemini Powered)
- * Operates headlessly in the background with zero teacher cognitive load:
- * 1. Timeline chapter indexing by minutes
- * 2. Strictly chronological Socratic in-video checkpoints
- * 3. 10-question post-lesson mastery bank strictly grounded in official textbooks
- */
 class AiVideoAnalyzerService
 {
     /**
-     * Headless Autonomous Execution: Analyzes lesson and creates checkpoints instantly
+     * التحليل الآلي المستقل للفيديو وإنشاء الفصول ونقاط الفحص السقراطي في قاعدة البيانات
+     * 
+     * @param int $lessonId معرّف الدرس
+     * @return array مصفوفة تحتوي على الفصول ونقاط الفحص وحالة التنفيذ
      */
     public static function processLessonAutonomously(int $lessonId): array
     {

backend/app/Services/CurriculumService.php

@@ -1,18 +1,26 @@
 <?php
+/**
+ * ==============================================================================
+ * SAQEL ENTERPRISE (EDTECH 2.0) - DYNAMIC CURRICULUM SERVICE
+ * ==============================================================================
+ * 
+ * ملف: CurriculumService.php
+ * الهدف المعماري:
+ * إدارة المنظومة الحية للمناهج والكتب الوزارية وشجرة الدروس (Zero Mock Data):
+ * 1. مسح وتوليد الشجرة الهرمية للمناهج من ملفات (manifest.json) وملفات الماركداون الحية.
+ * 2. البحث الدلالي اللحظي في عناوين الدروس ونتاجات التعلم والمفاهيم.
+ * 3. قراءة وحفظ وتحديث نصوص الماركداون للدروس والمصادر والملخصات.
+ * 4. الربط المرجعي بين شجرة المناهج وقاعدة بيانات الدورات والدروس والفيديوهات.
+ */
 
 namespace App\Services;
 
 use App\Core\Database;
 
-/**
- * 100% Live Dynamic Curriculum Service (Zero Fake Data)
- * Manages real uploaded textbook manifests and dynamic markdown files.
- */
 class CurriculumService
 {
     /**
-     * Stub for backwards compatibility with controllers calling ensureSchema.
+     * التحقق التوافقي التلقائي من بنية قاعدة البيانات للمناهج
-     * Curriculum is now file-based.
      */
     public static function ensureSchema(): void
     {

backend/app/Services/NabehService.php

@@ -1,4 +1,17 @@
 <?php
+/**
+ * ==============================================================================
+ * SAQEL ENTERPRISE (EDTECH 2.0) - NABEH WHATSAPP & GUARDIAN NOTIFICATION SERVICE
+ * ==============================================================================
+ * 
+ * ملف: NabehService.php
+ * الهدف المعماري:
+ * بوابة التكامل الرسمية مع خدمة نبّه (Nabeh Gateway) لإرسال رسائل وإشعارات الواتساب:
+ * 1. إرسال بطاقات رموز التحقق الفاخرة (Luxury Image OTP Cards) أو الرسائل النصية المباشرة.
+ * 2. إرسال الإشعارات التوجيهية الهادئة لأولياء الأمور (Guardian Remedial Alerts) عند تعثر الطالب
+ *    في أي مفهوم دراسي أو فحص سقراطي لمتابعة رحلة تعليمه دون قلق.
+ * 3. إدارة الجلسات والمصادقة المؤقتة مع Nabeh API والتخزين المؤقت للتوكن في Redis لمدة 24 ساعة.
+ */
 
 namespace App\Services;
 

backend/database_schema.sql

@@ -329,21 +329,21 @@ CREATE TABLE IF NOT EXISTS `video_quality_assessments` (
 ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
 
 -- ------------------------------------------------------------------------------
--- 12. Table: exams (الامتحانات: فحص سقراطي، امتحان درس، وحدة، وامتحان وزاري)
+-- 12. Table: exams (الامتحانات وبنوك الأسئلة التكيفية: فحص سقراطي، امتحان درس، وحدة، وامتحان وزاري)
 -- ------------------------------------------------------------------------------
 CREATE TABLE IF NOT EXISTS `exams` (
   `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
   `uuid` CHAR(36) NOT NULL UNIQUE,
   `course_id` BIGINT UNSIGNED NOT NULL,
-  `lesson_id` BIGINT UNSIGNED DEFAULT NULL,
+  `lesson_id` BIGINT UNSIGNED DEFAULT NULL COMMENT 'معرّف الدرس — يكون NULL في امتحانات نهاية الوحدة والامتحانات الشاملة',
   `created_by_id` BIGINT UNSIGNED DEFAULT NULL,
   `creator_type` ENUM('teacher', 'ai_adaptive', 'ministry_standard') NOT NULL DEFAULT 'ai_adaptive',
-  `scope` ENUM('in_video_checkpoint', 'lesson_exam', 'unit_exam', 'semester_final') NOT NULL DEFAULT 'in_video_checkpoint',
+  `scope` ENUM('in_video_checkpoint', 'lesson_exam', 'unit_exam', 'unit_comprehensive', 'semester_final') NOT NULL DEFAULT 'in_video_checkpoint' COMMENT 'نطاق الامتحان: فحص سقراطي، امتحان درس، أو امتحان وحدة شامل',
   `title` VARCHAR(255) NOT NULL,
   `description` TEXT DEFAULT NULL,
   `duration_minutes` INT UNSIGNED NOT NULL DEFAULT 30,
-  `timestamp_seconds` INT UNSIGNED NOT NULL DEFAULT 0,
+  `timestamp_seconds` INT UNSIGNED NOT NULL DEFAULT 0 COMMENT 'توقيت ظهور الفحص السقراطي أثناء تشغيل الفيديو',
-  `rewind_on_fail_seconds` INT UNSIGNED NOT NULL DEFAULT 45,
+  `rewind_on_fail_seconds` INT UNSIGNED NOT NULL DEFAULT 45 COMMENT 'عدد الثواني التي يرجع إليها الفيديو عند الخطأ لترسيخ الفهم',
   `passing_percentage` DECIMAL(5, 2) NOT NULL DEFAULT 60.00,
   `total_points` INT UNSIGNED NOT NULL DEFAULT 100,
   `is_mandatory` TINYINT(1) NOT NULL DEFAULT 1,
@@ -366,14 +366,15 @@ CREATE TABLE IF NOT EXISTS `questions` (
   `exam_id` BIGINT UNSIGNED NOT NULL,
   `question_text` TEXT NOT NULL,
   `question_type` ENUM('multiple_choice', 'true_false', 'short_answer') NOT NULL DEFAULT 'multiple_choice',
-  `bloom_taxonomy` ENUM('recall', 'comprehension', 'application', 'analysis') NOT NULL DEFAULT 'comprehension',
+  `bloom_taxonomy` ENUM('recall', 'comprehension', 'application', 'analysis') NOT NULL DEFAULT 'comprehension' COMMENT 'تصنيف بلوم المعرفي للقياس والتقويم',
-  `topic_tag` VARCHAR(150) DEFAULT NULL,
+  `topic_tag` VARCHAR(150) DEFAULT NULL COMMENT 'الوسم الموضوعي الدقيق للمفهوم العلمي — يُستخدم لمحرك التعليم التكيفي وسد الثغرات',
   `points` INT UNSIGNED NOT NULL DEFAULT 10,
-  `explanation_text` TEXT DEFAULT NULL,
+  `explanation_text` TEXT DEFAULT NULL COMMENT 'خطوات الحل والتعليل العلمي النموذجي الموجه للطالب',
-  `ai_hint` TEXT DEFAULT NULL,
+  `ai_hint` TEXT DEFAULT NULL COMMENT 'تلميح ذكي يظهر للطالب عند التعثر دون إعطاء الإجابة المباشرة',
   `created_at` TIMESTAMP NULL DEFAULT CURRENT_TIMESTAMP,
   PRIMARY KEY (`id`),
   KEY `idx_questions_exam` (`exam_id`),
+  KEY `idx_questions_topic` (`topic_tag`),
   CONSTRAINT `fk_questions_exam` FOREIGN KEY (`exam_id`) REFERENCES `exams` (`id`) ON DELETE CASCADE
 ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
 
@@ -405,9 +406,9 @@ CREATE TABLE IF NOT EXISTS `exam_attempts` (
   `percentage` DECIMAL(5, 2) NOT NULL DEFAULT 0.00,
   `status` ENUM('passed', 'failed', 'needs_remediation', 'in_progress') NOT NULL DEFAULT 'in_progress',
   `time_spent_seconds` INT UNSIGNED NOT NULL DEFAULT 0,
-  `weak_topics_json` JSON DEFAULT NULL,
+  `weak_topics_json` JSON DEFAULT NULL COMMENT 'مصفوفة JSON للمفاهيم التي تعثر فيها الطالب لتوجيهه علاجياً',
-  `ai_diagnostic_report` TEXT DEFAULT NULL,
+  `ai_diagnostic_report` TEXT DEFAULT NULL COMMENT 'تقرير التشخيص السقراطي المولد بالذكاء الاصطناعي',
-  `completed_at` TIMESTAMP NULL DEFAULT NULL,
+  `completed_at` TIMESTAMP NULL DEFAULT NULL COMMENT 'وقت اكتمال المحاولة — يُستخدم لتتبع جاهزية الطالب وإشعار ولي الأمر',
   `created_at` TIMESTAMP NULL DEFAULT CURRENT_TIMESTAMP,
   PRIMARY KEY (`id`),
   KEY `idx_attempts_student` (`student_id`),
@@ -417,7 +418,7 @@ CREATE TABLE IF NOT EXISTS `exam_attempts` (
 ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
 
 -- ------------------------------------------------------------------------------
--- 15.5. Table: student_question_answers (تفاصيل إجابات الطالب)
+-- 15.5. Table: student_question_answers (تفاصيل إجابات الطالب للتحليل التكيفي)
 -- ------------------------------------------------------------------------------
 CREATE TABLE IF NOT EXISTS `student_question_answers` (
   `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
@@ -428,8 +429,11 @@ CREATE TABLE IF NOT EXISTS `student_question_answers` (
   `is_correct` TINYINT(1) NOT NULL DEFAULT 0,
   `points_awarded` DECIMAL(6,2) NOT NULL DEFAULT 0.00,
   `time_spent_seconds` INT UNSIGNED NOT NULL DEFAULT 0,
+  `created_at` TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
   PRIMARY KEY (`id`),
   KEY `idx_sqa_attempt` (`attempt_id`),
+  KEY `idx_sqa_student` (`student_id`),
+  KEY `idx_sqa_question` (`question_id`),
   CONSTRAINT `fk_sqa_attempt` FOREIGN KEY (`attempt_id`) REFERENCES `exam_attempts` (`id`) ON DELETE CASCADE,
   CONSTRAINT `fk_sqa_student` FOREIGN KEY (`student_id`) REFERENCES `students` (`id`) ON DELETE CASCADE,
   CONSTRAINT `fk_sqa_question` FOREIGN KEY (`question_id`) REFERENCES `questions` (`id`) ON DELETE CASCADE