# معمارية تطبيق الجوال فلاتر ونظام الكيوبت (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` الأساسية

```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 وزين كاش المرفوعة، وتفعيل اشتراك المستخدم بضغطة زر وتوليد بطاقته فورياً.