113 lines
4.2 KiB
Markdown
113 lines
4.2 KiB
Markdown
# DispelEvilBot
|
||
|
||
Telegram-бот клана Dispel Evil (aiogram 3 + Postgres). Монорепозиторий:
|
||
общий пакет `common` используется сервисом бота `bot` (и, в будущем, админкой `admin`).
|
||
|
||
## Структура
|
||
|
||
```
|
||
common/ # общий пакет: config, logging, db, repositories, models, texts
|
||
bot/ # сервис бота: handlers, services, keyboards, notifications
|
||
sql/ # миграции Flyway (V__*.sql, R__*.sql)
|
||
images/ # статичные картинки (приветствие)
|
||
deploy/ # материалы деплоя (Caddyfile, инструкции)
|
||
tests/ # тесты
|
||
Dockerfile # образ бота
|
||
docker-compose.yml / docker-compose.prod.yml
|
||
.gitea/ # CI (Gitea Actions)
|
||
```
|
||
|
||
## Требования
|
||
|
||
- Python 3.12
|
||
- PostgreSQL 14+
|
||
|
||
## Настройка
|
||
|
||
```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` перед ботом.
|
||
|
||
## Docker
|
||
|
||
Локальный запуск (postgres + migrate + 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
|
||
```
|
||
|
||
## Версионирование
|
||
|
||
- Единый источник версии — `common/version.py` (`__version__`), текущая — `0.3.3`.
|
||
- Схема — 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 "feat: ..."
|
||
git push origin master
|
||
|
||
# выпуск релиза
|
||
# 1) поднять __version__ в common/version.py
|
||
git commit -am "chore: bump version to X.Y"
|
||
git tag -a vX.Y -m "Release vX.Y"
|
||
git push origin master --tags
|
||
```
|
||
|
||
## Команды бота
|
||
|
||
`/ник`, `/список`, `/кто`, `/инфо`, `/помощь`, `/очищение`, `/яички`,
|
||
`/магазин`, `/рейтинг`, `/отписка`, `/подписка`.
|
||
|
||
## Переменные окружения
|
||
|
||
См. `.env.example`.
|