طراحی ربات تلگرام

**مشخصات کامل پروژه ساخت ربات تلگرام + پنل مدیریت** **تعریف کلی پروژه** یک ربات تلگرام لازم است که ورودی متنی کاربران را دریافت کند، آن را بر اساس قالب‌های قابل‌تعریف توسط ادمین پردازش کند و خروجی متنی تولید کند. این خروجی باید از طریق یک API خارجی (OpenAI، Gemini یا هر سرویس دیگر) تولید شود. همه تنظیمات مربوط به API، مدل، پرامپت‌ها، قالب‌ها، پیام‌ها و محدودیت‌ها باید از طریق یک پنل مدیریتی تحت وب قابل تغییر باشد و در کد ثابت نباشد. **امکانات مورد نیاز سمت کاربر (در ربات تلگرام)** 1. فرمان `/start` * پیام خوش‌آمدگویی * نمایش دکمه‌های شیشه‌ای شامل: * «ساخت متن جدید» * «ثبت توضیحات من» * «وضعیت من» * «دعوت از دوستان» * «عضویت در کانال» 2. ثبت توضیحات کاربر * یک فلوی چندمرحله‌ای برای دریافت توضیح کاربر درباره فعالیت یا پروژه‌اش * ذخیره این توضیحات در دیتابیس به عنوان `user_profile` * این اطلاعات باید در هنگام تولید متن، به عنوان یکی از پارامترهای ورودی API استفاده شود 3. تولید متن * کاربر روی «ساخت متن جدید» کلیک می‌کند * ربات از کاربر موضوع یا توضیح مختصر را درخواست می‌کند * ورودی کاربر همراه با مشخصات ذخیره‌شده او و قالب مربوطه، در قالب یک تمپلیت تکمیل شده و به API خارجی ارسال می‌شود * خروجی API مستقیماً برای کاربر ارسال شود 4. محدودیت مصرف (Quota) * هر کاربر مقدار مشخصی اعتبار رایگان دارد * هر بار تولید متن، یک واحد از اعتبار او کم می‌شود * اگر اعتبار تمام شد، ربات باید پیام مخصوص نمایش دهد و اجازه ادامه ندهد * پیام شامل دکمه‌های: * «دعوت دوست» * «عضویت در کانال» * پس از انجام این اکشن‌ها، مقدار اعتبار کاربر افزایش یابد 5. سیستم دعوت (Referral System) * برای هر کاربر لینک دعوت اختصاصی تولید شود * اگر کاربر جدید با آن لینک وارد شد، در دیتابیس ثبت شود * پس از فعال شدن کاربر جدید (مثلاً انجام اولین درخواست)، مقدار مشخصی اعتبار به معرف اضافه شود 6. بررسی عضویت در کانال (اختیاری اما قابل تنظیم) * اگر این ویژگی در پنل فعال باشد، ربات قبل از تولید متن چک کند کاربر عضو کانال معرفی‌شده است یا خیر * در صورت عدم عضویت، پیام مربوطه با دکمه «بررسی عضویت» ارسال شود 7. نمایش وضعیت کاربر * تعداد استفاده‌ها * تعداد اعتبار باقی‌مانده * تعداد دعوت‌های موفق --- **پنل ادمین (تحت وب)** پنل باید با احراز هویت محافظت شود و شامل امکانات زیر باشد: 1. **مدیریت ارائه‌دهندگان API** * افزودن / ویرایش API Provider * تنظیم موارد زیر: * Base URL * Model Name * API Key (به صورت امن ذخیره شود) * فعال / غیرفعال کردن هر Provider 2. **مدیریت Templateها** * تعریف قالب جدید * شامل فیلدهای: * System Prompt * User Prompt Template * امکان استفاده از Placeholderها مانند: * `{user_input}` * `{user_profile}` * ربات باید همین قالب‌ها را هنگام ساخت درخواست API پر کند 3. **تنظیمات محدودیت‌ها (Quota Settings)** * تعداد اعتبار رایگان اولیه هر کاربر جدید * میزان اعتباری که پس از دعوت موفق به کاربر معرف اضافه می‌شود * امکان تنظیم سقف روزانه (در صورت نیاز) 4. **مدیریت پیام‌ها (Editable Texts)** * همه پیام‌هایی که ربات برای کاربر ارسال می‌کند، باید از پنل قابل ویرایش باشد * شامل پیام شروع، پیام اتمام اعتبار، پیام دعوت، پیام مراحل ثبت توضیحات و … 5. **مدیریت کاربران** * لیست کاربران * نمایش: * telegram_id * username * تعداد اعتبار مصرف‌شده و باقی‌مانده * پروفایل ثبت‌شده * امکان ریست کردن اعتبار یک کاربر * امکان بلاک کردن کاربر 6. **لاگ درخواست‌ها** * نمایش درخواست‌های اخیر * وضعیت موفق / خطا * زمان انجام --- **ساختار دیتابیس پیشنهادی** 1. جدول `users` * id * telegram_id * username * user_profile (text) * free_credits * used_credits * total_referrals * created_at 2. جدول `referrals` * id * referrer_user_id * referred_user_id * status (pending / active) * created_at 3. جدول `templates` * id * name * system_prompt * user_prompt_template * extra_config (json) 4. جدول `api_providers` * id * name * base_url * model_name * api_key * is_active 5. جدول `settings` * key * value (json/text) --- **الزامات فنی** 1. ربات با یکی از موارد زیر نوشته شود: * Python + aiogram یا * Node.js + telegraf / grammy 2. ارتباط با API خارجی در یک ماژول جداگانه انجام شود و قابل توسعه باشد 3. هیچ متن مهمی در کد هاردکد نشود و همه پیام‌ها و پرامپت‌ها از پنل فراخوانی شوند 4. وبهوک یا پولینگ بر اساس نیاز پروژه پیاده‌سازی شود 5. امنیت: * توکن ربات و API Keyها در محیط امن (ENV یا دیتابیس رمزگذاری‌شده) ذخیره شوند * پنل مدیریت با احراز هویت قوی محافظت شود * تمام ارتباط‌ها با HTTPS انجام شود --- **فلوی کلی پردازش کاربر** 1. کاربر درخواست تولید متن ارسال می‌کند 2. ربات پروفایل کاربر و میزان اعتبار را از دیتابیس می‌گیرد 3. اگر اعتبار کافی نبود، پیام محدودیت ارسال می‌شود 4. اگر اعتبار کافی بود: * تمپلیت فعال از دیتابیس دریافت می‌شود * Placeholderها با داده‌های واقعی جایگزین می‌شوند * درخواست نهایی به API Provider ارسال می‌شود * خروجی به کاربر ارسال می‌شود * اعتبار کاربر یک واحد کاهش پیدا می‌کند