sno-quiz/bot

Telegram Bot for Звёздные Викторины

Этот бот предоставляет доступ к Telegram Mini App "Звёздные Викторины" и управляет QR-кодами с токен-ориентированной системой безопасности.

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

🎫 QR-код система

• Токен-ориентированная: Уникальные токены для каждого QR-кода
• Безопасная: Серверная валидация через backend API
• Одноразовая: Каждый токен используется только один раз
• Типы QR-кодов: reward (награды), quiz (викторины), shop (магазин)

👥 Администрирование

• Роли: Администраторы и операторы
• Генерация QR-кодов: Через бота с валидацией
• Управление: Панель администратора в боте

🔗 Deep Links

• Поддержка параметров startapp:
  • Начисление звёзд: reward_X
  • Открытие викторин: quiz_X
  • Переход в магазин: shop
  • Переход к призу: reward_X

🎯 Команды бота

• /start - Запуск бота с параметрами
• /help - Помощь
• /qr - Информация о QR-кодах
• /admin - Панель администратора

📦 Установка

1. Установите зависимости:

pip install -r requirements.txt

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

cp .env.example .env

3. Заполните переменные окружения в .env:

BOT_TOKEN=ваш_токен_бота
BACKEND_API_URL=http://localhost:8080
FRONTEND_URL=http://localhost:5173
BOT_USERNAME=ваш_бот_юзернейм
ADMIN_USER_IDS=123456789,987654321
OPERATOR_USER_IDS=111111111,222222222

🛠 Запуск

Локальный запуск

python bot.py

С помощью Docker

docker build -t quiz-bot .
docker run -p 8080:8080 quiz-bot

С помощью webhook

Для продакшн-развертывания используйте webhook:

from aiogram.webhook.aiohttp_server import SimpleRequestHandler, setup_application

# Добавьте в main()
webhook_url = "https://your-domain.com/webhook"
await bot.set_webhook(webhook_url)

# Настройте aiohttp приложение
from aiohttp import web
app = web.Application()
setup_application(app, dp, webhook_path="/webhook")

🎫 Работа с QR-кодами

Генерация QR-кодов (администраторы)

1. Используйте команду /admin
2. Выберите "Генерировать QR-коды"
3. Выберите тип (reward/quiz/shop)
4. Введите параметры (сумма, ID викторины и т.д.)
5. Получите список токенов для QR-кодов

Использование QR-кодов

1. Сгенерируйте QR-коды с полученными токенами
2. Разместите QR-коды в нужных местах
3. Пользователи сканируют их через приложение
4. Приложение отправляет токен на /api/qr/validate

Пример QR-кода

Содержимое: a1b2c3d4e5f678901234567890abcdef

📋 Примеры Deep Links

Начисление звёзд

https://t.me/YourBot?startapp=reward_50
https://t.me/YourBot?startapp=reward_100

Открытие викторины

https://t.me/YourBot?startapp=quiz_123
https://t.me/YourBot?startapp=quiz_456

Переход в магазин

https://t.me/YourBot?startapp=shop

Переход к призу

https://t.me/YourBot?startapp=reward_789

🔧 Конфигурация

Переменная	Описание	Обязательна
BOT_TOKEN	Токен Telegram бота	✅
BACKEND_API_URL	URL бэкенда	✅
FRONTEND_URL	URL фронтенда	✅
BOT_USERNAME	Юзернейм бота	❌
ADMIN_USER_IDS	ID администраторов (через запятую)	❌
OPERATOR_USER_IDS	ID операторов (через запятую)	❌
WEBHOOK_URL	URL для webhook	❌
WEBHOOK_SECRET	Секрет для webhook	❌

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

bot/
├── bot.py              # Основной файл бота
├── config.py           # Конфигурация
├── handlers.py         # Обработчики команд
├── admin_handlers.py   # Административные обработчики
├── qr_service.py       # Сервис для работы с QR API
├── utils.py            # Утилиты
├── requirements.txt    # Зависимости
├── .env.example        # Пример .env
├── Dockerfile          # Docker конфигурация
├── examples.py         # Примеры использования
└── README.md          # Документация

🚨 Безопасность

QR-коды

• Уникальные токены: 128-битная энтропия
• Одноразовые: После использования помечаются как использованные
• Срок действия: 30 дней
• Серверная валидация: Проверка через backend API

Пользователи

• Аутентификация: Через Telegram User ID
• Роли: Администраторы и операторы
• Права доступа: Разграничение по ролям

Сеть

• Вебхуки: Поддержка секретного ключа
• HTTPS: Рекомендуется для продакшена
• Логирование: Все действия записываются

📊 Логирование

Бот логирует важные события:

• Запуск и остановку
• Обработку команд
• Генерацию QR-кодов
• Ошибки и исключения
• Действия администраторов

Уровень логирования можно настроить через переменную LOG_LEVEL.

🔌 Интеграция

С бэкендом

Бот интегрируется с бэкендом через API:

• Генерация QR-токенов: POST /api/admin/qrcodes
• Валидация QR-токенов: POST /api/qr/validate
• Управление пользователями и викторинами

С фронтендом

Мини-приложение открывается через Web App API:

• Автоматическая передача Telegram initData
• Поддержка параметров startapp
• Сканирование QR-кодов через камеру
• Валидация токенов через API

🛠️ Разработка

Добавление новых команд

1. Создайте обработчик в handlers.py или admin_handlers.py
2. Зарегистрируйте команду в bot.py
3. Обновите документацию

Тестирование

• Используйте тестовые токены для разработки
• Проверяйте права доступа для административных функций
• Тестируйте валидацию QR-кодов через backend API