# دليل تثبيت عرض «مسار» V002 المنفصل عبر cPanel

هذه حزمة **تثبيت جديد للعرض**: تطبيق جديد، وقاعدة بيانات جديدة فارغة، ونطاق فرعي خاص بها. تبقى نسخة V001 القائمة كما هي ولا تُلمس. البيانات كلها وهمية: بيانات V001 التجريبية (64 مستخدماً و12 مشروعاً) مع بيانات وحدة الإنتاج التجريبية وثلاثة سيناريوهات مراجعة جاهزة.

**لا تستعمل هذه الحزمة لترقية تثبيت قائم.** الترقية لها حزمتها (`masar-cpanel.zip` ودليلها `INSTALL_GUIDE_AR.md`). أمر البذر هنا يرفض أي قاعدة فيها مستخدمون.

يلزم Node.js 22.12 فأحدث وPostgreSQL 16 فأحدث (المتوفران لنسخة V001).

## ما في المجلد `dist/masar-demo/`

| الملف | ما هو |
|---|---|
| `masar-cpanel-demo.zip` | التطبيق مبنياً وجاهزاً، بلا أي سر |
| `secrets-demo.env` | أسرار جديدة لهذا العرض وحده، وُلّدت عشوائياً. احفظه في مكان آمن، ولا ترسله في بريد أو محادثة، ولا ترفعه إلى Git |
| `INSTALL_DEMO_AR.md` | هذا الدليل |

## الخطوات

1. **النطاق الفرعي:** من cPanel ← Domains أنشئ نطاقاً فرعياً للعرض (مثل `demo.<نطاقك>`)، وفعّل له شهادة HTTPS (SSL/TLS Status ← Run AutoSSL).
2. **قاعدة البيانات:** من «PostgreSQL Databases» أنشئ قاعدة جديدة ومستخدماً جديداً بكلمة مرور قوية، وامنحه كل الصلاحيات على هذه القاعدة وحدها. **لا تستعمل قاعدة V001.**
3. **مجلدات البيانات:** من File Manager أنشئ `masar-demo-data/uploads` و`masar-demo-data/backups` في مجلدك الرئيسي، **خارج** `public_html`.
4. **رفع التطبيق:** ارفع `masar-cpanel-demo.zip` إلى مجلد جديد (مثل `masar-demo`) خارج `public_html`، ثم فكّه هناك.
5. **إنشاء التطبيق:** من «Setup Node.js App» ← Create Application:
   - Node.js version: 22.12 فأحدث؛
   - Application mode: Production؛
   - Application root: `masar-demo`؛
   - Application URL: النطاق الفرعي من الخطوة 1؛
   - Application startup file: `server.js`.
6. **المتغيرات:** افتح `secrets-demo.env`، واملأ ما بين `< >`:
   - `DATABASE_URL` باسم القاعدة ومستخدمها وكلمة مروره من الخطوة 2 (إن احتوت كلمة المرور رموزاً مثل `@` أو `#` فاكتبها مرمّزة، أو اختر كلمة مرور من حروف وأرقام)؛
   - `APP_URL` بعنوان النطاق الفرعي كاملاً مع `https://` ودون `/` في آخره؛
   - `UPLOAD_DIR` و`BACKUP_DIR` بالمسارين من الخطوة 3.
   ثم أضف كل سطر (عدا الأسطر التي تبدأ بـ `#`) في «Environment variables» للتطبيق، الاسم في خانة والقيمة في خانة.
7. **إنشاء الجداول:** في صفحة التطبيق نفسها، «Run JS script» ← اختر `db:migrate` وانتظر رسالة النجاح.
8. **تحميل البيانات التجريبية:** «Run JS script» ← اختر `db:seed`. يأخذ دقيقة أو أكثر، وينتهي برسالة `setup marked done`.
9. **التشغيل:** اضغط «Restart»، ثم افتح `https://<النطاق الفرعي>/api/health`. يجب أن تظهر `"status":"ok"`.
10. **الدخول:**
    - مدير النظام: اسم المستخدم `admin`، وكلمة المرور قيمة `SEED_ADMIN_PASSWORD` من الملف.
    - بقية المستخدمين: كلمة المرور قيمة `SEED_USERS_PASSWORD`. من أمثلتهم: `khalid` مدير المحفظة، و`noura` مديرة مشروع، و`turki` مشرف الإنتاج، و`saud.prod04` منفّذ، و`tariq.sci01` الخبير العلمي، و`sara.id01` المصممة التعليمية، و`owner.1` مراجع الجهة المالكة.
    - مدير النظام يستطيع أن يرى المنصة بصفة أي مستخدم من «اعرض بصفتي».

## المهام المجدولة (cPanel ← Cron Jobs)

كل أمر يحمل الترويسة `x-cron-key` بقيمة `CRON_KEY` من الملف. الأوقات بتوقيت الرياض.

| الجدول | الوجهة |
|---|---|
| `*/5 * * * *` | `POST https://<النطاق الفرعي>/api/cron/production-outbox` (تنبيهات الإنتاج والمراجعة — **ضرورية للعرض**) |
| `0 6 * * *` | `POST https://<النطاق الفرعي>/api/cron/daily` |
| `0 2 * * *` | `POST https://<النطاق الفرعي>/api/cron/backup?kind=daily` |

مثال: `curl -fsS -m 240 -X POST -H "x-cron-key: <CRON_KEY>" https://<النطاق الفرعي>/api/cron/production-outbox > /dev/null`

## بعد العرض

- **إعادة البيانات إلى حالتها الأولى:** مدير النظام من «الإدارة ← النظام» ← «إعادة البيانات التجريبية». يُتاح لأن `DEMO_MODE=true`.
- **إزالة العرض:** أوقف التطبيق واحذفه من «Setup Node.js App»، ثم احذف قاعدته ومستخدمها ومجلد `masar-demo-data`. لا أثر لذلك على نسخة V001.
- **إن وافقت الإدارة:** الانتقال إلى خوادم الشركة يكون بحزمة Docker وبأسرار جديدة يولّدها فريق تقنية المعلومات، لا بأسرار هذا العرض (`docs/HANDOVER_AR.md`).