🤖 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 пайплайн

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

• 📖 Быстрый старт - Начало работы с проектом
• 🐳 Docker инструкции - Контейнеризация и развертывание
• 🏗️ DevOps инфраструктура - CI/CD и автоматизация
• <EFBFBD> Drone 1.x+ конфигурация - Современный CI/CD pipeline
• 🔄 Миграция Drone 0.8 - Переход с устаревшей версии
• <EFBFBD>🔧 Инфраструктура - Архитектура и компоненты
• 🔧 Отчет по исправлениям - История изменений

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

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

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

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

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

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

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

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

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

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

# Разработка
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 файлов

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

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

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

База данных

# Переинициализация
python tools/init_project.py

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

Логи и мониторинг

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

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

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

Code Style

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

📄 Лицензия

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

📞 Поддержка

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

---

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