💬 Blue Chat

ربات تلگرام برای گفتگوی ناشناس — کاربران به صورت تصادفی یا هدفمند به هم وصل می‌شن و چت می کنند.

نمونه اجرا شده: @Blluchatbot

---

📑 فهرست مطالب

• ✨ امکانات
• 🛠 تکنولوژی‌ها
• 🚀 راه‌اندازی
• 🧪 تست‌ها
• 📊 مانیتورینگ
• ⚡ مقیاس‌پذیری
• 🏗 معماری
• 📁 ساختار پروژه
• 📜 لایسنس

---

✨ امکانات

💬 چت ناشناس

• اتصال تصادفی — وصل شدن فوری به یه کاربر ناشناس با یه دکمه

• جستجوی هدفمند — فیلتر بر اساس جنسیت، بازه سنی، استان و شهر؛ انتخابِ استان بدونِ شهر مشکلی نداره (جستجو فقط بر اساسِ استان انجام می‌شه)، ولی انتخابِ شهر قبل از استان ممکن نیست و صراحتاً گفته می‌شه اول استان رو انتخاب کن. فیلترِ فاصله هم داره (همون گزینه‌های ۵/۱۰/۲۰/۵۰ کیلومتریِ «افراد نزدیک»، به‌علاوه‌ی «🎯 نزدیک‌ترین آدم ممکن»)؛ برای فعال‌کردنش باید قبلاً از بخشِ «افراد نزدیک» موقعیتت رو به اشتراک گذاشته باشی

• درخواست چت — ارسال درخواست چت به کاربر خاص از طریق پروفایل عمومی (۲ سکه هزینه)؛ هویت و پروفایل درخواست‌دهنده تا قبل از زدنِ «مشاهده» توسط گیرنده فاش نمی‌شه، و بعد از مشاهده به فرستنده هم اطلاع داده می‌شه که درخواستش دیده شده. کلِ درخواست (دکمه‌های مشاهده/قبول/رد) فقط تا ۵ دقیقه معتبره (صراحتاً به هر دو طرف اعلام می‌شه) و بعدش خودکار لغو و سکه برمی‌گرده؛ ضمناً لحظه‌ی قبول‌کردن، هر دو طرف باید آزادِ چتِ ۱به۱ و اتاقِ چت باشن (نه جفت‌شده/عضو، نه منتظرِ صف) وگرنه درخواست لغو می‌شه، حتی اگه موقعِ ارسالِ درخواست آزاد بودن. هر کاربر هم‌زمان حداکثر ۵ درخواستِ بی‌پاسخ می‌تونه داشته باشه؛ برای فرستادنِ درخواستِ بعدی باید صبر کنه یکی‌شون قبول/رد بشه یا منقضی بشه

• چت امن — پیام‌های غیرقابل فوروارد و ذخیره با protect_content تلگرام؛ هر کاربر مستقلاً برای پیام‌های خودش فعال می‌کنه

• حذف پیام — ارسال «حذف» یا «del» به‌عنوان ریپلای روی پیام ارسالی خودت، پیام رو از هر دو طرف پاک می‌کنه

• ویرایش پیام — ویرایش پیام متنی برای طرف مقابل هم اعمال میشه با برچسب «✏️ ویرایش شده · HH:MM»

• پاکسازی تاریخچه — بعد از پایان هر چت، دکمه‌ی پاکسازیِ دوطرفه و دکمه‌ی گزارشِ گفتگو فقط ۲ دقیقه معتبرن (صراحتاً اعلام می‌شه)؛ بعد از ۲ دقیقه تاریخچه‌ی متنیِ سرور (برای قضاوتِ AI) خودکار پاک می‌شه بدونِ اینکه پیام‌های خودِ تلگرامِ کاربرها حذف بشه، و کلیک روی دکمه‌ها بعد از انقضا پیامِ «درخواست معتبر نیست» می‌ده. اگه گفتگو اصلاً پیامی نداشته، به‌جای پیشنهادِ الکی صراحتاً اعلام می‌شه که چیزی برای پاک‌سازی یا گزارش‌دادن نیست

• گزارشِ تک‌پیام — دستورِ /report حذف شده؛ برای گزارشِ یه پیامِ مشخص، روی همون پیامِ طرفِ مقابل ریپلای کن و بنویس «گزارش»/«report»

• گزارشِ کلِ گفتگو — فقط بعد از پایانِ چت، از طریقِ دکمه‌ی «🚫 گزارش این گفتگو» (تا ۲ دقیقه معتبر) ممکنه؛ در هر دو حالت، بررسیِ نهایی توسط هوش مصنوعی انجام می‌شه

• قضاوت آنی با هوش مصنوعی — گزارش‌های ارسالی به‌صورت خودکار و لحظه‌ای توسط DeepSeek تحلیل و قضاوت می‌شن؛ در صورت تخلف، اخطار یا بن صادر میشه

• حداقل زمان چت — امکان بستن چت قبل از ۱۰ ثانیه وجود نداره

• تأیید بستن چت — قبل از پایان چت، پیام تأیید با دو دکمه نمایش داده می‌شه

🏠 اتاق چت

• ساخت اتاق — اتاقِ چتِ گروهیِ دائمی با ظرفیتِ ۲ تا ۵ نفر و جنسیتِ مشخص (پسرونه/دخترونه/فرقی نداره)؛ ۲۰ سکه هزینه؛ هر اتاق یه شماره‌ی یکتا (ID) داره که توی وضعیت و پیامِ عضویت نمایش داده می‌شه

• عضویت در اتاق — جستجو بر اساس جنسیتِ دلخواه با ۳ سکه؛ در صورت نبودِ جای خالی، وارد صف می‌شه (تایم‌اوت ۲ دقیقه‌ای با بازگشتِ خودکارِ سکه، یا لغوِ دستی با دکمه)

• اطلاع‌رسانیِ عضویت — با ورودِ هر عضوِ جدید (فوری یا از صف)، بقیه‌ی اعضای فعلیِ اتاق باخبر می‌شن

• رله‌ی چندنفره — پیام‌ها بینِ همه‌ی اعضا رله می‌شن؛ حذف، ویرایش و چتِ امن مشابهِ چتِ ۱به۱ پشتیبانی می‌شن؛ هر پیام با نامِ نمایشی و لینکِ پروفایلِ عمومیِ فرستنده (/user_<code>) برچسب می‌خوره

• وضعیتِ اتاق — دکمه‌ی «👥 وضعیت اتاق» تعدادِ اعضا و لیستِ تک‌تکشون رو با نقش (owner/عضو)، لینکِ پروفایلِ عمومی، و وضعیتِ حضورِ فعلی (🟢 حاضر یا 🌙 ترکِ موقت) نشون می‌ده

• مدیریتِ owner — بستن/بازکردنِ اتاق برای عضوگیری، اخراجِ عضو، حذفِ پیامِ هرکسی، و حذفِ کاملِ اتاق. وقتی اتاق بسته می‌شه، اعضای غیرِ owner به منوی اصلی (بدونِ تغییر) هدایت می‌شن و به بقیه‌ی امکاناتِ ربات (بجز چتِ ۱به۱ و اتاقِ جدید) دسترسیِ کامل دارن؛ با /room یا دکمه‌ی «🏠 اتاق چت» دوباره وارد اتاق می‌شن

• پاک‌سازیِ تاریخچه‌ی اتاق — بعد از هر نوع پایانِ اتاق (حذفِ دستیِ owner، یا حذفِ خودکار به‌خاطرِ ترک/اخراجِ آخرین عضوِ غیرِ owner)، owner پیشنهادِ پاک‌سازیِ کاملِ تاریخچه رو می‌گیره؛ فقط تا ۲ دقیقه معتبره (صراحتاً اعلام می‌شه) و واقعاً شاملِ همه‌ی اعضای سابقِ اتاقه، نه فقط کسانی که لحظه‌ی پایان هنوز عضو بودن. اگه اتاق اصلاً پیامی نداشته، به‌جای پیشنهادِ الکی صراحتاً اعلام می‌شه که تاریخچه‌ای برای پاک‌سازی وجود نداره

• خروج موقت — دکمه‌ی «🚪 خروج» فقط هندلرِ اتاق رو برای همون کاربر غیرفعال می‌کنه (عضویت دست‌نخورده می‌مونه)؛ با /room یا «🏠 اتاق چت» دوباره فعال می‌شه — جدا از «🚪 ترک اتاق» که واقعاً از عضویت خارج می‌کنه

• ترکِ اتاق — عضوِ عادی می‌تونه اتاق رو کامل ترک کنه؛ owner فقط با حذفِ کاملِ اتاق خارج می‌شه؛ اگه فقط owner باقی بمونه، اتاق خودکار حذف می‌شه

• انحصاریِ ۱به۱/اتاق — هر کاربر در هر لحظه یا توی چتِ ۱به۱ می‌تونه باشه یا توی یه اتاق (یا منتظرِ یکی از این دوتا)، نه هر دو هم‌زمان

🔧 دستورات

• /stop — پایان دادن به چت جاری یا خروج از صف انتظار

• /next — پایان چت فعلی و جستجوی فوری برای همراه جدید

• /room — وضعیتِ اتاقِ چتِ فعلی، یا منوی ساخت/عضویت اگه اتاقی نداری

• /settings — تنظیمات شخصی (ترجیح جنسیت، حریم خصوصی و غیره)

👤 پروفایل

• پروفایل عمومی — نام نمایشی، بیوگرافی، جنسیت، سن، استان، شهر و عکس پروفایل

• آنلاین بودن — نمایش وضعیت آنلاین یا آخرین بازدید (مثل «۵ دقیقه پیش»)

• انتخاب استان/شهر — کیبورد اینلاین با لیست کامل ۳۱ استان و تمام شهرهای ایران

• لینک اختصاصی — هر کاربر یه لینک /u_<code> داره برای اشتراک‌گذاری پروفایل

• بلاک/آنبلاک از پروفایلِ عمومی — دکمه‌ی زیرِ پروفایل بینِ «🚫 بلاک» و «✅ آنبلاک» تاگل می‌شه؛ اگه طرفِ مقابل بلاکت کرده باشه، درخواستِ چت یا پیامِ دایرکت با پیامِ صریحِ «بلاکت کرده» رد می‌شه (نه یه موفقیتِ ساختگی)؛ اگه بلاک نباشه ولی طرف سایلنت باشه، خطای سایلنت جداگانه نشون داده می‌شه

📩 پیام ناشناس

• نوت ناشناس — ارسال پیام ناشناس از طریق لینک اختصاصی کاربر

• پیام دایرکت — ارسال پیام با حفظ هویت فرستنده (برای دوستان)؛ هر پیام ۱ سکه هزینه دارد، مستقل از اینکه مقصد ببینتش یا نه

• پاسخ ناشناس — صاحب لینک می‌تونه به پیام ناشناس پاسخ بده

• بلاکِ فرستنده — صاحبِ لینک می‌تونه فرستنده رو برای همیشه بلاک کنه؛ بعدِ بلاک نه پیامِ ناشناسِ جدید تحویل داده می‌شه نه ادامه‌ی زنجیره‌ی پاسخ‌ها (حتی اگه فرستنده از دکمه‌ی «↩️ پاسخ دادن» زیرِ یه پاسخِ قبلی استفاده کنه)؛ فرستنده‌ی بلاک‌شده صراحتاً باخبر می‌شه که دیگه نمی‌تونه از این لینک پیام بفرسته (نه یه موفقیتِ ساختگی)

🪙 سیستم سکه

• سکه‌ی هدیه — ۱۰ سکه در شروع به همه کاربران

• معرفی دوستان — دریافت سکه با معرفی کاربر جدید از طریق لینک رفرال

• جستجوی با فیلتر جنسیت — انتخاب دختر یا پسر ۲ سکه هزینه دارد؛ «فرقی نمی‌کنه» رایگان است

• درخواست چت — ارسال درخواست چت از طریق پروفایل عمومی ۲ سکه هزینه دارد

• پیام دایرکت — هر پیام دایرکت ۱ سکه هزینه دارد، مستقل از دیده‌شدن (پیام ناشناسِ لینک مستقیم رایگانه)

• بازگشت خودکار سکه — اگه چت کمتر از ۳ پیام داشته باشه (ناموفق)، جستجو لغو/تایم‌اوت بشه، درخواست چت رد/لغو بشه، یا درخواست چت ظرف ۵ دقیقه بی‌پاسخ بمونه، سکه برگشت داده می‌شه

• تاریخچه‌ی تراکنش‌ها — تمام واریز و برداشت‌های سکه در دیتابیس ثبت می‌شن

🤖 هوش مصنوعی

• مدیریت محتوا — بررسی خودکار عکس پروفایل با Google Gemini

• قضاوت گزارش — تحلیل تاریخچه‌ی چت و قضاوت گزارش‌های کاربران با DeepSeek

• اخطار و بن خودکار — ۵ اخطار = بن خودکار توسط سیستم AI

• اثرِ فوریِ بن روی چت/اتاق — به‌محضِ بن‌شدنِ یه کاربر (چه با ۵مین اخطار، چه بلافاصله در گزارشِ پروفایل)، اگه توی یه چتِ ۱به۱ فعال باشه چت خودکار بسته می‌شه و طرفِ مقابل باخبر می‌شه؛ اگه عضوِ یه اتاقِ چت باشه: owner بن‌شده → اتاق بسته می‌شه، آخرین عضوِ غیرِ owner بن‌شده → اتاق بسته می‌شه، وگرنه فقط از اتاق اخراج می‌شه

• گیتِ سراسریِ بن — کاربرِ بن‌شده دیگه هیچ کامند/پیام/دکمه‌ای رو نمی‌تونه اجرا کنه؛ یه پیامِ صریحِ «حسابت مسدود شده» می‌گیره (حداکثر هر ۶ ساعت یه‌بار، نه با هر پیام) و برای callback query‌ها یه alert می‌بینه. پیاده‌سازی: python-telegram-bot میان‌افزارِ رسمی (middleware) نداره؛ معادلش با ابزارهای خودِ کتابخانه ساخته شده — یه MessageHandler(filters.ALL, ...) و یه CallbackQueryHandler روی گروهِ -1 (main.reject_banned_users) ثبت شدن که همیشه قبل از گروهِ پیش‌فرضِ 0 (جایی که همه‌ی هندلرهای اصلی — کامندها، متن، رسانه، callback query‌ها — هستن) اجرا می‌شن؛ اگه کاربر بن باشه، با پرتابِ ApplicationHandlerStop کلِ پردازشِ همون آپدیت متوقف می‌شه و هیچ‌کدوم از هندلرهای گروهِ 0 اصلاً اجرا نمی‌شن.

🛡 امنیت

• آنتی‌اسپم — نرخ‌سنج لغزنده (sliding window) با Redis؛ محدودیت ۱۲ پیام در ۵ ثانیه، ۳۰ پیام در ۳۰ ثانیه (flood)، ۸ callback در ۱۰ ثانیه — تخطی = بلاک موقت ۶۰ ثانیه‌ای

• پاک‌سازی ورودی — حذف null byte، کنترل‌کاراکترها و normalize یونیکد (NFC) روی تمام فیلدهای متنی کاربر

• جلوگیری از HTML injection — تمام داده‌های کاربر قبل از درج در پیام‌های HTML-mode با html.escape escape می‌شن

• محدودیت طول فیلد — نام نمایشی ۲۴ کاراکتر، بیو ۱۵۰ کاراکتر، تگ واکنش ۲۰ کاراکتر (server-side)

📍 افراد نزدیک

• یافتن کاربران در محدوده‌ی جغرافیایی با PostGIS

• فیلترِ شعاعی — انتخابِ محدوده‌ی جستجو بینِ ۵، ۱۰، ۲۰، یا ۵۰ کیلومتری

• لیستِ نتایج — هر نتیجه با نام، لینکِ پروفایلِ عمومی (/user_<code>)، فاصله‌ی تقریبی، و وضعیتِ آنلاینی نمایش داده می‌شه؛ حداکثر ۵۰ نفر در هر شعاع، مرتب‌شده بر اساسِ زودترین آنلاینی (نه صرفاً نزدیک‌ترین فاصله)، با صفحه‌بندیِ ۲۰تایی و دکمه‌ی صفحه‌ی بعد/قبل

• ذخیره‌ی موقعیت مکانی با رضایت کاربر

---

🛠 تکنولوژی‌ها

لایه	ابزار
زبان	Python 3.11
فریم‌ورک ربات	python-telegram-bot 21 (async)
دیتابیس	PostgreSQL + PostGIS
ORM	SQLAlchemy (async) + asyncpg
کش / real-time	Redis
هوش مصنوعی — تصویر	Google Gemini
هوش مصنوعی — گزارش	DeepSeek
مانیتورینگ	Prometheus + Grafana
آنتی‌اسپم	Redis sliding window
استقرار	Docker Compose

---

🚀 راه‌اندازی

پیش‌نیازها

• Docker و Docker Compose
• توکن ربات تلگرام از @BotFather
• API key برای Google Gemini (بررسی عکس پروفایل و مدیریت محتوا)
• API key برای DeepSeek (تحلیل گزارش‌ها و قضاوت تخلفات)

مراحل

# ۱. کلون کن
git clone https://github.com/Moorgan21/bluechat.git
cd bluechat

# ۲. فایل env بساز
cp .env.example .env
# مقادیر .env رو پر کن

# ۳. دیتابیس رو بساز
psql $DATABASE_URL -f schema.sql

# ۴. اجرا کن
docker compose up -d --build

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

BOT_TOKEN=          # توکن ربات از BotFather
BOT_USERNAME=       # یوزرنیم ربات (بدون @)
DATABASE_URL=       # آدرس PostgreSQL (primary)
READ_DATABASE_URL=  # آدرس read replica — اگه خالی باشه از primary استفاده می‌شه
REDIS_URL=          # آدرس Redis
GEMINI_API_KEY=     # کلید Google Gemini (مدیریت محتوا و تصویر)
DEEPSEEK_API_KEY=   # کلید DeepSeek (قضاوت گزارش‌ها)
GEMINI_RPM=100      # حداکثر درخواست به Gemini در هر دقیقه (پیش‌فرض: ۱۰۰)
DB_POOL_SIZE=20     # اندازه connection pool دیتابیس (پیش‌فرض: ۲۰)
DB_MAX_OVERFLOW=40  # حداکثر اتصال اضافه (پیش‌فرض: ۴۰)
WEBHOOK_URL=        # آدرس کامل webhook — اگه خالی باشه polling استفاده می‌شه
WEBHOOK_SECRET=     # توکن امنیتی webhook (یه رشته تصادفی)
WEBHOOK_PORT=8080   # پورت داخلی bot برای دریافت webhook (پیش‌فرض: ۸۰۸۰)
GRAFANA_PASSWORD=   # رمز ورود Grafana (پیش‌فرض: admin)

# آنتی‌اسپم (اختیاری — مقادیر پیش‌فرض برای اکثر حالت‌ها کافیه)
SPAM_MSG_LIMIT=12         # حداکثر پیام در پنجره‌ی کوتاه
SPAM_MSG_WINDOW=5         # پنجره‌ی کوتاه (ثانیه)
SPAM_FLOOD_LIMIT=30       # حداکثر پیام در پنجره‌ی flood
SPAM_FLOOD_WINDOW=30      # پنجره‌ی flood (ثانیه)
SPAM_CMD_LIMIT=8          # حداکثر callback/دستور
SPAM_CMD_WINDOW=10        # پنجره‌ی callback (ثانیه)
SPAM_BLOCK_DURATION=60    # مدت بلاک موقت (ثانیه)

---

🧪 تست‌ها

تست‌های واحد (tests/) روی یه دیتابیس PostgreSQL و یه ایندکسِ Redis کاملاً ایزوله از پروداکشن اجرا می‌شن — conftest.py عمداً قبل از اجرای هر تستی چک می‌کنه که DATABASE_URL به دیتابیسی با نام شاملِ _test و REDIS_URL به ایندکسِ ۱۵ اشاره کنه، وگرنه کلِ session بلافاصله fail می‌شه (برای جلوگیریِ قطعی از دست‌کاریِ تصادفیِ دیتای واقعی).

# ۱. یه دیتابیسِ تستی بساز (یک‌بار کافیه)
createdb -U bluechat bluechat_test
DATABASE_URL=postgresql+asyncpg://bluechat:bluechat@localhost:5432/bluechat_test \
  python3 -c "import asyncio, db; asyncio.run(db.init_db())"

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

# ۳. اجرا کن (حتماً با env جداگانه، نه env پروداکشن)
DATABASE_URL=postgresql+asyncpg://bluechat:bluechat@localhost:5432/bluechat_test \
REDIS_URL=redis://localhost:6379/15 \
  pytest -v

اگه با Docker Compose کار می‌کنی، همین دستورات رو از داخلِ کانتینرِ bot (که به شبکه‌ی postgres/redis دسترسی داره) با docker compose exec bot sh -c "..." اجرا کن.

---

📊 مانیتورینگ

معماری

bot / worker  ──► prometheus_client (port 8081)  ─┐
node-exporter ──► سیستم (CPU، RAM، دیسک)          ├──► Prometheus ──► Grafana
postgres-exporter ──► دیتابیس                     │
redis-exporter ──► Redis                          ─┘

دسترسی به Grafana

پنل مانیتورینگ از طریق nginx روی آدرس زیر در دسترسه:

https://your-domain.com/grafana/

• user: admin
• pass: مقدار GRAFANA_PASSWORD در .env (پیش‌فرض: admin)

متریک‌های ربات

متریک	نوع	توضیح
bot_active_chats	Gauge	تعداد چت‌های در حال اجرا
bot_waiting_users	Gauge	کاربران در صف انتظار
bot_ai_queue_size	Gauge	جاب‌های AI در انتظار پردازش
bot_messages_relayed_total	Counter	کل پیام‌های relay شده در چتِ ۱به۱ (پیام‌های اتاق جداگانه شمرده می‌شن)
bot_chats_started_total	Counter	کل چت‌های شروع‌شده
bot_chats_ended_total	Counter	کل چت‌های پایان‌یافته
bot_ai_jobs_processed_total	Counter	کل جاب‌های AI پردازش‌شده
bot_spam_blocks_total	Counter	درخواست‌های مسدودشده توسط spam guard (label: kind)
bot_rooms_created_total	Counter	کل اتاق‌های چتِ ساخته‌شده
bot_room_joins_total	Counter	کل عضویت‌های موفق در اتاق (فوری یا از صف)
bot_room_messages_relayed_total	Counter	کل پیام‌های relay شده داخلِ اتاق‌های چت
bot_room_auto_deleted_total	Counter	اتاق‌هایی که با ماندنِ فقط owner خودکار حذف شدن

متریک‌های دیتابیس (custom queries)

متریک	توضیح
pg_users_total_count	کل کاربران ثبت‌شده
pg_users_total_new_today	کاربران جدید ۲۴ ساعت اخیر
pg_users_total_new_week	کاربران جدید هفته اخیر
pg_users_by_gender_count	تعداد کاربر به تفکیک جنسیت
pg_users_by_province_count	تعداد کاربر به تفکیک استان
pg_users_by_city_count	تعداد کاربر به تفکیک شهر
pg_total_coins_total	مجموع سکه‌های همه کاربران
pg_warnings_total	کل اخطارهای صادرشده توسط DeepSeek
pg_banned_users_total	کل کاربران بن‌شده
pg_banned_users_by_deepseek	بن‌شده‌های خودکار توسط DeepSeek (۵+ اخطار)
pg_gemini_bans_unique_users_banned	کاربران یونیک بن‌شده توسط Gemini
pg_gemini_bans_profile_report_guilty	کل احکام guilty توسط Gemini

داشبورد پیش‌فرض

داشبورد Blue Chat Bot به‌صورت خودکار هنگام راه‌اندازی بارگذاری می‌شه و در ۶ بخش سازمان‌یافته:

بخش	محتوا
⚡ وضعیت لحظه‌ای	چت فعال، صف انتظار، صف AI، CPU/RAM/دیسک (Gauge)
👥 آمار کاربران	کل/جدید کاربران، سکه‌ها، توزیع جنسیت، جدول شهر/استان
🤖 هوش مصنوعی	اخطارهای DeepSeek، بن‌های Gemini، جاب‌های AI
📈 ترافیک	نرخ پیام relay، چت شروع/پایان
🛡 آنتی اسپم	بلاک‌های ۲۴ ساعت، نرخ لحظه‌ای، timeseries موج حملات
🏠 اتاق‌های چت	پیام‌های اتاق در ثانیه، نرخ ساخت/عضویت، کل اتاق‌ها، حذفِ خودکار
🖥️ زیرساخت	CPU، RAM، Redis، اتصالات PostgreSQL

---

⚡ مقیاس‌پذیری

ظرفیت فعلی

معیار	ظرفیت	محدودکننده
کاربر ثبت‌شده (کل)	نامحدود	PostgreSQL
کاربر فعال ماهانه (MAU)	~۵۰,۰۰۰–۱۰۰,۰۰۰	زیرساخت سرور
کاربر همزمان آنلاین	~۱,۸۰۰	Telegram API (30 msg/s رایگان)
چت همزمان فعال	~۱۰۰–۲۰۰ جفت	Telegram API (30 msg/s رایگان)
اتصال همزمان به DB	حداکثر ۶۰	pool_size=20, max_overflow=40

سقف اصلی: محدودیت ۳۰ پیام در ثانیه Telegram برای همه ربات‌ها صدق می‌کنه. با فعال‌سازی Paid Broadcast در BotFather این سقف به ۱,۰۰۰ msg/s می‌رسد.

ظرفیت با Paid Broadcast (1,000 msg/s)

سرعت چت	چت همزمان	کاربر همزمان
۱ پیام/ثانیه (خیلی سریع)	۱,۰۰۰ جفت	~۲,۰۰۰ نفر
۱ پیام/۵ ثانیه (نرمال)	۵,۰۰۰ جفت	~۱۰,۰۰۰ نفر
۱ پیام/۳۰ ثانیه (کند)	۳۰,۰۰۰ جفت	~۶۰,۰۰۰ نفر

هزینه: هر پیام بیشتر از سقف رایگان ۳۰/s برابر ۰.۱ Star از موجودی ربات کسر می‌شه. نیازی به تغییر کد نیست — فقط از BotFather فعال میشه.

نتیجه: با ترکیب افزایش زیرساخت سرور (CPU، RAM، DB replica، Redis Cluster) و فعال‌سازی Telegram Paid Broadcast، مقیاس‌پذیری ربات عملاً نامحدود میشه و هیچ سقف ثابتی وجود نداره.

ویژگی‌های مقیاس‌پذیری

ویژگی	جزئیات
Webhook	تلگرام آپدیت‌ها رو push می‌کنه؛ latency کمتر و overhead polling حذف شده
asyncio غیرمسدودکننده	تمام I/O async هستن؛ هیچ عملیاتی event loop رو بلاک نمی‌کنه
AI worker جداگانه	worker.py در پروسه‌ی مستقل؛ جاب‌ها روی Redis queue ماندگارن و با restart از دست نمیرن
Rate limiter Gemini	Token bucket با نرخ قابل تنظیم (GEMINI_RPM) از خطای ۴۲۹ جلوگیری می‌کنه
Redis برای state	جفت‌شدن، صف انتظار و وضعیت چت in-memory نگه داشته می‌شن؛ latency زیر ۱ms
matchingِ atomic با Lua	جستجو-یا-صف‌شدنِ چتِ ۱به۱ توی یه اسکریپتِ Lua واحد اجرا می‌شه؛ بدونِ فاصله‌ی زمانیِ TOCTOU بینِ دو کاربرِ هم‌زمان
DB connection pool	پیش‌فرض ۲۰+۴۰ اتصال همزمان؛ قابل تنظیم با DB_POOL_SIZE و DB_MAX_OVERFLOW
Read replica	با تنظیم READ_DATABASE_URL query های خواندنی به replica هدایت می‌شن

---

🏗 معماری

┌─────────────────────────────────────────┐
│              Telegram API               │
└────────────────┬────────────────────────┘
                 │
┌────────────────▼────────────────────────┐
│           python-telegram-bot 21        │
│            (async webhook)              │
└──────┬──────────────┬───────────────────┘
       │              │
┌──────▼──────┐ ┌─────▼──────┐
│  PostgreSQL │ │   Redis    │
│  + PostGIS  │ │  real-time │
│  (دیتا دائم)│ │ (session/  │
│             │ │  matching) │
└──────┬──────┘ └─────┬──────┘
       │              │
┌──────▼──────────────▼───────────────────┐
│         Gemini API + DeepSeek API       │
│    (مدیریت محتوا + قضاوت گزارش‌ها)     │
└─────────────────────────────────────────┘

---

📁 ساختار پروژه

bluechat/
├── main.py               # نقطه‌ی ورود و routing اصلی
├── db/                    # لایه‌ی دیتابیس (پکیج)
│   ├── connections.py     # engine/session/Base و init_db()
│   ├── models.py          # enumها و کلاس‌های ORM (جدول‌ها)
│   └── queries.py         # توابعِ async روی مدل‌ها (کوین، گزارش، واکنش و...)
├── redis_client.py       # تمام عملیات Redis
├── keyboards.py          # کیبوردهای inline و reply
├── metrics.py            # متریک‌های Prometheus (counters و gauges)
├── security.py           # پاک‌سازی ورودی، escape HTML، جلوگیری از injection
├── spam_guard.py         # آنتی‌اسپم — sliding window rate limiter با Redis
├── schema.sql            # ساختار کامل دیتابیس (از صفر)
├── handlers/
│   ├── chat/              # منطق چت ناشناس (پکیج)
│   │   ├── matching.py     # انتخاب جنسیت، صف‌بندی، matching، timeout صف
│   │   ├── session.py      # پایانِ چت (/stop, /next)، تاییدِ پایان، ثبتِ سشن
│   │   ├── relay.py        # انتقالِ پیام/ویرایش/ریکشن
│   │   └── extras.py       # پروفایلِ طرفِ مقابل، چتِ امن، پاک‌سازیِ تاریخچه
│   ├── chatroom/           # منطق اتاقِ چتِ گروهی (پکیج)
│   │   ├── creation.py     # ساختِ اتاق و نمایشِ وضعیت
│   │   ├── matching.py     # عضویت، صفِ انتظار، لغو، trigger پرکردنِ اتاق از صف
│   │   ├── relay.py        # رله‌ی یک‌به‌چندِ پیام + حذف/اخراج با ریپلای
│   │   ├── membership.py   # ترکِ اتاق توسطِ عضوِ عادی
│   │   └── moderation.py   # حذف/بستن/بازکردنِ اتاق و پاک‌سازیِ تاریخچه توسطِ owner
│   ├── profile.py        # پروفایل و onboarding
│   ├── public_profile.py # پروفایل عمومی و درخواست چت
│   ├── anon_note.py      # پیام‌های ناشناس و دایرکت
│   ├── search.py         # جستجوی هدفمند با فیلتر
│   ├── nearby.py         # افراد نزدیک (PostGIS)
│   ├── coins.py          # سیستم سکه و رفرال
│   ├── report.py         # گزارش تخلف
│   ├── settings.py       # تنظیمات کاربر
│   └── menu.py           # منوی اصلی
├── judge.py              # قضاوت گزارش‌ها با DeepSeek
├── moderation.py         # بررسی عکس پروفایل با Gemini
├── gemini_limiter.py     # rate limiter برای Gemini API (token bucket)
├── worker.py             # AI worker — پردازش صف قضاوت در پروسه‌ی جداگانه
├── verdict_notify.py     # اطلاع‌رسانی نتیجه‌ی قضاوت (مشترک بین bot و worker)
├── ban_enforcement.py    # اثرِ فوریِ بن روی چتِ ۱به۱/اتاقِ چتِ فعلیِ کاربر
├── tests/                 # تست‌های واحد (pytest، روی دیتابیس/Redis ایزوله‌ی تستی)
├── prometheus.yml        # تنظیمات scrape برای Prometheus
├── pg_custom_queries.yml # کوئری‌های سفارشی postgres-exporter
├── grafana/
│   ├── provisioning/
│   │   ├── datasources/  # auto-provision اتصال به Prometheus
│   │   └── dashboards/   # auto-provision مسیر داشبوردها
│   └── dashboards/
│       └── bluechat.json # داشبورد پیش‌فرض Blue Chat Bot
├── iran_cities.json      # لیست ۳۱ استان و تمام شهرهای ایران
├── LICENSE               # GNU Affero General Public License v3 (AGPL-3.0)
├── requirements.txt      # وابستگی‌های Python (پروداکشن)
└── requirements-dev.txt  # وابستگی‌های اضافیِ تست (pytest)

---

📜 لایسنس

Copyright (C) 2026 Dariush Lashani

این پروژه تحت مجوز GNU Affero General Public License v3.0 منتشر شده.

برای جزئیات کامل فایل LICENSE را ببینید یا به gnu.org/licenses/agpl-3.0 مراجعه کنید.