# راهنمای کامل: نصب پچ‌ها (خیلی دقیق) + آموزش استفاده از پنل

این راهنما فرض می‌کنه هیچ‌وقت با File Manager یا phpMyAdmin کار نکردی، پس همه‌چیز رو با جزئیات کامل می‌نویسم.

چیزهایی که باید از قبل دم دستت باشه:
- یوزرنیم و پسورد **cPanel** هاستت (همون که فایل‌های سایتت توش هست)
- سه فایلی که برات ساختم: `persian-ui-patch.zip`، `menu-buttons-feature.zip`، و این راهنما

---

# بخش اول: نصب پچ‌ها

## گام ۱ — ورود به cPanel
1. مرورگر رو باز کن و برو به آدرسی که شرکت هاستینگت بهت داده (معمولاً چیزی شبیه `https://farazpin.com/cpanel` یا `https://farazpin.com:2083`). اگه مطمئن نیستی، توی ایمیلی که موقع خرید هاست برات اومده دنبال کلمه‌ی cPanel بگرد.
2. یوزرنیم و پسورد رو وارد کن و وارد شو.
3. توی صفحه‌ی اصلی cPanel دنبال آیکون **File Manager** بگرد (معمولاً زیر بخش «Files» با یه آیکون پوشه‌ی زرد) و روش کلیک کن.

## گام ۲ — رفتن به پوشه‌ی پروژه
1. توی File Manager، از ستون سمت چپ یا با دابل‌کلیک روی پوشه‌ها این مسیر رو باز کن:
   ```
   public_html → botbuilder
   ```
2. الان باید توی مسیر `/home/farazpin/public_html/botbuilder` باشی — همون‌جایی که پوشه‌های `admin`, `views`, `src`, `config` و... توش هستن. مطمئن شو همین‌جایی.

## گام ۳ — بک‌آپ گرفتن از فایل‌ها (خیلی مهم، رد نکن)
1. توی همون صفحه، از بالای پنجره روی **Settings** (بالا سمت راست File Manager) بزن و مطمئن شو «Show Hidden Files» تیک خورده — بعد Save کن.
2. برگرد توی پوشه‌ی `botbuilder`، همه‌ی فایل‌ها و پوشه‌ها رو انتخاب کن (کلیک روی اولین آیتم، بعد `Ctrl+A` یا از منوی بالا گزینه‌ی **Select All**).
3. از نوار بالا روی **Compress** بزن، نوع فشرده‌سازی رو **Zip Archive** بذار و اسمی مثل `backup-before-patch.zip` بهش بده، بعد **Compress File(s)** رو بزن.
4. یه فایل zip ساخته می‌شه. روش راست‌کلیک کن و **Download** بزن تا روی کامپیوتر خودت هم یه نسخه داشته باشی. (این فایل رو دست نزن، فقط برای اطمینانه.)

## گام ۴ — بک‌آپ گرفتن از دیتابیس
1. برگرد به صفحه‌ی اصلی cPanel (از لینک بالای صفحه یا دکمه‌ی خانه).
2. دنبال آیکون **phpMyAdmin** بگرد (زیر بخش «Databases») و باز کن.
3. از ستون سمت چپ، اسم دیتابیس پروژه رو پیدا کن و روش کلیک کن تا جدول‌هاش باز بشه.
4. از نوار بالای صفحه روی تب **Export** بزن.
5. گزینه‌ی **Quick** انتخاب‌شده باشه، فرمت روی **SQL** باشه، بعد دکمه‌ی **Go** رو بزن — یه فایل `.sql` دانلود می‌شه. اینم نگه‌دار.

اگه از این به بعد چیزی خراب شد، با همین دو فایل (zip فایل‌ها + sql دیتابیس) می‌تونی برگردی به حالت قبل.

## گام ۵ — اجرای دستور SQL روی دیتابیس
1. همون‌جا توی phpMyAdmin که هستی، همون دیتابیس رو (که توی گام قبل انتخاب کرده بودی) از ستون چپ باز نگه‌دار.
2. از نوار بالا این‌بار روی تب **SQL** بزن (نه Export).
3. یه کادر متنی بزرگ باز می‌شه. این خط رو دقیقاً همین‌طوری داخلش کپی کن:
```sql
ALTER TABLE menus ADD COLUMN is_main TINYINT(1) NOT NULL DEFAULT 0 AFTER parent_id;
```
4. دکمه‌ی **Go** (پایین یا گوشه‌ی صفحه) رو بزن.
5. باید پیام سبزرنگ موفقیت ببینی. اگه پیام قرمز خورد و توش نوشته بود «Duplicate column» یعنی این دستور قبلاً اجرا شده — مشکلی نیست، برو مرحله‌ی بعد.

## گام ۶ — نصب فایل‌های فارسی‌سازی پنل (`persian-ui-patch.zip`)
1. توی چت، روی فایل `persian-ui-patch.zip` که برات ساختم بزن و روی گوشی/کامپیوترت دانلودش کن.
2. برگرد به File Manager توی همون مسیر `public_html/botbuilder`.
3. از نوار بالا روی دکمه‌ی **Upload** بزن.
4. توی صفحه‌ای که باز می‌شه، دکمه‌ی **Select File** (یا کادر کشیدن‌وانداختن) رو بزن و فایل `persian-ui-patch.zip` رو از روی گوشی/کامپیوترت انتخاب کن. صبر کن تا نوار آپلود ۱۰۰٪ بشه.
5. برگرد به تب File Manager (یا رفرشش کن). حالا باید فایل `persian-ui-patch.zip` رو کنار پوشه‌های `admin`, `views` و... ببینی.
6. روی `persian-ui-patch.zip` **راست‌کلیک** کن و گزینه‌ی **Extract** رو بزن.
7. یه پنجره باز می‌شه که مسیر استخراج رو نشون می‌ده (باید همون `public_html/botbuilder` باشه). دکمه‌ی **Extract File(s)** رو بزن.
8. اگه سوال کرد «فایل‌های موجود overwrite بشن یا نه»، گزینه‌ی **Overwrite** یا **Yes to All** رو انتخاب کن.
9. بعد از تموم شدن، یه پوشه‌ی جدید به اسم `persian-ui-patch` هم اضافه می‌شه (کنار admin و views) — این فقط باقی‌مونده‌ی استخراجه، خودش تاثیری نداره ولی بهتره پاکش کنی: روش کلیک کن، بعد از نوار بالا **Delete** بزن.
10. فایل zip (`persian-ui-patch.zip`) رو هم می‌تونی همون‌جا پاک کنی (اختیاریه، فقط جا اشغال می‌کنه).

## گام ۷ — نصب قابلیت منو/دکمه (`menu-buttons-feature.zip`)
دقیقاً همون مراحل گام ۶ رو تکرار کن، ولی این‌بار با فایل `menu-buttons-feature.zip`:
1. دانلودش کن.
2. توی File Manager، همون مسیر `public_html/botbuilder`، دکمه‌ی **Upload** → انتخاب فایل → صبر تا تموم بشه.
3. راست‌کلیک روی `menu-buttons-feature.zip` → **Extract** → مسیر همون `botbuilder` باشه → **Extract File(s)**.
4. اگه سوال overwrite کرد → **Yes/Overwrite**.
5. پوشه‌ی باقی‌مونده‌ی `menu-buttons-feature` و خودِ فایل zip رو پاک کن (اختیاری).

⚠️ نکته‌ی مهم: این پچ دوتا فایل رو (`views/management/menus.php` و `views/management/menu_buttons.php`) با نسخه‌ی جدیدتری از پچ گام ۶ overwrite می‌کنه — این طبیعیه و باید همین‌طور بشه، پس حتماً «Yes/Overwrite» رو بزن، **Skip** نزن.

## گام ۸ — پاک‌سازی کش (اگه لازم بود)
1. برگرد به صفحه‌ی اصلی cPanel.
2. دنبال آیکون **Select PHP Version** بگرد (زیر بخش «Software»).
3. اگه واردش شدی و تب یا گزینه‌ای به اسم **Options** یا لیستی از extension ها دیدی، دنبال چیزی به اسم `opcache` بگرد. اگه فعال بود (تیک‌خورده)، یه‌بار تیکش رو بردار و Save کن، صبر کن صفحه لود بشه، دوباره تیک بزن و Save کن. (این کار opcache رو ریست می‌کنه.)
4. اگه اصلاً همچین گزینه‌ای پیدا نکردی، این مرحله رو رد کن — یعنی سایتت این مشکل رو نداره.

## گام ۹ — تست نهایی
1. برو به آدرس پنل مدیریتت توی مرورگر و لاگین کن.
2. مطمئن شو صفحه‌ها فارسی نمایش داده می‌شن (مثلاً `/bots` باید ستون‌هاش «نام»، «نام کاربری»، «وضعیت» باشه، نه انگلیسی).
3. برو `/menus` و طبق «بخش دوم» پایین یه منو با یکی دو تا دکمه بساز.
4. توی تلگرام برو سراغ رباتت و `/start` رو بزن — باید دکمه‌ها رو زیر پیام خوش‌آمد ببینی.
5. اگه هرجا با ارور یا صفحه‌ی سفید مواجه شدی، دقیقاً بنویس کجا بودی و چه ارور/عکسی دیدی، تا بررسی کنم.

---

# بخش دوم: راهنمای کامل استفاده از پنل مدیریت

فرض می‌کنیم از الان به بعد داری با مرورگر وارد پنل شدی (نه cPanel).

## ۱) ساخت اولین ربات — `/bots`
1. از منوی کناری روی **ربات‌ها** بزن.
2. یه فرم می‌بینی: باید یه **توکن ربات تلگرام** بدی. اگه هنوز نساختی:
   - توی تلگرام برو سراغ اکانت **@BotFather**.
   - بهش پیام `/newbot` بده.
   - یه اسم دلخواه برای رباتت بفرست (مثلاً «فروشگاه من»).
   - یه یوزرنیم بفرست که حتماً به `bot` ختم بشه (مثلاً `MyShop_bot`).
   - BotFather یه رشته‌ی طولانی بهت می‌ده شبیه `123456789:AAExxxxxxxxxxxxxxxxxxxxxx` — این توکنته.
3. این توکن رو توی فرم پنل کپی کن و دکمه‌ی ساخت رو بزن.
4. بعد از ساخته‌شدن، ربات توی جدول ظاهر می‌شه. کنارش چندتا دکمه هست:
   - **وبهوک**: بزن تا تلگرام بدونه آپدیت‌ها (پیام‌ها) رو کجا بفرسته. **این کار رو حتماً انجام بده وگرنه ربات هیچ پیامی دریافت نمی‌کنه.**
   - **حذف وبهوک**: برای وقتی موقتاً می‌خوای ربات خاموش باشه.
   - **فعال/غیرفعال**: روشن‌وخاموش کردن ربات بدون حذفش.
   - **شبیه‌سازی**: یه کپی از تنظیمات همین ربات می‌سازه (بدون توکن، باید توکن جدید بدی).

## ۲) ساخت منو و دکمه — `/menus`
1. از منوی کناری روی **منو / سازنده دکمه** بزن.
2. توی فرم بالا:
   - **نام منو**: مثلاً بنویس `منوی اصلی`.
   - **ربات**: رباتی که تازه ساختی رو از لیست انتخاب کن.
   - **والد**: چون این اولین منوته، همون «منوی مستقل (بدون والد)» رو نگه‌دار.
   - دکمه‌ی **ساخت منو** رو بزن.
3. این منو خودکار به‌عنوان «منوی اصلی» ثبت می‌شه (یه برچسب سبزرنگ کنارش می‌بینی) — یعنی زیر `/start` نشون داده می‌شه.
4. کنار همین منو، روی **مدیریت دکمه‌ها** بزن.
5. توی فرم «افزودن دکمه»:
   - **متن دکمه**: مثلاً `🛍 محصولات`
   - **ایموجی**: اختیاریه، اگه توی متن دکمه گذاشتی لازم نیست دوباره بنویسی.
   - **نوع دکمه**: یکی از این پنج تا رو انتخاب کن:
     - **کال‌بک (داخل ربات)**: با کلیک، یه ورک‌فلو اجرا می‌شه. توی «مقدار» یه اسم دلخواه بنویس (مثلاً `show_products`) — بعداً باید از بخش «سازنده ورک‌فلو» یه ورک‌فلو با **همین اسم دقیق** بسازی.
     - **لینک (URL)**: توی «مقدار» یه آدرس وب بنویس (مثلاً `https://example.com`)؛ با کلیک کاربر رو اونجا می‌بره.
     - **مینی‌اپ**: باید از قبل توی بخش «مینی‌اپ تلگرام» یه صفحه ساخته باشی؛ لینکش رو اینجا بذار.
     - **زیرمنو**: به‌جای نوشتن مقدار، یه لیست کشویی از منوهای همون ربات ظاهر می‌شه؛ یکی رو انتخاب کن — با کلیک کاربر، اون منو باز می‌شه.
     - **بازگشت**: چیزی لازم نیست بنویسی؛ کاربر رو به منوی قبلی برمی‌گردونه.
   - **ترتیب**: عدد کوچیک‌تر بالاتر قرار می‌گیره (مثلاً ۰، ۱، ۲...).
   - دکمه‌ی **افزودن دکمه** رو بزن.
6. می‌تونی چندتا دکمه‌ی دیگه هم همین‌طوری اضافه کنی. توی تلگرام `/start` بزن تا نتیجه رو ببینی.
7. برای ساخت زیرمنو: از همون فرم بالا (بخش «ساخت منوی جدید»)، یه منوی جدید بساز ولی این‌بار توی «والد» همون منوی اصلی رو انتخاب کن. بعد از یه دکمه توی منوی اصلی، نوعش رو «زیرمنو» بذار و همین منوی تازه‌ساخته رو انتخاب کن.

## ۳) دستورات سفارشی — `/commands`
1. از منوی کناری روی **دستورات** بزن.
2. توی فرم: نام دستور (مثلاً `price` — بدون `/`)، عنوان (توضیح داخلی)، و ربات مربوطه رو انتخاب کن، بعد **افزودن**.
3. این دستور با زدن `/price` توی تلگرام فعال می‌شه، به‌شرطی که از بخش ورک‌فلو یه ورک‌فلو باهاش وصل کرده باشی (این وصل‌کردن معمولاً موقع ساخت ورک‌فلو انجام می‌شه — اگه بخوای دقیق‌تر راهنماییت کنم بگو).

## ۴) سازنده ورک‌فلو — `/workflows`
1. از منوی کناری روی **سازنده ورک‌فلو** بزن.
2. یه ورک‌فلوی جدید با یه **اسم دقیق** بساز (همون اسمی که توی دکمه‌های «کال‌بک» یا دستورات استفاده کردی).
3. داخل ورک‌فلو می‌تونی مراحل پیام/شرط/اکشن بچینی (اگه بخوای مرحله‌به‌مرحله همین بخش رو هم کامل باز کنم بگو، چون خودش بحث مفصلیه).

## ۵) اتوماسیون — `/automations`
1. از منوی کناری روی **سازنده اتوماسیون** بزن.
2. یه نام بده، **محرک** رو انتخاب کن (مثلاً «شروع ربات (/start)» یا «پیام کاربر»).
3. اگه خواستی، یه **شرط** اضافه کن (مثلاً فقط اگه نام‌کاربری برابر فلان بود).
4. یک یا چند **اکشن** اضافه کن: ارسال پیام متنی / افزودن برچسب / شارژ کیف‌پول / ارسال اعلان به خودت / تاخیر و سپس ارسال پیام بعدی.
5. دکمه‌ی **ساخت اتوماسیون** رو بزن.

## ۶) پیام همگانی — `/broadcasts`
1. از منوی کناری روی **پیام همگانی** بزن.
2. متن پیام رو بنویس (یا از یه قالب آماده انتخاب کن).
3. می‌تونی بگی فقط برای کاربرانی که یه **برچسب** خاص دارن بفرسته، یا برای همه.
4. می‌تونی زمان ارسال رو برای آینده تنظیم کنی.
5. ⚠️ برای اینکه پیام واقعاً ارسال بشه، باید یه **Cron Job** روی هاستت فعال باشه که فایل `cron/worker.php` رو هر چند دقیقه اجرا کنه. اگه این کار رو نکرده باشی، پیام‌ها توی صف می‌مونن ولی فرستاده نمی‌شن. (بگو تا این تنظیمات cPanel رو هم قدم‌به‌قدم برات بنویسم.)

## ۷) فرم‌ساز — `/forms`
برای وقتی می‌خوای از کاربر داخل تلگرام اطلاعات بگیری (مثل فرم سفارش). یه فرم با چند فیلد (متن، عدد، انتخابی) بساز و به یه دستور یا دکمه وصلش کن.

## ۸) محصولات و دسته‌بندی — `/products`, `/categories`
1. اول از `/categories` یکی‌دو تا دسته بساز (مثلاً «پوشاک»، «لوازم دیجیتال»).
2. بعد از `/products` محصول بساز: نام، نوع (دیجیتال/فیزیکی/دانلودی/اشتراکی)، قیمت، و دسته‌بندیش رو مشخص کن.

## ۹) سفارش‌ها — `/orders`
- سفارش‌های ثبت‌شده (چه از تلگرام چه دستی از پنل) اینجا لیست می‌شن.
- برای پرداخت کارت‌به‌کارت، کاربر کد پیگیری رو وارد می‌کنه و وضعیت «در انتظار» می‌مونه تا از پنل سوپر ادمین تاییدش کنی (بخش پایین توضیح داده شده).

## ۱۰) کوپن تخفیف — `/coupons`
یه کد بساز (مثلاً `OFF20`)، نوعش رو درصدی یا مبلغ ثابت بذار، مقدار تخفیف و در صورت نیاز حداکثر تعداد استفاده/تاریخ انقضا رو مشخص کن.

## ۱۱) تیکت پشتیبانی — `/tickets`
- کاربر با نوشتن `/ticket موضوع من` توی ربات، یه تیکت باز می‌کنه.
- تو از این صفحه لیست تیکت‌ها رو می‌بینی، وارد هرکدوم می‌شی، پاسخ می‌دی، و وضعیتش رو (باز/در انتظار/بسته) تغییر می‌دی.
- دکمه‌ی «پیشنهاد پاسخ با هوش مصنوعی» فقط اگه از بخش ۱۵ یه AI Provider وصل کرده باشی کار می‌کنه.

## ۱۲) کیف‌پول کاربران
1. از `/users` وارد پروفایل یه کاربر بشو (روی «مدیریت» کنار اسمش بزن).
2. لینک «مشاهده کیف‌پول» رو بزن.
3. از اونجا می‌تونی دستی شارژش کنی، تاریخچه‌ی تراکنش‌ها رو ببینی، و درخواست‌های برداشتی که کاربر ثبت کرده رو تایید کنی.

## ۱۳) مدیریت کاربران ربات — `/users`
لیست همه‌ی کسایی که وارد ربات شدن. از پروفایل هرکدوم می‌تونی: مسدود/رفع مسدودیت کنی، براش برچسب بذاری، یادداشت داخلی ثبت کنی، اشتراک فعال کنی، یا کیف‌پولش رو ببینی.

## ۱۴) تحلیل و آمار — `/analytics`
نمودارهای رشد کاربران، فروش روزانه، آمار زیرمجموعه‌گیری، و حجم پیام‌ها رو نشون می‌ده — فقط برای دیدن، نیازی به تنظیم نداره.

## ۱۵) تنظیمات هوش مصنوعی — `/ai-settings`
1. یه **ارائه‌دهنده** انتخاب کن (باید سرویسی سازگار با فرمت OpenAI باشه).
2. **کلید API** همون سرویس رو وارد کن.
3. اگه خواستی چت‌بات هوشمند فعال باشه (به پیام‌های بدون دستور خودکار جواب بده)، تیک «فعال‌سازی چت‌بات هوش مصنوعی» رو بزن.
4. توی «پرامپت سیستمی» می‌تونی شخصیت/لحن ربات رو توصیف کنی (مثلاً «تو دستیار فروشگاه لباس هستی، مودب و کوتاه جواب بده»).
5. از بخش «دانش پایه» می‌تونی اطلاعاتی (مثل قوانین فروشگاه، پرسش‌های متداول) اضافه کنی تا هوش مصنوعی موقع جواب دادن ازش استفاده کنه.

## ۱۶) کلید API — `/api-keys`
فقط اگه بخوای از یه برنامه‌ی بیرونی (نه تلگرام) به داده‌های پنل دسترسی داشته باشی؛ برای شروع لازم نیست بهش دست بزنی.

## ۱۷) مینی‌اپ تلگرام — `/miniapp`
یه صفحه‌ی وب (HTML) بساز که داخل تلگرام باز می‌شه؛ بعداً لینکش رو توی «سازنده دکمه» با نوع «مینی‌اپ» وصل کن.

## ۱۸) سیستم قالب‌ها — `/templates`
متن‌های پرکاربرد رو از قبل ذخیره کن (متنی / عکس+کپشن / فایل) تا موقع ساخت «پیام همگانی» سریع انتخابشون کنی.

---

# پنل سوپر ادمین — `/admin` (فقط برای خودت، مالک کل سیستم)

آدرس این بخش با پنل کاربری فرق داره؛ باید با `/admin` وارد بشی و با اکانت سوپرادمین لاگین کنی (نه اکانت مشتری عادی).

- **مشتریان**: لیست همه‌ی کسایی که از طریق ربات مرکزی برای خودشون یه اکانت/ربات ساختن.
- **تمام ربات‌ها**: لیست همه‌ی بات‌های کل سیستم؛ از اینجا مشخص می‌کنی کدوم بات «مرکزی» (بات ثبت‌نام خودکار) باشه.
- **پرداخت‌ها**: پرداخت‌های کارت‌به‌کارت در انتظار تایید (از بخش ۹ پنل کاربری) اینجا میان؛ روی «تایید پرداخت» بزن تا سفارش تکمیل بشه.
- **گزارش‌ها**: لاگ کامل رویدادهای مهم سیستم.
- **تنظیمات**: مقادیر کلی سیستم که کمتر لازمه بهشون دست بزنی.
- **مدیریت ادمین‌ها**: اگه بخوای یه نفر دیگه هم دسترسی سوپرادمین داشته باشه، اکانتش رو از اینجا می‌سازی.

---

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