299 lines
17 KiB
Markdown
299 lines
17 KiB
Markdown
# خطة تنفيذ المعمارية الخلفية ونظام النشر المؤتمت — تطبيق نبيه (Nabeh)
|
||
|
||
<div dir="rtl" align="right">
|
||
|
||
توضح هذه الخطة التفاصيل الهيكلية والخطوات العملية لبناء النواة البرمجية للخلفية (Backend Base Architecture) باستخدام **Pure PHP OOP** وبناء نظام نشر تلقائي آمن عبر **Git/SSH** إلى السيرفر.
|
||
|
||
---
|
||
|
||
## أولاً: تقسيم المشروع إلى مراحل (Milestones)
|
||
|
||
من أجل ضمان الانتقال السلس وبناء أساسات متينة وقابلة للتطوير، سنقسم العمل على الخلفية والنشر إلى المراحل التالية:
|
||
|
||
### المرحلة 1: بناء نواة الـ MVC وتهيئة الهيكل البرمجي
|
||
- بناء هيكل المجلدات المنظم وفصل الملفات العامة (Public) عن الكود البرمجي الأساسي.
|
||
- إعداد نظام التحميل التلقائي للملفات (Autoloader) المتوافق مع معيار PSR-4.
|
||
- برمجة موجه الطلبات (Router) المتوافق مع خادم Nginx.
|
||
- برمجة قارئ ملفات البيئة المتطور والآمن (`.env` Reader) مع تخزينه خارج المسار العام لضمان أعلى مستويات الحماية.
|
||
|
||
### المرحلة 2: تصميم قاعدة البيانات ونواة الاتصال (Database & Core)
|
||
- تصميم ملف تهيئة الاتصال بقاعدة البيانات باستخدام PDO.
|
||
- بناء الموديل الرئيسي (Base Model) والمتحكم الرئيسي (Base Controller) لإدارة المدخلات والمخرجات (JSON Responses).
|
||
- بناء مخطط الجداول الأساسية لقاعدة البيانات (الهيكل متعدد المستأجرين - Multi-Tenant Prep).
|
||
|
||
### المرحلة 3: نظام النشر التلقائي للسيرفر (`deploy.sh`)
|
||
- كتابة سكربت النشر الآمن لرفع التحديثات لـ Git وعمل Pull تلقائي وإعادة بناء التهيئات على السيرفر.
|
||
- إعداد البنية التحتية للمجلدات على السيرفر وربط الـ Subdomain.
|
||
|
||
---
|
||
|
||
## ثانياً: معمارية مجلدات الخلفية المقترحة (Directory Structure)
|
||
|
||
سنقوم بتنظيم كود الخلفية داخل مجلد `backend/` لحماية كود التطبيق وملف البيانات الحساسة (`.env`) من الوصول المباشر من المتصفح، حيث سيكون مجلد `public/` هو المجلد الوحيد المتاح للعامة والمربوط بالـ Document Root في Nginx.
|
||
|
||
الهيكل المستهدف للمجلدات هو كالتالي:
|
||
|
||
</div>
|
||
|
||
```
|
||
nabeh/
|
||
├── backend/
|
||
│ ├── app/
|
||
│ │ ├── Controllers/ # متحكمات معالجة الطلبات
|
||
│ │ │ ├── BaseController.php
|
||
│ │ │ └── AuthController.php
|
||
│ │ ├── Models/ # موديلات قواعد البيانات
|
||
│ │ │ ├── BaseModel.php
|
||
│ │ │ └── Tenant.php
|
||
│ │ ├── Core/ # نواة التطبيق البرمجية
|
||
│ │ │ ├── Router.php
|
||
│ │ │ ├── Database.php
|
||
│ │ │ ├── Request.php
|
||
│ │ │ ├── Response.php
|
||
│ │ │ └── Env.php
|
||
│ │ └── Middlewares/ # فلاتر التحقق والوساطة
|
||
│ │ └── AuthMiddleware.php
|
||
│ ├── config/ # ملفات الإعدادات العامة
|
||
│ │ └── app.php
|
||
│ ├── public/ # المجلد الوحيد المتاح للمتصفح
|
||
│ │ └── index.php # نقطة الدخول الموحدة (Front Controller)
|
||
│ ├── .env # ملف البيئة الحساس (مخفي تماماً)
|
||
│ ├── .env.example
|
||
│ └── composer.json # لإدارة التحميل التلقائي PSR-4 وحزم التطبيق
|
||
```
|
||
|
||
<div dir="rtl" align="right">
|
||
|
||
---
|
||
|
||
## ثالثاً: تصميم النواة البرمجية (Core Architecture)
|
||
|
||
### 1. نقطة الدخول الموحدة `backend/public/index.php`
|
||
يقوم هذا الملف بتهيئة بيئة العمل، تحميل الملفات تلقائياً، قراءة متغيرات البيئة، ثم تمرير الطلب إلى الـ Router.
|
||
|
||
### 2. قارئ البيئة الآمن `backend/app/Core/Env.php`
|
||
يقرأ ملف `.env` المتواجد خارج المجلد العام ويقوم بتحميل المتغيرات داخل `$_ENV` و `getenv()` بأمان تام.
|
||
|
||
### 3. نظام توجيه الطلبات `backend/app/Core/Router.php`
|
||
نظام توجيه خفيف وقوي يدعم تعبيرات Regex، ويتيح تعريف مسارات من نوع GET و POST و PUT و DELETE وتمرير البارامترات للمتحكمات (Controllers) وتطبيق فلاتر الوساطة (Middlewares).
|
||
|
||
---
|
||
|
||
## رابعاً: نظام النشر المؤتمت (`deploy.sh`)
|
||
|
||
سنقوم بإنشاء سكربت النشر الذكي في الجذر الرئيسي للمشروع لتبسيط عملية الدفع والتحديث. سيقوم السكربت بالخطوات التالية بشكل تفاعلي وآمن:
|
||
|
||
1. التأكد من كتابة تعليق الالتزام (Commit Message).
|
||
2. إضافة كافة التغييرات محلياً والدفع إلى الفرع الرئيسي على GitHub/GitLab.
|
||
3. الاتصال بالسيرفر عبر بروتوكول SSH بشكل آمن.
|
||
4. التوجه إلى مجلد المشروع على السيرفر وسحب الكود البرمجي المحدث (`git pull origin main`).
|
||
5. تطبيق أي أوامر تهيئة مثل تثبيت حزم الملحقات (`composer install`) أو تنظيف الكاش.
|
||
|
||
محتوى سكربت `deploy.sh` المقترح:
|
||
|
||
</div>
|
||
|
||
```bash
|
||
#!/bin/bash
|
||
|
||
# ==========================================
|
||
# سكريبت النشر الآلي وتحديث السيرفر - تطبيق نبيه
|
||
# ==========================================
|
||
|
||
# 1. إعدادات السيرفر والمتغيرات الأساسية
|
||
SERVER_USER="hamza" # اسم مستخدم السيرفر
|
||
SERVER_IP="your-server-ip" # عنوان السيرفر
|
||
SERVER_PATH="/var/www/nabeh" # مسار المشروع على السيرفر
|
||
GIT_BRANCH="main" # الفرع الرئيسي للنشر
|
||
|
||
echo "=========================================="
|
||
echo "🚀 بدء عملية النشر والتحديث لتطبيق (نبيه)..."
|
||
echo "=========================================="
|
||
|
||
# 2. التأكد من حالة التغييرات المحلية
|
||
if [ -z "$(git status --porcelain)" ]; then
|
||
echo "ℹ️ لا توجد تغييرات برمجية غير محفوظة للنشر."
|
||
else
|
||
# طلب وصف للتحديثات (Commit Message)
|
||
echo "✍️ الرجاء إدخال رسالة الالتزام (Commit Message):"
|
||
read commit_msg
|
||
|
||
if [ -z "$commit_msg" ]; then
|
||
commit_msg="Update: Automatic deployment via deploy.sh"
|
||
fi
|
||
|
||
# الإضافة والالتزام البرمجي
|
||
git add .
|
||
git commit -m "$commit_msg"
|
||
fi
|
||
|
||
# 3. الدفع إلى Git Remote
|
||
echo "📤 دفع التحديثات إلى المستودع البعيد (Git Push)..."
|
||
git push origin $GIT_BRANCH
|
||
|
||
if [ $? -ne 0 ]; then
|
||
echo "❌ فشلت عملية الدفع البرمجي (Git Push). تم إلغاء النشر."
|
||
exit 1
|
||
fi
|
||
|
||
echo "✅ تم رفع الكود بنجاح إلى المستودع البرمجي."
|
||
|
||
# 4. الاتصال بالسيرفر وتحديث الكود (Git Pull)
|
||
echo "🌐 الاتصال بالسيرفر وسحب الكود المحدث (Git Pull)..."
|
||
ssh ${SERVER_USER}@${SERVER_IP} << EOF
|
||
cd ${SERVER_PATH}
|
||
echo "📁 الانتقال إلى مجلد المشروع: ${SERVER_PATH}"
|
||
|
||
echo "📥 سحب التحديثات من الفرع ${GIT_BRANCH}..."
|
||
git pull origin ${GIT_BRANCH}
|
||
|
||
if [ -f "backend/composer.json" ]; then
|
||
echo "📦 تحديث الحزم البرمجية والتحميل التلقائي (Composer)..."
|
||
cd backend
|
||
composer install --no-dev --optimize-autoloader
|
||
cd ..
|
||
fi
|
||
|
||
echo "🎉 تم تحديث السيرفر وتثبيت التحديثات بنجاح!"
|
||
EOF
|
||
|
||
echo "=========================================="
|
||
echo "✨ تمت عملية النشر والتحديث بالكامل بنجاح!"
|
||
echo "=========================================="
|
||
```
|
||
|
||
<div dir="rtl" align="right">
|
||
|
||
---
|
||
|
||
## خامساً: خطة إعداد الخادم والـ Subdomain
|
||
|
||
لتشغيل نظام الـ Front Controller والمسارات الديناميكية بشكل متوافق مع **Nginx** وبدون الحاجة لملفات `.htaccess` الخاصة بـ Apache، يجب إعداد ملف تهيئة الـ Subdomain (مثال: `api.nabeh.sa` أو `app.nabeh.sa`) ليوجه الطلبات إلى المجلد العام `backend/public/`:
|
||
|
||
إعداد Nginx المقترح للمخدم:
|
||
|
||
</div>
|
||
|
||
```nginx
|
||
server {
|
||
listen 80;
|
||
listen [::]:80;
|
||
|
||
server_name api.nabeh.sa; # النطاق الفرعي للتطبيق
|
||
|
||
# تحديد مسار المجلد العام فقط
|
||
root /var/www/nabeh/backend/public;
|
||
index index.php index.html;
|
||
|
||
charset utf-8;
|
||
|
||
# توجيه كافة الطلبات إلى index.php لدعم الـ Router
|
||
location / {
|
||
try_files $uri $uri/ /index.php?$query_string;
|
||
}
|
||
|
||
location = /favicon.ico { access_log off; log_not_found off; }
|
||
location = /robots.txt { access_log off; log_not_found off; }
|
||
|
||
error_page 404 /index.php;
|
||
|
||
# تشغيل ملفات PHP وتكاملها مع PHP-FPM
|
||
location ~ \.php$ {
|
||
fastcgi_pass unix:/var/run/php/php8.2-fpm.sock; # حسب إصدار PHP المثبت
|
||
fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
|
||
include fastcgi_params;
|
||
}
|
||
|
||
# منع الوصول تماماً لأي ملفات حساسة أو مخفية
|
||
location ~ /\.(?!well-known).* {
|
||
deny all;
|
||
}
|
||
}
|
||
```
|
||
|
||
<div dir="rtl" align="right">
|
||
|
||
---
|
||
|
||
## سادساً: خطة التحقق والتدقيق (Verification Plan)
|
||
|
||
### التحقق الذاتي والمحلي:
|
||
1. **التحقق من المسارات (Router Testing)**: إنشاء طلبات محلية للتحقق من تشغيل المسارات المختلفة (GET/POST) وإرجاع بيانات JSON صحيحة.
|
||
2. **التحقق من حماية متغيرات البيئة (`.env` Security)**: محاولة استعراض ملف `.env` عبر المسار المباشر للتأكد من حظر الوصول العام إليه، وقراءته بنجاح من داخل تطبيق PHP.
|
||
3. **فحص التحميل التلقائي**: التحقق من استدعاء كلاسات الـ Controllers والموديلات دون الحاجة لكتابة `require_once` يدوياً لكل ملف.
|
||
|
||
---
|
||
|
||
## المرحلة الرابعة: نظام التوثيق والمصادقة (Authentication Phase)
|
||
|
||
بناءً على النواة الأمنية التي تم تجهيزها (JWT, AES-256-GCM, Bcrypt, HMAC Blind Index)، سنقوم ببناء نظام المصادقة ليكون جاهزاً لإدارة جلسات المستخدمين.
|
||
|
||
### Proposed Changes
|
||
|
||
#### [NEW] `backend/app/Models/User.php`
|
||
- كلاس يمتد من `BaseModel` لإدارة جدول `users`.
|
||
- يحتوي على دالة `findByEmail` التي تقوم بتوليد (Blind Index HMAC) للبريد الإلكتروني للبحث السريع في قاعدة البيانات دون فك التشفير.
|
||
- دالة `createSecure` لإنشاء مستخدم جديد مع تشفير بريده الإلكتروني وكلمة مروره.
|
||
|
||
#### [NEW] `backend/app/Controllers/AuthController.php`
|
||
- دالة `login`: تستقبل البريد الإلكتروني وكلمة المرور، تتحقق منها عبر الموديل، وتولد JWT Token.
|
||
- دالة `register` (اختيارية كأداة تطوير مبدئية أو للأدمن): إنشاء حساب موظف جديد.
|
||
- دالة `me`: جلب بيانات المستخدم الحالي باستخدام الـ `AuthMiddleware` لاختبار سلامة الجلسة.
|
||
|
||
#### [MODIFY] `backend/public/index.php`
|
||
- إضافة المسارات الخاصة بنظام التوثيق:
|
||
- `POST /api/auth/login`
|
||
- `GET /api/auth/me` (مرفق بـ `AuthMiddleware`)
|
||
|
||
### User Review Required
|
||
|
||
> [!IMPORTANT]
|
||
> - هل ترغب بإنشاء مسار `POST /api/auth/register` مفتوح للجميع لإنشاء حسابات شركات جديدة؟ أم نكتفي حالياً بإنشاء مستخدم مدير (Admin) افتراضي يدوياً أو عبر سكربت ليكون النظام مغلقاً للشركات المعتمدة فقط؟
|
||
> - في عملية تسجيل الدخول، هل نحتاج لإرجاع بيانات الشركة المرتبطة بالمستخدم ضمن نفس الـ Response، أم نكتفي بإرجاع التوكن (Token) وبيانات المستخدم الأساسية فقط؟
|
||
|
||
---
|
||
|
||
## المرحلة الخامسة: معالجة وإصلاح الثغرات الأمنية (Security Audit Remediation)
|
||
|
||
بناءً على التقرير الأمني الصادر، سنقوم بتطبيق التعديلات البرمجية لرفع مستوى أمان الخادم وحماية البيانات.
|
||
|
||
### Proposed Changes
|
||
|
||
#### [MODIFY] [Security.php](file:///Users/hamzaaleghwairyeen/development/App/nabeh/backend/app/Core/Security.php)
|
||
- إرجاع خطأ (Exception) فوراً في حال عدم وجود متغيرات البيئة (`ENCRYPTION_KEY`, `HMAC_SALT`, `JWT_SECRET`) لمنع تشفير البيانات بمفاتيح فارغة.
|
||
|
||
#### [MODIFY] [BaseModel.php](file:///Users/hamzaaleghwairyeen/development/App/nabeh/backend/app/Models/BaseModel.php)
|
||
- تنظيف وفلترة أسماء الأعمدة ديناميكياً باستخدام مصفوفة بيضاء (Whitelist Regex) لمنع ثغرات الـ SQL Injection عبر أسماء الأعمدة في دالتي `create()` و `update()`.
|
||
|
||
#### [MODIFY] [SecurityMiddleware.php](file:///Users/hamzaaleghwairyeen/development/App/nabeh/backend/app/Middlewares/SecurityMiddleware.php)
|
||
- إلغاء تطبيق `htmlspecialchars` و `strip_tags` على المدخلات الخام القادمة للخلفية لمنع تلف كلمات المرور والرموز الخاصة، وتأجيل التنظيف ليكون حصراً عند الطباعة/العرض (Output Encoding).
|
||
|
||
#### [MODIFY] [AuthController.php](file:///Users/hamzaaleghwairyeen/development/App/nabeh/backend/app/Controllers/AuthController.php)
|
||
- إزالة التنظيف المزدوج (Double Encoding) لأسماء المستخدمين والشركات.
|
||
|
||
#### [MODIFY] [Router.php](file:///Users/hamzaaleghwairyeen/development/App/nabeh/backend/app/Core/Router.php)
|
||
- إخفاء مسار الملفات الحقيقي من رسائل الخطأ 404 و 500 وإظهار رسائل عامة لمنع تسريب بنية المجلدات (Information Disclosure).
|
||
|
||
#### [MODIFY] [Response.php](file:///Users/hamzaaleghwairyeen/development/App/nabeh/backend/app/Core/Response.php)
|
||
- جعل رابط الـ CORS ديناميكياً يعتمد على متغير بيئة `ALLOWED_ORIGIN` بدلاً من فتح النطاق للجميع عبر `*`.
|
||
|
||
#### [MODIFY] [bootstrap.php](file:///Users/hamzaaleghwairyeen/development/App/nabeh/backend/app/bootstrap.php)
|
||
- تسجيل معالج أخطاء عام (`set_exception_handler` / `set_error_handler`) لتحويل الأخطاء الفادحة غير المعالجة إلى استجابات JSON نظيفة ومخفية في الإنتاج، مع تسجيل التفاصيل التقنية في الـ `error_log` فقط.
|
||
|
||
#### [MODIFY] [Request.php](file:///Users/hamzaaleghwairyeen/development/App/nabeh/backend/app/Core/Request.php)
|
||
- تعريف الخصائص المعرفية (`$user_id`, `$company_id`, `$role`) بشكل صريح لتفادي مشاكل الخصائص الديناميكية (Dynamic Properties Deprecation) في إصدارات PHP 8.2+.
|
||
|
||
#### [NEW] [RateLimitMiddleware.php](file:///Users/hamzaaleghwairyeen/development/App/nabeh/backend/app/Middlewares/RateLimitMiddleware.php)
|
||
- بناء فلتر مخصص للحد من معدل الطلبات (Rate Limiting) على مسارات تسجيل الدخول والتسجيل لحماية التطبيق من محاولات التخمين العنيف (Brute Force).
|
||
|
||
#### [MODIFY] [index.php](file:///Users/hamzaaleghwairyeen/development/App/nabeh/backend/public/index.php)
|
||
- تفعيل فلتر الحد من معدل الطلبات على مسارات الحماية.
|
||
|
||
### User Review Required
|
||
|
||
> [!IMPORTANT]
|
||
> هل نعتمد نظام تخزين المحاولات للحد من معدل الطلبات (Rate Limiting) في ملفات مؤقتة داخل مجلد `storage/` محلي (سهل الإعداد ومستقل)، أم نستخدم جدولاً مخصصاً في قاعدة البيانات؟
|
||
|
||
</div>
|
||
|