# راهنمای نصب قدم‌به‌قدم روی cPanel (فارسی)

این راهنما فرض می‌کند شما یک هاست اشتراکی با پنل cPanel دارید و
دسترسی SSH لازم نیست (همه‌ی مراحل از طریق پنل وب قابل انجام است،
هرچند اگر SSH دارید سریع‌تر است).

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

قبل از شروع، مطمئن شوید هاست شما موارد زیر را دارد:

- **PHP نسخه 8.1 یا بالاتر** (ترجیحاً 8.2+)
- اکستنشن‌های PHP فعال: `pdo_mysql`، `json`، `mbstring`، `curl`، `openssl`
- یک دیتابیس **MySQL یا MariaDB**
- گواهی **SSL/HTTPS** فعال روی دامنه (تلگرام برای وبهوک فقط HTTPS معتبر می‌پذیرد)

برای بررسی نسخه PHP: در cPanel به بخش **«Select PHP Version»** یا
**«MultiPHP Manager»** بروید و نسخه و اکستنشن‌های لازم را فعال کنید.

## ۲. ساخت ساب‌دامین یا پوشه addon

اگر می‌خواهید ربات را روی یک ساب‌دامین (مثلاً `bot.example.com`) یا
دامنه addon جداگانه اجرا کنید:

1. در cPanel به **«Subdomains»** یا **«Addon Domains»** بروید.
2. یک ساب‌دامین جدید بسازید (مثلاً `bot`).
3. یادداشت کنید که cPanel چه پوشه‌ای برای آن ساخته (مثلاً `bot.example.com`).

اگر می‌خواهید روی همان دامنه اصلی (بدون ساب‌دامین) اجرا شود، پوشه
`public_html` را مستقیم استفاده کنید.

## ۳. ساخت دیتابیس MySQL و کاربر

1. در cPanel به **«MySQL Databases»** بروید.
2. یک دیتابیس جدید بسازید (مثلاً `youruser_tfb`).
3. یک کاربر دیتابیس جدید بسازید با رمز عبور قوی (مثلاً `youruser_tfbbot`).
4. کاربر را به دیتابیس اضافه کنید و در بخش **«Privileges»** گزینه
   **«ALL PRIVILEGES»** را انتخاب کنید.
5. نام کامل دیتابیس، کاربر، و رمز عبور را یادداشت کنید — در مرحله
   نصب لازم خواهید داشت (توجه: cPanel معمولاً یک پیشوند مثل
   `youruser_` جلوی نام دیتابیس/کاربر اضافه می‌کند).

## ۴. آپلود فایل‌ها و استخراج ZIP

1. فایل zip پروژه (مثلاً `tfb-engine-mvp-v1.3.0.zip`) را دانلود کنید.
2. در cPanel به **«File Manager»** بروید و به پوشه‌ای که برای
   ساب‌دامین/دامنه ساخته‌اید بروید (یا `public_html` اگر روی دامنه
   اصلی هستید).
3. فایل zip را آپلود کنید (دکمه **«Upload»**).
4. روی فایل آپلودشده راست‌کلیک کرده و **«Extract»** را بزنید.
5. بعد از استخراج، محتوای پوشه باید شامل `public/`، `src/`، `config/`،
   `storage/`، `bin/`، `templates/`، `bootstrap/` و `docs/` باشد.

## ۵. تنظیم DocumentRoot روی پوشه public/

**این مرحله بسیار مهم است** — اگر انجام نشود، فایل‌های حساس پروژه
(کد منبع، کانفیگ) ممکن است در معرض دید قرار بگیرند.

### روش ۱ (توصیه‌شده): تغییر Document Root در تنظیمات ساب‌دامین

اگر از یک ساب‌دامین/Addon Domain استفاده می‌کنید:
1. در cPanel به **«Subdomains»** یا **«Addon Domains»** بروید.
2. مسیر Document Root آن را ویرایش کنید و به زیرپوشه `public` اشاره
   دهید (مثلاً از `bot.example.com` به `bot.example.com/public`).

### روش ۲ (اگر روش ۱ ممکن نبود): جابه‌جایی فایل‌ها

اگر امکان تغییر Document Root وجود ندارد (بعضی هاست‌های ارزان‌تر این
گزینه را نمی‌دهند)، این جایگزین امن است:
1. تمام پوشه پروژه (`src`, `config`, `storage`, ...) را **بالاتر از**
   `public_html` منتقل کنید (مثلاً به یک پوشه هم‌سطح مثل
   `tfb_engine_core/`، خارج از دسترس مستقیم وب).
2. فقط محتوای پوشه `public/` (یعنی `index.php`, `install.php`,
   `.htaccess`) را داخل `public_html` کپی کنید.
3. در `index.php` و `install.php`، خط زیر را پیدا کنید:
   ```php
   $app = require dirname(__DIR__) . '/bootstrap/app.php';
   ```
   و مسیر را به محل جدید `bootstrap/app.php` اصلاح کنید.

اگر مطمئن نیستید کدام روش برای هاست شما کار می‌کند، با پشتیبانی هاست
تماس بگیرید و بپرسید: «چطور Document Root یک ساب‌دامین را به یک
زیرپوشه‌ی خاص تغییر دهم؟»

### راه تشخیص اینکه درست تنظیم شده یا نه

بعد از تنظیم، آدرس اصلی سایت را در مرورگر باز کنید (مثلاً
`https://bot.example.com/`). باید یک پاسخ JSON شبیه این ببینید (نه
لیست فایل‌ها، نه صفحه خطا):
```json
{"ok":true,"service":"TFB Engine","phase":7,"installed":false,"php":"8.2.x"}
```

⚠️ **یک تست امنیتی مهم دیگر** (این محافظت به تنظیمات Apache هاست
شما بستگی دارد، نه فقط کد پروژه): آدرس
`https://bot.example.com/config/app.php` را هم امتحان کنید — باید
خطای «۴۰۳ Forbidden» یا مشابه ببینید، **نه** محتوای فایل کانفیگ
(که شامل توکن ربات و رمز دیتابیس است). اگر محتوای فایل را دیدید یا
کد PHP خام نمایش داده شد:
1. مطمئن شوید ماژول `mod_rewrite` آپاچی روی هاست فعال است.
2. مطمئن شوید تنظیم `AllowOverride All` (یا حداقل `AllowOverride
   FileInfo Limit`) برای پوشه پروژه در تنظیمات Apache هاست فعال است
   — بدون این، فایل‌های `.htaccess` پروژه (که این محافظت را انجام
   می‌دهند) اصلاً خوانده نمی‌شوند. اکثر هاست‌های cPanel این را
   به‌صورت پیش‌فرض فعال دارند، ولی بعضی هاست‌های محدودتر ممکن است
   نداشته باشند — در این صورت با پشتیبانی هاست تماس بگیرید.

## ۶. تنظیم مجوز پوشه‌ها (Permissions)

از **File Manager** یا از طریق FTP، مطمئن شوید پوشه‌های زیر توسط
وب‌سرور قابل نوشتن هستند (معمولاً مجوز `755` یا `775` کافی است، بسته
به تنظیمات هاست):

- `storage/`
- `storage/logs/`
- `storage/cache/`
- `storage/backup/`
- `config/`

نصاب (installer) در همان قدم اول (پیش‌نیازها) این مجوزها را بررسی
می‌کند و اگر مشکلی باشد با علامت ❌ نشان می‌دهد.

## ۷. ساخت ربات در BotFather و گرفتن Token

1. در تلگرام، به [@BotFather](https://t.me/BotFather) پیام بدهید.
2. دستور `/newbot` را بفرستید.
3. یک نام نمایشی برای ربات انتخاب کنید (مثلاً «آزمون کنکور من»).
4. یک نام کاربری منحصربه‌فرد انتخاب کنید که به `bot` ختم شود (مثلاً
   `my_konkur_test_bot`).
5. BotFather یک **توکن** به شما می‌دهد، شبیه:
   `123456789:AAExxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`
   این را کپی و در جایی امن نگه دارید — در مرحله نصب لازم دارید.

## ۸. گرفتن شناسه عددی ادمین

برای اینکه ربات شما را به‌عنوان ادمین بشناسد، به شناسه عددی
تلگرامتان (نه نام کاربری) نیاز دارید:

- **روش ۱:** بعد از نصب و بالا آمدن ربات، در تلگرام به آن پیام
  `/myid` بدهید — عدد را برمی‌گرداند (اما توجه: تا قبل از نصب، ربات
  پاسخ نمی‌دهد — پس این روش فقط برای گرفتن آیدی ادمین‌های اضافه‌تر
  بعد از نصب اول مناسب است).
- **روش ۲ (پیشنهادی، قبل از نصب):** به ربات
  [@userinfobot](https://t.me/userinfobot) پیام بدهید — بلافاصله
  شناسه عددی شما را نمایش می‌دهد.

## ۹. ساخت کانال اصلی و کانال خصوصی فایل‌ها

دو کانال تلگرام لازم دارید:

1. **کانال اصلی**: کانالی که می‌خواهید کاربران بعد از تکمیل آزمون
   عضو آن شوند (اختیاری، اگر «الزام عضویت» را فعال کنید کاربردی
   می‌شود).
2. **کانال خصوصی فایل‌ها**: یک کانال **خصوصی** که فقط ربات از آن
   برای نگهداری فایل‌های صوتی/سند نتایج استفاده می‌کند (کاربران هرگز
   مستقیم وارد این کانال نمی‌شوند).

هر دو کانال را در تلگرام بسازید (از منوی «New Channel»).

## ۱۰. ادمین کردن ربات در هر دو کانال

1. وارد هر کانال شوید → **Administrators** → **Add Admin**.
2. نام کاربری ربات خود را جستجو و اضافه کنید.
3. حتماً دسترسی **«Post Messages»** (ارسال پیام) را برای ربات فعال
   نگه دارید — بدون این، آپلود فایل/ویس نتایج و بررسی عضویت کار
   نمی‌کند.

## ۱۱. گرفتن شناسه عددی کانال‌ها

شناسه عددی کانال‌های تلگرام معمولاً با `-100` شروع می‌شود (یک عدد
منفی طولانی). ساده‌ترین روش:

1. یک پیام هرکدام از کانال‌ها را به ربات
   [@userinfobot](https://t.me/userinfobot) یا
   [@JsonDumpBot](https://t.me/JsonDumpBot) فوروارد کنید.
2. آن ربات شناسه عددی کانال مبدأ را نمایش می‌دهد (فیلد `chat.id`).

اگر کانال فقط برای ادمین‌ها قابل مشاهده است (خصوصی)، از یک اکانت که
عضو کانال است این کار را انجام دهید.

## ۱۲. باز کردن install.php روی HTTPS

آدرس زیر را در مرورگر باز کنید (با دامنه/ساب‌دامین واقعی خودتان):

```
https://bot.example.com/install.php
```

نصاب به‌صورت خودکار پیش‌نیازها را بررسی می‌کند. اگر هر مورد با ❌
مشخص شده، قبل از ادامه آن را برطرف کنید (نسخه PHP، اکستنشن‌ها،
مجوزهای پوشه، یا نبود HTTPS).

## ۱۳. پر کردن فرم‌ها

نصاب در چند مرحله اطلاعات زیر را از شما می‌پرسد:

| فیلد | مقدار |
|---|---|
| توکن ربات | همان مقداری که از BotFather گرفتید |
| نام کاربری ربات | بدون یا با `@` |
| شناسه عددی ادمین | حداقل یک نفر؛ می‌توانید بعداً هم اضافه کنید (با ویرایش دستی `config/app.php`) |
| کانال اصلی (شناسه + نام کاربری) | از مرحله ۱۱ |
| کانال فایل‌ها (شناسه + نام کاربری) | از مرحله ۱۱ |
| هاست/پورت/نام/کاربر/رمز دیتابیس | از مرحله ۳ |
| آدرس عمومی سایت (Public Base URL) | نصاب معمولاً این را خودکار حدس می‌زند؛ اگر اشتباه بود دستی اصلاح کنید |
| منطقه زمانی | پیش‌فرض `Asia/Tehran` |
| Threshold پیش‌فرض | یک عدد صحیح (مثلاً 5)، بعداً هم قابل تغییر از پنل ادمین است |
| سطح لاگ | `warning` برای production توصیه می‌شود |
| Debug | **خاموش** بگذارید (فقط برای توسعه/عیب‌یابی موقت روشن کنید) |

در صفحه «تأیید نهایی»، تمام مقادیر (با ماسک‌شدن رمزها) نمایش داده
می‌شود. اگر جداول قبلی در دیتابیس پیدا شود، باید صراحتاً تیک
«پاک‌سازی» را بزنید تا نصب ادامه یابد (این محافظت از داده‌های موجود
است).

## ۱۴. پایان نصب و قفل شدن

بعد از زدن «شروع نصب»:
- تمام جدول‌های دیتابیس ساخته می‌شوند.
- تنظیمات پیش‌فرض فارسی و کاربر ادمین ثبت می‌شوند.
- فایل `config/app.php` نوشته می‌شود (شامل یک رمز وبهوک تصادفی).
- ربات سعی می‌کند خودش را در Telegram به‌عنوان وبهوک ثبت کند.
- فایل `storage/install.lock` ساخته می‌شود — از این لحظه، اجرای
  دوباره `install.php` **مسدود** است (برای جلوگیری از پاک شدن
  ناخواسته اطلاعات).

اگر ثبت وبهوک ناموفق بود (مثلاً به دلیل مشکل شبکه موقت)، نصب همچنان
با موفقیت کامل می‌شود و یک دکمه **«تلاش مجدد برای ثبت وبهوک»** در
همان صفحه نمایش داده می‌شود — بدون نیاز به نصب دوباره.

## ۱۵. تست /start و /admin

1. در تلگرام، ربات خودتان را پیدا کنید و `/start` بفرستید.
2. باید یک پاسخ متنی دریافت کنید (چون هنوز آزمونی نساخته‌اید، پیام
   پیش‌فرض «آزمون فعالی وجود ندارد» را می‌بینید — طبیعی است).
3. با همان اکانتی که شناسه‌اش را به‌عنوان ادمین وارد کردید، `/admin`
   بفرستید — باید منوی کامل پنل ادمین (📊 داشبورد، 🧪 آزمون‌ها، ...)
   را ببینید.

اگر هیچ پاسخی نگرفتید، به بخش «مشکلات رایج» در پایین همین سند یا
فایل `docs/TROUBLESHOOTING_FA.md` مراجعه کنید.

## ۱۶. ساخت اولین آزمون

از پنل ادمین (`/admin`):
1. 🧪 آزمون‌ها → ➕ آزمون جدید → فقط یک عنوان بفرستید.
2. 👤 پروفایل‌ها → حداقل یک پروفایل با عنوان فارسی بسازید.
3. ❓ سوالات → حداقل یک سوال بسازید.
4. 🔘 گزینه‌ها → برای آن سوال حداقل ۲ گزینه بسازید.
5. برای هر گزینه، 🎯 امتیازدهی پروفایل‌ها را باز کنید و با +/- امتیاز
   بدهید، سپس ✅ ثبت را بزنید.
6. 🏁 نتایج → برای هر پروفایل حداقل یک متن تحلیل یا فایل/ویس اضافه
   کنید.
7. برگردید به صفحه مدیریت آزمون و «✅ فعال‌سازی» را بزنید — اگر
   چیزی ناقص باشد، دلایل دقیق فارسی نمایش داده می‌شود.
8. لینک اختصاصی آزمون (`https://t.me/your_bot?start=t_...`) را کپی
   کنید.

راهنمای کامل‌تر ساخت آزمون در `docs/ADMIN_GUIDE.md` است.

## ۱۷. تست با اکانت غیر ادمین

قبل از تبلیغ لینک، حتماً با یک اکانت تلگرام دیگر (که ادمین نیست)
لینک آزمون را باز کنید و کل مسیر (سوالات → نتیجه → CTA → عضویت
کانال در صورت فعال بودن) را تا انتها امتحان کنید.

## ۱۸. مشکلات رایج و راه‌حل

| مشکل | راه‌حل احتمالی |
|---|---|
| صفحه اصلی سایت لیست فایل‌ها یا کد PHP خام را نشان می‌دهد | Document Root درست تنظیم نشده — به بخش ۵ برگردید |
| `/start` هیچ پاسخی نمی‌دهد | وبهوک ثبت نشده؛ از پنل هاست بررسی کنید که خروجی (outbound) اینترنت باز است؛ از صفحه نتیجه نصب دکمه «تلاش مجدد وبهوک» را بزنید |
| نصب با «اتصال به دیتابیس برقرار نشد» متوقف می‌شود | اطلاعات دیتابیس (خصوصاً پیشوند نام کاربری cPanel) را دوباره بررسی کنید |
| آپلود فایل/ویس نتیجه کار نمی‌کند | مطمئن شوید ربات هنوز ادمین کانال فایل‌ها است (از `/admin` → 🩺 سلامت سیستم بررسی کنید) |
| بعد از مدتی ربات کند شده یا پاسخ نمی‌دهد | فایل‌های `storage/logs/problems-*.log` و `error-*.log` را بررسی کنید (یا از پنل ادمین → 📋 لاگ‌ها استفاده کنید) — جزئیات کامل در `docs/TROUBLESHOOTING_FA.md` |

برای فهرست کامل‌تر مشکلات، `docs/TROUBLESHOOTING_FA.md` را ببینید.

## ۱۹. نکات امنیتی نهایی (بعد از نصب موفق)

- فایل `public/install.php` را حذف کنید یا نام آن را تغییر دهید
  (مثلاً به `install.php.disabled`) — دیگر لازم نیست و روی هاست
  باقی ماندنش یک ریسک غیرضروری است (هرچند خودش بعد از نصب اول قفل
  می‌شود، حذف کامل امن‌تر است).
- `app.debug` را در `config/app.php` روی `false` نگه دارید.
- سطح لاگ (`log_level`) را روی `warning` یا `info` نگه دارید، نه
  `debug`، مگر برای عیب‌یابی موقت.
- به‌صورت دوره‌ای از پنل ادمین → 🗜 پشتیبان‌گیری یک بکاپ تازه بگیرید
  (فایل مستقیم در همان چت تلگرام برایتان ارسال می‌شود).