110 lines
5.7 KiB
Markdown
110 lines
5.7 KiB
Markdown
# معمارية تطبيق الجوال فلاتر ونظام الكيوبت (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 وزين كاش المرفوعة، وتفعيل اشتراك المستخدم بضغطة زر وتوليد بطاقته فورياً.
|