192 lines
6.0 KiB
Markdown
192 lines
6.0 KiB
Markdown
# Random Coffee Bot
|
||
|
||
Telegram бот для организации случайных встреч (Random Coffee) между участниками групп.
|
||
|
||
## Описание
|
||
|
||
Бот автоматически создает уникальные пары участников для неформальных встреч:
|
||
- 📊 Отправляет опросы участникам каждую пятницу
|
||
- 👥 Формирует пары каждое воскресенье
|
||
- 🔄 Отслеживает историю встреч (пары не повторяются)
|
||
- 🌐 Поддержка нескольких групп одновременно
|
||
- 🗄️ Миграции базы данных через Alembic
|
||
|
||
## Быстрый старт
|
||
|
||
### 1. Клонирование репозитория
|
||
|
||
```bash
|
||
git clone https://github.com/yourusername/random_coffee_bot.git
|
||
cd random_coffee_bot
|
||
```
|
||
|
||
### 2. Настройка окружения
|
||
|
||
Создайте файл `.env` на основе `.env.example`:
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
Заполните `.env`:
|
||
|
||
```env
|
||
bot__token=YOUR_BOT_TOKEN # Токен от @BotFather
|
||
bot__group_chat_ids='[]' # Оставьте пустым, группы добавятся через команды
|
||
bot__admin_chat_ids='[YOUR_TELEGRAM_ID]' # Ваш Telegram ID
|
||
db__url='sqlite+aiosqlite:///random_coffee.db'
|
||
```
|
||
|
||
**Как получить Telegram ID:**
|
||
- Напишите боту [@userinfobot](https://t.me/userinfobot)
|
||
|
||
### 3. Запуск
|
||
|
||
#### Docker (рекомендуется)
|
||
|
||
```bash
|
||
# Собрать и запустить
|
||
docker-compose up -d --build
|
||
|
||
# Просмотр логов
|
||
docker-compose logs -f
|
||
|
||
# Остановка
|
||
docker-compose down
|
||
```
|
||
|
||
#### Локально
|
||
|
||
```bash
|
||
# Установка зависимостей
|
||
uv sync
|
||
|
||
# Применить миграции
|
||
alembic upgrade head
|
||
|
||
# Запуск
|
||
python -m src.main
|
||
```
|
||
|
||
## Использование
|
||
|
||
### Команды для админов
|
||
|
||
**В личных сообщениях с ботом:**
|
||
- `/groups` - Список подключенных групп
|
||
|
||
**В группах (только админы):**
|
||
- `/add_group` - Добавить текущую группу
|
||
- `/remove_group` - Удалить текущую группу
|
||
- `/send_quiz` - Отправить опрос вручную
|
||
- `/create_pairs` - Создать пары вручную
|
||
|
||
### Автоматическое расписание
|
||
|
||
Бот работает по расписанию (московское время):
|
||
- **Пятница 17:00** - Отправка опроса участникам
|
||
- **Воскресенье 19:00** - Формирование и публикация пар
|
||
|
||
### Первая настройка
|
||
|
||
1. Запустите бота
|
||
2. Добавьте бота в нужные группы
|
||
3. Выдайте боту права администратора (для чтения сообщений)
|
||
4. Напишите боту в личку `/start`
|
||
5. В каждой группе напишите `/add_group`
|
||
|
||
## Архитектура
|
||
|
||
Проект следует принципам Clean Architecture:
|
||
|
||
```
|
||
src/
|
||
├── adapter/ # Внешние интерфейсы
|
||
│ ├── database/ # SQLAlchemy + async
|
||
│ └── telegram/ # Aiogram 3.x
|
||
├── controller/ # Обработчики и планировщик
|
||
├── usecase/ # Бизнес-логика
|
||
├── model/ # Модели данных
|
||
└── config.py # Конфигурация (Pydantic)
|
||
```
|
||
|
||
### Технологии
|
||
|
||
- **Python 3.13**
|
||
- **aiogram 3.x** - Telegram Bot API
|
||
- **SQLAlchemy 2.0** - ORM с async support
|
||
- **Alembic** - Миграции БД
|
||
- **APScheduler** - Планировщик задач
|
||
- **Pydantic** - Валидация конфигурации
|
||
- **uv** - Управление зависимостями
|
||
|
||
## Разработка
|
||
|
||
### Работа с базой данных
|
||
|
||
```bash
|
||
# Создать новую миграцию
|
||
alembic revision --autogenerate -m "описание"
|
||
|
||
# Применить миграции
|
||
alembic upgrade head
|
||
|
||
# Откатить миграцию
|
||
alembic downgrade -1
|
||
|
||
# Текущая версия
|
||
alembic current
|
||
```
|
||
|
||
### Структура базы данных
|
||
|
||
- **participants** - Участники опроса (очищается после создания пар)
|
||
- **pairs** - История всех пар (для предотвращения повторов)
|
||
- **poll_mappings** - Связь poll_id → group_id
|
||
|
||
### Docker команды
|
||
|
||
```bash
|
||
# Пересборка
|
||
docker-compose up -d --build
|
||
|
||
# Логи
|
||
docker-compose logs -f randomcoffee_bot
|
||
|
||
# Перезапуск
|
||
docker-compose restart
|
||
|
||
# Очистка
|
||
docker-compose down --rmi all --volumes
|
||
```
|
||
|
||
## Логирование
|
||
|
||
Логи сохраняются в `shared/logs/bot.log` и дублируются в консоль. При критических ошибках отправляется уведомление всем админам.
|
||
|
||
## Мультигрупповая поддержка
|
||
|
||
- Каждая группа имеет независимый пул участников
|
||
- История пар **общая для всех групп** - если два человека встретились в группе A, они не встретятся в группе B
|
||
- Планировщик обрабатывает все группы одновременно
|
||
|
||
## Troubleshooting
|
||
|
||
**Бот не видит команды в группе:**
|
||
- Проверьте права администратора
|
||
- Отключите Privacy Mode у @BotFather: `/setprivacy` → Disable
|
||
|
||
**База данных заблокирована:**
|
||
```bash
|
||
# Остановите все процессы и пересоздайте базу
|
||
rm random_coffee.db
|
||
alembic upgrade head
|
||
```
|
||
|
||
**Изменение часового пояса:**
|
||
Измените `Europe/Moscow` в `src/controller/scheduler.py`
|
||
|
||
## License
|
||
|
||
MIT
|