diff --git a/EXECUTION_MASTER_PLAN.md b/EXECUTION_MASTER_PLAN.md new file mode 100644 index 0000000..df3448f --- /dev/null +++ b/EXECUTION_MASTER_PLAN.md @@ -0,0 +1,173 @@ +# وثيقة خطة التنفيذ الشاملة وخارطة الطريق (Master Execution Plan) +## منصة وتطبيق جائزة أوروك الدولية (Uruk International Prize) + +> **وثيقة معمارية حية (Living Roadmap):** يتم تحديث هذه القائمة بوضع علامة إنجاز `[x]` لكل مهمة فور إتمامها واختبارها على السيرفر والتطبيق. + +--- + +## 📌 الفهرس العام للمراحل التنفيذية +- [المرحلة 1: المحرك السحابي وقواعد البيانات (Backend Core & DB)](#1) +- [المرحلة 2: البوتات والبرمجيات الميدانية والتحقق (Automation Bots & Gateways)](#2) +- [المرحلة 3: تطبيق الهاتف الذكي للمشتركين (Flutter Mobile App)](#3) +- [المرحلة 4: بوابة الشركاء وماسح الاستقبال السريع (Partner Reception Scanner)](#4) +- [المرحلة 5: لوحة تحكم الإدارة المركزية (Super Admin Dashboard)](#5) +- [المرحلة 6: الاختبارات الميدانية، الأمان، والإطلاق (Security & Go-Live)](#6) + +--- + + +## 🗄️ المرحلة الأولى: المحرك السحابي وقواعد البيانات (Backend Core & Database) +*الهدف: بناء الأساس البرمجي المتين، إدارة قواعد البيانات، وتوفير واجهات برمجة التطبيقات (APIs) الآمنة والسريعة.* + +### 1.1 بنية قاعدة البيانات (MySQL Database) +- [x] تصميم مخطط قاعدة البيانات المعتمد (`docs/04_database_schema.sql`). +- [ ] استيراد وإنشاء الجداول على قاعدة بيانات السيرفر الحي (`urukprize_db`). +- [ ] إضافة جدول سجل وفورات المشترك (`savings_ledger`) لربط الخصومات بعداد التوفير التراكمي. +- [ ] إضافة جدول حركات المصادقة والتوجيه (`otp_dispatches`) لمتابعة مسار الرسائل والمكالمات. +- [ ] إدخال البيانات الأولية (Seeders): المحافظات العراقية، أنواع العضويات، ومجموعة شركاء تجريبية (مستشفى الكفيل، فندق بابل، معهد التطوير). + +### 1.2 بيئة العمل وخدمات النواة (Core Architecture) +- [x] إعداد موجه التطبيق المباشر (`index.php`) لدعم الواجهات السحابية والملفات الثابتة. +- [x] معمارية الفئات المتوافقة مع معايير PSR-4 بدون اعتمادات خارجية ثقيلة. +- [ ] إعداد ملف البيئة الإنتاجي (`backend/.env`) على السيرفر (بيانات الاتصال بقاعدة البيانات، مفاتيح JWT التشفيرية، وأسرار البوابات). +- [ ] تشغيل واختبار نقطة فحص الحالة الصحية للنظام (`GET /api/v1/health`). + +### 1.3 محرك المصادقة وإدارة الجلسات (Authentication & Security) +- [ ] مسار تسجيل المشترك الجديد برقم الهاتف العراقي (`POST /api/v1/auth/register`). +- [ ] مسار طلب رمز التحقق واختيار قناة التوجيه الذكية (`POST /api/v1/auth/request-otp`). +- [ ] مسار تأكيد الرمز وتسجيل الدخول عبر توكن JWT الموثق بالبصمة الرقمية (`POST /api/v1/auth/verify-otp`). +- [ ] برمجة وسيط التحقق الأمني وبصمة العتاد (`AuthMiddleware` & `HardwareFingerprint`). + +### 1.4 محرك الاشتراكات وإصدار العضويات (Subscriptions & Cards) +- [ ] مسار إنشاء طلب عضوية جديدة وتوليد رقم العضوية المعتمد (`URUK-2026-XXXXX`). +- [ ] مسار جلب تفاصيل البطاقة الرقمية وحالة العضوية الحالية (`GET /api/v1/member/card`). +- [ ] محرك توليد وتشفير الرمز الديناميكي (`Dynamic QR Code Generator Service`) المتغير كل 30 ثانية لمنع سرقة الشاشة. +- [ ] محرك احتساب وتتبع وفورات المشترك (`GET /api/v1/member/savings-summary`). + +### 1.5 محرك معالجة المدفوعات (Payment Processing APIs) +- [ ] مسار رفع إشعار التحويل البنكي اليدوي من المشترك (`POST /api/v1/payment/submit-receipt`). +- [ ] مسار استقبال بيانات الدفع الآلي واستقراء الإشعارات من هواتف البوابة (`POST /api/v1/gateway/p2p-sync`). +- [ ] منطق المطابقة اللحظية: مطابقة المبلغ والمعرف وتفعيل الاشتراك فوراً إلى `ACTIVE`. + +--- + + +## 🤖 المرحلة الثانية: البوتات والبرمجيات الميدانية والتحقق (Bots & Automation) +*الهدف: تشغيل المحركات المستقلة التي تمنح المنصة تفوقها الاقتصادي وتوفر أكثر من 140,000 دولار.* + +### 2.1 بوت المصادقة الرقمية الصامتة (Zero-Cost Silent Caller Daemon) +- [ ] برمجة البرنامج الطرفي الميداني لأجهزة الأندرويد (`SilentCallerService`). +- [ ] الربط مع نقطة الـ API السحابية لسحب طلبات التحقق المعلقة. +- [ ] تنفيذ الرنة الخاطفة (Missed Call) المشفرة وإنهاء المكالمة فورياً عبر أوامر الاتصال الداخلية دون احتساب أي تعرفة. +- [ ] آلية فحص الرنين والتأكيد اللحظي على الخادم المركزي. + +### 2.2 بوت أتمتة وتثبيت المدفوعات (P2P Payment Matching Bot) +- [ ] برمجة برنامج الاستقراء الذكي للإشعارات المصرفية في العراق (`PaymentNotificationListener`). +- [ ] دعم استقراء إشعارات تطبيق سوبر كيو آي (Super Qi) واستخراج رقم الحركة والمبلغ. +- [ ] دعم استقراء إشعارات وتطبيقات زين كاش (ZainCash) ومصرف العراق الأول (FIB). +- [ ] إرسال بيانات الحركة المشفرة لخادم المنصة لمطابقة الفاتورة وتفعيل بطاقة المشترك آلياً خلال 5 ثوانٍ. + +### 2.3 محرك التوجيه متعدد القنوات (Multi-Channel Dispatcher) +- [ ] إنشاء بوت التيليغرام الرسمي للجائزة (`@UrukPrizeBot`) وربط Webhook الخاص به. +- [ ] مسار إرسال كود الـ OTP عبر التيليغرام مجاناً للمشتركين المفعلين للبوت. +- [ ] مولد كود الصورة الذكية (WhatsApp Image Captcha) لتجاوز حظر الأرقام. +- [ ] تفعيل بوابة الرسائل الرسمية (`OTPIQ Gateway`) كقناة طوارئ احتياطية في حال تعذر الإنترنت. + +--- + + +## 📱 المرحلة الثالثة: تطبيق المشتركين للهواتف الذكية (Flutter Mobile App) +*الهدف: تطبيق فخم بهوية أبل الملكية الداكنة بلمسات ذهبية يوفر تجربة سلسة للمشتركين على iOS و Android.* + +### 3.1 الهيكل العام والهوية البصرية (Theme & Apple Architecture) +- [x] إنشاء مشروع فلاتر ودعم نظام الحزم الأساسية. +- [ ] ضبط الثيم الفاخر: درجات الأسود الملكي، الذهب المطفي، وخطوط Apple الرسمية (`SF Pro` و `SF Arabic`). +- [ ] شاشات البداية والترحيب التفاعلية (Onboarding Flow) للتعريف بجائزة أوروك ومزايا العضوية. + +### 3.2 استمارة التسجيل السريعة والتحقق (Mobile Signup & Auth UI) +- [ ] شاشة إدخال رقم الهاتف العراقي واختيار القناة المفضلة للتحقق (مكالمة صامتة / تيليغرام / واتساب / SMS). +- [ ] واجهة إدخال الكود السري التلقائية مع استشعار الإشعارات. +- [ ] استمارة إكمال الملف الشخصي (الاسم الثلاثي، المحافظة، والصفة/المهنة). + +### 3.3 بطاقة العضوية التفاعلية (Apple Wallet Style Card) +- [ ] تصميم بطاقة العضوية ثلاثية الأبعاد بلمعات ذهبية وشعار الجائزة والشريحة الذكية. +- [ ] عرض رمز الـ QR الديناميكي مع مؤشر التحديث الأمني التلقائي. +- [ ] زر حفظ البطاقة في محفظة الهاتف (Apple Wallet / Google Wallet). +- [ ] مؤشر حالة العضوية (نشطة / منتهية / قيد التجديد) مع تاريخ الصلاحية لسنتين. + +### 3.4 محفظة التوفير الذكية ونظام التلعيب (Savings Wallet & Gamification) +- [ ] لوحة تحكم المشترك: عداد التوفير المالي الكلي بالدينار العراقي كاش. +- [ ] تفصيل الاستخدامات السابقة (زيارات المستشفيات، ليالي الفنادق، والدورات التدريبية). +- [ ] نظام الشارات والرتب (عضو برونزي -> فضي -> ذهبي -> ماسي أوروك). +- [ ] حاسبة الوفر التقديري عند كل استخدام للمشترك. + +### 3.5 دليل الشركاء الذكي (Partners Directory) +- [ ] تصفح شبكة المستشفيات والفنادق والمراكز التدريبية الشريكة. +- [ ] الفلترة الذكية حسب المحافظة (بغداد، أربيل، البصرة، النجف، إلخ). +- [ ] صفحة تفاصيل الشريك: نسبة الخصم، الخدمات المشمولة، الموقع على الخريطة، وأرقام التواصل. + +--- + + +## 🏥 المرحلة الرابعة: بوابة الشركاء وماسح الاستقبال (Partner Reception Scanner) +*الهدف: واجهة خفيفة وفائقة السرعة لموظفي المستشفيات والفنادق لاعتماد الخصم دون أخطاء.* + +### 4.1 واجهة الماسح السريع (Web Scanner App) +- [ ] بناء تطبيق ويب تقدمي (PWA) خفيف وسريع الاستجابة يعمل على الهواتف والأجهزة اللوحية وأجهزة الاستقبال. +- [ ] تشغيل كاميرا الجهاز وقراءة باركود العضوية في أقل من ثانية واحدة. +- [ ] إرسال رمز العضوية للتحقق اللحظي مع الخادم المركزي. + +### 4.2 شاشة اعتماد الخصم وتوثيق الوفر +- [ ] ظهور علامة التأكيد الخضراء فورياً مع اسم المشترك وصورته ونوع العضوية. +- [ ] حقل إدخال مبلغ الفاتورة الإجمالي ليقوم النظام باحتساب نسبة الخصم آلياً. +- [ ] تسجيل العملية في قاعدة البيانات وتحديث محفظة المشترك فوراً بإشعار الوفر المالي. + +--- + + +## 👑 المرحلة الخامسة: لوحة تحكم الإدارة المركزية (Super Admin Dashboard) +*الهدف: تمكين إدارة الجائزة ومجلس الأمناء من مراقبة المشتركين والتحصيل المالي وإدارة الشركاء.* + +### 5.1 الشاشة الرئيسية والمؤشرات المالية (Executive Analytics) +- [ ] عداد إجمالي المشتركين النشطين ومعدل النمو اليومي. +- [ ] إجمالي المبالغ المحصلة كاش (GMV) بالدولار والدينار العراقي. +- [ ] إجمالي الوفورات المحققة للمشتركين لدى كافة الشركاء في العراق. +- [ ] إحصائيات بوابات الدفع وقنوات المصادقة. + +### 5.2 إدارة الأعضاء والاشتراكات (Members Management) +- [ ] جدول المشتركين مع البحث المتقدم (بالرقم، الاسم، المحافظة، وحالة العضوية). +- [ ] تفعيل العضويات يدوياً أو تجميدها عند الضرورة. +- [ ] تصدير تقارير المشتركين الرسمية بصيغة Excel و PDF. + +### 5.3 إدارة الشركاء والخصومات (Partners Network Management) +- [ ] نموذج إضافة شريك جديد (مستشفى، فندق، معهد تدريبي). +- [ ] تحديد نسبة الخصم، الخدمات المشمولة، وصور وشعار الشريك. +- [ ] توليد حسابات اعتماد لموظفي الاستقبال التابعين لكل شريك. + +--- + + +## 🚀 المرحلة السادسة: الاختبارات الميدانية، الأمان، والإطلاق (Security & Go-Live) +*الهدف: فحص كافة المكونات في بيئة حية بالعراق وضمان الجاهزية التامة للانطلاق.* + +### 6.1 اختبارات الشبكة العراقية والتكامل الميداني +- [ ] اختبار شريحة زين الإلكترونية (`Zain eSIM QR`) على جهاز المعماري حمزة عايد. +- [ ] اختبار الرنين الصامت على شبكات زين وآسياسيل وكورك والتأكد من عدم حظر الخطوط. +- [ ] اختبار قناة رسائل الطوارئ عبر بوابة OTPIQ برصيد التجربة المجاني. +- [ ] اختبار مطابقة دفعة حية عبر سوبر كيو آي وزين كاش. + +### 6.2 تدقيق الأمان والامتثال +- [ ] مراجعة تشفير التوكنات ومقاومة التلاعب والتزوير في البطاقات الرقمية. +- [ ] فحص حماية الخادم ومحدد المعدل (Rate Limiting) لمنع هجمات حجب الخدمة (DDoS). +- [ ] تجهيز نسخة احتياطية دورية آلية لقاعدة البيانات (`Daily Automated Backups`). + +### 6.3 النشر والإنتاج (Production Launch) +- [ ] نشر خادم الإنتاج وربطه بالنطاق الرسمي (`urukprize.intaleqapp.com`). +- [ ] رفع واجهة الويب الاستقبالية ولوحة الإدارة. +- [ ] تجميع وبناء ملفات التطبيق الرسمية (`Release APK` للأندرويد ونسخة متجر أبل `iOS App Store`). + +--- + +**آخر تحديث:** 2026-09-18 +**المشرف المعماري على التنفيذ:** حمزة عايد (Hamza Ayed) +**الشريك الراعي والمؤسس:** د. ثامر (رئيس مجلس أمناء جائزة أوروك الدولية)