DispelEvilBot

Telegram-бот клана Dispel Evil (aiogram 3 + Postgres). Монорепозиторий: общий пакет common используется сервисом бота bot (и, в будущем, админкой admin).

Структура

common/     # общий пакет: config, logging, db, repositories, models, texts, analytics
bot/        # сервис бота: handlers, services, keyboards, middlewares, notifications
sql/        # миграции Flyway (V__*.sql, R__*.sql)
clickhouse/ # init-скрипты ClickHouse (схема аналитики)
docs/       # документация (docs/events.md — события аналитики)
scripts/    # эксплуатационные скрипты (проверка контура, бэкап событий)
images/     # статичные картинки (приветствие)
deploy/     # материалы деплоя (Caddyfile, инструкции)
tests/      # тесты
Dockerfile  # образ бота
docker-compose.yml / docker-compose.prod.yml
.gitea/     # CI (Gitea Actions)

Требования

• Python 3.12
• PostgreSQL 14+
• ClickHouse 25.3 (аналитика событий; можно выключить — CLICKHOUSE_ENABLED=false)

Настройка

cp .env.example .env
# заполнить BOT_TOKEN, DB_*, чаты и ADMIN_IDS
pip install -r requirements.txt

Запуск

APP_ENV=dev python -m bot     # dev
APP_ENV=prod python -m bot    # prod

или через ./start.sh (режим берётся из APP_ENV).

База данных

Схема управляется миграциями Flyway в sql/ (V__*.sql — versioned, R__*.sql — repeatable). При Docker-развёртывании накат выполняется автоматически сервисом migrate перед ботом.

Аналитика (ClickHouse)

Все значимые действия бота пишутся в ClickHouse в единую таблицу analytics.events. Контракт событий — docs/events.md (типы, payload, примеры запросов).

• схема — clickhouse/init/001_events.sql (применяется при первой инициализации контейнера);
• клиент и батчинг — common/analytics/ (запись неблокирующая, сбой ClickHouse не влияет на бота);
• сырые события живут на VPS 7 дней и ежедневно уезжают архивом на домашний сервер, на VPS остаются агрегаты (events_daily, money_daily) — см. DEPLOY.md;
• выключается флагом CLICKHOUSE_ENABLED=false.

Уведомления в чат логов

В ALERT_CHAT_ID (если задан) уходят: вход и выход участников, успешные очищения и ежечасный пинг «бот живой». Отправка не критична: ошибки только пишутся в лог.

Docker

Локальный запуск (postgres + migrate + clickhouse + bot):

cp .env.example .env      # заполнить
docker compose up --build

Прод/test-контуры — один docker-compose.prod.yml, разделяются Compose-проектом и env-файлом:

docker compose -p prod --env-file env/prod.env -f docker-compose.prod.yml up -d
docker compose -p test --env-file env/test.env -f docker-compose.prod.yml up -d

Пошаговое развёртывание контуров test/prod — см. DEPLOY.md.

Разработка

pip install -r requirements-dev.txt
ruff check .
black --check .
pytest

Бэкап событий

Сырые события ClickHouse ежедневно выгружаются архивом на домашний сервер (по cron), на VPS остаются только агрегаты и последние дни сырых данных:

make backup E=test     # ./scripts/clickhouse_backup.sh test

Настройка и расписание — см. DEPLOY.md.

Версионирование

• Единый источник версии — common/version.py (__version__), текущая — 0.3.5.
• Схема — SemVer-подобная (MAJOR.MINOR.PATCH); git-тег = v + версия (v0.1).
• Docker-образы тегируются версией (Блок 2), события ClickHouse получают bot_version (Блок 3).
• Выпуск: изменить common/version.py → коммит → аннотированный тег vX.Y → git push --tags.

Процесс работы с git

Проект ведётся в режиме trunk-based (один разработчик): основная работа — прямо в master.

• master — интеграционная ветка, всегда в рабочем состоянии.
• Релизы — аннотированные теги vX.Y (см. «Версионирование»).
• Для крупных/рискованных изменений — короткая ветка feature/... и merge обратно в master.
• Push в master → CI (Gitea Actions) собирает образ; авто-выката в прод нет.
• Выкатка: сначала контур test, затем prod по подтверждению (см. Блок 2.5 плана).
• Переход на «ветки + PR» и защиту ветки — когда появится второй разработчик.

# обычная работа: сообщение без префиксов, по существу изменения
git add -A
git commit -m "Краткое описание изменения"
git push origin master

# выпуск релиза
# 1) поднять __version__ в common/version.py
git commit -am "Версия X.Y"
git tag -a vX.Y -m "Release vX.Y"
git push origin master --tags

Команды бота

/ник, /список, /кто, /инфо, /помощь, /очищение, /яички, /магазин, /рейтинг, /отписка, /подписка.

Переменные окружения

• общие — .env.example (включая CLICKHOUSE_* и параметры батчинга ANALYTICS_*);
• контуры — env/prod.env.example, env/test.env.example;
• бэкап событий — env/backup.env.example.