generated from FOSS/Bot-Template
Update README.md
This commit is contained in:
@@ -1,8 +1,6 @@
|
|||||||
# Djimbo Template для Telegram-ботов на aiogram 3
|
# Channel Notifier
|
||||||
|
|
||||||
Шаблон для быстрого старта Telegram-бота на `aiogram 3`, `SQLAlchemy`, `aiosqlite`, `Alembic` и `.env`-настройках через `pydantic-settings`.
|
Telegram-бот на aiogram 3, который автоматически отправляет личное сообщение пользователям, подавшим заявку в закрытый канал.
|
||||||
|
|
||||||
Внутри уже есть базовая структура проекта, подключение роутеров, middleware для пользователя, админские фильтры, логирование, миграции БД и пример пользовательского/админского меню.
|
|
||||||
|
|
||||||
## Стек
|
## Стек
|
||||||
|
|
||||||
@@ -62,46 +60,6 @@ python migrate.py up
|
|||||||
python main.py
|
python main.py
|
||||||
```
|
```
|
||||||
|
|
||||||
## Docker Compose
|
|
||||||
|
|
||||||
Запуск через compose:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
docker compose up --build
|
|
||||||
```
|
|
||||||
|
|
||||||
Остановка:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
docker compose down
|
|
||||||
```
|
|
||||||
|
|
||||||
`docker-compose.yml` использует `Dockerfile`: Dockerfile собирает образ, а compose управляет запуском, `.env`, volume и restart-политикой.
|
|
||||||
|
|
||||||
При запуске контейнер сначала применяет миграции командой `python migrate.py up`, а потом запускает бота через `python main.py`.
|
|
||||||
|
|
||||||
Volume `./tgbot/data:/app/tgbot/data` нужен, чтобы база и логи не пропадали после остановки контейнера.
|
|
||||||
|
|
||||||
Если compose не нужен, можно запустить Docker вручную:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
docker build -t djimbo-template .
|
|
||||||
docker run --rm --env-file .env -v "$(pwd)/tgbot/data:/app/tgbot/data" djimbo-template
|
|
||||||
```
|
|
||||||
|
|
||||||
## pyproject.toml
|
|
||||||
|
|
||||||
`pyproject.toml` описывает проект для современных Python-инструментов.
|
|
||||||
|
|
||||||
В этом шаблоне он нужен для:
|
|
||||||
|
|
||||||
- указания версии Python;
|
|
||||||
- описания зависимостей проекта;
|
|
||||||
- установки проекта как пакета через `pip install -e .`;
|
|
||||||
- настройки сборки через `setuptools`.
|
|
||||||
|
|
||||||
`requirements.txt` оставлен для простого запуска и Docker. Если коротко: `requirements.txt` удобен для установки зависимостей, а `pyproject.toml` описывает сам проект.
|
|
||||||
|
|
||||||
## Настройки
|
## Настройки
|
||||||
|
|
||||||
| Параметр | Что делает |
|
| Параметр | Что делает |
|
||||||
@@ -116,187 +74,4 @@ docker run --rm --env-file .env -v "$(pwd)/tgbot/data:/app/tgbot/data" djimbo-te
|
|||||||
| `PATH_DATABASE` | Путь к SQLite-базе |
|
| `PATH_DATABASE` | Путь к SQLite-базе |
|
||||||
| `PATH_LOGS` | Путь к файлу логов |
|
| `PATH_LOGS` | Путь к файлу логов |
|
||||||
|
|
||||||
По умолчанию `BOT_DATABASE_EXPORT=False`. Это специально: база может содержать персональные данные, поэтому экспорт надо включать руками и осознанно.
|
По умолчанию `BOT_DATABASE_EXPORT=False`. Это специально: база может содержать персональные данные, поэтому экспорт надо включать руками и осознанно.
|
||||||
|
|
||||||
## Структура проекта
|
|
||||||
|
|
||||||
```text
|
|
||||||
.
|
|
||||||
├── main.py # Точка входа
|
|
||||||
├── migrate.py # Удобная CLI-обертка для Alembic
|
|
||||||
├── Dockerfile # Запуск шаблона в Docker
|
|
||||||
├── docker-compose.yml # Удобный запуск Docker-контейнера
|
|
||||||
├── .dockerignore # Что не попадет в Docker-образ
|
|
||||||
├── pyproject.toml # Метаданные проекта
|
|
||||||
├── alembic.ini # Настройки Alembic
|
|
||||||
├── migrations/ # Миграции базы данных
|
|
||||||
├── .env.example # Пример локального .env
|
|
||||||
├── tgbot/
|
|
||||||
│ ├── data/config.py # Настройки и пути
|
|
||||||
│ ├── database/ # SQLAlchemy-модели и репозитории
|
|
||||||
│ ├── keyboards/ # Reply и inline-клавиатуры
|
|
||||||
│ ├── middlewares/ # Middleware
|
|
||||||
│ ├── routers/ # Обработчики aiogram
|
|
||||||
│ ├── services/ # Внешние сервисы и aiohttp-сессия
|
|
||||||
│ └── utils/ # Общие утилиты
|
|
||||||
└── requirements.txt
|
|
||||||
```
|
|
||||||
|
|
||||||
## База данных
|
|
||||||
|
|
||||||
Проект использует SQLite через `aiosqlite`, но работа с таблицами идёт через async `SQLAlchemy`.
|
|
||||||
|
|
||||||
Ключевые файлы БД:
|
|
||||||
|
|
||||||
- `core.py` - `Base`, `engine`, `session_factory`, `session_scope`
|
|
||||||
- `repository.py` - базовый репозиторий и проверка готовности БД
|
|
||||||
- `migration_runner.py` - запуск Alembic из кода
|
|
||||||
- `db_users.py` - пользователи Telegram
|
|
||||||
- `db_settings.py` - настройки бота в БД
|
|
||||||
|
|
||||||
### UNIQUE
|
|
||||||
|
|
||||||
В таблице пользователей поле `user_id` уникальное.
|
|
||||||
|
|
||||||
Это значит, что один Telegram-пользователь не может появиться в таблице два раза. Если пользователь уже есть, база не создаст дубль.
|
|
||||||
|
|
||||||
### UPSERT
|
|
||||||
|
|
||||||
UPSERT - это логика “создай запись, а если она уже есть, обнови”.
|
|
||||||
|
|
||||||
В шаблоне пользователь добавляется по `user_id`. Если он уже есть, обновляются только изменившиеся поля: username, имя, фамилия и полное имя. Если данные не поменялись, лишнего UPDATE в БД не будет.
|
|
||||||
|
|
||||||
## Миграции
|
|
||||||
|
|
||||||
Миграции управляются через Alembic, но запускать их удобнее через готовый CLI.
|
|
||||||
|
|
||||||
Показать справку:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
python migrate.py
|
|
||||||
```
|
|
||||||
|
|
||||||
Применить все миграции:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
python migrate.py up
|
|
||||||
```
|
|
||||||
|
|
||||||
То же самое длинной командой:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
python migrate.py upgrade
|
|
||||||
```
|
|
||||||
|
|
||||||
Посмотреть текущую версию БД:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
python migrate.py status
|
|
||||||
```
|
|
||||||
|
|
||||||
Посмотреть историю:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
python migrate.py history
|
|
||||||
```
|
|
||||||
|
|
||||||
Создать новую миграцию вручную:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
python migrate.py new "add payments table"
|
|
||||||
```
|
|
||||||
|
|
||||||
Создать миграцию по изменениям SQLAlchemy-моделей:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
python migrate.py auto "add payments table"
|
|
||||||
```
|
|
||||||
|
|
||||||
Откатить последнюю миграцию:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
python migrate.py down
|
|
||||||
```
|
|
||||||
|
|
||||||
Полные Alembic-команды тоже доступны: `upgrade`, `downgrade`, `revision`, `current`, `history`, `heads`.
|
|
||||||
|
|
||||||
Короткие алиасы: `up`, `down`, `new`, `auto`, `autogen`, `cur`, `hist`, `st`.
|
|
||||||
|
|
||||||
## Роутеры
|
|
||||||
|
|
||||||
Роутеры подключаются в `tgbot/routers/__init__.py`.
|
|
||||||
|
|
||||||
Текущие группы:
|
|
||||||
|
|
||||||
- `main_start.py` - старт и главное меню
|
|
||||||
- `user/user_menu.py` - пользовательские обработчики
|
|
||||||
- `admin/admin_menu.py` - админские обработчики
|
|
||||||
- `main_missed.py` - fallback на неизвестные сообщения и callback
|
|
||||||
- `main_errors.py` - обработка безопасных Telegram-ошибок
|
|
||||||
|
|
||||||
Админский роутер уже закрыт фильтром `IsAdmin()` и для сообщений, и для callback query.
|
|
||||||
|
|
||||||
## Middleware
|
|
||||||
|
|
||||||
`ExistsUserMiddleware` добавляет или обновляет пользователя в БД и прокидывает объект пользователя в обработчик как `User`.
|
|
||||||
|
|
||||||
Чтобы не писать в БД на каждый одинаковый update, middleware кеширует пользователя по `user_id`.
|
|
||||||
|
|
||||||
Пример:
|
|
||||||
|
|
||||||
```python
|
|
||||||
async def handler(message: Message, User: UserModel):
|
|
||||||
await message.answer(User.user_fullname)
|
|
||||||
```
|
|
||||||
|
|
||||||
## Логирование
|
|
||||||
|
|
||||||
Логи пишутся в `tgbot/data/logs.log`.
|
|
||||||
|
|
||||||
Файл не растёт бесконечно: используется `RotatingFileHandler`, который вращает логи по размеру.
|
|
||||||
|
|
||||||
Админ может получить логи командой:
|
|
||||||
|
|
||||||
```text
|
|
||||||
/log
|
|
||||||
```
|
|
||||||
|
|
||||||
Очистить логи:
|
|
||||||
|
|
||||||
```text
|
|
||||||
/clear_log
|
|
||||||
```
|
|
||||||
|
|
||||||
## Админские команды
|
|
||||||
|
|
||||||
| Команда | Что делает |
|
|
||||||
| --- | --- |
|
|
||||||
| `/log` | Отправляет файл логов |
|
|
||||||
| `/clear_log` | Очищает файлы логов |
|
|
||||||
| `/db` | Отправляет файл БД, только если `BOT_DATABASE_EXPORT=True` |
|
|
||||||
|
|
||||||
Команда `/db` скрывается из меню команд, если экспорт БД выключен.
|
|
||||||
|
|
||||||
## Как добавить новую таблицу
|
|
||||||
|
|
||||||
1. Создать модель в `tgbot/database/`.
|
|
||||||
2. Импортировать её в `tgbot/database/__init__.py`.
|
|
||||||
3. Создать миграцию:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
python migrate.py auto "add new table"
|
|
||||||
```
|
|
||||||
|
|
||||||
4. Проверить созданный файл в `migrations/versions/`.
|
|
||||||
5. Применить миграцию:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
python migrate.py up
|
|
||||||
```
|
|
||||||
|
|
||||||
## Важно
|
|
||||||
|
|
||||||
- Не коммить `.env`, базу данных и логи.
|
|
||||||
- Если токен попал в Git, его надо перевыпустить у BotFather.
|
|
||||||
- Перед деплоем проверь `BOT_DATABASE_EXPORT`: на проде лучше держать `False`, если экспорт БД реально не нужен.
|
|
||||||
- Для нового проекта сначала менять тексты, команды и клавиатуры под свою логику, а потом уже добавлять бизнес-код.
|
|
||||||
Reference in New Issue
Block a user