# 🤖 Quiz Bot - Телеграм бот для викторин

Асинхронный телеграм-бот для проведения викторин и тестирования по различным материалам с полной DevOps инфраструктурой.

## 📋 Описание

Quiz Bot поддерживает два режима работы:

### 🎯 Гостевой режим (QUIZ)
- Быстрые викторины без регистрации
- 5 случайных вопросов
- Результаты не сохраняются
- Подходит для развлечения

### 📚 Режим тестирования
- Полноценные тесты по материалам  
- До 10 вопросов на тест
- Сохранение результатов и статистики
- Отслеживание прогресса

## 🏗️ Структура проекта

```
quiz_test/
├── config/                 # Конфигурация приложения
├── src/                    # Исходный код бота
│   ├── bot.py             # Основной файл бота
│   ├── database/          # Работа с базой данных
│   ├── services/          # Бизнес-логика
│   └── utils/             # Утилиты
├── tests/                  # Тесты приложения
├── tools/                  # Вспомогательные инструменты
├── docs/                   # Документация
├── data/                   # CSV файлы и база данных
├── logs/                   # Логи приложения
├── scripts/                # Скрипты автоматизации
├── requirements.txt        # Зависимости Python
├── Dockerfile             # Контейнеризация
├── docker-compose.yml     # Оркестрация контейнеров
├── Makefile               # Автоматизация команд
└── .drone.yml             # CI/CD пайплайн
```

## 📚 Документация

- 📖 [Быстрый старт](docs/QUICKSTART.md) - Начало работы с проектом
- 🐳 [Docker инструкции](docs/DOCKER_README.md) - Контейнеризация и развертывание
- 🏗️ [DevOps инфраструктура](docs/DEVOPS_SUMMARY.md) - CI/CD и автоматизация
- 🔧 [Инфраструктура](docs/INFRASTRUCTURE.md) - Архитектура и компоненты
- 🔧 [Отчет по исправлениям](docs/FIX_REPORT.md) - История изменений

## 🚀 Быстрый старт

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

```bash
# Разработка
make docker-dev

# Продакшен
make docker-prod

# Остановка
make docker-stop
```

### 🔧 Локальная разработка

```bash
# Установка зависимостей
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# Инициализация проекта
python tools/init_project.py

# Запуск бота
python -m src.bot
```

## 🛠️ Доступные команды

```bash
# Разработка
make install          # Установка зависимостей
make run             # Запуск бота локально
make test            # Запуск тестов
make lint            # Проверка кода
make format          # Форматирование кода

# Docker
make docker-dev      # Разработка в Docker
make docker-prod     # Продакшен в Docker  
make docker-logs     # Просмотр логов
make docker-shell    # Вход в контейнер

# Качество кода
make security-check  # Проверка безопасности
make type-check      # Проверка типов
make coverage        # Покрытие тестов
```

## 🏛️ Архитектура

### Основные компоненты

- **src/bot.py** - Главный модуль с Telegram Bot API
- **src/database/** - Модули работы с SQLite базой данных
- **src/services/** - Бизнес-логика (загрузка CSV, обработка тестов)
- **tests/** - Автотесты приложения
- **tools/** - Вспомогательные инструменты и скрипты

### DevOps компоненты

- **Dockerfile** - Многоступенчатая сборка контейнера
- **docker-compose.yml** - Оркестрация для разработки и продакшена
- **.drone.yml** - CI/CD пайплайн с 9 этапами проверки
- **Makefile** - Автоматизация всех команд разработки

## 📊 Доступные тесты

### 🇰🇷 Корейский язык

- **Уровень 1-5** - От базовых фраз до продвинутой грамматики
- Поддержка CSV импорта новых тестов
- Автоматическая генерация тестовых данных

**Уровень 4** (20 вопросов)
- Продвинутая грамматика
- Сравнения и предположения
- Абстрактные понятия

**Уровень 5** (20 вопросов)
- Высокий уровень языка
- Сложные концепции
- Профессиональная лексика

## 📁 Формат CSV файлов

Формат для добавления новых тестов:

```csv
Вопрос,Ответ1,Ответ2,Ответ3,Ответ4,Правильный_ответ
"Как сказать привет?","안녕하세요","감사합니다","죄송합니다","안녕히 가세요",1
"Что означает 물?","Огонь","Вода","Земля","Воздух",2
```

**Правила:**
- Первая строка - заголовки
- Правильный ответ - номер от 1 до 4
- Используйте кавычки для текста с запятыми
- Кодировка UTF-8

## 🎮 Команды бота

- `/start` - Главное меню
- `/help` - Справка по командам
- `/stats` - Личная статистика
- `/stop` - Остановить текущий тест

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

Основные настройки в файле `.env`:

```bash
# Обязательные
BOT_TOKEN=your_token_here
ADMIN_IDS=123456789,987654321

# Опциональные
QUESTIONS_PER_QUIZ=10          # Вопросов в полном тесте
TIME_PER_QUESTION=30           # Время на вопрос (сек)
GUEST_MODE_ENABLED=true        # Включить гостевой режим
TEST_MODE_ENABLED=true         # Включить режим тестирования
DATABASE_PATH=data/quiz_bot.db # Путь к БД
CSV_DATA_PATH=data/            # Папка с CSV файлами
```

## 📈 База данных

Бот использует SQLite с таблицами:

- `users` - Пользователи и их статистика
- `tests` - Доступные тесты
- `questions` - Вопросы тестов
- `results` - Результаты прохождения
- `active_sessions` - Активные сессии

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

### Добавление новых языков/категорий

1. Создайте CSV файлы в папке `data/`
2. Добавьте категорию в `src/services/csv_service.py`
3. Обновите интерфейс в `src/bot.py`

### Расширение функционала

- Добавляйте новые хендлеры в папку `src/handlers/`
- Расширяйте базу данных в `src/database/database.py`
- Добавляйте утилиты в `src/utils/`

### Пример добавления нового теста

```python
# В csv_service.py
@staticmethod
def generate_english_level_1() -> List[Dict]:
    return [
        {
            'question': 'What is "привет" in English?',
            'option1': 'Hello',
            'option2': 'Goodbye', 
            'option3': 'Please',
            'option4': 'Thank you',
            'correct_answer': 1
        }
        # ... больше вопросов
    ]
```

## 🐛 Решение проблем

### Бот не отвечает
- Проверьте токен в `.env`
- Убедитесь что бот запущен
- Проверьте логи в консоли

## 🐛 Устранение неисправностей

### База данных
```bash
# Переинициализация
python tools/init_project.py

# Проверка через Docker
make docker-shell
```

### Логи и мониторинг
```bash
make docker-logs    # Просмотр логов
make status         # Статус системы
```

## 🤝 Участие в разработке

1. Форк репозитория
2. Создание feature ветки
3. Коммиты с осмысленными сообщениями  
4. Pull request с описанием изменений

### Code Style
- Используйте `make format` перед коммитом
- Пишите тесты для нового функционала
- Следуйте PEP8 и принципам Clean Code

## 📄 Лицензия

MIT License - свободное использование для любых целей.

## 📞 Поддержка

- 📖 [Документация](docs/) - полные инструкции
- 🐛 Issues - для сообщения о багах  
- 💬 Discussions - для вопросов и идей

---
🎓 **Успехов в изучении языков!** 🚀