Initial commit: Uruk Prize Platform architecture, backend core, mobile app, gateway caller & deployment pipeline

2026-09-18 17:12:05 +03:00
commit 879dd36f1b
1149 changed files with 97122 additions and 0 deletions
@@ -0,0 +1,109 @@
+# معمارية تطبيق الجوال فلاتر ونظام الكيوبت (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 وزين كاش المرفوعة، وتفعيل اشتراك المستخدم بضغطة زر وتوليد بطاقته فورياً.