215 lines
23 KiB
Markdown
215 lines
23 KiB
Markdown
<div dir="rtl" align="right">
|
|
|
|
# 📋 دفتر متابعة وتنفيذ مهام منصة صَقِل — السجل المعماري الحي
|
|
|
|
تاريخ التحديث الأخير: **16 أيلول 2026**
|
|
المرجع الأساسي: `docs/NEXT_PHASE_MASTER_SPEC.md` و `docs/NEXT_PHASE_EXECUTION_BACKLOG.md` و `AGENTS.md`
|
|
الهدف: هذا الدفتر هو المرجع التوثيقي والتنفيذي المباشر لجميع محاور ومنعطفات منصة صَقِل، يوضح بدقة متناهية **ما تم إنجازه فعلياً في الكود**، و**شو تبقى من كل نقطة**، مع معايير القبول وشروط الانتقال للمرحلة التالية.
|
|
|
|
---
|
|
|
|
## 1. جدول الموقف التنفيذي العام (Executive Task Matrix)
|
|
|
|
| المعرّف | المحور / المهمة | النطاق والمستوى | الحالة الحالية | ما تم إنجازه في الكود | شو تبقى لإتمامه بدقة |
|
|
|---|---|---|---|---|---|
|
|
| **NP-00** | بيئة الاختبار وخط الأساس الآمن | البنية التحتية / P0 | `implemented_unverified` | منع Runtime DDL، فحص syntax لكل PHP، سكربت `run_migrations.php` مع مطابقة Checksum | تجهيز بيئة staging معزولة، تشغيل suite تكامل متصل بـ MySQL و Redis |
|
|
| **NP-01** | إيقاف النجاح والمحتوى المصطنع | الأمان والمصداقية / P0 | `verified_in_code` | تعطيل الاعتماد التلقائي لكليك، تعطيل سحب الأرباح التقديري، إزالة التوليد في GET، رد صريح بـ `unavailable` | جرد تنظيف الجداول من أي بيانات demo قديمة بعد المطابقة اليدوية |
|
|
| **NP-02** | الهوية المنهجية وحزم الأصول | المناهج والمحتوى / P0 | `in_progress` | 13 مبحثاً (392 درس ماركداون + 371 مواصفة مختبر)، جداول `curriculum_lessons` و `content_assets` | مراجعة واعتماد أول حزمة نشر (Bundle) رسمية لـ 12 درساً نموذجياً وربط الـ PDF الرسمي |
|
|
| **NP-03** | حصة المعلم والاستبدال الذري | استوديو المعلم / P1 | `verified_in_code` | `TeacherSubmissionService` مع Preflight و Idempotency-Key وقفل المعاملات، وربط التحقق في `TeacherStudioCubit` وراية التنبيه بالنسخة المرشحة في الواجهة | اختبارات E2E لرفع الفيديو الفعلي ومطابقة الصوت |
|
|
| **NP-04** | تدقيق الفيديو والأسئلة السقراطية | الجودة الأكاديمية / P0 | `in_progress` | مشغل قراءة صارم، إيقاف التوليد في GET، فحص Checkpoints المنشورة فقط، عقد البرومبتات | ربط الـ Worker بتفريغ صوتي حقيقي وأدلة مرئية كاملة للحصص المنشورة |
|
|
| **NP-05** | اختيار المعلم (0 / 1 / متعدد) | تجربة الطالب / P1 | `implemented_unverified` | `TeacherSelectionSheet` بالفرز التنازلي للتقييم، تشغيل الـ UUID المختار، كشف المعلم المصرح فقط | ربط شجرة المنهج في التطبيق بهوية الدرس المنشور بعد تفعيل الـ Bundles |
|
|
| **NP-06** | دفتر الحسابات وحجز الرصيد | المحاسبة المالية / P0 | `implemented_unverified` | `TeacherLedgerService` بوحدة الفلس، قيود القيد المزدوج، حجز السحب الذري بـ Idempotency | تسوية الرصيد الافتتاحي وتدقيق الصلاحيات متعدية الحسابات لمنع IDOR |
|
|
| **NP-07** | قياس الدقائق المستحقة بالخادم | استحقاق المشاهدة / P1 | `implemented_unverified` | `WatchSessionService` مع فترات متصلة وحساب Server-side Delta ومقارنة زمن الخادم والعميل | اختبار الإجهاد وانقطاع الاتصال ومحاكاة التلاعب بسرعة المشغل |
|
|
| **NP-08** | توزيع الإيراد وكشف حساب المعلم | المالية والشفافية / P1 | `blocked_policy` | فصل أوعية الدخل (مدرسي / مستقل)، إيقاف افتراض أرباح من حجم المنصة ككل | **قرار تجاري معلق:** حسم سعر الدقيقة، ونسبة صندوق المعلمين، وفترة التسوية |
|
|
| **NP-09** | بوابة الدفع والبصمة والتحويل | الدفع المالي / P0 | `blocked_psp` | عزل مسارات كليك بوضع غير متاح بدلاً من المحاكاة الصورية والاحتيال | **تعاقد مصرفي معلق:** ربط PSP أردني معتمد، وبناء Webhooks موقعة، وبصمة الجهاز |
|
|
| **NP-10** | حزمة الإنجليزية والصوت الموحد | المناهج التفاعلية / P1 | `in_progress` | تطوير مختبر الإنجليزية، تنظيم ملفات الوحدات والقواعد، إزالة IPA التخميني | توفير ملفات الصوت البشري المعتمدة للمفردات والنصوص وربطها بروابط CDN |
|
|
| **NP-11** | إكمال حلقة التعلم ودفتر الأخطاء | التجربة التعليمية / P1 | `verified_in_code` | 18 مختبراً، نافذة التفكير، دورة التكرار المتباعد بمرحلتين (تثبيت + استرجاع 7 أيام) بالخادم والواجهة | ربط واجهات الواجبات المدرسية بنظام مهام وتكليفات المعلم |
|
|
| **NP-12** | المؤسسات والمديريات والإشراف | إدارة التعليم / P1 | `implemented_unverified` | لوحات SuperAdmin والمديريات بقراءة حقيقية، عزل أدوار الـ Middlewares، blind index | استيراد شعب المدارس الحكومية والخاصة واختبارات العزل التام بين المدارس |
|
|
| **NP-13** | إثبات الصف العاشر والإطلاق | بوابة الإطلاق النهائي | `gate_pending` | جاهزية التطبيقات الأربعة، مسار التدريب المهني (VTC)، صفحة الهبوط الفاخرة | إجراء التجربة الحية على 12 درساً للصف العاشر مع عينة حقيقية من المعلمين والطلبة |
|
|
|
|
---
|
|
|
|
## 2. تفصيل كل نقطة: ما تم إنجازه وما تبقى منها بدقة
|
|
|
|
### [NP-00] خط الأساس وبيئة الاختبار الآمنة
|
|
* **الهدف:** توفير بيئة تشغيل آمنة، خالية من الأوامر المدمرة، ومعزولة عن قاعدة الإنتاج.
|
|
* **ما تم إنجازه في الكود:**
|
|
- إلغاء الـ Runtime DDL نهائياً في خدمات المناهج والمدفوعات والمشاهدة.
|
|
- إضافة `backend/scripts/run_migrations.php` كمنصة تحكم موحدة للملفات مع فحص الـ Checksum ومنع تكرار التنفيذ.
|
|
- فحص syntax لجميع ملفات الـ PHP في المشروع، وضمان خلو ملفات Dart من أخطاء الـ Compile.
|
|
* **شو تبقى منها بدقة:**
|
|
- [ ] تشغيل بيئة Staging حقيقية متصلة بـ MySQL و Redis و Nabeh.
|
|
- [ ] كتابة Automated Integration Test Harness للـ Backend لا يعتمد على أطر عمل خارجية غير مثبتة.
|
|
- [ ] اختبار استعادة النسخة الاحتياطية وتأكيد سلامة الـ Rollback.
|
|
|
|
---
|
|
|
|
### [NP-01] إيقاف النجاح والمحتوى المصطنع (Truth in Core)
|
|
* **الهدف:** التخلص الكامل من أي إيهام بالنجاح المالي أو التعليمي، ومنع أي بيانات مزورة.
|
|
* **ما تم إنجازه في الكود:**
|
|
- دالة `CliqPaymentService::unavailable` تعطل فورياً اعتماد الإيصالات أو إنشاء حركات وهمية وتعيد رسالة صريحة للطالب والمعلم.
|
|
- دالة `TeacherController::getMonetizationDashboard` توقف الحسابات التقديرية التلقائية لدخل المعلم وتعرض الرصيد كغير متاح حتى اكتمال الربط.
|
|
- مسار `VideoController::getPlaybackData` أصبح للقراءة فقط (Read-only)، وتم منع توليد أو حذف أي أسئلة سقراطية أثناء طلب الـ GET.
|
|
- إزالة الـ Fallback الذي كان يعرض درساً بديلاً عند فقدان ملف الدرس المطلوب في `CurriculumController`.
|
|
* **شو تبقى منها بدقة:**
|
|
- [ ] تدقيق سجلات قاعدة البيانات الحالية لعزل أي صفوف تجريبية (demo rows) قديمة وضمان عدم دخولها في أرصدة المعلمين.
|
|
|
|
---
|
|
|
|
### [NP-02] الهوية المنهجية وحزم الملفات (Curriculum Identity & Bundles)
|
|
* **الهدف:** تمييز كل درس بهوية ثابتة (الصف، المبحث، الفصل، الوحدة، الدرس، النسخة)، وربط الأصول كحزم نشر موثوقة.
|
|
* **ما تم إنجازه في الكود:**
|
|
- 13 مبحثاً كاملاً للصف العاشر في `backend/storage/curriculum/grade_10` تضم 392 ملف ماركداون.
|
|
- 371 وثيقة مواصفات للمختبرات الافتراضية في `docs/virtual_labs/grade_10`.
|
|
- تطبيق جدول `curriculum_lessons` وجدول `content_assets` وجدول `publication_bundles`.
|
|
- نقطة `GET /api/curriculum/assets/{assetId}` التي تخدم الأصول عبر UUID فقط دون تمرير مسارات ملفات من العميل.
|
|
- سكربت `publish_grade10_bundle.php` المخصص لنشر حزم الصف العاشر مع خيار `--pilot` للدروس الـ 12 النموذجية.
|
|
* **شو تبقى منها بدقة:**
|
|
- [ ] مراجعة واعتماد الحزم المنشورة للدفعة الأولى ونقلها من حالة `draft` إلى `published`.
|
|
- [ ] رفع ملفات الـ PDF الرسمية للكتب وأوراق العمل وتخزينها في التخزين السيادي كأصول ذات Checksum.
|
|
|
|
---
|
|
|
|
### [NP-03] حصة المعلم والإصدار والاستبدال الذري
|
|
* **الهدف:** ضمان أن لكل معلم حصة أساسية واحدة منشورة لكل درس، وأن أي تسجيل جديد يكون نسخة مرشحة للاستبدال تخضع للفحص دون إيقاف الحصة القديمة.
|
|
* **ما تم إنجازه في الكود:**
|
|
- خدمة `TeacherSubmissionService` المزودة بـ Preflight، والتحقق من `Idempotency-Key` عبر SHA-256.
|
|
- قيد فريد في قاعدة البيانات للمعلم والدرس المنهجي لمنع الازدواجية.
|
|
- تسجيل النسخ المرشحة بحقل `replaces_video_version_id` وقفل المعاملات بـ `FOR UPDATE`.
|
|
- ربط خطوة التحقق المسبق (Preflight) داخل `apps/teacher_app/lib/logic/cubits/teacher_studio_cubit.dart` وتمرير معلمات الاستبدال ورقم النسخة.
|
|
- إضافة شريط التنبيه المرئي في واجهة الرفع `apps/teacher_app/lib/presentation/screens/tabs/teacher_studio_upload_tab.dart` لإعلام المعلم بصراحة: "نسخة مرشحة للاستبدال (إصدار X) — الحصة المنشورة الحالية تظل متاحة للطلاب حتى اجتياز الفحص".
|
|
* **شو تبقى منها بدقة:**
|
|
- [ ] اختبارات E2E لرفع الفيديو الفعلي ومطابقة الصوت الميداني.
|
|
- [ ] إشعار المعلم اللحظي عند انتهاء التدقيق البشري للنسخة المرشحة.
|
|
|
|
---
|
|
|
|
### [NP-04] تدقيق الفيديو والأسئلة السقراطية من الأدلة
|
|
* **الهدف:** لا يُنشر فيديو إلا بعد فحص أكاديمي وربط الأسئلة السقراطية بتوقيتات حقيقية وتفريغ صوتي موثق.
|
|
* **ما تم إنجازه في الكود:**
|
|
- صياغة وثيقة برومبتات التدقيق `VIDEO_REVIEW_AND_SOCRATIC_PROMPTS.md`.
|
|
- إنشاء جدول `video_review_jobs` وجدول `video_review_evidence`.
|
|
- إيقاف التوليد العشوائي للأسئلة واشتراط وجود أسئلة منشورة ومعتمدة فقط.
|
|
* **شو تبقى منها بدقة:**
|
|
- [ ] ربط العامل الخلفي (`curriculum_worker.php` / `video_upload_worker.php`) بخدمة التفريغ الصوتي الفعلي.
|
|
- [ ] بناء شاشة مراجعة للمعلم تعرض تقرير الملاحظات مع التوقيت الدقيق لكل ملحوظة.
|
|
|
|
---
|
|
|
|
### [NP-05] اختيار المعلم (0 / 1 / متعدد)
|
|
* **الهدف:** تطبيق منطق صَقِل: صفر حصص = إظهار الموارد المتاحة بصدق، حصة واحدة = تشغيل مباشر، أكثر من حصة = قائمة بالتقييم الموثق.
|
|
* **ما تم إنجازه في الكود:**
|
|
- واجهة `TeacherSelectionSheet` في تطبيق الطالب بفرز تنازلي للتقييم الحقيقي وعدد التقييمات وشارة التوثيق.
|
|
- نقطة `GET /api/curriculum/lessons/{lessonId}/videos` التي تعيد فقط النسخ المنشورة والمصرح بها للطالب.
|
|
* **شو تبقى منها بدقة:**
|
|
- [ ] ربط شجرة المنهج في واجهة الطالب (`subject_hub_screen.dart`) بالـ UUID المعتمد للحزم المنشورة عند توفرها.
|
|
|
|
---
|
|
|
|
### [NP-06] دفتر الحسابات المحاسبي وحجز الرصيد
|
|
* **الهدف:** نظام محاسبي صارم بوحدة الفلس (بدون فواصل عشرية عائمة)، وقيد مزدوج يمنع السحب المتجاوز للرصيد.
|
|
* **ما تم إنجازه في الكود:**
|
|
- خدمة `TeacherLedgerService` الداعمة لـ `balance` و `placeWithdrawalHold` و `releaseHold`.
|
|
- حجز السحب ذري (Atomic Transaction) يمنع طلبين متزامنين يتجاوزان الرصيد الفعلي.
|
|
- جداول `ledger_accounts` و `ledger_entries` و `teacher_withdrawal_holds`.
|
|
* **شو تبقى منها بدقة:**
|
|
- [ ] تسوية الأرصدة الافتتاحية السابقة ومطابقتها قبل تفعيل أي قيد حي.
|
|
- [ ] تدقيق أمان الـ IDOR للتأكد من عدم وصول أي معلم لدفتر معلم آخر.
|
|
|
|
---
|
|
|
|
### [NP-07] قياس الدقائق المستحقة بالخادم
|
|
* **الهدف:** حساب دقائق المشاهدة المستحقة للدخل من خلال الخادم حصراً، دون الاعتماد على عداد الهاتف.
|
|
* **ما تم إنجازه في الكود:**
|
|
- خدمة `WatchSessionService` وجداول `watch_sessions` و `watch_events` و `eligible_watch_intervals`.
|
|
- التحقق من تسلسل الأحداث المتصلة (Sequence continuity)، ورفض القفزات غير المتصلة (Seek leaps).
|
|
- احتساب الفترات المؤهلة بمقارنة الفرق الزمني للخادم مع العميل وبحد أقصى دقيقة واحدة لكل Heartbeat.
|
|
* **شو تبقى منها بدقة:**
|
|
- [ ] إجراء اختبارات تزامن لجلستي مشاهدة لنفس الطالب والتأكد من عدم احتساب الدقائق المزدوجة.
|
|
- [ ] معالجة حالات انقطاع الشبكة المفاجئ وإغلاق الجلسات المعلقة تلقائياً.
|
|
|
|
---
|
|
|
|
### [NP-08] توزيع الإيراد وكشف حساب المعلم
|
|
* **الهدف:** توزيع عادل لصافي الاشتراكات على دقائق المشاهدة المكتسبة وفق معادلة تجارية معلنة.
|
|
* **ما تم إنجازه في الكود:**
|
|
- عزل دخل المدارس (المشمول بالاتفاقيات المؤسسية) عن سوق الطلاب المستقلين.
|
|
- إيقاف الحسابات الصورية في لوحة المعلم وعرض حالة عدم التوفر بوضوح.
|
|
* **شو تبقى منها بدقة (محجوب بقرار تجاري):**
|
|
- [ ] **قرار تجاري ملزم:** تحديد سعر الدقيقة المؤهلة، ونسبة صندوق المعلمين، وسياسة الاسترداد.
|
|
- [ ] بناء سكربت الإغلاق الشهري (Monthly Period Close) وتوزيع الفلسات الناتجة حتمياً.
|
|
|
|
---
|
|
|
|
### [NP-09] مزود الدفع والبصمة والتحويل
|
|
* **الهدف:** ربط بوابة دفع وتحويل بنكية حقيقية في الأردن مع تأكيد العمليات بالبصمة البيومترية.
|
|
* **ما تم إنجازه في الكود:**
|
|
- إيقاف المحاكاة المصطنعة لخدمة كليك وحظر إنشاء إيصالات معتمدة دون تحقق.
|
|
* **شو تبقى منها بدقة (محجوب بتعاقد المزود):**
|
|
- [ ] التعاقد مع مزود دفع مصرفي / PSP أردني معتمد (مثل أورنج موني، زين كاش، أو بوابة بنكية).
|
|
- [ ] بناء Webhook موقع ومحمي ضد إعادة الإرسال (Replay attacks).
|
|
- [ ] إضافة تحدي البصمة (`local_auth`) على الهاتف قبل إرسال طلب السحب أو الاشتراك.
|
|
|
|
---
|
|
|
|
### [NP-10] حزمة الإنجليزية والصوت الموحد
|
|
* **الهدف:** تجربة لغة إنجليزية مطابقة لكتاب الصف العاشر المعتمد، خالية من التخمين وبصوت واضح.
|
|
* **ما تم إنجازه في الكود:**
|
|
- بناء مختبر الإنجليزية التفاعلي المتقدم `english_interactive_lab_view.dart`.
|
|
- تقسيم المحتوى إلى أتهيأ / أقرأ وأسمع / الكلمات / القاعدة / أتدرب.
|
|
- نقطة `GET /api/curriculum/lessons/{lessonId}/english-package` لقراءة الحزم المنشورة فقط.
|
|
* **شو تبقى منها بدقة:**
|
|
- [ ] توريد التسجيلات الصوتية البشرية المعتمدة لنصوص وكلمات كتاب Action Pack 10.
|
|
- [ ] ربط ملفات الصوت بخادم الأصول السيادي (CDN).
|
|
|
|
---
|
|
|
|
### [NP-11] إكمال حلقة التعلم ودفتر الأخطاء
|
|
* **الهدف:** إغلاق حلقة التعليم: استراحة التفكير السقراطية، حل الواجبات، توثيق الأخطاء، والكويز العلاجي، واختبار التثبيت.
|
|
* **ما تم إنجازه في الكود:**
|
|
- 18 مختبراً تفاعلياً مدمجاً ومفحوصاً باختبارات Smoke (12 لغة عربية + 6 فيزياء).
|
|
- نافذة التفكير الإلزامي `ScaffoldedThinkingPauseSheet` (60 ثانية) مع التدرج المعرفي خطوة بخطوة.
|
|
- تطبيق دورة التكرار المتباعد بمرحلتين (Two-Stage Spaced Repetition) في `ErrorNotebookController.php`:
|
|
- المرحلة الأولى (التدريب العلاجي الأولي): ينتقل الخطأ من `pending_remediation` إلى `in_remediation` وتتم جدولة اختبار الاسترجاع بعد 7 أيام (`retention_scheduled_at = NOW() + 7 DAYS`).
|
|
- المرحلة الثانية (تحدي الاسترجاع والتثبيت): عند اجتياز الطالب للاختبار بعد اكتمال الفترة ينتقل إلى `mastered` مع تسجيل تاريخ الإتقان الفعلي.
|
|
- شاشة دفتر الأخطاء الذكي `SmartErrorNotebookScreen`: إضافة تبويبات التصفية بحسب الحالة (الكل، بانتظار المعالجة، قيد التثبيت 🌱، تم الإتقان ✨)، وصندوق إحصائي مستقل لقيد التثبيت، وزر خاص لبدء اختبار الاسترجاع والتثبيت المتباعد.
|
|
- منظومة ربط ولي الأمر المشروطة بموافقة صريحة من الطالب.
|
|
* **شو تبقى منها بدقة:**
|
|
- [ ] ربط واجهات الواجبات المدرسية بنظام مهام وتكليفات المعلم.
|
|
- [ ] دفع إشعارات تذكير للطالب عند استحقاق موعد اختبار التثبيت (اليوم السابع).
|
|
|
|
---
|
|
|
|
### [NP-12] المؤسسات والمديريات والإشراف
|
|
* **الهدف:** إدارة شاملة للمدارس والمديريات مع عزل كامل للبيانات وحماية الخصوصية.
|
|
* **ما تم إنجازه في الكود:**
|
|
- لوحات الإدارة والسوبر أدمن تقرأ إحصاءات قاعدة البيانات الحقيقية.
|
|
- تشفير الرقم الوطني بـ AES-256-GCM مع فهرسة عمياء بـ HMAC.
|
|
- عزل الصلاحيات عبر الـ Middlewares لكل دور.
|
|
* **شو تبقى منها بدقة:**
|
|
- [ ] بناء آلية استيراد شعب المدارس وقوائم الطلبة من ملفات Excel/CSV.
|
|
- [ ] اختبارات اختراق وعزل (IDOR multi-tenant isolation) لضمان عدم تسريب أي بيانات بين المدارس.
|
|
|
|
---
|
|
|
|
### [NP-13] بوابة إثبات الصف العاشر والإطلاق
|
|
* **الهدف:** تشغيل تجربة حية على 12 درساً نموذجياً تثبت نجاح الدورة التعليمية كاملة قبل التوسع.
|
|
* **ما تم إنجازه في الكود:**
|
|
- جاهزية أربعة تطبيقات Flutter متكاملة.
|
|
- صفحة هبوط رئيسية فاخرة بهندسة أبل (`index.html`).
|
|
- مسار التدريب المهني (VTC) لمركبات الكهرباء والسلامة المهنية.
|
|
* **شو تبقى منها بدقة:**
|
|
- [ ] تنفيذ تجربة الـ 12 درساً مع عينة مستخدمين فعلية (معلمون وطلبة وأولياء أمور).
|
|
- [ ] قياس الأثر التعليمي ونسبة استرجاع المفاهيم بعد أسبوع.
|
|
- [ ] اتخاذ قرار الإطلاق التجاري الرسمي.
|
|
|
|
---
|
|
|
|
## 3. الخطوات المباشرة للتنفيذ الآن (Action Plan)
|
|
|
|
1. **الخطوة الأولى (تقني) — [تم الإنجاز]:** ربط خطوة التحقق المسبق (Preflight) وتنبيه النسخة المرشحة في استوديو المعلم داخل `apps/teacher_app`.
|
|
2. **الخطوة الثانية (تعليمي) — [تم الإنجاز]:** تطبيق خوارزمية التكرار المتباعد (المرحلتين: المعالجة الأولية + اختبار الاسترجاع والتثبيت بعد 7 أيام) في الخادم والواجهة.
|
|
3. **الخطوة الثالثة (محتوى) — [التركيز الحالي]:** فحص واعتماد حزمة الـ 12 درساً النموذجية للصف العاشر (`publish_grade10_bundle.php --pilot`) والتحقق من سلامة الأصول والربط.
|
|
|
|
</div>
|