init commit
This commit is contained in:
264
README.md
Normal file
264
README.md
Normal file
@@ -0,0 +1,264 @@
|
||||
# 🤖 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 с описанием проблемы
|
||||
|
||||
---
|
||||
**Удачи в изучении языков! 🎓**
|
||||
Reference in New Issue
Block a user