# دليل النشر على Shared Hosting (cPanel) — بدون SSH

هذا الدليل مخصص لاستضافتك تحديدًا: مشتركة، بها cPanel، بدون وصول SSH،
وموجود بها أيقونة **Setup Node.js App**.

---

## 1) إنشاء قاعدة البيانات (MySQL)

1. من الـ cPanel افتح **MySQL Databases**.
2. أنشئ Database جديدة (مثال: `cpaneluser_smmpanel`).
3. أنشئ MySQL User جديد بباسورد قوي.
4. من قسم **Add User to Database** اربط الـ User بالـ Database وامنحه **All Privileges**.
5. احتفظ بالبيانات دي، هتحتاجها في `DATABASE_URL`:
   ```
   DATABASE_URL="mysql://cpaneluser_dbuser:PASSWORD@localhost:3306/cpaneluser_smmpanel"
   ```

> ⚠️ أسماء الـ Database والـ User على cPanel بتتحط تلقائيًا بادئة زي `cpaneluser_` — خد بالك من الاسم الكامل الظاهر فعليًا.

---

## 2) رفع الكود

اختر واحدة من الطريقتين:

**أ) Git Version Control** (لو متاحة في cPanel):
- cPanel > Git Version Control > Create، وحط رابط الريبو (لو عندك واحد على GitHub).

**ب) File Manager (الأبسط لو معندكش Git):**
- ارفع المشروع كملف ZIP عبر **File Manager**، في مجلد خارج `public_html` (مثلاً `smm-panel-app`)
  — Node.js apps بتتحط عادة برّه `public_html` والـ cPanel بيربطها بدومين/ساب دومين تلقائيًا.
- فك الضغط (Extract) من نفس File Manager.

---

## 3) إعداد Node.js App

1. من الـ cPanel افتح **Setup Node.js App**.
2. اضغط **Create Application**.
3. اختار:
   - **Node.js version**: أعلى نسخة LTS متاحة (18 أو 20).
   - **Application mode**: Production.
   - **Application root**: المجلد اللي رفعت فيه الكود (مثلاً `smm-panel-app`).
   - **Application URL**: الدومين أو الساب دومين اللي هيتفتح منه الموقع.
   - **Application startup file**: `server.js` ← **مهم جدًا**، ده الملف اللي جهّزناه خصيصًا عشان يشتغل مع Passenger.
4. بعد إنشاء الـ App، هتلاقي زرار **Run NPM Install** — اضغطه (ده بديل `npm install` من غير Terminal).
5. من نفس الصفحة تقدر تضيف **Environment Variables** (بدل ملف `.env`):
   - انسخ كل المتغيرات من `.env.example` وحط قيمها الحقيقية واحد واحد من الواجهة.

---

## 4) بناء المشروع (Build)

المشكلة: `npm run build` محتاج ينفّذ من Terminal، وإحنا معندناش SSH.

**الحل:** لو الاستضافة فيها زرار **Terminal** جوه cPanel (بعض الاستضافات بتديك Terminal من المتصفح
حتى من غير SSH حقيقي — دور عليه تحت قسم Advanced)، استخدمه لتنفيذ:
```bash
npm run build
npx prisma generate
```

**لو مفيش Terminal خالص:**
- ابني المشروع (`npm run build`) على جهازك محليًا.
- ارفع مجلد `.next` الناتج + `node_modules` (أو خليه يتعمل NPM Install من واجهة cPanel) + باقي الملفات.
- ده أبطأ لكنه شغّال 100%.

---

## 5) إنشاء الجداول في قاعدة البيانات

### الطريقة الأساسية (موصى بها): معالج التثبيت `/install`

بعد ما التطبيق يشتغل (خطوة 3 و 4)، افتح `https://yourdomain.com/install` من المتصفح مباشرة.
المعالج هيتحقق من الاتصال بقاعدة البيانات، وبضغطة زر واحدة هيُنشئ كل الجداول تلقائيًا
(من غير Terminal ولا phpMyAdmin)، وهيوجّهك لإنشاء حساب الأدمن الأول مباشرة. راجع قسم
"معالج التثبيت" في `README.md` لتفاصيل أكتر.

### الطريقة البديلة (لو حصلت مشكلة في المعالج): استيراد يدوي عبر phpMyAdmin

1. ملف `prisma/migration.sql` جاهز بالفعل في المشروع (نفس الملف اللي بيستخدمه المعالج).
2. افتح **phpMyAdmin** من الـ cPanel، اختار الـ Database اللي عملتها.
3. من تبويب **Import**، ارفع ملف `prisma/migration.sql` ونفّذه.
4. تحقق إن كل الجداول (`User`, `Order`, `Wallet`, `Service`...) ظهرت في phpMyAdmin.
5. بعد كده افتح `/install` عادي وهيكتشف إن الجداول موجودة وينقلك مباشرة لخطوة إنشاء الأدمن.

---

## 6) تشغيل معالجة الطلبات (بديل BullMQ Worker)

بما إن Redis والـ Worker المستمر مش متاحين:

1. من الـ cPanel افتح **Cron Jobs**.
2. أضف Cron Job جديد:
   - **Command**:
     ```
     curl -s "https://yourdomain.com/api/cron/process-orders?token=YOUR_CRON_SECRET" > /dev/null 2>&1
     ```
   - **Timing**: كل دقيقة (`* * * * *`) — أو كل 5 دقائق لو الاستضافة بتحدد عدد أقل من الـ Cron Jobs.
3. تأكد إن `CRON_SECRET` في الـ Environment Variables بتاعة الـ Node App مطابق للتوكن في أمر الـ Cron.

هذا الـ Endpoint (`src/app/api/cron/process-orders/route.ts`) بيعالج دفعة صغيرة من الطلبات المعلّقة
في كل استدعاء بدل عملية خلفية مستمرة — أنسب حل لبيئة Shared Hosting بحدود CPU/Memory محدودة.

---

## 7) إعادة تشغيل التطبيق بعد أي تعديل

من **Setup Node.js App**، اضغط **Restart** بعد أي تغيير في الكود أو الـ Environment Variables.

---

## ⚠️ قيود مهمة لازم تكون واعي بيها

| القيد | التأثير |
|---|---|
| مفيش Redis | أي ميزة كانت هتعتمد على Queue حقيقي (Retry فوري، Rate limiting دقيق) هتتحول لمنطق أبسط مبني على Cron + جدول DB |
| مفيش Worker مستمر | معالجة الطلبات مش لحظية 100%، فيها تأخير بين دقيقة والتانية حسب توقيت الـ Cron |
| حدود CPU/Memory | لازم `BATCH_SIZE` صغير في الـ Cron endpoint (موجود بالفعل = 20) عشان الاستضافة متوقفش الـ Process |
| مفيش SSH مضمون | البناء (`build`) والـ Migrations محتاجين حل بديل (محليًا + رفع، أو phpMyAdmin) |
| حدود عدد Cron Jobs | بعض الاستضافات بتمنع Cron كل دقيقة، وبتفرض حد أدنى 5 دقائق — تحقق من حدود خطتك |

لو حجم الطلبات كبر مستقبلاً وده بقى يضيّق عليك، الخطوة الطبيعية هي الترقية لـ VPS بسيط
(فيه SSH كامل) — ساعتها نرجّع Redis + BullMQ + Worker حقيقي بسهولة لأن الكود مبني بالفعل
بـ Abstraction (`SmmProvider` interface, Pricing Engine) بيسمح بالتبديل من غير إعادة كتابة المنطق.