urukprize/docs/05_backend_core_and_composer.md

معمارية خادم الـ 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)

لضمان عمل النظام بشكل مستقل تماماً عند نقله لأي سيرفر سحابي آخر، يُحدد ملف التبعيات المستقل التالي:

{
    "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، ثم تشغيل المزامنة على السيرفر لجلب التحديثات فورياً:

#!/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!"