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. Подготовка окружения

# Клонируйте репозиторий или создайте папку проекта
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. Скопируйте файл конфигурации:

   cp .env.example .env
   

4. Отредактируйте .env файл:

   BOT_TOKEN=ваш_токен_от_BotFather
   ADMIN_IDS=ваш_telegram_id
   

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

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

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

Этот скрипт:

• Создаст базу данных SQLite
• Сгенерирует тестовые CSV файлы
• Загрузит тесты в базу данных

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

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

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

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

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

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

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

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

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

Уровень 1 (20 вопросов)

• Базовые приветствия и фразы
• Простые слова и числа
• Основная лексика

Уровень 2 (20 вопросов)

• Повседневное общение
• Покупки и путешествия
• Время и погода

Уровень 3 (20 вопросов)

• Сложные грамматические конструкции
• Условные предложения
• Выражение мнений

Уровень 4 (20 вопросов)

• Продвинутая грамматика
• Сравнения и предположения
• Абстрактные понятия

Уровень 5 (20 вопросов)

• Высокий уровень языка
• Сложные концепции
• Профессиональная лексика

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

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

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

Правила:

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

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

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

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

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

# Обязательные
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/

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

# В 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 с описанием проблемы

---

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