مستندات جامع SafeGanjineh Bot

مرجع رسمی پروژه ربات تلگرامی مدیریت گارانتی و امداد فنی — طراحی، توسعه، استقرار و پشتیبانی.

وضعیت: مستند کامل
محیط: Python / cPanel
پشتیبانی: MySQL

۱. معرفی و چشم‌انداز

SafeGanjineh یک ربات مدیریت گارانتی و امداد فنی برای برندهای لوازم خانگی است که سناریوهای زیر را یکپارچه می‌کند:

  • ثبت و مدیریت گارانتی، فروشگاه‌ها و کاتالوگ‌ها
  • دریافت درخواست‌های امداد از مشتریان و ارزیابی وضعیت گارانتی
  • مسیردهی خودکار درخواست‌ها به تکنسین‌های در دسترس بر اساس تقویم صبح/بعدازظهر
  • ثبت گزارش‌ها، فیدبک مشتریان و خروجی‌های تحلیلی

پروژه به شکل یک اپلیکیشن Python روی cPanel (Passenger) اجرا می‌شود و منطق اصلی در فایل app/bot_ptb.py پیاده شده است.

۲. معماری و ساختار کد

.
├── app/
│   ├── bot_ptb.py             # منطق اصلی ربات (PTB 20)
│   ├── db.py                  # لایه دسترسی به MySQL و ساخت جداول
│   ├── membership_guard.py    # کنترل عضویت کانال
│   └── ...                    # فایل‌های جانبی (bridges, handlers, views)
├── scripts/
│   ├── manage_webhook.py      # مدیریت وب‌هوک
│   └── tools_init_db.py       # راه‌اندازی/seed پایگاه‌داده
├── public/, storage/, logs/   # پوشه‌های موردنیاز cPanel / Passenger
├── passenger_wsgi.py          # entry point برای Passenger
├── requirements.txt           # وابستگی‌ها
└── readme.md                  # همین مستند

ماژول‌های کلیدی

  • bot_ptb.py: هندلرهای تلگرام، جریان‌های محاوره، صف‌بندی پیام‌ها، مدیریت تقویم تکنسین‌ها.
  • db.py: ساخت جداول (guarantees, stores, catalogs, support_requests, technician_unavailable_slots, …) و تمامی کوئری‌های CRUD.
  • membership_guard.py: اطمینان از عضویت کاربر در کانال قبل از دسترسی به منوها.
  • scripts/tools_init_db.py: اجرای اولیه دیتابیس و seed نقش‌های admin/technician.

۳. پیش‌نیازهای فنی

  • Python 3.10 یا 3.13 (مطابق محیط cPanel)
  • MySQL 5.7+
  • دسترسی SSH/cPanel با امکان استفاده از Passenger
  • Git برای دریافت/به‌روزرسانی سورس (در محیط توسعه محلی)

۴. متغیرهای محیطی (.env)

متغیرها

نامتوضیح
BOT_TOKENتوکن ربات تلگرام
WEBHOOK_SECRET_PATHپَت وب‌هوک (برای مسیر /webhook/<secret>)
MYSQL_HOST, MYSQL_PORT, MYSQL_DB, MYSQL_USER, MYSQL_PASSWORDتنظیمات اتصال MySQL
ADMIN_IDSفهرست ID مدیریت (کاما جدا)
TECHNICIAN_CHAT_IDSفهرست ID تکنسین‌های اولیه
APP_LOG_FILEمسیر فایل لاگ (پیشنهاد: /home/<user>/bots/safeganjineh/logs/app.log)
TZمنطقه زمانی (مانند Asia/Tehran)
DEBUGمقدار بولی برای شفافیت بیشتر لاگ‌ها
CHANNEL_ID, CHANNEL_PUBLIC_URLبرای membership_guard.py درصورت نیاز

نمونه .env:

BOT_TOKEN=123456:ABC...
WEBHOOK_SECRET_PATH=safeganjineh
MYSQL_HOST=localhost
MYSQL_DB=botnegar_safeganjineh
MYSQL_USER=botnegar_ganjinehadmin
MYSQL_PASSWORD=********
ADMIN_IDS=100970431,119119806
TECHNICIAN_CHAT_IDS=100970431,119119806,1372667993
APP_LOG_FILE=/home/botnegar/public_html/ganjine/logs/app.log
TZ=Asia/Tehran
DEBUG=False

۵. راه‌اندازی محلی (توسعه)

  1. کلون کردن مخزن و ورود به پوشه پروژه.
  2. نصب محیط مجازی: 
    python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
  3. ایجاد فایل .env با محتویات مناسب (می‌توان از یک Bot Token تستی استفاده کرد).
  4. اجرای اسکریپت دیتابیس: 
    python -m scripts.tools_init_db
  5. اجرای ربات به صورت polling (برای توسعه): 
    python -m app.bot_ptb
  6. برای استاپ: Ctrl+C یا kill <PID>.

نکته: در محیط توسعه می‌توانید وب‌هوک را غیرفعال نگه‌دارید و با polling تست کنید. برای اتصال به نسخه واقعی، باید Webhook را ست کنید (بخش عملیات).

۶. استقرار روی cPanel/Passenger

  1. آپلود سورس در مسیر مثلا /home/<user>/public_html/ganjine یا /home/<user>/bots/safeganjineh.
  2. ایجاد Python App در cPanel → Python Selector، با تنظیمات:
    • Python: 3.10 یا 3.13
    • Application Root: مسیر پروژه
    • Startup file: passenger_wsgi.py
    • Application entry: application
  3. ایجاد virtualenv توسط cPanel و سپس نصب وابستگی‌ها: 
    source /home/<user>/virtualenv/public_html/ganjine/3.13/bin/activate
cd /home/<user>/public_html/ganjine
pip install -r requirements.txt
deactivate
  4. تنظیم متغیرهای محیطی: یا در .env (در root پروژه) و یا از UI cPanel.
  5. اجرای init_db (فقط یک‌بار یا پس از تغییر جداول): 
    source /home/<user>/virtualenv/public_html/ganjine/3.13/bin/activate
cd /home/<user>/public_html/ganjine
python -m scripts.tools_init_db
deactivate
  6. ریست Passenger با لمس فایل tmp/restart.txt یا دکمه Restart در cPanel: 
    cd /home/<user>/public_html/ganjine
touch tmp/restart.txt

۷. وب‌هوک و تلگرام

مسیر وب‌هوک: https://<domain>/webhook/<WEBHOOK_SECRET_PATH>

برای ست کردن وب‌هوک:

curl "https://api.telegram.org/bot<token>/setWebhook?url=https://<domain>/webhook/<secret>"

برای حذف وب‌هوک (و استفاده از polling): deleteWebhook

توصیه: SSL فعال باشد و وب‌هوک در پنل تلگرام به‌روز شود.

۸. دیتابیس و مهاجرت‌ها

ساخت جداول

کد در db.py به صورت idempotent (با CREATE TABLE IF NOT EXISTS) اجرا می‌کند:

  • guarantees, stores, catalogs, catalog_files
  • support_requests + ستون‌های assignment و تقویم (scheduled_slot_date, scheduled_slot_part)
  • technician_unavailable_slots برای ثبت روزهای استراحت/غیبت تکنسین‌ها
  • support_reports, staff_roles

اسکریپت‌ها

  • python -m scripts.tools_init_db: ساخت اولیه جداول و seed کردن admin/technician بر اساس .env
  • reset_db در db.py: حذف و ساخت مجدد (مراقب از دست‌دادن داده‌ها باشید)

نکته نگهداری

  • بعد از تغییر در ساختار DB، حتماً اسکریپت بالا را در محیط staging اجرا کنید و سپس در production لمس کنید.
  • برای بک‌آپ گیری از MySQL می‌توانید از ابزار cPanel یا mysqldump استفاده کنید.

۹. جریان‌های کاری کلیدی ربات

۹.۱ ثبت گارانتی و مدیریت فروشگاه/کاتالوگ

منوهای مربوطه در bot_ptb.py با ConversationHandler پیاده شده‌اند. Admin می‌تواند فروشگاه‌ها و کاتالوگ‌های مرتبط را اضافه/ویرایش/حذف کند.

۹.۲ درخواست امداد و تقویم تکنسین

  1. کاربر از منوی «درخواست امداد» وارد می‌شود و ویدئو/آدرس/موقعیت را ارسال می‌کند.
  2. سیستم وضعیت گارانتی را بررسی می‌کند.
  3. انتخاب بازه زمانی: ربات بازه‌های صبح (۹-۱۲) و بعدازظهر (۱۳-۱۸) را برای روزهای کاری (شنبه تا چهارشنبه) نشان می‌دهد؛ فقط بازه‌هایی که دست‌کم یک تکنسین آزاد دارند نمایش داده می‌شود.
  4. بعد از انتخاب، درخواست فوراً به اولین تکنسین آزاد آن بازه تخصیص داده می‌شود و به تکنسین و ادمین اطلاع داده می‌شود.
  5. تکنسین‌ها از منوی «تقویم خدمات» می‌توانند برای هر روز، بازه‌های صبح/بعدازظهر را فعال/غیرفعال کنند یا کل روز را تعطیل اعلام کنند (technician_unavailable_slots).

۹.۳ مدیریت تیم و گزارش‌ها

منوی «مدیریت تیم» امکان افزودن/حذف admin و technician را فراهم می‌کند. تکنسین‌ها می‌توانند گزارش فنی ارسال کرده یا درخواست را بپذیرند/رد کنند.

۱۰. عملیات و DevOps

۱۰.۱ ریست سرویس

cd /home/<user>/public_html/ganjine
touch tmp/restart.txt

برای kill دستی (در صورت اجرا به صورت background):

ps -fu <user> | grep ganjine | grep -v grep
kill -9 <PID>

۱۰.۲ مشاهده لاگ

  • اپلیکیشن: tail -f logs/app.log
  • Passenger: در cPanel → Error Logs یا ~/logs/<domain>-error.log

۱۰.۳ به‌روزرسانی سورس

  1. فایل‌ها را از git pull یا SFTP به‌روزرسانی کنید.
  2. در virtualenv pip install -r requirements.txt در صورت نیاز.
  3. python -m scripts.tools_init_db اگر جداول تغییر کرده‌اند.
  4. touch tmp/restart.txt

۱۰.۴ حل مشکلات رایج

  • NameError/ImportError: مطمئن شوید فایل ویرایش‌شده ذخیره شده و Passenger ریست شده است.
  • خطای دیتابیس: بررسی اتصال و صحت credentials، سپس لاگ mysql.
  • Webhook 500: لاگ logs/app.log را چک کنید، معمولاً مرتبط با نبودن توکن یا env است.

۱۱. تست و کنترل کیفیت

  • py_compile: به عنوان sanity check 
    python -m py_compile app/bot_ptb.py app/db.py
  • تست جریان‌ها: هر تغییر مهم در ConversationHandler را با یک Bot Test انجام دهید (استفاده از گروه تست با ادمین/تکنسین‌های واقعی).
  • Monitoring: پیشنهاد می‌شود یک مانیتور بیرونی (UptimeRobot) روی /health قرار گیرد.

۱۲. دستورهای مفید

# فعال‌سازی virtualenv
source /home/<user>/virtualenv/public_html/ganjine/3.13/bin/activate

# نصب وابستگی‌ها
pip install -r requirements.txt

# اجرای اسکریپت دیتابیس
python -m scripts.tools_init_db

# اجرای ربات در پس‌زمینه (در محیط تست)
python -m app.bot_ptb &
disown

# توقف همه‌ی پردازه‌های مرتبط
ps -fu <user> | grep ganjine | grep -v grep | awk '{print $2}' | xargs kill -9

۱۳. نگهداری و توسعه آینده

  • Automation: در صورت امکان، استقرار CI/CD (GitHub Actions یا GitLab CI) برای lint، test و deployment پیشنهاد می‌شود.
  • Observability: افزودن متریک‌های Prometheus یا یک صفحه وضعیت ساده برای شمارش درخواست‌ها و خطاها.
  • Localization: تمامی پیام‌ها اکنون فارسی رسمی هستند؛ برای پشتیبانی چندزبانه، ساختار constantها در bot_ptb.py را گسترش دهید.
  • آزمون واحد: ماژول DB و منطق تقویم قابلیت تست‌نویسی ساده دارند (pytest + یک Docker MySQL).

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