# راهنمای استقرار روی سرور

این سند مراحل کامل deploy پروژه **Cheragh Bot Manager** روی سرور Linux (Ubuntu/Debian) را پوشش می‌دهد.

## پیش‌نیازهای سرور

| نرم‌افزار | نسخه پیشنهادی | توضیح |
|-----------|----------------|--------|
| PHP | 8.2+ (ترجیحاً 8.3/8.4) | با اکستنشن‌های: `pdo_mysql`, `mbstring`, `openssl`, `tokenizer`, `xml`, `ctype`, `json`, `bcmath`, `fileinfo`, `zip` |
| Composer | 2.x | مدیریت وابستگی‌های PHP |
| MySQL / MariaDB | 8.0+ | دیتابیس اصلی |
| Redis | 7.x | صف و cache (توصیه production) |
| Nginx | 1.18+ | وب‌سرور |
| Node.js | 20+ | فقط برای `npm run build` (اختیاری اگر asset از قبل build شده) |
| Supervisor | آخرین نسخه | worker صف‌ها و scheduler |
| Certbot | — | SSL رایگان Let's Encrypt |

---

## ۱) Clone پروژه

```bash
sudo mkdir -p /var/www/cheraghbot
sudo chown -R $USER:www-data /var/www/cheraghbot

git clone https://github.com/Yadak-Shop/cheraghbot.git /var/www/cheraghbot
cd /var/www/cheraghbot

# برای production پایدار:
git checkout main

# یا برای آخرین تغییرات توسعه:
# git checkout dev
```

---

## ۲) تنظیم `.env`

```bash
cp .env.example .env
php artisan key:generate
nano .env
```

### متغیرهای حیاتی production

```env
APP_NAME="مدیریت ربات‌های چراغ برق"
APP_ENV=production
APP_DEBUG=false
APP_URL=https://bot.your-domain.com
APP_TIMEZONE=Asia/Tehran

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=cheragh_bot_manager
DB_USERNAME=cheragh_bot_user
DB_PASSWORD=YOUR_STRONG_DB_PASSWORD

SESSION_DRIVER=database
QUEUE_CONNECTION=redis
CACHE_STORE=redis

REDIS_CLIENT=predis
REDIS_HOST=127.0.0.1
REDIS_PORT=6379

# آدرس عمومی HTTPS برای webhook پلتفرم‌ها (حیاتی)
BOT_WEBHOOK_BASE_URL=https://bot.your-domain.com
BOT_DEFAULT_MODE=webhook
BOT_POLLING_ENABLED=false

# ادمین اولیه — فقط بار اول seed
ADMIN_SEED_EMAIL=admin@your-domain.com
ADMIN_SEED_PASSWORD=YOUR_VERY_STRONG_PASSWORD

# امنیت لاگین ادمین
CAPTCHA_DISABLE=false
ADMIN_LOGIN_MAX_ATTEMPTS=5
ADMIN_LOGIN_DECAY_MINUTES=15

# OTP — در production حتماً false
OTP_LOCAL_FAKE_DELIVERY=false
OTP_LOCAL_EXPOSE_CODE=false
OTP_VERIFY_LIMIT=10
OTP_VERIFY_WINDOW_MINUTES=15

# دانلود امن فایل export
SECURE_DOWNLOAD_TTL_MINUTES=60

# AI (اختیاری)
AI_ENABLED=false
```

> **هشدار:** بدون `BOT_WEBHOOK_BASE_URL` با HTTPS، ربات‌ها webhook دریافت نمی‌کنند. `php artisan system:doctor` این مورد را بررسی می‌کند.

---

## ۳) نصب اولیه

```bash
composer install --no-dev --optimize-autoloader --no-interaction

# اگر Node روی سرور دارید:
npm ci --no-audit --no-fund
npm run build

php artisan storage:link
php artisan migrate --force

# فقط بار اول — ساخت ادمین، دکمه‌ها و layout کیبورد
php artisan db:seed --force
```

### دسترسی فایل‌ها

```bash
sudo chown -R www-data:www-data storage bootstrap/cache
sudo chmod -R 775 storage bootstrap/cache
```

---

## ۴) Nginx

```bash
sudo cp deploy/nginx/cheraghbot.conf /etc/nginx/sites-available/cheraghbot
sudo nano /etc/nginx/sites-available/cheraghbot
```

موارد قابل ویرایش در فایل:

- `server_name` → دامنه واقعی
- `root` → `/var/www/cheraghbot/public`
- `fastcgi_pass` → سوکت PHP-FPM (مثلاً `unix:/run/php/php8.3-fpm.sock`)

```bash
sudo ln -sf /etc/nginx/sites-available/cheraghbot /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

# SSL
sudo certbot --nginx -d bot.your-domain.com
```

---

## ۵) Supervisor (صف‌ها + Scheduler)

جزئیات بیشتر: [production-supervisor.md](production-supervisor.md)

```bash
sudo apt install -y supervisor
sudo cp deploy/supervisor/cheraghbot.conf /etc/supervisor/conf.d/cheraghbot.conf
sudo nano /etc/supervisor/conf.d/cheraghbot.conf   # مسیر پروژه و user

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl status
```

### صف‌های الزامی

| صف | کاربرد |
|----|--------|
| `default` | رویدادهای عمومی |
| `inventory` | import/export اکسل |
| `bot-heavy` | ارسال پیام، webhook setup، keyboard |
| `bot-webhooks` | پردازش پیام‌های ورودی (**حیاتی**) |
| `ai` | پاسخ و خلاصه AI |
| `manual-runs` | اجراهای دستی ادمین |

---

## ۶) Scheduler (جایگزین cron)

Supervisor برنامه `cheraghbot-scheduler` با `schedule:work` اجرا می‌شود.

اگر cron ترجیح می‌دهید:

```bash
* * * * * cd /var/www/cheraghbot && php artisan schedule:run >> /dev/null 2>&1
```

وظایف زمان‌بندی‌شده:

- `bots:health-check` — هر ۵ دقیقه
- `bots:retry-failed-jobs` — ساعتی
- `exports:cleanup` — روزانه
- `manual-runs:cleanup` — روزانه
- `bots:poll` — هر دقیقه (فقط اگر `BOT_POLLING_ENABLED=true`)

---

## ۷) بررسی سلامت بعد از نصب

```bash
php artisan system:doctor
php artisan config:cache
php artisan route:cache
php artisan view:cache
```

ورود به پنل‌ها:

| پنل | URL |
|-----|-----|
| کاربر (OTP) | `https://bot.your-domain.com/` |
| ادمین | `https://bot.your-domain.com/dashboard` |
| داشبورد ادمین | `https://bot.your-domain.com/admin` |

---

## ۸) Deployهای بعدی (git pull)

**لوکال (برنچ dev):**

```bash
git add .
git commit -m "توضیح تغییر"
git push origin dev
```

**سرور:**

```bash
cd /var/www/cheraghbot
git pull origin main    # یا dev
bash deploy/post-deploy.sh
```

اسکریپت `deploy/post-deploy.sh` این کارها را انجام می‌دهد:

1. `composer install --no-dev`
2. `npm ci && npm run build` (اگر npm موجود باشد)
3. `php artisan migrate --force`
4. cache کردن config/route/view
5. `php artisan queue:restart`
6. `php artisan system:doctor`

> **توجه:** `db:seed` در post-deploy اجرا نمی‌شود. فقط نصب اولیه.

---

## ۹) استقرار روی Runflare

1. مخزن را به GitHub وصل کنید (`Yadak-Shop/cheraghbot`)
2. برنچ: `main` یا `dev`
3. Document root: `public`
4. PHP: 8.3+
5. Build command:

```bash
composer install --no-dev --optimize-autoloader && npm ci && npm run build
```

6. متغیرهای `.env` را در پنل Runflare تنظیم کنید (بخش ۲)
7. Worker جدا:

```bash
php artisan queue:work --queue=bot-webhooks,default,bot-heavy,inventory,ai,manual-runs --sleep=1 --tries=3 --max-time=3600
```

8. Scheduler جدا:

```bash
php artisan schedule:work
```

---

## ۱۰) راه‌اندازی ربات بعد از deploy

مراحل کامل: [bot-setup.md](bot-setup.md)

```bash
php artisan bots:setup-webhook --bot=1
php artisan queue:work --queue=bot-heavy --once
php artisan bots:webhook-info --bot=1
php artisan bots:test --bot=1 --chat=CHAT_ID
```

---

## ۱۱) چک‌لیست Go-Live

- [ ] `system:doctor` بدون خطای blocking
- [ ] `BOT_WEBHOOK_BASE_URL` با `https://` تنظیم شده
- [ ] Redis و MySQL در دسترس
- [ ] Supervisor: ۶ worker + scheduler فعال
- [ ] SSL فعال روی دامنه
- [ ] `ADMIN_SEED_PASSWORD` قوی و تغییر یافته
- [ ] `OTP_LOCAL_FAKE_DELIVERY=false`
- [ ] OTP Delivery در `/admin/settings/otp` تنظیم شده
- [ ] webhook ثبت و `last_webhook_received_at` به‌روز می‌شود
- [ ] تست OTP ورود کاربر از `/`
- [ ] تست آپلود فایل و export از `/panel`

---

## ۱۲) عیب‌یابی رایج

| مشکل | راه‌حل |
|------|--------|
| ربات پیام نمی‌گیرد | webhook ثبت نشده یا صف `bot-webhooks` خاموش است |
| OTP ارسال نمی‌شود | `/admin/settings/otp` + `ChannelIdentity` کاربر |
| export/import کار نمی‌کند | worker صف `inventory` را بررسی کنید |
| کپچا ادمین نمایش نمی‌دهد | `storage` و فونت `public/assets/fonts/captcha/tahoma.ttf` |
| ۵۰۳ / timeout | `client_max_body_size` در Nginx (پیش‌فرض 32M) |
| جاب failed | `/admin/jobs` → retry از پنل ادمین |

### لاگ‌ها

```bash
tail -f storage/logs/laravel.log
tail -f storage/logs/supervisor-queue-bot-webhooks.log
sudo supervisorctl status
php artisan queue:failed
```