# وثيقة المعمارية الهندسية الشاملة - منصة وتطبيق جائزة أوروك الدولية
**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):
* جدول سنوي للمحاضرات والورش الحضورية في قاعات الفنادق الشريكة.
* روابط مباشرة للمنصة الرقمية للبث المباشر وتسجيل الحضور آلياً.
* نظام إصدار الشهادات الرقمية المعتمدة وتوليد رقم تسلسلي فريد لكل متدرب.