# وثيقة خطة التنفيذ الشاملة وخارطة الطريق (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)

---

<a name="1"></a>
## 🗄️ المرحلة الأولى: المحرك السحابي وقواعد البيانات (Backend Core & Database)
*الهدف: بناء الأساس البرمجي المتين، إدارة قواعد البيانات، وتوفير واجهات برمجة التطبيقات (APIs) الآمنة والسريعة.*

### 1.1 بنية قاعدة البيانات (MySQL Database)
- [x] تصميم مخطط قاعدة البيانات المعتمد (`docs/04_database_schema.sql`).
- [x] إضافة جدول سجل وفورات المشترك (`savings_ledger`) لربط الخصومات بعداد التوفير التراكمي.
- [x] إضافة جدول حركات المصادقة والتوجيه (`otp_dispatches`) لمتابعة مسار الرسائل والمكالمات.
- [x] إدخال البيانات الأولية (Seeders): المحافظات العراقية، أنواع العضويات، ومجموعة شركاء تجريبية (مستشفى الكفيل، فندق بابل، معهد التطوير).
- [ ] استيراد وإنشاء الجداول على قاعدة بيانات السيرفر الحي (`urukprize_db`).

### 1.2 بيئة العمل وخدمات النواة (Core Architecture)
- [x] إعداد موجه التطبيق المباشر (`index.php`) لدعم الواجهات السحابية والملفات الثابتة.
- [x] معمارية الفئات المتوافقة مع معايير PSR-4 بدون اعتمادات خارجية ثقيلة.
- [x] إعداد ملف البيئة النموذجي الكامل (`backend/.env.example`) مع مفاتيح JWT و Telegram و OTP.
- [x] تشغيل واختبار نقطة فحص الحالة الصحية للنظام (`GET /api/v1/health`).
- [ ] إعداد ملف البيئة الإنتاجي (`backend/.env`) على السيرفر الحي.

### 1.3 محرك المصادقة وإدارة الجلسات (Authentication & Security)
- [x] مسار تسجيل المشترك الجديد برقم الهاتف العراقي وبصمة الجهاز.
- [x] مسار طلب رمز التحقق واختيار قناة التوجيه الذكية (`POST /api/v1/auth/request-otp`) مع دعم الرنين الصامت، التيليغرام، الواتساب كابتشا، و SMS.
- [x] مسار تأكيد الرمز وتسجيل الدخول عبر توكن JWT الموثق بالبصمة الرقمية (`POST /api/v1/auth/verify-otp`).
- [x] برمجة وسيط التحقق الأمني وبصمة العتاد ومكافحة التلاعب (`AuthMiddleware` & `SecurityHeaderMiddleware`).

### 1.4 محرك الاشتراكات وإصدار العضويات (Subscriptions & Cards)
- [x] مسار إنشاء طلب عضوية جديدة وتوليد رقم العضوية المعتمد (`URUK-2026-XXXXX`).
- [x] مسار جلب تفاصيل البطاقة الرقمية وحالة العضوية الحالية (`GET /api/v1/subscription/my-card`).
- [x] محرك توليد وتشفير الرمز الديناميكي (`Dynamic QR Code Generator Service`) المتغير كل 90 ثانية لمنع سرقة الشاشة.
- [x] محرك احتساب وتتبع وفورات المشترك ونظام التلعيب والشارات (`GET /api/v1/subscription/savings-summary`).
- [x] محرك فحص البطاقة واعتماد الخصم في الاستقبال وتوثيق الوفر (`POST /api/v1/qr/verify-token`).

### 1.5 محرك معالجة المدفوعات (Payment Processing APIs)
- [x] مسار رفع إشعار التحويل البنكي اليدوي من المشترك وتفعيل الانتظار (`POST /api/v1/subscription/submit`).
- [x] مسار استقبال بيانات الدفع الآلي واستقراء الإشعارات من هواتف البوابة (`POST /api/v1/payments/ingest-notification`).
- [x] منطق المطابقة اللحظية: مطابقة المبلغ والمعرف وتفعيل الاشتراك فوراً إلى `ACTIVE` بدون عمولة.

---

<a name="2"></a>
## 🤖 المرحلة الثانية: البوتات والبرمجيات الميدانية والتحقق (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`) كقناة طوارئ احتياطية في حال تعذر الإنترنت.

---

<a name="3"></a>
## 📱 المرحلة الثالثة: تطبيق المشتركين للهواتف الذكية (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)
- [ ] تصفح شبكة المستشفيات والفنادق والمراكز التدريبية الشريكة.
- [ ] الفلترة الذكية حسب المحافظة (بغداد، أربيل، البصرة، النجف، إلخ).
- [ ] صفحة تفاصيل الشريك: نسبة الخصم، الخدمات المشمولة، الموقع على الخريطة، وأرقام التواصل.

---

<a name="4"></a>
## 🏥 المرحلة الرابعة: بوابة الشركاء وماسح الاستقبال (Partner Reception Scanner)
*الهدف: واجهة خفيفة وفائقة السرعة لموظفي المستشفيات والفنادق لاعتماد الخصم دون أخطاء.*

### 4.1 واجهة الماسح السريع (Web Scanner App)
- [ ] بناء تطبيق ويب تقدمي (PWA) خفيف وسريع الاستجابة يعمل على الهواتف والأجهزة اللوحية وأجهزة الاستقبال.
- [ ] تشغيل كاميرا الجهاز وقراءة باركود العضوية في أقل من ثانية واحدة.
- [ ] إرسال رمز العضوية للتحقق اللحظي مع الخادم المركزي.

### 4.2 شاشة اعتماد الخصم وتوثيق الوفر
- [ ] ظهور علامة التأكيد الخضراء فورياً مع اسم المشترك وصورته ونوع العضوية.
- [ ] حقل إدخال مبلغ الفاتورة الإجمالي ليقوم النظام باحتساب نسبة الخصم آلياً.
- [ ] تسجيل العملية في قاعدة البيانات وتحديث محفظة المشترك فوراً بإشعار الوفر المالي.

---

<a name="5"></a>
## 👑 المرحلة الخامسة: لوحة تحكم الإدارة المركزية (Super Admin Dashboard)
*الهدف: تمكين إدارة الجائزة ومجلس الأمناء من مراقبة المشتركين والتحصيل المالي وإدارة الشركاء.*

### 5.1 الشاشة الرئيسية والمؤشرات المالية (Executive Analytics)
- [ ] عداد إجمالي المشتركين النشطين ومعدل النمو اليومي.
- [ ] إجمالي المبالغ المحصلة كاش (GMV) بالدولار والدينار العراقي.
- [ ] إجمالي الوفورات المحققة للمشتركين لدى كافة الشركاء في العراق.
- [ ] إحصائيات بوابات الدفع وقنوات المصادقة.

### 5.2 إدارة الأعضاء والاشتراكات (Members Management)
- [ ] جدول المشتركين مع البحث المتقدم (بالرقم، الاسم، المحافظة، وحالة العضوية).
- [ ] تفعيل العضويات يدوياً أو تجميدها عند الضرورة.
- [ ] تصدير تقارير المشتركين الرسمية بصيغة Excel و PDF.

### 5.3 إدارة الشركاء والخصومات (Partners Network Management)
- [ ] نموذج إضافة شريك جديد (مستشفى، فندق، معهد تدريبي).
- [ ] تحديد نسبة الخصم، الخدمات المشمولة، وصور وشعار الشريك.
- [ ] توليد حسابات اعتماد لموظفي الاستقبال التابعين لكل شريك.

---

<a name="6"></a>
## 🚀 المرحلة السادسة: الاختبارات الميدانية، الأمان، والإطلاق (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)  
**الشريك الراعي والمؤسس:** د. ثامر (رئيس مجلس أمناء جائزة أوروك الدولية)