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,135 @@
+# معمارية خادم الـ Pure PHP وملف Composer ونظام المزامنة (Backend Core & Deploy)
+**Document Version:** 1.0.0  
+**Date:** September 2026  
+
+---
+
+## 1. فلسفة المعمارية البرمجية (Pure PHP Core)
+
+بناءً على التوجيه التقني المباشر، لن يتم استخدام أطر عمل ضخمة (كاللارافيل المتشعب) لتفادي استهلاك موارد السيرفر (Overhead)، بل سيتم بناء **Pure PHP Core** خفيف، صلب، وعالي الأداء:
+* زمن استجابة للطلب (Latency) أقل من 15 مللي ثانية.
+* استهلاك أدنى للذاكرة RAM (أقل من 3MB لكل طلب).
+* بنية نظيفة وقابلة للصيانة والتطوير تعتمد معايير PSR الحديثة والبرمجة كائنية التوجه (OOP).
+
+---
+
+## 2. الهيكلية المقترحة لملفات الـ Backend
+
+```
+backend/
+├── composer.json               # حزم الكمبوزر المعزولة والمستقلة
+├── .env.example                # نموذج المتغيرات البيئية الحساسة
+├── deploy.sh                   # سكربت المزامنة والنشر الآلي على السيرفر
+│
+├── config/                     # ملفات الإعدادات الثابتة
+│   ├── app.php
+│   ├── database.php
+│   └── security.php
+│
+├── core/                       # محرك النظام الأساسي (The Core Engine)
+│   ├── Database.php            # إدارة اتصالات PDO مع MySQL بشكل آمن
+│   ├── Router.php              # موجه الروابط السريع والمطابقة النمطية
+│   ├── Request.php             # كبسلة الطلب وقراءة الترويسات (Headers)
+│   ├── Response.php            # إرجاع ردود JSON المشفرة والمنظمة
+│   ├── Security.php            # دوال التشفير، الـ HMAC، والبصمة
+│   └── Middleware.php          # الأساس المنطقي لاعتراض وفحص الطلبات
+│
+├── app/
+│   ├── Middlewares/            # طبقات الحماية واعتراض الروابط
+│   │   ├── SecurityHeaderMiddleware.php  # فحص البصمة، النونس، والتوقيع
+│   │   ├── AuthMiddleware.php            # التحقق من جلسة العضو
+│   │   └── AdminMiddleware.php           # حماية لوحة الإدارة لـ د. ثامر
+│   │
+│   ├── Controllers/            # متحكمات مسارات الـ API
+│   │   ├── AuthController.php            # تسجيل، دخول، وطلب OTP عبر OTPIQ
+│   │   ├── SubscriptionController.php    # خطط الاشتراك، إصدار رقم العضوية
+│   │   ├── QrController.php              # توليد والتحقق من رموز QR المشفرة
+│   │   ├── PartnerController.php         # دليل المستشفيات والفنادق والخصومات
+│   │   ├── PaymentController.php         # استقبال التحويلات وWebhooks
+│   │   └── AdminController.php           # إدارة الشركاء والاعتمادات السريعة
+│   │
+│   ├── Services/               # طبقة التكامل مع الخدمات الخارجية
+│   │   ├── OtpIqService.php              # الربط مع منصة OTPIQ (واتساب + SMS)
+│   │   ├── SwiftPayService.php           # الربط مع بوابة SwiftPayIQ
+│   │   ├── SuperQiParserService.php      # معالجة إشعارات التحويل المباشر
+│   │   └── QrCryptographerService.php     # توقيع وتشفير رموز الدخول
+│   │
+│   └── Models/                 # التفاعل مع جداول قاعدة البيانات
+│       ├── User.php
+│       ├── Subscription.php
+│       ├── Transaction.php
+│       ├── Partner.php
+│       └── Course.php
+│
+└── public/                     # المجلد المتاح للويب فقط (Web Root)
+    ├── index.php               # نقطة الدخول الموحدة (Front Controller)
+    └── .htaccess               # إعادة توجيه الروابط وتأمين المجلدات
+```
+
+---
+
+## 3. مواصفات حزم الـ Composer المعزولة (`composer.json`)
+
+لضمان عمل النظام بشكل مستقل تماماً عند نقله لأي سيرفر سحابي آخر، يُحدد ملف التبعيات المستقل التالي:
+
+```json
+{
+    "name": "uruk/prize-backend",
+    "description": "Uruk International Prize Core Backend Engine",
+    "type": "project",
+    "license": "proprietary",
+    "require": {
+        "php": ">=8.1",
+        "ext-pdo": "*",
+        "ext-pdo_mysql": "*",
+        "ext-openssl": "*",
+        "ext-json": "*",
+        "vlucas/phpdotenv": "^5.6",
+        "guzzlehttp/guzzle": "^7.8"
+    },
+    "autoload": {
+        "psr-4": {
+            "Core\\": "core/",
+            "App\\": "app/"
+        }
+    },
+    "config": {
+        "optimize-autoloader": true,
+        "preferred-install": "dist",
+        "sort-packages": true
+    }
+}
+```
+
+---
+
+## 4. سكربت النشر والمزامنة السحابية على الماك (`deploy.sh`)
+
+يحقق السكربت التدفق المطلوب: كتابة الكود على جهاز الماك، وإرساله فوراً عبر Git، ثم تشغيل المزامنة على السيرفر لجلب التحديثات فورياً:
+
+```bash
+#!/usr/bin/env bash
+# ==============================================================================
+# Uruk International Prize - Zero-Downtime Deployment & Git Sync
+# Author: Hamza Ayed
+# ==============================================================================
+
+set -e
+
+echo "🚀 [1/4] Checking local Git working tree on Mac..."
+git status -s
+
+echo "📦 [2/4] Staging and Committing changes..."
+COMMIT_MSG=${1:-"Sync Uruk Prize core updates: $(date '+%Y-%m-%d %H:%M:%S')"}
+git add .
+git commit -m "$COMMIT_MSG" || echo "No new local changes to commit."
+
+echo "⬆️ [3/4] Pushing changes to Remote Git Repository..."
+git push origin main
+
+echo "🌐 [4/4] Triggering Production Server Deployment..."
+# يمكن استخدام SSH المباشر أو Webhook آمن على السيرفر
+# ssh user@uruk-server.iq "cd /var/www/uruk-backend && git pull origin main && composer install --no-dev --optimize-autoloader && php core/cache_clear.php"
+
+echo "✅ Deployment completed successfully!"
+```