first commit
This commit is contained in:
Artem Tsyrulnikov
191
README.md
Normal file
191
README.md
Normal file
@@ -0,0 +1,191 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user