Random Coffee Bot

Telegram бот для организации случайных встреч (Random Coffee) между участниками групп.

Описание

Бот автоматически создает уникальные пары участников для неформальных встреч:

• 📊 Отправляет опросы участникам каждую пятницу
• 👥 Формирует пары каждое воскресенье
• 🔄 Отслеживает историю встреч (пары не повторяются)
• 🌐 Поддержка нескольких групп одновременно
• 🗄️ Миграции базы данных через Alembic

Быстрый старт

1. Клонирование репозитория

git clone https://github.com/yourusername/random_coffee_bot.git
cd random_coffee_bot

2. Настройка окружения

Создайте файл .env на основе .env.example:

cp .env.example .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

3. Запуск

Docker (рекомендуется)

# Собрать и запустить
docker-compose up -d --build

# Просмотр логов
docker-compose logs -f

# Остановка
docker-compose down

Локально

# Установка зависимостей
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 - Управление зависимостями

Разработка

Работа с базой данных

# Создать новую миграцию
alembic revision --autogenerate -m "описание"

# Применить миграции
alembic upgrade head

# Откатить миграцию
alembic downgrade -1

# Текущая версия
alembic current

Структура базы данных

• participants - Участники опроса (очищается после создания пар)
• pairs - История всех пар (для предотвращения повторов)
• poll_mappings - Связь poll_id → group_id

Docker команды

# Пересборка
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

База данных заблокирована:

# Остановите все процессы и пересоздайте базу
rm random_coffee.db
alembic upgrade head

Изменение часового пояса: Измените Europe/Moscow в src/controller/scheduler.py

License

MIT