# 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