# PRODUCTION_SERVER_PATCH_V5_4 — cPanel Deployment Checklist

## نطاق التنفيذ

هذه الحزمة مخصصة للنشر المرحلي بعد مراجعة المستخدم. **لم يتم استخدامها للنشر أو تعديل Production.** تحتوي الحزمة على ملفات الخادم المصححة والـmigrations المطلوبة فقط. لا تحتوي `.env` أو قاعدة بيانات أو كلمات مرور أو مفاتيح أو APK.

## 1. النسخ الاحتياطي الإلزامي قبل أي تغيير

1. سجّل نافذة الصيانة واسم النطاق ونسخة الحزمة وSHA-256 الخاص بها.
2. من cPanel File Manager، انتقل إلى `public_html/backend` وأنشئ Archive كاملًا للنسخة الحالية، بما في ذلك `public`, `config`, `.htaccess` وملفات الرفع. احفظ النسخة خارج document root أو نزّلها محليًا.
3. صدّر قاعدة البيانات الحالية من cPanel Backup أو phpMyAdmin. احفظ SQL dump خارج document root، وتحقق من إمكانية قراءته.
4. لا ترفع `.env` من الحزمة ولا تستبدله. احتفظ بملف Production الحالي وقيم `DB_*`, `APP_URL`, `JWT_SECRET` كما هي.
5. لا تبدأ الخطوة التالية قبل التأكد من وجود نسختي الملفات وقاعدة البيانات.

عند توفر SSH، مثال غير قابل للتنفيذ كما هو إلا بعد مراجعة المسارات:

```bash
STAMP=$(date +%Y%m%d_%H%M%S)
tar -czf "$HOME/backend_before_v5_4_${STAMP}.tgz" "$HOME/retnuhking/public_html/backend"
mysqldump --single-transaction --routines --triggers -u "$DB_USER" -p "$DB_NAME" > "$HOME/db_before_v5_4_${STAMP}.sql"
sha256sum "$HOME/backend_before_v5_4_${STAMP}.tgz" "$HOME/db_before_v5_4_${STAMP}.sql"
```

## 2. فك الحزمة خارج المسار الحي

1. ارفع `PRODUCTION_SERVER_PATCH_V5_4.zip` إلى مجلد مؤقت خارج `public_html` أو إلى حساب staging.
2. فك الضغط خارج المسار الحي وافحص أن الملفات الموجودة هي Backend والـmigrations وقائمة التحقق فقط.
3. تأكد أن `.env` الحالي ليس ضمن الحزمة المستخرجة وأنه لن يُحذف أو يُستبدل.

## 3. رفع ملفات Backend

1. في cPanel File Manager، ارفع محتويات مجلد `backend/` من الحزمة إلى المسار المقابل الحالي، والمتوقع عادة:
   `public_html/backend/`
2. استبدل ملفات Backend المصححة، خصوصًا `backend/public/index.php` و`backend/config/bootstrap.php` و`.htaccess`.
3. لا تستبدل مجلدات الوسائط الموجودة ولا تحذف صور المستخدمين.
4. حافظ على صلاحيات الملفات الحالية الآمنة. لا تجعل كامل Backend أو `.env` قابلًا للكتابة العامة.
5. لا ترفع أي ملف من مشروع Flutter إلى Production ضمن هذه الخطوة.

## 4. تشغيل migrations بالترتيب على staging ثم Production

شغّل أولًا على قاعدة staging/test، وبعد نجاح اختبارات staging فقط شغّل على Production:

```text
database/migrations/005_user_avatar_and_session_ui.sql
database/migrations/006_v5_2_home_and_error_monitoring.sql
```

إذا كانت migration 005 و006 مطبقتين أصلًا، تحقق من المخطط بدل تشغيل SQL عشوائيًا. يجب التأكد من:

- وجود `users.avatar_path`.
- وجود `app_error_logs`.
- وجود إعدادات V5.2 الرئيسية مثل `home_new_limit` و`home_best_limit` وحقول التواصل.
- عدم تخزين كلمات مرور أو tokens في جدول أخطاء العميل.

لا تتجاوز migrations سابقة مطلوبة في تاريخ قاعدة البيانات. لا تستخدم اسم قاعدة الاختبار على Production.

## 5. صلاحيات رفع صورة الحساب

تحقق من أن document root الفعلي للـAPI هو `public_html/backend/public` أو ما يعادله في الحساب. يجب أن يستطيع مستخدم PHP/Apache إنشاء وكتابة:

```text
backend/public/uploads/avatars
```

الكود ينشئ المجلد عند غيابه ويتحقق من `is_writable`. استخدم أقل صلاحيات تسمح بالتشغيل، ولا تجعل `backend` كاملًا world-writable.

## 6. اختبارات staging الإلزامية

باستخدام حساب اختبار غير حقيقي وغير إنتاجي:

```text
GET  /api/health
GET  /api/storefront
GET  /api/products?limit=80&q=...
GET  /api/products?limit=80&category_id=...
POST /api/profile/avatar   (Bearer token + multipart field image)
POST /api/auth/logout      (Bearer token)
```

تحقق من الآتي:

- `/api/health` يعيد success دون أسرار أو مسارات أو بيانات قاعدة.
- `/api/storefront` لا يجلب 217 منتجًا ولا يعيد معرضًا كاملًا لكل منتج.
- قائمة المنتجات تحتوي الصورة الأساسية فقط، بينما تفاصيل منتج واحد تعيد `images` الكاملة.
- البحث العام والبحث داخل التصنيف يعيدان نتائج صحيحة.
- رفع الصورة يعيد رابطًا عامًا من نوع `/uploads/avatars/...`.
- بعد تسجيل الخروج، يفشل استخدام الـtoken نفسه؛ لا يكفي حذف token محليًا فقط.
- مدة JWT العميل 30 يومًا، بينما الإدارة 12 ساعة.
- لا يظهر `stock_qty` للمستخدم.

## 7. التحقق من الهاتف الحقيقي

بعد نشر Server Patch على staging، ثبّت APK Debug على هاتف Android حقيقي واختبر البحث، التصنيف، فتح التفاصيل ومعرض الصور، السلة، رفع صورة الحساب، تسجيل الدخول/الخروج، وانتهاء الجلسة. سجّل النتيجة لكل تدفق. **لا تُسمّى النسخة Production Ready قبل نجاح هذا الاختبار وبعد نشر Server Patch فعليًا.**

## 8. التراجع Rollback

1. إذا فشل رفع الملفات، أوقف النشر واستعد Archive Backend السابق كاملًا.
2. إذا فشلت migration، لا تشغّل migration التالية. احتفظ برسالة الخطأ وسجلات الخادم.
3. استعد SQL dump السابق وفق آلية الاستعادة المدعومة في cPanel/phpMyAdmin، ثم استعد ملفات Backend السابقة.
4. تحقق بعد التراجع من تسجيل الدخول، `/api/products`, `/api/storefront`, السلة، ورفع الصورة.
5. لا تحذف النسخ الاحتياطية أو سجلات الفشل حتى إغلاق عملية النشر رسميًا.

## 9. سجل التسليم

سجّل checksum للحزمة، ونسخة الملفات السابقة، ونسخة قاعدة البيانات، ونتائج كل اختبار staging، ونتيجة اختبار الهاتف، وقرار النشر أو التراجع. لا تغيّر `.env` ولا تنسخ أي بيانات اعتماد من الأمثلة.