# 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