# تثبيت تطبيق إدارة المبيعات على cPanel

هذه الحزمة تشغّل التطبيق على استضافة cPanel التي تتيح **Setup Node.js App / Passenger**. يلزم أن تدعم الاستضافة Node.js 22، أو Node.js 20.19 فأحدث، وقاعدة MySQL أو MariaDB مع SSL للموقع.

## 1. رفع الملفات

1. أنشئ تطبيقًا فرعيًا أو نطاقًا فرعيًا للموقع، مثل `sales.example.com`.
2. ارفع ملف ZIP وفكّه في مجلد التطبيق خارج `public_html`، مثل `~/sales-ops-hub`.
3. انسخ `.env.example` إلى ملف باسم `.env` داخل مجلد التطبيق. لا تضع هذا المجلد داخل مجلد عام يمكن للزوار تصفحه.

## 2. إنشاء قاعدة البيانات

من **MySQL Database Wizard** في cPanel، أنشئ قاعدة بيانات ومستخدمًا، ثم امنح المستخدم جميع الصلاحيات على قاعدة البيانات. احتفظ باسم القاعدة واسم المستخدم وكلمة المرور.

## 3. ضبط المتغيرات

افتح `.env` وأدخل القيم التالية:

```env
NODE_ENV=production
SELF_HOSTED_AUTH=true
VITE_SELF_HOSTED_AUTH=true
VITE_APP_ID=sales-ops-hub-cpanel
OWNER_OPEN_ID=cpanel-admin
DATABASE_URL=mysql://اسم_المستخدم:كلمة_المرور@localhost:3306/اسم_القاعدة
JWT_SECRET=اكتب_هنا_سرا_عشوائيا_طويلا_لا_يقل_عن_32_حرفا
SELF_HOSTED_ADMIN_USERNAME=اسم_دخول_الإدارة
SELF_HOSTED_ADMIN_PASSWORD=كلمة_مرور_قوية_وفريدة
SELF_HOSTED_ADMIN_NAME=مسؤول المبيعات
```

إذا احتوت كلمة مرور قاعدة البيانات على رموز مثل `@` أو `:` أو `/`، حوّلها إلى صيغة URL-encoded قبل وضعها في `DATABASE_URL`. استخدم HTTPS للموقع حتى تعمل ملفات جلسة الدخول الآمنة.

## 4. إعداد تطبيق Node.js

1. افتح **Setup Node.js App** في cPanel وأنشئ تطبيقًا جديدًا.
2. اختر Node.js 22 (أو 20.19 فأحدث)، وضع التطبيق `production`.
3. اجعل **Application root** هو مجلد التطبيق، و**Application URL** هو النطاق أو النطاق الفرعي الذي اخترته.
4. اكتب `app.cjs` في خانة **Application startup file**.
5. احفظ التطبيق، ثم فعّل بيئة Node.js الخاصة به في Terminal ونفّذ `npm install --include=dev` من مجلد التطبيق. يمكن استخدام زر **Run NPM Install** أولًا إذا ظهر في لوحة cPanel، لكن تأكد من تثبيت حزم التطوير لأن عملية البناء تحتاجها.

## 5. بناء التطبيق وتهيئة قاعدة البيانات

من Terminal في cPanel، فعّل بيئة Node.js الخاصة بالتطبيق بحسب الأمر الذي تعرضه صفحة Setup Node.js App، ثم نفّذ:

```bash
cd ~/sales-ops-hub
npm run build
npm run db:push
```

يقرأ أمر التهيئة `DATABASE_URL` من ملف `.env`، وينشئ جداول التطبيق في قاعدة البيانات. لا تعِد تنفيذ التهيئة على قاعدة فيها بيانات مهمة دون أخذ نسخة احتياطية أولًا.

## 6. تشغيل التطبيق

ارجع إلى **Setup Node.js App** واضغط **Restart**. افتح النطاق وسجّل الدخول باستعمال اسم المستخدم وكلمة المرور اللذين ضبطتهما في `.env`.

## ملاحظات عن الميزات

- يوفّر وضع cPanel دخولًا محليًا لحساب الإدارة. إنشاء حسابات فريق إضافية في صفحة «الفريق والصلاحيات» ما زال مرتبطًا بتسجيل OAuth الموروث من النسخة الأصلية.
- ميزات الذكاء الاصطناعي، ورفع الملفات إلى التخزين السحابي، وبعض ميزات الخرائط تعتمد على خدمات Forge الأصلية. تعمل وحدات إدارة المبيعات والمخزون والإنتاج على قاعدة البيانات، أما الميزات الخارجية فتحتاج إلى إعداد مفاتيح الخدمة المناسبة.
- يجب أن تتيح الاستضافة تشغيل تطبيق Node.js عبر Passenger. استضافة cPanel التي تتيح PHP فقط لا تكفي لهذا التطبيق.
- احتفظ بنسخة احتياطية من قاعدة البيانات ومجلد التطبيق. لا تشارك ملف `.env` لأنه يحتوي كلمات المرور ومفتاح الجلسات.