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

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();