urukprize/docs/01_system_architecture.md

وثيقة المعمارية الهندسية الشاملة - منصة وتطبيق جائزة أوروك الدولية

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)

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):

• جدول سنوي للمحاضرات والورش الحضورية في قاعات الفنادق الشريكة.
• روابط مباشرة للمنصة الرقمية للبث المباشر وتسجيل الحضور آلياً.
• نظام إصدار الشهادات الرقمية المعتمدة وتوليد رقم تسلسلي فريد لكل متدرب.