🎅 Secret Santa Telegram Bot

Телеграм-бот для организации и проведения игры «Тайный Санта» (Secret Santa). Бот позволяет создавать комнаты для игры, приглашать участников по уникальной ссылке, настраивать исключения (кто кому не может дарить) и проводить автоматическую жеребьевку.

Воспользоваться ботом можно по ссылке: https://t.me/magicsantabot

✨ Возможности

• Создание игры: Организатор задает название, бюджет, место и время встречи.
• Присоединение к игре: Вступление в игру осуществляется только по уникальной ссылке-приглашению.
• Анкетирование: Удобный пошаговый ввод данных (имя, пожелания к подарку).
• Управление исключениями: Создатель может настроить пары, которые не должны выпасть.
• Умная жеребьевка: Алгоритм перемешивает участников с учетом всех исключений.
• Приватность: Каждый игрок видит только своего подопечного.
• Мои игры: Просмотр списка активных игр и их участников.

🛠 Технический стек

• Язык: Python 3.10+
• Фреймворк: aiogram 3.x
• База данных: SQLite3

📂 Структура проекта

secret_santa_bot/
├── bot.py                 # Запуск бота
├── config.py              # Конфигурация
├── database/              # Работа с данными
│   ├── core.py            # Подключение и инициализация таблиц
│   └── requests.py        # Запросы к БД
├── handlers/              # Обработка сообщений
│   ├── common.py          # Базовые команды
│   ├── game_creation.py   # Создание игры
│   ├── game_joining.py    # Вступление в игру
│   ├── game_management.py # Управление списками
│   └── draw_logic.py      # Жеребьевка и исключения
├── keyboards/             # Инлайн-кнопки
├── services/              # Алгоритм бота
├── states/                # Состояния
└── utils/                 # Текстовые константы

🚀 Установка и запуск

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

git clone https://github.com/bolgoff/secret-santa.git
cd secret-santa-bot

2. Создание виртуального окружения Windows:

python -m venv venv
venv\Scripts\activate

macOS / Linux:

python3 -m venv venv
source venv/bin/activate

3. Установка зависимостей

pip install -r requirements.txt

4. Настройка переменных окружения Создайте файл .env в корне проекта и добавьте туда токен вашего бота (получить можно у @BotFather):

BOT_TOKEN=000000000:AAAA...........

5. Запуск бота

При первом запуске бот автоматически создаст файл базы данных santa.db и необходимые таблицы.

python bot.py

📖 Использование

1. Напишите боту /start.
2. Нажмите "Создать игру".
3. Следуйте инструкциям бота (введите название, бюджет, место встречи).
4. Получите ссылку-приглашение и отправьте её друзьям.

В меню игры ("Мои игры") вы можете:

• Смотреть список вступивших.
• Добавлять исключения (например, чтобы Пупа не дарил Лупе).
• Нажать "Жеребьевка", когда все соберутся --> Бот разошлет каждому участнику в личные сообщения имя того, кому нужно дарить подарок и его пожелание.

🤝 Contributing

Если вы хотите улучшить бота:

• Форкните репозиторий.
• Создайте ветку для новой фичи (git checkout -b feature/NewFeature).
• Закоммитьте изменения (git commit -m 'Add some NewFeature').
• Запушьте ветку (git push origin feature/NewFeature).
• Откройте Pull Request.