# راهنمای رفع مشکلات رایج (Troubleshooting)

این سند برای وقتی است که چیزی طبق انتظار کار نمی‌کند. برای هر مشکل،
اول علائم را پیدا کنید، بعد راه‌حل پیشنهادی را امتحان کنید.

> 💡 **قانون طلایی:** برای هر مشکلی، اول فایل
> `storage/logs/problems-امروز-تاریخ.log` را چک کنید (یا از پنل
> ادمین → 📋 لاگ‌ها → «ارسال فایل مشکلات امروز»). این فایل معمولاً
> مستقیم می‌گوید مشکل کجاست و چطور رفع شود. جزئیات کامل در
> `docs/LOGGING_AND_DIAGNOSTICS_FA.md`.

## ۱. ربات اصلاً به `/start` پاسخ نمی‌دهد

**علائم:** پیام می‌فرستید، هیچ پاسخی نمی‌آید.

**بررسی کنید:**
1. آیا نصب واقعاً کامل شده؟ (`storage/install.lock` باید وجود داشته
   باشد.)
2. از `/admin` → 🩺 سلامت سیستم بررسی کنید: ردیف «وضعیت وبهوک» چه
   می‌گوید؟
   - اگر «وبهوک ثبت نشده» → دوباره `install.php` را باز کنید (اگر
     قفل شده، `storage/install.lock` و `storage/install.partial.lock`
     را بررسی کنید) یا مسیر بازنصب دستی زیر را دنبال کنید.
   - اگر خطای خاصی نشان می‌دهد (`last_error_message`)، همان پیام
     تلگرام دقیقاً می‌گوید مشکل چیست (معمولاً یعنی سرور شما در
     دسترس نیست یا SSL نامعتبر است).
3. مطمئن شوید Document Root واقعاً روی `public/` تنظیم شده — آدرس
   اصلی سایت را باز کنید، باید یک پاسخ JSON با `"ok":true` ببینید،
   نه لیست فایل یا صفحه ۴۰۴.
4. `storage/logs/error-امروز.log` را بررسی کنید — اگر یک استثنای
   PHP رخ داده، آنجا با فایل/خط دقیق ثبت شده.

## ۲. نصب با خطای «اتصال به دیتابیس برقرار نشد» متوقف می‌شود

- نام هاست/پورت/نام‌دیتابیس/کاربر/رمز را دوباره از پنل هاست کپی
  کنید (روی هاست‌های cPanel معمولاً یک پیشوند مثل `username_` جلوی
  نام دیتابیس و کاربر اضافه می‌شود — این را فراموش نکنید).
- مطمئن شوید کاربر دیتابیس روی دیتابیس مربوطه دسترسی «ALL
  PRIVILEGES» دارد.
- اگر هاست شما اتصال از `127.0.0.1` را نمی‌پذیرد، مقدار `db_host`
  را طبق راهنمای هاست خودتان (گاهی `localhost` به‌جای IP) تنظیم
  کنید.

## ۳. آپلود ویس/فایل نتیجه کار نمی‌کند

**علائم:** وقتی ادمین می‌خواهد ویس/فایل به یک نتیجه اضافه کند، پیام
خطای «ربات باید ادمین کانال فایل‌ها باشد» می‌بیند.

**راه‌حل:**
1. مطمئن شوید یک «کانال خصوصی فایل‌ها» واقعاً در نصب مشخص شده
   (`channels.files.id` در `config/app.php` نباید خالی/صفر باشد).
2. وارد آن کانال شوید → Administrators → مطمئن شوید ربات هنوز آنجا
   ادمین است **و** دسترسی «Post Messages» را دارد (بعضی وقت‌ها یک
   ادمین دیگر این دسترسی را خاموش می‌کند).
3. از `/admin` → 🩺 سلامت سیستم، ردیف «کانال فایل‌ها» را چک کنید —
   دقیقاً می‌گوید مشکل کجاست.

## ۴. عضویت کانال درست تشخیص داده نمی‌شود

**علائم:** کاربر عضو کانال است ولی ربات می‌گوید «هنوز عضو نیستی».

- مطمئن شوید `channels.main.id` درست است (شناسه عددی، نه نام
  کاربری).
- مطمئن شوید ربات در آن کانال حداقل عضو عادی است (بهتر است ادمین
  باشد) — بدون این، `getChatMember` تلگرام برای ربات جواب نمی‌دهد.
- اگر تنظیم `soft_join_fail_open` روشن باشد و تلگرام موقتاً در
  دسترس نباشد، کاربر رد می‌شود مگر این حالت خاص باشد؛ در
  `storage/logs/problems-*.log` دنبال کد `E_TG_API` با متد
  `getChatMember` بگردید.

## ۵. پنل ادمین باز نمی‌شود / «دسترسی ندارید» می‌بینم

- شناسه عددی خودتان را با [@userinfobot](https://t.me/userinfobot)
  دوباره چک کنید (نه نام کاربری، عدد).
- مطمئن شوید همان عدد دقیقاً در `config/app.php` زیر
  `admins.ids` وجود دارد (آرایه، می‌تواند چند ادمین داشته باشد).
- بعد از ویرایش دستی `config/app.php`، نیازی به ری‌استارت چیزی
  نیست — تغییرات فوراً روی درخواست بعدی اعمال می‌شود.

## ۶. یک آزمون فعال نمی‌شود

از صفحه مدیریت آن آزمون، بخش «🚫 موانع فعال‌سازی» را بخوانید — همیشه
دلیل دقیق فارسی نشان داده می‌شود:

| پیام | راه‌حل |
|---|---|
| «هیچ پروفایلی تعریف نشده» | حداقل یک پروفایل اضافه کنید |
| «هیچ سوال فعالی وجود ندارد» | حداقل یک سوال اضافه کنید |
| «کمتر از ۲ گزینه دارد» | برای آن سوال گزینه اضافه کنید |
| «به سوال نامعتبر یا حذف‌شده پرش می‌کند» | مسیر (branch) آن گزینه را دوباره تنظیم کنید |
| «هیچ‌کدام از نتایج محتوایی ندارند» | حداقل به یک نتیجه متن/ویس/فایل اضافه کنید |
| «برای حالت دو‌نتیجه نزدیک باید آستانه تنظیم شود» | یک عدد صحیح غیرمنفی برای Threshold بگذارید |

## ۷. بکاپ ساخته نمی‌شود یا فایل در تلگرام دریافت نمی‌شود

- مطمئن شوید پوشه `storage/backup/` توسط وب‌سرور قابل نوشتن است
  (مجوز فایل).
- اگر فایل ساخته می‌شود ولی در تلگرام دریافت نمی‌کنید، احتمالاً
  حجم بکاپ از سقف مجاز تلگرام (۵۰ مگابایت) بیشتر است — فایل همچنان
  روی سرور در `storage/backup/` باقی می‌ماند، فقط ارسال مستقیم در
  چت انجام نمی‌شود.

## ۸. بازیابی (Restore) با خطا متوقف می‌شود

- پیام خطا را کامل بخوانید — معمولاً یعنی فایل بکاپ خراب/ناقص است
  یا از یک نسخه خیلی قدیمی/متفاوت است.
- مطمئن شوید فایلی که آپلود می‌کنید واقعاً یک بکاپ ساخته‌شده توسط
  همین ربات است (پسوند `.sql` و شروع‌شده با مارکر داخلی پروژه —
  فایل‌های SQL دیگر رد می‌شوند).
- اگر بازیابی نیمه‌کاره متوقف شد، دوباره یک بکاپ تازه از وضعیت فعلی
  بگیرید و با پشتیبانی فنی تماس بگیرید (جزئیات دقیق در
  `storage/logs/problems-*.log` با کد `E_DB_QUERY` یا مشابه ثبت
  شده).

## ۹. ربات کند شده یا گاهی جواب نمی‌دهد

1. از `/admin` → 🩺 سلامت سیستم، بخش «قابل نوشتن بودن logs/cache/backup»
   را چک کنید.
2. `storage/logs/app-امروز.log` را برای خطوط `WARNING Slow query
   detected` بگردید — اگر زیاد است، شاید دیتابیس هاست شما زیر فشار
   است.
3. مطمئن شوید سطح لاگ (`log_level`) روی `debug` نمانده — این حالت
   حجم زیادی لاگ تولید می‌کند و کمی سربار اضافه می‌کند.
4. تعداد کاربران/آزمون‌های همزمان را با ظرفیت هاست اشتراکی خودتان
   مقایسه کنید — هاست‌های اشتراکی ارزان معمولاً محدودیت CPU/تعداد
   پردازش همزمان دارند؛ این محدودیت هاست است، نه لزوماً باگ ربات.

## ۱۰. چطور یک بار دیگر کامل نصب کنم (ریست کامل)؟

⚠️ **این کار همه داده‌های فعلی را برای همیشه پاک می‌کند.** فقط اگر
مطمئنید انجام دهید (و ترجیحاً یک بکاپ قبلی داشته باشید):

1. فایل `storage/install.lock` را حذف کنید.
2. فایل `storage/install.partial.lock` را هم اگر وجود دارد حذف
   کنید.
3. فایل `config/app.php` را حذف کنید (یا جای دیگری منتقل کنید).
4. دوباره `install.php` را باز کنید — این‌بار اجازه نصب می‌دهد
   (اگر جداول قبلی در دیتابیس باشد، از شما تأیید صریح پاک‌سازی
   می‌خواهد).

## ۱۱. هنوز مشکل حل نشد — چه اطلاعاتی برای پشتیبانی/کدنویس بفرستم؟

1. فایل `storage/logs/problems-امروز-تاریخ.log` (از پنل ادمین →
   📋 لاگ‌ها → ارسال فایل مشکلات امروز، یا مستقیم از File Manager).
2. فایل `storage/logs/error-امروز-تاریخ.log`.
3. توضیح دقیق: چه کاری انجام دادید، چه انتظاری داشتید، چه چیزی به‌جای
   آن دیدید.
4. **هرگز** فایل `config/app.php` را کامل برای کسی نفرستید (حاوی
   توکن ربات و رمز دیتابیس است) — اگر لازم بود مقادیر حساس را قبل
   از ارسال با `***` جایگزین کنید.

این فایل‌ها هرگز از طریق وب/مرورگر قابل دسترسی نیستند، پس همیشه باید
از طریق File Manager هاست یا دستور «ارسال فایل مشکلات» در پنل ادمین
دریافت شوند.