urukprize/docs/06_flutter_architecture_and_cubit.md

معمارية تطبيق الجوال فلاتر ونظام الكيوبت (Flutter Architecture & Cubit)

Document Version: 1.0.0
Date: September 2026
Package: iq.urukprize.app

---

1. الهيكلية المعمارية لتطبيق فلاتر (Clean Architecture with Cubit)

يتبع التطبيق نموذج فصل المسؤوليات الصارم (Layered Architecture):

lib/
├── main.dart                   # نقطة الدخول وتهيئة بيئة التخزين الآمن والبصمة
│
├── core/                       # الوحدات المشتركة والبنية التحتية
│   ├── constants/              # الروابط، الألوان، وأنماط التصميم
│   ├── network/                # عميل الـ HTTP المخصص وحاقن الترويسات
│   │   ├── api_client.dart     # حقن X-User-Id, X-Device-Fingerprint, والتوقيع تلقائياً
│   │   └── api_endpoints.dart
│   ├── security/               # إدارة البصمة والمفاتيح المشفرة
│   │   ├── fingerprint_helper.dart  # استخراج معرفات العتاد ودمج الملح
│   │   └── secure_vault.dart        # واجهة FlutterSecureStorage
│   └── theme/                  # ثيم جائزة أوروك الفاخر (Dark Gold & Navy)
│
├── features/                   # وحدات الأعمال المستقلة (Feature-Driven)
│   ├── auth/                   # المصادقة والدخول
│   │   ├── cubit/ (AuthCubit, AuthState)
│   │   └── presentation/ (PhoneInputScreen, OtpVerificationScreen)
│   │
│   ├── membership/             # بطاقة العضوية والـ QR الديناميكي
│   │   ├── cubit/ (MembershipCubit, MembershipState)
│   │   └── presentation/ (DigitalCardScreen, DynamicQrModal)
│   │
│   ├── partners/               # دليل المستشفيات والفنادق
│   │   ├── cubit/ (PartnersCubit, PartnersState)
│   │   └── presentation/ (PartnersDirectoryScreen, PartnerDetailsScreen)
│   │
│   ├── courses/                # أكاديمية أوروك والشهادات
│   │   ├── cubit/ (CoursesCubit, CoursesState)
│   │   └── presentation/ (CoursesCatalogScreen, CertificateViewScreen)
│   │
│   ├── subscription/           # الدفع والسداد (SuperQi / ZainCash / SwiftPayIQ)
│   │   ├── cubit/ (SubscriptionCubit, SubscriptionState)
│   │   └── presentation/ (PlanSelectionScreen, PaymentInstructionsScreen)
│   │
│   └── admin/                  # بوابة الإدارة المخفية (لـ د. ثامر والإدارة)
│       ├── cubit/ (AdminCubit, AdminState)
│       └── presentation/ (AdminGateModal, AddPartnerScreen, ApproveTransactionsScreen)

---

2. مواصفات حزم pubspec.yaml الأساسية

name: uruk_prize
description: "Uruk International Prize Smart Membership Application"
publish_to: "none"
version: 1.0.0+1

environment:
  sdk: ">=3.0.0 <4.0.0"

dependencies:
  flutter:
    sdk: flutter
  
  # State Management
  flutter_bloc: ^8.1.3
  equatable: ^2.0.5

  # Security & Storage
  flutter_secure_storage: ^9.0.0
  crypto: ^3.0.3
  device_info_plus: ^10.1.0

  # Networking & QR
  http: ^1.2.1
  qr_flutter: ^4.1.0
  mobile_scanner: ^5.1.1

  # Utilities
  intl: ^0.19.0

---

3. آلية الحقن التلقائي للترويسات والبصمة في كل طلب (Auto-Header Injection)

تم تصميم فئة ApiClient لترث أو تكبسيل http.Client، بحيث تقوم تلقائياً وقبل خروج أي حزمة بيانات عبر الشبكة بما يلي:

1. جلب معرف المستخدم X-User-Id من التخزين الآمن.
2. جلب بصمة الجهاز المعتمدة X-Device-Fingerprint.
3. توليد توقيت لحظي X-Timestamp، ورمز استخدام فردي X-Nonce.
4. حساب توقيع X-Signature مشفر بـ HMAC-SHA256 يجمع محتوى الطلب وبيانات الترويسة.
5. إرفاق Authorization: Bearer <Token>.

بهذا التدفق، لا يمكن لأي مستخدم أو محاول تلاعب التلاعب بالطلبات أو مشاركة الحساب عبر أجهزة متعددة.

---

4. وضع الإدارة المخفي داخل التطبيق (Hidden In-App Admin Mode)

استجابةً للنقاش الوارد في التسجيل الصوتي بشأن تمكين الإدارة (د. ثامر وفريقه) من إدخال وتعديل المستشفيات والفنادق المتعاقد معها في أي وقت ومن أي مكان:

• طريقة الدخول: ضغط مطول لمدة 5 ثوانٍ على شعار جائزة أوروك في الشاشة الرئيسية (أو النقر المتتالي 5 مرات على رقم الإصدار).
• الحماية: فتح نافذة منبثقة تطلب المصادقة البيومترية (بصمة الإصبع/الوجه) أو رمز المشرف المخصص.
• المميزات المتاحة للإدارة فوراً:
  1. إضافة شريك جديد فوراً (Add Partner): إدخال اسم المستشفى/الفندق، الدولة (العراق، الأردن، مصر، لبنان...)، المدينة، ونسبة الخصم (50% أو غيرها). فور الحفظ تظهر لجميع المشتركين مباشرة.
  2. التحقق من سداد المشتركين (Verify Receipts): مراجعة إيصالات SuperQi وزين كاش المرفوعة، وتفعيل اشتراك المستخدم بضغطة زر وتوليد بطاقته فورياً.