saqel/docs/PLATFORM_EXECUTION_LEDGER.md

📋 دفتر متابعة وتنفيذ مهام منصة صَقِل — السجل المعماري الحي

تاريخ التحديث الأخير: 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) والتحقق من سلامة الأصول والربط.