# راهنمای دپلوی SignalPro روی cPanel (لینوکس)

دامنه هدف: **https://online.rayanasr.com/**

---

## معماری روی هاست

```
online.rayanasr.com
        │
        ▼
   Node.js App (Passenger)
        │
        ├── /api/*        → API بک‌اند
        ├── /uploads/*    → فایل‌های آپلود
        ├── /socket.io/*  → بروزرسانی زنده
        └── /*            → فرانت React (build شده)
```

یک اپ Node.js هم API و هم فرانت را سرو می‌کند — نیازی به دو سرور جدا نیست.

---

## پیش‌نیازهای هاست

- cPanel با **Setup Node.js App** (نسخه ۱۳۴ ✓)
- Node.js **۱۸** یا **۲۰** (LTS)
- SSL فعال برای `online.rayanasr.com`
- حداقل **۵۱۲MB RAM** (ترجیحاً ۱GB)
- دسترسی **Terminal** در cPanel (اختیاری ولی توصیه می‌شود)

---

## مرحله ۱ — آماده‌سازی فایل‌ها روی کامپیوتر خودتان

### ۱.۱ بیلد فرانت‌اند (روی ویندوز)

```powershell
cd C:\Users\hesam\Desktop\cursor\signalpro
npm run build
```

پوشه `frontend\dist` ساخته می‌شود.

### ۱.۲ فایل `.env` پروداکشن

در مسیر `backend` فایل `.env` بسازید (از روی نمونه):

```env
NODE_ENV=production
PORT=3001
APP_URL=https://online.rayanasr.com
FRONTEND_URL=https://online.rayanasr.com
JWT_SECRET=یک-رمز-تصادفی-خیلی-قوی-حداقل-۳۲-کاراکتر
OTP_EXPIRY_MINUTES=10
```

> **مهم:** `JWT_SECRET` را حتماً عوض کنید. می‌توانید از [randomkeygen.com](https://randomkeygen.com) استفاده کنید.

### ۱.۳ فشرده‌سازی برای آپلود

این پوشه‌ها را **آپلود نکنید** (حجم زیاد و غیرضروری):

- `node_modules` (همه جا)
- `.git`

این‌ها را **حتماً آپلود کنید**:

```
signalpro/
├── app.js                 ← نقطه ورود cPanel
├── package.json           ← اسکریپت start
├── backend/
│   ├── src/
│   ├── data/              ← دیتابیس (بعد از seed)
│   ├── uploads/
│   ├── package.json
│   └── .env               ← تنظیمات پروداکشن
└── frontend/
    └── dist/              ← خروجی build
```

کل پوشه `signalpro` را ZIP کنید.

---

## مرحله ۲ — آپلود روی cPanel

### ۲.۱ ورود به cPanel

1. وارد cPanel هاست شوید
2. بخش **File Manager** (مدیر فایل) را باز کنید

### ۲.۲ محل قرارگیری فایل‌ها

برای ساب‌دامنه `online.rayanasr.com` معمولاً یکی از این مسیرهاست:

| حالت | مسیر معمول |
|------|------------|
| ساب‌دامنه جدا | `/home/USERNAME/online.rayanasr.com/` |
| زیرپوشه | `/home/USERNAME/public_html/online/` |

> مسیر دقیق را از **Domains → Subdomains** در cPanel ببینید.

### ۲.۳ آپلود و استخراج

1. به پوشه ساب‌دامنه بروید
2. اگر فایل پیش‌فرض (`index.html`) هست، پاکش کنید یا rename کنید
3. فایل ZIP را **Upload** کنید
4. راست‌کلیک روی ZIP → **Extract**
5. ساختار نهایی باید این باشد:

```
/home/USERNAME/online.rayanasr.com/signalpro/app.js
/home/USERNAME/online.rayanasr.com/signalpro/package.json
...
```

اگر ZIP مستقیم محتویات را ریخت (بدون پوشه signalpro)، مشکلی نیست — فقط `app.js` باید در **Application root** باشد.

---

## مرحله ۳ — تنظیم Node.js App در cPanel

### ۳.۱ ساخت اپلیکیشن

1. cPanel → **Software** → **Setup Node.js App**
2. دکمه **Create Application** را بزنید
3. مقادیر را این‌طور پر کنید:

| فیلد | مقدار |
|------|--------|
| **Node.js version** | `18.x` یا `20.x` (جدیدترین LTS) |
| **Application mode** | `Production` |
| **Application root** | مسیر پوشه پروژه، مثلاً `online.rayanasr.com/signalpro` |
| **Application URL** | `online.rayanasr.com` |
| **Application startup file** | `app.js` |
| **Passenger log file** | پیش‌فرض بماند |

4. **Create** را بزنید

### ۳.۲ متغیرهای محیطی (Environment Variables)

در همان صفحه Node.js App، بخش **Environment variables** را پر کنید:

| نام | مقدار |
|-----|--------|
| `NODE_ENV` | `production` |
| `APP_URL` | `https://online.rayanasr.com` |
| `FRONTEND_URL` | `https://online.rayanasr.com` |
| `JWT_SECRET` | رمز تصادفی قوی شما |
| `OTP_EXPIRY_MINUTES` | `10` |

> `PORT` را معمولاً cPanel خودش تنظیم می‌کند — دستی نگذارید مگر خطا داد.

### ۳.۳ نصب وابستگی‌ها

در صفحه Node.js App:

1. دکمه **Run NPM Install** را بزنید  
   (یا در **Terminal** cPanel):

```bash
cd ~/online.rayanasr.com/signalpro
source /home/USERNAME/nodevenv/online.rayanasr.com/signalpro/18/bin/activate
npm install --prefix backend
```

> مسیر `nodevenv` را از صفحه Node.js App کپی کنید (دکمه Enter to the virtual environment).

### ۳.۴ بیلد فرانت (اگر روی سرور build نکردید)

اگر `frontend/dist` را از ویندوز آپلود کردید، این مرحله را **رد کنید**.

در غیر این صورت در Terminal:

```bash
cd ~/online.rayanasr.com/signalpro
npm run build
```

### ۳.۵ دسترسی نوشتن (مهم)

```bash
chmod 755 ~/online.rayanasr.com/signalpro/backend/data
chmod 755 ~/online.rayanasr.com/signalpro/backend/uploads
chmod 755 ~/online.rayanasr.com/signalpro/backend/uploads/receipts
```

### ۳.۶ ساخت دیتابیس اولیه (یک‌بار)

```bash
cd ~/online.rayanasr.com/signalpro
npm run seed
```

خروجی باید شامل `Demo user: demo@signalpro.ir / demo1234` باشد.

### ۳.۷ راه‌اندازی

در صفحه Node.js App دکمه **Restart** را بزنید.

---

## مرحله ۴ — SSL و HTTPS

1. cPanel → **SSL/TLS Status**
2. برای `online.rayanasr.com` گواهی **Let's Encrypt** را فعال کنید (AutoSSL)
3. cPanel → **Domains** → مطمئن شوید ساب‌دامنه به پوشه درست اشاره می‌کند

برای اجبار HTTPS:

- cPanel → **Domains** → **Redirects**
- یا در `.htaccess` (اگر Apache مستقیم سرو می‌کند):

```apache
RewriteEngine On
RewriteCond %{HTTPS} off
RewriteRule ^(.*)$ https://%{HTTP_HOST}%{REQUEST_URI} [L,R=301]
```

---

## مرحله ۵ — تست نهایی

| تست | آدرس | انتظار |
|-----|--------|--------|
| سلامت API | `https://online.rayanasr.com/api/health` | `{"ok":true,...}` |
| صفحه ورود | `https://online.rayanasr.com/login` | فرم ورود فارسی |
| ورود دمو | `demo@signalpro.ir` / `demo1234` | صفحه OTP |

### کد OTP روی هاست

در حالت production کد OTP در **لاگ سرور** چاپ می‌شود، نه در ترمینال ویندوز:

1. cPanel → Node.js App → **Open Passenger log** یا **stderr.log**
2. یا Terminal:

```bash
tail -f ~/online.rayanasr.com/signalpro/stderr.log
```

خط شبیه: `[OTP] demo@signalpro.ir: 123456`

> برای production واقعی، بعداً سرویس ایمیل (SMTP) وصل کنید.

---

## مرحله ۶ — به‌روزرسانی بعدی

هر بار که کد را عوض کردید:

```bash
cd ~/online.rayanasr.com/signalpro
# فایل‌های جدید را آپلود کنید
npm install --prefix backend
npm run build          # اگر فرانت عوض شده
# Restart از صفحه Node.js App
```

---

## عیب‌یابی

### صفحه سفید یا ۵۰۳

- Node.js App را **Restart** کنید
- لاگ Passenger را ببینید
- مطمئن شوید `frontend/dist/index.html` وجود دارد

### `frontend/dist not found`

```bash
npm run build
```

### خطای permission روی دیتابیس

```bash
chmod -R 755 backend/data backend/uploads
```

### API کار می‌کند ولی صفحه login نه

- `npm run build` را دوباره اجرا کنید
- Cache مرورگر را پاک کنید (`Ctrl+Shift+R`)

### CORS / خطای ورود

- `APP_URL` و `FRONTEND_URL` باید دقیقاً `https://online.rayanasr.com` باشند (بدون `/` آخر)
- اپ را Restart کنید

### WebSocket کار نمی‌کند

سیگنال‌های فعال با **polling** هم کار می‌کنند. اگر WebSocket لازم است، از هاست بخواهید `mod_proxy_wstunnel` فعال باشد.

---

## امنیت production

- [ ] `JWT_SECRET` قوی و یکتا
- [ ] رمز کاربر دمو را عوض کنید یا حذف کنید
- [ ] SSL فعال
- [ ] فایل `.env` در دسترس وب نباشد (خارج از public_html یا محافظت‌شده)

---

## پشتیبانی

اگر در مرحله‌ای گیر کردید، این اطلاعات را بفرستید:

1. اسکرین‌شات صفحه Setup Node.js App
2. محتوای لاگ Passenger (۱۰ خط آخر)
3. خروجی `https://online.rayanasr.com/api/health`