معرفی و ورود
وب‌اپ PasarguardBot چیست، چطور باز می‌شود و کاربر و ادمین با چه روش‌هایی وارد آن می‌شوند.
کنار ربات تلگرام، PasarguardBot یک وب‌اپ هم دارد. این وب‌اپ یک برنامهٔ واحد است که سه جور باز می‌شود:
- داخل تلگرام (Mini App): با یک دکمه داخل خود ربات باز می‌شود و کاربر خودکار وارد حسابش می‌شود.
- در مرورگر معمولی: آدرس وب‌اپ را در Chrome یا Safari یا هر مرورگری باز می‌کنید و با شماره تلفن یا کلید API وارد می‌شوید.
- به‌صورت اپ نصبی (PWA): می‌شود آن را روی صفحهٔ اصلی گوشی نصب کرد تا مثل یک اپ جدا باز شود. راهنما: نصب روی گوشی (PWA).
داخل این وب‌اپ دو بخش هست:
| بخش | برای چه کسی | چه کارهایی |
|---|---|---|
| اپ کاربر | همهٔ کاربران ربات | دیدن و مدیریت سرویس‌ها، تمدید، خرید، شارژ کیف پول، تراکنش‌ها و پروفایل |
| پنل مدیریت تحت وب | فقط ادمین‌های ربات | داشبورد و گزارش، کاربران، تراکنش‌ها، پنل‌ها، پلن‌ها، متن‌ها و دکمه‌ها، تنظیمات ربات و ابزارها |
پیش‌نیازها
وب‌اپ روی همان وب‌سرور ربات سرو می‌شود و چیز جدایی برای نصب ندارد. فقط دو چیز لازم است:
FASTAPI_PORT: وب‌سرور ربات باید روشن باشد (پیش‌فرض پورت6160). جزئیات: پورت‌ها.WEBAPP_URLباhttps://: تلگرام فقط آدرس HTTPS با دامنه و گواهی معتبر را قبول می‌کند. تا وقتیWEBAPP_URLباhttps://شروع نشود، دکمه‌های مینی‌اپ و دکمهٔ 🖥 پنل تحت وب در ربات دیده نمی‌شوند.
اول SSL را درست کنید
روش گرفتن گواهی و تنظیم WEBAPP_URL قدم‌به‌قدم در صفحهٔ دامنه و SSL آمده است. بعد از تنظیم، با دستور /webapp در ربات (با اکانت ادمین) تست کنید. باید دکمهٔ 🧪 باز کردن وب‌اپ بیاید.
کاربران چطور وب‌اپ را باز می‌کنند؟
از داخل ربات: تنظیم 🚀 مینی‌اپ
نمایش وب‌اپ به کاربران با تنظیم ⚙️ تنظیمات ربات → 🚀 مینی‌اپ کنترل می‌شود. هر بار که روی این دکمه بزنید، حالت بعدی انتخاب می‌شود (خاموش ← دکمه در منو ← فقط مینی‌اپ ← خاموش). همین تنظیم در پنل وب هم هست: تنظیمات ربات → تنظیمات اصلی → مینی‌اپ.
| حالت | چه اتفاقی می‌افتد |
|---|---|
| خاموش | دکمهٔ مینی‌اپ در منوی ربات نیست. کاربر هنوز می‌تواند آدرس وب‌اپ را در مرورگر باز کند. |
| دکمه در منو (در پنل وب: «دکمه در منوی اصلی») | دکمهٔ 🚀 ورود به اپلیکیشن به منوی اصلی ربات اضافه می‌شود. بقیهٔ منوی ربات سر جایش است. |
| فقط مینی‌اپ (در پنل وب: «فقط مینی‌اپ (منوی ربات خاموش)») | منوی ربات کامل جمع می‌شود و کاربر فقط یک دکمهٔ 🚀 ورود به اپلیکیشن می‌بیند. همهٔ کارها داخل وب‌اپ انجام می‌شود. ادمین‌ها دکمهٔ پنل مدیریت را هم کنارش می‌بینند. |
اگر WEBAPP_URL با https:// تنظیم نشده باشد، حالت انتخابی ذخیره می‌شود ولی اثری ندارد و ربات مثل حالت «خاموش» رفتار می‌کند تا آدرس درست شود.
چرا با زدن دکمه یک پیام می‌آید؟
تلگرام دو جور دکمهٔ وب‌اپ دارد. دکمه‌ای که روی کیبورد پایین صفحه است، اپ را بدون معرفی کاربر باز می‌کند و وب‌اپ نمی‌فهمد چه کسی آن را باز کرده. اما دکمهٔ شیشه‌ای (اینلاین) زیر پیام، اطلاعات امضاشدهٔ کاربر را هم می‌فرستد و ورود خودکار انجام می‌شود.
برای همین وقتی کاربر در کیبورد معمولی روی 🚀 ورود به اپلیکیشن می‌زند، ربات یک پیام کوتاه با دکمهٔ شیشه‌ای 🚀 باز کردن اپلیکیشن می‌فرستد. این پیام در چت می‌ماند و دفعه‌های بعد یک کلیک روی همان کافی است.
- متن این پیام و دکمه‌ها از پنل وب قابل تغییر است (متن‌های ربات و دکمه‌های ربات).
- اگر دکمه‌های شیشه‌ای صفحه اصلی روشن باشد (حالت شیشه‌ای منو)، خود دکمهٔ 🚀 ورود به اپلیکیشن شیشه‌ای است و مستقیم و با ورود خودکار وب‌اپ را باز می‌کند، بدون پیام واسط.
- در حالت فقط مینی‌اپ هم دکمه شیشه‌ای است و مستقیم باز می‌شود.
اختیاری: دکمهٔ Mini App در پروفایل ربات
می‌توانید همین WEBAPP_URL را در @BotFather به‌عنوان Mini App اصلی ربات (و در صورت تمایل دکمهٔ منوی کنار کادر پیام) ثبت کنید. این کار برای کارکرد وب‌اپ لازم نیست. روش: دامنه و SSL → Mini App اصلی ربات.
از مرورگر
کافی است همان آدرس WEBAPP_URL را در مرورگر باز کنید (مثلاً https://bot.example.com:6160/api/webapp). اگر وارد نشده باشید، صفحهٔ ورود می‌آید.
روش‌های ورود
وقتی وب‌اپ از یک دکمهٔ شیشه‌ای داخل ربات باز شود، تلگرام اطلاعات امضاشدهٔ کاربر را به آن می‌دهد و ورود خودکار انجام می‌شود. هیچ فرمی پر نمی‌شود.
- این اطلاعات تا ۲۴ ساعت بعد از باز شدن اپ معتبر است. اگر اپ خیلی طولانی باز مانده بود و خطای احراز هویت دیدید، آن را ببندید و دوباره از ربات باز کنید.
- کاربری که هنوز ربات را استارت نکرده، با اولین باز کردن وب‌اپ خودکار ثبت‌نام می‌شود (درست مثل
/start). - کاربری که ادمین مسدود کرده، با پیام «دسترسی شما مسدود شده است» متوقف می‌شود.
برای ورود از مرورگر:
شماره را وارد کنید
در کادر شماره تلفن شمارهٔ حساب تلگرام را بنویسید (مثل +989123456789) و ارسال کد را بزنید.
کد را از ربات بگیرید
ربات یک کد ۶ رقمی در چت تلگرام برایتان می‌فرستد. کد ۵ دقیقه معتبر است.
تایید و ورود
کد را در کادر کد تایید بنویسید و تایید و ورود را بزنید. برای اصلاح شماره، تغییر شماره تلفن را بزنید.
- شماره باید از قبل در ربات ثبت شده باشد (کاربر شماره‌اش را در ربات به اشتراک گذاشته باشد). در غیر این صورت پیام «شماره پیدا نشد یا کاربر ربات را شروع نکرده است» می‌آید.
- ادمین می‌تواند شمارهٔ یک کاربر را از پنل وب ثبت یا اصلاح کند: صفحهٔ جزئیات کاربر ← دکمهٔ شمارهٔ تلفن.
- برای هر کد حداکثر ۵ بار می‌شود کد اشتباه زد. بعد از آن باید کد تازه گرفت. درخواست‌های پشت‌سرهم زیاد هم موقتاً محدود می‌شوند («تعداد درخواست‌ها زیاد است…»).
- بعد از هر ورود موفق، یک گزارش «🔐 ورود به وب‌سایت» در کانال گزارش ثبت‌نام‌ها ارسال می‌شود.
کاربر می‌تواند در صفحهٔ پروفایل یک کلید API بسازد و بعداً بدون شماره و کد، فقط با همین کلید وارد شود. در صفحهٔ ورود روی ورود با کلید API بزنید، کلید (شروع با mzb_) را وارد کنید و تایید و ورود را بزنید.
ادمین با تنظیم ورود با کلید API تعیین می‌کند چه کسانی اجازهٔ ساختن کلید دارند (در ربات: ⚙️ تنظیمات ربات، در پنل وب: تنظیمات ربات → تنظیمات اصلی):
| مقدار | معنی |
|---|---|
| غیرفعال (پیش‌فرض) | بخش کلید API در پروفایل نشان داده نمی‌شود و کسی نمی‌تواند کلید بسازد. |
| فقط دارای شماره ثبت‌شده | فقط کاربرانی که شماره‌شان در ربات ثبت است می‌توانند کلید بسازند. |
| همه کاربران | هر کاربری می‌تواند کلید بسازد. |
نکات مهم کلید API
- این تنظیم فقط ساختن کلید را کنترل می‌کند. کلیدی که قبلاً ساخته شده، حتی بعد از «غیرفعال» شدن تنظیم، همچنان برای ورود کار می‌کند.
- کلید فقط یک بار و همان لحظهٔ ساخت نمایش داده می‌شود. آن را کپی و در جای امن نگه دارید.
- با ساخت کلید جدید، کلید قبلی باطل می‌شود و همهٔ نشست‌های فعلی (حتی همین دستگاه) خارج می‌شوند و باید دوباره وارد شوید.
- تلاش‌های اشتباه پشت‌سرهم موقتاً مسدود می‌شود.
نشست و خروج
- بعد از ورود از مرورگر، نشست شما تا وقتی از اپ استفاده می‌کنید خودکار تمدید می‌شود. فقط اگر ۱۴ روز پشت‌سرهم از وب‌اپ استفاده نکنید، باید دوباره وارد شوید.
- دکمهٔ خروج از حساب در پایین صفحهٔ پروفایل است. با خروج، نشست‌های ورود با شماره یا کلید روی همهٔ دستگاه‌ها بسته می‌شوند. ورود خودکار داخل تلگرام همچنان کار می‌کند.
زبان، ظاهر و تمام‌صفحه
بالای صفحه (در موبایل) یا در نوار کناری (در دسکتاپ) سه کنترل هست:
| کنترل | گزینه‌ها |
|---|---|
| 🌐 زبان | فارسی / English |
| ظاهر | روشن، خودکار (هماهنگ با گوشی یا تلگرام)، تیره |
| تمام‌صفحه | باز کردن اپ در کل صفحه (داخل تلگرام هم کار می‌کند) |
همین کنترل‌ها در پنل مدیریت هم هستند.
ورود ادمین به پنل مدیریت
پنل مدیریت فقط برای حساب‌هایی است که آیدی عددی‌شان در ADMIN_ID فایل .env آمده. هیچ نام کاربری و رمز جدایی ندارد: ادمین با همان روش‌های بالا (تلگرام، شماره یا کلید API) وارد وب‌اپ می‌شود و سرور با ADMIN_ID تشخیص می‌دهد که ادمین است. اگر حساب دیگری پنل را باز کند، پیام «این حساب دسترسی مدیریت ندارد.» می‌بیند.
راه‌های رسیدن به پنل:
| راه | توضیح |
|---|---|
| پروفایل ← پنل مدیریت | در اپ کاربر، صفحهٔ پروفایل، برای ادمین‌ها گزینهٔ پنل مدیریت نشان داده می‌شود. مطمئن‌ترین راه است. |
| دکمهٔ 🖥 پنل تحت وب | در پنل مدیریت ربات (فقط وقتی WEBAPP_URL با https:// باشد). با زدنش پیامی با دکمهٔ شیشه‌ای 🖥 پنل تحت وب می‌آید. |
دستور /webapp | فقط برای ادمین. دکمهٔ 🧪 باز کردن وب‌اپ می‌دهد، برای تست ورود از سمت تلگرام. |
| آدرس مستقیم در مرورگر | <WEBAPP_URL>#/panel، مثلاً https://bot.example.com:6160/api/webapp#/panel. اگر وارد نشده باشید، بعد از ورود مستقیم به پنل برمی‌گردید. |
دکمهٔ 🖥 پنل تحت وب و /webapp در نسخهٔ فعلی
در نسخهٔ فعلی، دکمهٔ شیشه‌ای 🖥 پنل تحت وب و دکمهٔ /webapp هر دو وب‌اپ را روی داشبورد کاربر باز می‌کنند (با ورود خودکار). از آنجا به پروفایل ← پنل مدیریت بروید. در مرورگر هم می‌توانید مستقیم آدرس #/panel را باز کنید.
برای برگشت از پنل به اپ کاربر، از نوار کناری پنل بازگشت به وب‌اپ را بزنید.