quiz_test/README.md

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

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

## 📋 Описание

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

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

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

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

```
quiz_test/
├── config/
│   └── config.py           # Конфигурация приложения
├── src/
│   ├── bot.py              # Основной файл бота
│   ├── database/
│   │   └── database.py     # Работа с базой данных
│   ├── handlers/           # Обработчики команд (будущее расширение)
│   ├── services/
│   │   └── csv_service.py  # Загрузка тестов из CSV
│   └── utils/              # Утилиты
├── data/                   # CSV файлы и база данных
├── .env                    # Переменные окружения
├── .env.example            # Пример файла окружения
├── requirements.txt        # Зависимости Python
├── init_project.py         # Скрипт инициализации
└── README.md              # Этот файл
```

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

### 1. Подготовка окружения

```bash
# Клонируйте репозиторий или создайте папку проекта
cd quiz_test

# Создайте виртуальное окружение
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
# или
.venv\Scripts\activate     # Windows

# Установите зависимости
pip install -r requirements.txt
```

### 2. Настройка бота

1. Создайте бота в Telegram через @BotFather
2. Скопируйте токен
3. Скопируйте файл конфигурации:
   ```bash
   cp .env.example .env
   ```
4. Отредактируйте `.env` файл:
   ```
   BOT_TOKEN=ваш_токен_от_BotFather
   ADMIN_IDS=ваш_telegram_id
   ```

### 3. Инициализация проекта

```bash
# Или используя Makefile
make init

# Или напрямую
python init_project.py
```

Этот скрипт:
- Создаст базу данных SQLite
- Сгенерирует тестовые CSV файлы
- Загрузит тесты в базу данных

### 4. Тестирование (опционально)

```bash
# Проверить импорты и конфигурацию
make test-bot

# Интерактивный тест в консоли
make test

# Демонстрация возможностей
make demo
```

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

```bash
# Используя Makefile
make run

# Или напрямую
python src/bot.py
```

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

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

**Уровень 1** (20 вопросов)
- Базовые приветствия и фразы
- Простые слова и числа
- Основная лексика

**Уровень 2** (20 вопросов)  
- Повседневное общение
- Покупки и путешествия
- Время и погода

**Уровень 3** (20 вопросов)
- Сложные грамматические конструкции
- Условные предложения
- Выражение мнений

**Уровень 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`
- Убедитесь что бот запущен
- Проверьте логи в консоли

### Ошибки базы данных
- Удалите файл `data/quiz_bot.db`
- Запустите `python init_project.py`

### CSV не загружается
- Проверьте формат файла
- Убедитесь в правильной кодировке (UTF-8)
- Проверьте путь к файлу

## 📝 TODO

- [ ] Веб-интерфейс для администратора
- [ ] Поддержка изображений в вопросах
- [ ] Система рейтингов
- [ ] Экспорт статистики
- [ ] Многоязычный интерфейс
- [ ] Таймер для вопросов
- [ ] Уведомления и напоминания

## 📄 Лицензия

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

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

Если возникли вопросы:
1. Проверьте этот README
2. Посмотрите логи бота
3. Создайте issue с описанием проблемы

---
**Удачи в изучении языков! 🎓**