# النشر إلى cPanel من داخل Housa Studio — v1.7.1

أضيفت شاشة **Administration → Publish to domain** لنشر نسخة الموقع المنشورة إلى استضافة خارجية تعمل بـ cPanel.

## قبل أول نشر

تأكد من أن الاستضافة الحية توفر:

- PHP 8.2 أو أحدث.
- PDO SQLite و mbstring و fileinfo.
- صلاحية الكتابة داخل مجلد الموقع مثل `public_html`.
- HTTPS للدومين الحي.
- في جهاز الـCMS المصدر: PHP cURL، بالإضافة إلى ZipArchive أو PharData لإنشاء حزمة النشر.

## بيانات الاتصال

من لوحة الإدارة افتح **Publish to domain** وأدخل:

- **cPanel server**: اسم خادم cPanel مثل `server.example.com`، وليس رابط الموقع العام.
- **Port**: الافتراضي `2083`.
- **Username**: مستخدم cPanel.
- **Authentication**:
  - **API token**: الخيار المفضل.
  - **cPanel password**: يعمل كخيار بديل إذا كانت الاستضافة تسمح به.
- **Remote document root**: غالبًا `public_html` أو `public_html/site`.
- **Live website URL**: مثل `https://example.com`.
- **Verify SSL**: اتركه مفعّلًا في الإنتاج.
- **Save secret securely**: يحفظ التوكن/كلمة المرور مشفرة محليًا داخل الـCMS.

اضغط **Test connection** أولًا. في v1.7.1 أصبح الاختبار Preflight تشخيصيًا وآمنًا ولا يرفع ملفات الموقع. يفحص:

- وصول HTTPS إلى cPanel.
- استجابة UAPI وصحة المصادقة.
- الوصول إلى **Remote document root**.
- قابلية وصول **Live website URL** عبر HTTPS.

تظهر لكل خطوة حالة مستقلة مع HTTP status واسم السيرفر وIP وزمن الاستجابة ورسالة cPanel الفعلية عند توفرها. إذا أعاد الخادم HTML بدل JSON (مثل صفحة WAF أو "One moment, please") سيظهر ذلك بوضوح مع توصية باستخدام hostname المباشر لـcPanel. يوجد زر **Copy diagnostics** لنسخ نتيجة التشخيص بدون التوكن أو كلمة المرور. لا يتم النشر ما لم ينجح اتصال cPanel والمجلد الهدف والدومين الحي. بعد نجاح الاختبار يحفظ النظام بصمة Preflight آمنة للإعدادات والسر؛ أي تغيير في السيرفر أو التوكن أو المسار أو الدومين يعطل زر Publish ويطلب Test connection جديدًا.

## ماذا يحدث عند Publish؟

1. يتحقق الـCMS من اتصال cPanel والمجلد الهدف.
2. ينشئ Release Package خاصة بالإنتاج.
3. يرفع الحزمة إلى cPanel.
4. يفك الحزمة داخل المجلد الهدف.
5. يستدعي Hook مؤقتًا عبر HTTPS لمزامنة المحتوى المنشور.
6. يحذف Hook بعد نجاح المزامنة ويحاول تنظيف ملف الحزمة من السيرفر.
7. يسجل العملية داخل **Deployment history** و **Activity log**.

## ما الذي يتم نشره؟

- الكود الحالي للموقع والـCMS.
- الصفحات **المنشورة فقط** ومحتواها المنشور.
- العناصر المنشورة من Properties / Articles / Agents / Services / Testimonials / FAQs.
- الصور والفيديوهات المرفوعة الموجودة في `public/uploads`.
- إعدادات الموقع والـAppearance والـCursor.

## ما الذي يتم الحفاظ عليه على الموقع الحي؟

عمليات النشر اللاحقة لا تستبدل حسابات المستخدمين ولا الاستفسارات الموجودة على الدومين الحي.

- **Users** على الموقع الحي محفوظون.
- **Inquiries** على الموقع الحي محفوظة.
- في أول نشر فقط، إذا لم توجد أي حسابات مستخدم على النسخة الحية، يتم نسخ حسابات الـCMS المصدر حتى تستطيع الدخول بنفس حساب الأدمن.

## حماية بيانات cPanel

- التوكن أو كلمة المرور لا تظهر مرة أخرى عبر API بعد الحفظ.
- يتم تشفير السر محليًا باستخدام Sodium إن توفر، أو AES-256-GCM عبر OpenSSL.
- مفتاح التشفير موجود في `storage/deployment.key` بصلاحيات خاصة.
- بيانات cPanel لا تدخل ضمن Content Backup العادي.
- يمكنك الضغط على **Forget saved connection** لمسح الاتصال والسر المحفوظ.

## ملاحظات مهمة

- لا ترفع `storage/` المحلي فوق `storage/` الحي يدويًا بعد بدء استخدام الموقع، لأن النسخة الحية ستحتوي مستخدمين واستفسارات خاصة بها.
- إذا كان الدومين خلف DNS جديد أو غير متاح عبر HTTPS، قد ينجح رفع الملفات ثم تفشل خطوة مزامنة المحتوى حتى يصبح الدومين قابلًا للوصول.
- إذا ظهرت Requirement باسم cURL أو Archive support على أنها Missing، فعّل الامتداد المطلوب في PHP الذي يشغّل لوحة الـCMS المصدر.
- جرّب أول نشر على Subdomain أو مجلد تجريبي قبل استبدال موقع إنتاج مهم.


## تشخيص مشاكل الاتصال في v1.7.1

- **401 / 403**: بيانات المصادقة رفضها cPanel؛ راجع Username والـAPI Token.
- **Redirect 301/302/307/308**: استخدم hostname المباشر لخدمة cPanel بدل دومين يوجّه إلى مكان آخر.
- **HTML instead of UAPI JSON**: Proxy/WAF/صفحة Login أو Browser Challenge تعترض الاتصال؛ استخدم hostname المباشر على 2083.
- **TLS certificate error**: استخدم اسم السيرفر المطابق للشهادة بدل IP كلما أمكن.
- **Remote document root failed**: المصادقة نجحت لكن المسار غير صحيح أو غير متاح لهذا الحساب.
- **Live website URL warning**: cPanel قد يكون متصلًا، لكن Hook النشر النهائي يحتاج الدومين الحي أن يكون قابلًا للوصول عبر HTTPS.