# حالة تنفيذ منصة صَقِل

آخر تحديث: 2026-09-02

هذه الوثيقة تفصل بين ما هو موجود في الكود وما هو جزء من الرؤية المستقبلية.

## منفذ فعليًا

- تطبيق Flutter موحد للطالب وولي الأمر.
- تسجيل الدخول عبر OTP والرقم الوطني مع تخزين آمن للتوكن.
- شجرة مناهج ديناميكية من الخادم ومحتوى فعلي للصف العاشر.
- رفع الفيديو، تحويله إلى HLS عبر FFmpeg، ورفع حزمة HLS إلى Cloudflare R2.
- رفع الفيديو من Curriculum Studio أصبح غير متزامن: الطلب يحفظ الملف ويرجع فورًا، ثم يعالج `backend/scripts/video_upload_worker.php` التحويل والرفع والربط بالدرس.
- تشغيل الفيديو عبر HLS من R2 أو المسار المحلي عند عدم توفر R2.
- فحوص سقراطية مرتبطة بالدرس من قاعدة البيانات.
- بوابات Web للطالب والمعلم وولي الأمر واستوديو المناهج.
- API للامتحانات والمحاولات والتحليلات والمحادثة وتقييم المعلم.

## منفذ جزئيًا

- تطبيق المعلم Flutter: shell ترحيبي فقط؛ الاستخدام الحالي للمعلم عبر Web Studio.
- امتحانات Flutter: واجهة أولية تحتاج ربطًا كاملًا بواجهات `/api/exams`.
- تنزيل موارد PDF: واجهة تحتاج ربطًا فعليًا بالملف.
- مؤشر الجاهزية: مصدره الخادم في التحليلات، ويحتاج استكمال عرضه وتحديثه في الشاشات.
- حماية الفيديو: HLS/R2 متوفران، أما DRM ومنع التسجيل فيحتاجان تكاملًا إنتاجيًا.

## غير منفذ بعد

- تطبيق الإدارة Flutter.
- RAG كامل مع Embeddings ومصادر إجابة قابلة للتتبع.
- تنبيهات ولي الأمر الفورية داخل التطبيق.
- خوارزمية تكيفية إنتاجية متعددة المفاهيم.

## المعمارية المعتمدة

- Backend: Native PHP 8.3+، PDO، Router داخلي، PHP-FPM/Nginx.
- Storage: Cloudflare R2 لحزمة HLS والملفات، مع تخزين محلي مؤقت أثناء التحويل.
- Apps: `student_app` موحد للطالب وولي الأمر، `teacher_app` مستقل، و`admin_app` مستقل.
- لا يعتمد التشغيل على Laravel أو Docker.

## خط سير الفيديو المعتمد

الربط المنطقي هو: `curriculum_key` للدرس ← `lesson.video_uuid` ← حزمة HLS في R2 على المسار `hls/{course_id}/{video_uuid}/`.
مجلدات R2 القديمة مثل `hls/0` و`hls/1` و`hls/4` ليست فهرس الدروس؛ المرجع المعتمد هو قاعدة البيانات و`curriculum_key`، لذلك لا تُحذف قبل ترحيلها والتحقق من كل درس.

بعد نشر الكود يجب أن يكون عامل PHP قادرًا على الكتابة إلى `backend/storage/curriculum/processing` و`backend/storage/videos` و`backend/storage/hls`، وأن يكون FFmpeg مثبتًا على الخادم. وللفيديوهات الكبيرة يجب ضبط `upload_max_filesize` و`post_max_size` في PHP و`client_max_body_size` في Nginx بما يتجاوز حجم أكبر فيديو.

إذا ظهر `HTTP 413 Request Entity Too Large` فهذا يعني أن Nginx رفض الملف قبل وصوله إلى PHP. في CloudPanel ارفع `client_max_body_size` إلى `512M` أو أكثر، وارفع `upload_max_filesize` و`post_max_size` في إعدادات PHP-FPM، ثم أعد تشغيل/Reload خدمة Nginx وPHP-FPM. لا تعالج 413 من كود التطبيق لأنه يحدث قبل تشغيل الـ API.