Architecture

Архитектура

AFZVPN Bot состоит из Telegram-бота, aiohttp web app, локальной базы, Redis и внешних 3X-UI панелей. 3X-UI остается источником правды для реальных VPN-клиентов, inbound, traffic и expiry.

Runtime

Telegram
  -> aiogram Router
  -> Services layer
  -> SQLite / Redis / 3X-UI
  -> aiohttp public endpoints
  -> Happ / payment gateways / web cabinet

Компоненты

Компонент	Ответственность
app/__main__.py	старт bot + web app, polling/webhook, scheduler, Redis, payment gateways
app/bot/routers	Telegram UI, callback navigation, user/admin flows
app/bot/services	подписки, VPN, server pool, notifications, job locks, runtime metrics
app/bot/tasks	фоновые reconciliation и expiry jobs
app/web	subscription proxy, additional profiles, connection redirect, cabinet
app/db	SQLAlchemy models, Alembic migrations
plans.json	коммерческий каталог тарифов

Public Endpoints

Route	Назначение
/healthz	health check
/webhook	Telegram webhook endpoint
/connection	redirect для Happ deep-links
/sub/{vpn_id}	основная подписка
/wl-filtered/{vpn_id}	рекомендуемая подписка обхода БС
/wl/{vpn_id}	запасная подписка обхода БС
/cabinet/{vpn_id}	web cabinet
payment callbacks	YooKassa, YooMoney, Cryptomus, Heleket

Data Ownership

Данные	Где источник правды
Telegram user, plan, local state	bot SQLite
VPN client, traffic, expiry	3X-UI
FSM/background state	Redis
тарифы	plans.json
платежные транзакции	bot SQLite + payment gateway callback

Важные Границы

• Бот не должен отдавать подписку неактивному пользователю.
• Web endpoints валидируют vpn_id и состояние подписки.
• Runtime state не хранится в Git.
• Миграции Alembic должны быть совместимы с существующей production-базой.