210 lines
7.8 KiB
Markdown
210 lines
7.8 KiB
Markdown
# 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. Установите зависимости:
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
2. Создайте файл `.env` на основе `.env.example`:
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
3. Заполните переменные окружения в `.env`:
|
||
```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
|
||
```
|
||
|
||
## 🛠 Запуск
|
||
|
||
### Локальный запуск
|
||
```bash
|
||
python bot.py
|
||
```
|
||
|
||
### С помощью Docker
|
||
```bash
|
||
docker build -t quiz-bot .
|
||
docker run -p 8080:8080 quiz-bot
|
||
```
|
||
|
||
### С помощью webhook
|
||
Для продакшн-развертывания используйте webhook:
|
||
|
||
```python
|
||
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 |