# معمارية خادم الـ 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!"
```