146 lines
6.6 KiB
Markdown
146 lines
6.6 KiB
Markdown
# 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`)
|
||
|
||
## Настройка
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
# заполнить BOT_TOKEN, DB_*, чаты и ADMIN_IDS
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
## Запуск
|
||
|
||
```bash
|
||
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`](docs/events.md) (типы, payload, примеры запросов).
|
||
|
||
- схема — `clickhouse/init/001_events.sql` (применяется при первой инициализации контейнера);
|
||
- клиент и батчинг — `common/analytics/` (запись неблокирующая, сбой ClickHouse не влияет на бота);
|
||
- сырые события живут на VPS 7 дней и ежедневно уезжают архивом на домашний сервер,
|
||
на VPS остаются агрегаты (`events_daily`, `money_daily`) — см. [DEPLOY.md](DEPLOY.md);
|
||
- выключается флагом `CLICKHOUSE_ENABLED=false`.
|
||
|
||
## Уведомления в чат логов
|
||
|
||
В `ALERT_CHAT_ID` (если задан) уходят: вход и выход участников, успешные очищения и
|
||
ежечасный пинг «бот живой». Отправка не критична: ошибки только пишутся в лог.
|
||
|
||
## Docker
|
||
|
||
Локальный запуск (postgres + migrate + clickhouse + bot):
|
||
|
||
```bash
|
||
cp .env.example .env # заполнить
|
||
docker compose up --build
|
||
```
|
||
|
||
Прод/test-контуры — один `docker-compose.prod.yml`, разделяются Compose-проектом и env-файлом:
|
||
|
||
```bash
|
||
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`](DEPLOY.md).
|
||
|
||
## Разработка
|
||
|
||
```bash
|
||
pip install -r requirements-dev.txt
|
||
ruff check .
|
||
black --check .
|
||
pytest
|
||
```
|
||
|
||
## Бэкап событий
|
||
|
||
Сырые события ClickHouse ежедневно выгружаются архивом на домашний сервер (по cron),
|
||
на VPS остаются только агрегаты и последние дни сырых данных:
|
||
|
||
```bash
|
||
make backup E=test # ./scripts/clickhouse_backup.sh test
|
||
```
|
||
|
||
Настройка и расписание — см. [`DEPLOY.md`](DEPLOY.md).
|
||
|
||
## Версионирование
|
||
|
||
- Единый источник версии — `common/version.py` (`__version__`), текущая — `0.3.6`.
|
||
- Схема — 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» и защиту ветки — когда появится второй разработчик.
|
||
|
||
```bash
|
||
# обычная работа: сообщение без префиксов, по существу изменения
|
||
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`.
|