# راهنمای راه‌اندازی ربات

مراحل عملیاتی افزودن ربات (Rubika / Telegram / Bale) از صفر تا go-live.

> پیش‌نیاز: پروژه طبق [deployment.md](deployment.md) روی سرور deploy شده باشد.

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

- HTTPS عمومی روی `BOT_WEBHOOK_BASE_URL`
- `php artisan system:doctor` بدون خطای blocking
- Supervisor با **۶ صف** فعال
- Scheduler فعال (`schedule:work` یا cron)

---

## ۱) متغیرهای `.env` مرتبط با ربات

```env
APP_URL=https://bot.your-domain.com
BOT_WEBHOOK_BASE_URL=https://bot.your-domain.com
BOT_DEFAULT_MODE=webhook
BOT_POLLING_ENABLED=false

RUBIKA_API_BASE_URL=https://botapi.rubika.ir/v3
TELEGRAM_API_BASE_URL=https://api.telegram.org
BALE_API_BASE_URL=https://tapi.bale.ai
```

---

## ۲) ایجاد ربات در پنل ادمین

1. ورود: `/dashboard`
2. منو **ربات‌ها** → **افزودن ربات**
3. فیلدها:

| فیلد | مقدار |
|------|--------|
| نام | نام داخلی |
| پلتفرم | `rubika` / `telegram` / `bale` |
| توکن | از پلتفرم |
| حالت | `webhook` (پیشنهادی) |
| فعال | بله |

`webhook_secret` پس از ذخیره خودکار ساخته می‌شود.

---

## ۳) ثبت Webhook

### از پنل

صفحه جزئیات ربات → **ثبت Webhook**

### از CLI

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

### فرمت URL

```
{BOT_WEBHOOK_BASE_URL}/webhooks/{platform}/{bot_id}/{webhook_secret}
```

مثال:

```
https://bot.your-domain.com/webhooks/rubika/1/abc123secret...
```

> در پنل ادمین، هشدار **آمادگی Webhook** در بالای صفحات نمایش داده می‌شود اگر URL یا HTTPS مشکل داشته باشد.

---

## ۴) تست اتصال

```bash
php artisan bots:test --bot=1 --chat=CHAT_ID
```

پس از ارسال پیام به ربات، فیلد **آخرین دریافت وب‌هوک** در پنل باید به‌روز شود.

---

## ۵) دکمه‌ها و کیبورد

### Seed اولیه

```bash
php artisan db:seed --class=BotButtonSeeder
php artisan db:seed --class=BotKeyboardLayoutSeeder
```

### استقرار کیبورد

1. `/admin/bot-keyboard-layouts` — ساخت/ویرایش layout
2. `/admin/bot-keyboard-deployments` — Deploy برای ربات

> کیبورد فقط به `ChannelIdentity`های موجود ارسال می‌شود. کاربر باید حداقل یک‌بار به ربات پیام داده باشد.

---

## ۶) گروه، مچینگ و نوتیفیکیشن

1. **گروه یکپارچه** — `/admin/unified-groups`
2. **چت پلتفرم** — `/admin/platform-chats` (اتصال به گروه)
3. **هویت کانال** — `/admin/channel-identities` (نگاشت کاربر ↔ chat_id)

وقتی کد فنی در گروه watch‌شده ارسال شود → `MatchLog` + نوتیفیکیشن.

---

## ۷) OTP و پنل کاربر

### تنظیم ارسال OTP

`/admin/settings/otp` — ربات و پلتفرم پیش‌فرض هر کانال

### فلو کاربر

1. کاربر در ربات `/start` و ثبت موبایل
2. `ChannelIdentity` فعال ساخته می‌شود
3. ورود وب از `/` با OTP
4. دسترسی به `/panel`:
   - کدها، فایل‌ها، export، AI، پروفایل

```env
OTP_LOCAL_FAKE_DELIVERY=false   # production
OTP_LOCAL_EXPOSE_CODE=false     # production
```

---

## ۸) هوش مصنوعی (اختیاری)

```env
AI_ENABLED=true
```

1. Provider در `/admin/ai-providers` (فقط super_admin)
2. Bind به ربات / گروه / کاربر
3. صف `ai` باید فعال باشد

---

## ۹) مانیتورینگ و عملیات

| بخش | مسیر | کاربرد |
|-----|------|--------|
| داشبورد | `/admin` | آمار + هشدار webhook |
| جستجو | `/admin/search` | کاربر، کد، ربات، گروه |
| لاگ مچ | `/admin/match-logs` | فیلتر بر اساس پلتفرم/وضعیت |
| پایش جاب | `/admin/jobs` | failed jobs + retry |
| لاگ ممیزی | `/admin/audit-logs` | عملیات ادمین |
| اجرای دستی | `/admin/manual-runs` | reprocess / retry |

---

## ۱۰) حالت Polling (جایگزین webhook)

```env
BOT_POLLING_ENABLED=true
```

ربات با `mode=polling` بسازید. Scheduler هر دقیقه `bots:poll` اجرا می‌کند.

```bash
php artisan bots:poll --bot=1
```

---

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

- [ ] `system:doctor` → PASS
- [ ] ۶ worker Supervisor + scheduler
- [ ] `BOT_WEBHOOK_BASE_URL` = HTTPS عمومی
- [ ] webhook ثبت شده (`bots:webhook-info`)
- [ ] پیام تست → `last_webhook_received_at` به‌روز
- [ ] کیبورد deploy شده
- [ ] OTP Delivery تنظیم + تست ورود `/`
- [ ] تست آپلود + export + مچینگ
- [ ] `OTP_LOCAL_FAKE_DELIVERY=false`

---

## Commandهای مفید

```bash
php artisan bots:setup-webhook --bot=ID
php artisan bots:delete-webhook --bot=ID
php artisan bots:webhook-info --bot=ID
php artisan bots:test --bot=ID --chat=CHAT_ID
php artisan bots:refresh-keyboards
php artisan bots:health-check
php artisan bots:retry-failed-jobs
php artisan system:doctor
```