Обзор
Бот использует PostgreSQL через SQLAlchemy 2.x async ORM. Все модели определены вapp/database/models.py.
Миграции (Alembic)
Миграции хранятся вmigrations/alembic/versions/.
alembic upgrade head через app/database/migrations.py.
Для существующих production баз после перехода на Alembic выполните
make migrate-stamp один раз.Настройка подключения
CRUD операции
Каждая сущность имеет свой CRUD-модуль вapp/database/crud/:
Enum-типы
Схема по доменам
Пользователи (3 таблицы)
users — центральная таблица, к ней привязаны все остальные сущности.
Связи:
subscription (1:1), transactions (1:N), referrals (self 1:N), user_promo_groups (1:N), tickets (1:N), referral_earnings (1:N), discount_offers (1:N)
cabinet_refresh_tokens — JWT refresh-токены для Cabinet.
partner_applications — заявки на партнерскую программу.
Подписки (5 таблиц)
subscriptions — VPN-подписка (1:1 с пользователем).
subscription_servers — привязка подписки к серверам.
subscription_conversions — конверсия триала в платную подписку.
subscription_events — журнал событий подписки (event_type, amount_kopeks, message, extra JSON).
traffic_purchases — докупки трафика (traffic_gb, expires_at = дата покупки + 30 дней).
Платежи и транзакции (12 таблиц)
transactions — единый финансовый реестр.
10 таблиц платежных провайдеров — по одной на каждый провайдер. Все содержат:
user_id, status, transaction_id, сумму и ID во внешней системе. Telegram Stars и Tribute не имеют отдельных таблиц — используют transactions напрямую.
payment_method_configs — настройки отображения платежных методов в Cabinet.
Промо-система (8 таблиц + 3 M2M)
promo_groups — группы со скидками.
M2M связи:
server_squads, tariffs, payment_method_configs
user_promo_groups — пользователь может состоять в нескольких группах (user_id + promo_group_id составной PK).
promocodes — промокоды (5 типов).
promocode_uses — журнал активаций (promocode_id, user_id, used_at).
discount_offers — персональные скидочные предложения.
promo_offer_templates — шаблоны предложений (тип, текст сообщения, кнопка, часы действия, серверы для test_access).
subscription_temporary_access — временный доступ к серверам через промо-предложения.
promo_offer_logs — журнал действий с предложениями (claimed, consumed, disabled).
Реферальная система (3 таблицы)
referral_earnings — начисления реферальных комиссий.
withdrawal_requests — заявки на вывод средств.
sent_notifications — трекинг отправленных уведомлений (предотвращает дублирование).
Поддержка (5 таблиц)
tickets — тикеты поддержки (status, priority, user_reply_block_permanent, user_reply_block_until).
ticket_messages — сообщения в тикетах (текст, медиа-вложения с media_file_id).
ticket_notifications — уведомления для Cabinet (notification_type: new_ticket, admin_reply, user_reply).
support_audit_logs — журнал действий модераторов (action, actor_user_id, target_user_id, details JSON).
broadcast_history — история рассылок.
Конкурсы (6 таблиц)
referral_contests — реферальные конкурсы (title, contest_type, start_at/end_at, daily_summary_times).
referral_contest_events — события конкурса (UNIQUE: contest_id + referral_id).
referral_contest_virtual_participants — виртуальные участники для буста лидерборда.
contest_templates — шаблоны ежедневных игр (7 типов).
contest_rounds — раунды игр (status: active/finished, winners_count).
contest_attempts — попытки участия (UNIQUE: round_id + user_id).
Кампании (2 таблицы)
advertising_campaigns — рекламные кампании с deep-link.
advertising_campaign_registrations — регистрации через кампании (UNIQUE: campaign_id + user_id).
Опросы (5 таблиц)
Цепочка:polls -> poll_questions -> poll_options -> poll_answers.
polls — опросы (title, reward_enabled, reward_amount_kopeks).
poll_responses — участие пользователя в опросе (UNIQUE: poll_id + user_id, reward_given).
Колесо фортуны (3 таблицы)
wheel_configs — конфигурация колеса (rtp_percent, spin_cost_stars, daily_spin_limit).
wheel_prizes — призы (prize_type: subscription_days/balance_bonus/traffic_gb/promocode/nothing, manual_probability).
wheel_spins — история вращений (user_id, prize_id, payment_type, is_applied).
Серверы и тарифы (3 таблицы)
tariffs — тарифные планы (см. Управление тарифами).
server_squads — серверные группы.
squads — устаревшая таблица серверов (заменена на server_squads).
Новости (3 таблицы)
news_articles — статьи новостей.
Индексы: slug (unique), composite
is_published + published_at DESC, composite is_published + category, created_at, FK-индексы.
news_categories — управляемые категории.
news_tags — управляемые теги.
Системные и контентные (12 таблиц)
Вебхуки (2 таблицы)
webhooks — настройки вебхуков (url, secret, event_type, failure_count, success_count).
webhook_deliveries — история доставок (status: pending/success/failed, attempt_number, next_retry_at).
Web API и Cabinet (2 таблицы)
web_api_tokens — API-ключи (token_hash UNIQUE, token_prefix, expires_at, is_active).
button_click_logs — журнал кликов по кнопкам меню (аналитика).