273 lines
9.9 KiB
Markdown
273 lines
9.9 KiB
Markdown
# 🤖 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 и автоматизация
|
||
- <20> [Drone 1.x+ конфигурация](docs/DRONE_1.x_CONFIG.md) - Современный CI/CD pipeline
|
||
- 🔄 [Миграция Drone 0.8](docs/DRONE_0.8_MIGRATION.md) - Переход с устаревшей версии
|
||
- <20>🔧 [Инфраструктура](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 - для вопросов и идей
|
||
|
||
---
|
||
🎓 **Успехов в изучении языков!** 🚀
|