Enrich full codebase with architectural Arabic docblocks and synchronize database_schema.sql with live database
This commit is contained in:
Hamza-Ayed
@@ -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 {
|
||||
|
||||
@@ -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});
|
||||
|
||||
|
||||
+14
@@ -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'
|
||||
|
||||
@@ -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;
|
||||
|
||||
|
||||
@@ -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;
|
||||
|
||||
@@ -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;
|
||||
|
||||
@@ -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
|
||||
{
|
||||
|
||||
@@ -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
|
||||
{
|
||||
|
||||
@@ -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();
|
||||
|
||||
@@ -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
|
||||
{
|
||||
|
||||
@@ -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
|
||||
{
|
||||
|
||||
@@ -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
|
||||
{
|
||||
|
||||
@@ -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
|
||||
{
|
||||
|
||||
@@ -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
|
||||
{
|
||||
|
||||
@@ -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;
|
||||
|
||||
|
||||
+17
-13
@@ -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,
|
||||
`rewind_on_fail_seconds` INT UNSIGNED NOT NULL DEFAULT 45,
|
||||
`timestamp_seconds` INT UNSIGNED NOT NULL DEFAULT 0 COMMENT 'توقيت ظهور الفحص السقراطي أثناء تشغيل الفيديو',
|
||||
`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',
|
||||
`topic_tag` VARCHAR(150) DEFAULT NULL,
|
||||
`bloom_taxonomy` ENUM('recall', 'comprehension', 'application', 'analysis') NOT NULL DEFAULT 'comprehension' COMMENT 'تصنيف بلوم المعرفي للقياس والتقويم',
|
||||
`topic_tag` VARCHAR(150) DEFAULT NULL COMMENT 'الوسم الموضوعي الدقيق للمفهوم العلمي — يُستخدم لمحرك التعليم التكيفي وسد الثغرات',
|
||||
`points` INT UNSIGNED NOT NULL DEFAULT 10,
|
||||
`explanation_text` TEXT DEFAULT NULL,
|
||||
`ai_hint` TEXT DEFAULT NULL,
|
||||
`explanation_text` TEXT DEFAULT NULL COMMENT 'خطوات الحل والتعليل العلمي النموذجي الموجه للطالب',
|
||||
`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,
|
||||
`ai_diagnostic_report` TEXT DEFAULT NULL,
|
||||
`completed_at` TIMESTAMP NULL DEFAULT NULL,
|
||||
`weak_topics_json` JSON DEFAULT NULL COMMENT 'مصفوفة JSON للمفاهيم التي تعثر فيها الطالب لتوجيهه علاجياً',
|
||||
`ai_diagnostic_report` TEXT DEFAULT NULL COMMENT 'تقرير التشخيص السقراطي المولد بالذكاء الاصطناعي',
|
||||
`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
|
||||
|
||||
Reference in New Issue
Block a user