Initial commit: Uruk Prize Platform architecture, backend core, mobile app, gateway caller & deployment pipeline

2026-09-18 17:12:05 +03:00
commit 879dd36f1b
1149 changed files with 97122 additions and 0 deletions
@@ -0,0 +1,124 @@
+# وثيقة المعمارية الهندسية الشاملة - منصة وتطبيق جائزة أوروك الدولية
+**Document Version:** 1.0.0  
+**Date:** September 2026  
+**Target Platform:** Mobile (iOS / Android) & Web Backend  
+
+---
+
+## 1. الملخص التنفيذي والرؤية الهندسية
+يهدف مشروع **جائزة أوروك الدولية** إلى إطلاق منصة رقمية متكاملة لتقديم خدمات العضوية الذكية، والتحقق الفوري من مزايا المشتركين، والتي تشمل:
+1. **القطاع الصحي:** خصم 50% لدى شبكة المستشفيات والمراكز التخصصية المتعاقد معها في العراق، إقليم كردستان، الأردن، مصر، ولبنان.
+2. **القطاع الفندقي:** خصومات سياحية تتراوح بين 40% و60% في الفنادق الشريكة.
+3. **أكاديمية التدريب والشهادات:** وصول مجاني لأكثر من 30 تخصصاً تدريبياً معتمداً (حضورياً في قاعات الفنادق الشريكة أو رقمياً عبر منصة البث المباشر لأوروك).
+
+---
+
+## 2. المكدس التقني المعتمد (Technology Stack)
+
+### أ. الواجهة الأمامية للجوال (Frontend Mobile App):
+* **إطار العمل:** `Flutter` (Cross-platform لنظامي Android و iOS).
+* **معرف الحزمة (Package Identifier):** `iq.urukprize.app` (مستقل وبدون كلمة example).
+* **إدارة الحالة (State Management):** `Bloc / Cubit` لضمان فصل منطق الأعمال عن واجهات العرض (Separation of Concerns) وقابلية الاختبار العالية.
+* **الحزم البرمجية الأساسية:**
+  * `flutter_bloc`
+  * `flutter_secure_storage` (تخزين المفاتيح الحساسة في Keychain على iOS و Keystore على Android).
+  * `http` (الاتصال المشفر بواجهات REST API).
+  * `crypto` (توليد البصمة المشفرة وتوقيع الطلبات HMAC-SHA256).
+  * `device_info_plus` (جمع معطيات العتاد لتوليد بصمة الجهاز Fingerprint).
+  * `qr_flutter` (عرض رمز الاستجابة السريعة الديناميكي).
+  * `mobile_scanner` (مسح الرموز لموظفي الاستقبال والتحقق).
+
+### ب. الواجهة الخلفية والخوادم (Backend Core Engine):
+* **اللغة والأسلوب:** `Pure PHP` (Custom Modular Core Framework).
+  * سرعة استجابة فائقة (Zero Framework Overhead).
+  * استهلاك خفيف لموارد الذاكرة ووحدة المعالجة المركزية.
+  * هيكلية معمارية تعتمد على طبقات: `Router`, `Controllers`, `Models`, `Services`, `Middlewares`.
+* **قاعدة البيانات:** `MySQL 8.0` مع محرك تخزين `InnoDB`، وتشفير `utf8mb4_unicode_ci` لدعم اللغة العربية بدقة كاملة.
+* **إدارة التبعيات:** ملف `composer.json` معزول ومستقل لضمان سهولة نقل المشروع لأي سيرفر آخر (`composer install`).
+* **التكامل الخارجي:**
+  * منصة `OTPIQ` للتحقق متعدد القنوات (WhatsApp Smart Fallback to SMS).
+  * منصة `SwiftPayIQ` لبوابة الدفع الرقمية في المرحلة الأولى، مع دعم قنوات SuperQi و ZainCash.
+  * بوابة التحقق من الهوية الرقمية عبر متصفح الويب لموظفي الاستقبال في الفنادق والمستشفيات.
+
+---
+
+## 3. المخطط المعماري للنظام (System Architecture Diagram)
+
+```mermaid
+graph TD
+    subgraph Client Layer
+        A[Flutter App - Android / iOS]
+        B[Reception Web Portal - Hospital / Hotel Scanner]
+        C[Admin Web Portal - Dr. Thamer & Management]
+    end
+
+    subgraph Security & Gateway Layer
+        D[HTTPS / TLS 1.3]
+        E[Security Middleware: Header & Fingerprint Validation]
+        F[HMAC Signature & Nonce Verification]
+        G[Rate Limiter & WAF]
+    end
+
+    subgraph Pure PHP Core Backend
+        H[Core Router]
+        I[Auth Controller]
+        J[Membership & QR Controller]
+        K[Partner Directory Controller]
+        L[Payment & Webhook Controller]
+        M[Admin In-App Controller]
+        
+        N[Services Layer]
+        N1[OTPIQ Gateway Service]
+        N2[SwiftPayIQ / Payment Service]
+        N3[QR Cryptographic Signer Service]
+        N4[Audit & Fingerprint Service]
+    end
+
+    subgraph Persistence Layer
+        O[(MySQL 8.0 Database)]
+        P[Encrypted Data at Rest: AES-256]
+    end
+
+    A --> D
+    B --> D
+    C --> D
+    D --> E
+    E --> F
+    F --> G
+    G --> H
+    H --> I & J & K & L & M
+    I & J & K & L & M --> N
+    N --> N1 & N2 & N3 & N4
+    N --> O
+    O --> P
+```
+
+---
+
+## 4. المكونات الوظيفية الرئيسية (Functional Modules)
+
+### 1. وحدة الهوية الرقمية والرمز الديناميكي (Smart Digital ID & Dynamic QR):
+* عرض هوية رقمية تفاعلية تحاكي الهوية الفيزيائية الفاخرة لجائزة أوروك.
+* توليد كود QR مشفر يتغير دورياً أو يتضمن توقيعاً رقمياً زمنياً يمنع أخذ لقطات شاشة (Screenshots) وتداولها بين غير المشتركين.
+* عند مسح الكود، يتم توجيه موظف المستشفى/الفندق إلى صفحة تحقق رسمية مشفرة تثبت:
+  * الاسم الرباعي وصورة المشترك.
+  * حالة الاشتراك (نشط / منتهي).
+  * رقم العضوية المعتمد.
+  * نسبة الخصم المعتمدة رسمياً للمؤسسة الشريكة.
+
+### 2. دليل الشركاء الذكي (Smart Directory):
+* تصفح وتصفية المستشفيات، المراكز الطبية، والفنادق حسب الدولة والمدينة والتخصص.
+* عرض مباشر لنسبة الخصم، معلومات الاتصال، والموقع الجغرافي.
+* تحديث لحظي للشركاء الجدد بمجرد إضافتهم من قبل الإدارة.
+
+### 3. بوابة الإدارة السريعة داخل التطبيق (In-App Admin Gateway):
+* وصول آمن مخصص لمسؤولي الجائزة (د. ثامر وفريق الإدارة) عبر إيماءة سرية (Secret Gesture / Long Press) مع مصادقة بصمة الوجه أو رمز مرور مشفر.
+* تمكين الإدارة من:
+  * إدخال عقود المستشفيات والفنادق الجديدة فور توقيعها وتفعيلها لجميع المشتركين مباشرة.
+  * تفعيل الاشتراكات اليدوية أو التحقق من الإيصالات المصرفية المباشرة فورياً.
+  * إحصائيات حية لعدد المشتركين والمبالغ المحصلة.
+
+### 4. وحدة الدورات التدريبية المعتمدة (Academy & Workshops):
+* جدول سنوي للمحاضرات والورش الحضورية في قاعات الفنادق الشريكة.
+* روابط مباشرة للمنصة الرقمية للبث المباشر وتسجيل الحضور آلياً.
+* نظام إصدار الشهادات الرقمية المعتمدة وتوليد رقم تسلسلي فريد لكل متدرب.