# Техническое задание: Telegram бот для изучения языков

## 1. Общее описание проекта

Telegram бот для изучения иностранных языков с использованием ИИ, персонализированным подходом и ежедневными заданиями.

**Версия 1.0**: Поддержка английского языка
**Будущие версии**: Расширение на другие языки

---

## 2. Основные функции

### 2.1 Управление словарным запасом

#### Способы добавления слов:

**1. Ручное добавление (по инициативе пользователя)**
- Команда `/add [слово]` или `/add [фраза]`
- Отправка слова в свободной форме (бот распознает и предложит добавить)
- Пользователь может добавить собственный перевод и заметки

**2. Автоматические предложения от бота**
- Бот ежедневно предлагает N новых слов на основе уровня пользователя
- Тематические подборки по запросу (команда `/words [тема]`)
  - Пример: `/words travel` → 10 слов про путешествия
  - Популярные темы: работа, еда, спорт, технологии, эмоции и т.д.
- Слова из частотных списков по уровням (A1-C2)
- "Слово дня" с интересными фактами

**3. Из контекста общения с ИИ**
- Во время диалоговой практики ИИ автоматически определяет сложные слова
- Бот предлагает: "В этом сообщении встретилось слово 'resilient' - хотите добавить в словарь?"
- Пользователь может одним кликом добавить слово

**4. Импорт из текста**
- Пользователь отправляет текст, статью или ссылку
- ИИ анализирует текст и выделяет полезные слова по уровню пользователя
- Показывает список слов с переводами
- Пользователь выбирает, какие добавить (через inline-кнопки)

**5. Из ошибок и сложных заданий**
- Если пользователь ошибается в задании, слово автоматически помечается для повторения
- Бот предлагает добавить синонимы/антонимы к уже изученным словам
- Слова, которые вызывают трудности, автоматически появляются чаще в заданиях

#### Функции управления словарем:
- Автоматическое сохранение слов с переводом, транскрипцией и примерами
- Категоризация слов по темам (автоматическая и ручная)
- Отметка уровня сложности слов (A1-C2)
- История изучения каждого слова (дата добавления, количество повторений, процент правильных ответов)
- Удаление и редактирование слов
- Поиск по словарю
- Экспорт словаря (CSV, Anki формат)

### 2.2 Ежедневные задания
- Автоматическая генерация заданий каждый день
- Типы заданий:
  - Перевод слов (EN→RU и RU→EN)
  - Составление предложений с новыми словами
  - Заполнение пропусков в предложениях
  - Аудирование (опционально для будущих версий)
  - Множественный выбор
- Адаптивная сложность на основе прогресса пользователя
- Настройка времени отправки заданий

### 2.3 Проверка заданий с использованием ИИ
- Автоматическая проверка ответов через ИИ (GPT/Claude/другие)
- Оценка правильности с объяснением ошибок
- Учет контекста и вариативности ответов
- Рекомендации по улучшению

### 2.4 Интеграция с ИИ
- Перевод слов и фраз
- Генерация примеров использования
- Создание персонализированных заданий
- Объяснение грамматических правил
- Диалоговый режим для практики общения

### 2.5 Статистика и прогресс
- Количество изученных слов
- Процент правильных ответов
- График прогресса
- Streak (дни подряд выполнения заданий)
- Уровень владения языком

---

## 3. Пользовательские сценарии

### 3.1 Первый запуск
1. Пользователь запускает бота командой `/start`
2. Бот приветствует и предлагает выбрать язык интерфейса
3. Бот проводит короткий тест для определения уровня
4. Пользователь настраивает время ежедневных заданий
5. Бот предлагает добавить первые слова

### 3.2 Добавление слов (ручное)
1. Пользователь отправляет `/add elephant` или просто `elephant`
2. Бот через ИИ получает перевод, транскрипцию, примеры использования
3. Показывает карточку слова с кнопками "Добавить" / "Редактировать" / "Отмена"
4. Пользователь подтверждает или редактирует информацию
5. Слово сохраняется в персональный словарь

### 3.2.1 Тематическая подборка
1. Пользователь отправляет `/words travel`
2. Бот генерирует 10 релевантных слов по теме с учетом уровня пользователя
3. Показывает список слов с переводами
4. Пользователь выбирает слова через inline-кнопки (✅/❌)
5. Выбранные слова добавляются в словарь

### 3.2.2 Импорт из текста
1. Пользователь отправляет текст или статью боту
2. Бот анализирует текст и находит 5-15 новых слов подходящего уровня
3. Показывает слова с переводами и контекстом из текста
4. Пользователь выбирает слова для добавления
5. Слова сохраняются с примерами из исходного текста

### 3.2.3 Добавление из диалога
1. Пользователь общается с ботом на английском (`/practice`)
2. Использует незнакомое слово или ИИ использует сложное слово
3. Бот предлагает: "💡 Слово 'resilient' - добавить в словарь?"
4. Пользователь нажимает кнопку "Добавить"
5. Слово сохраняется с контекстом из диалога

### 3.3 Выполнение ежедневного задания
1. Бот отправляет задание в настроенное время
2. Пользователь выполняет задания (5-10 вопросов)
3. ИИ проверяет ответы и дает обратную связь
4. Результаты сохраняются в статистику

### 3.4 Свободная практика
1. Пользователь инициирует диалог с ботом
2. Общение на английском языке с ИИ
3. ИИ исправляет ошибки и дает советы
4. Новые слова могут автоматически добавляться в словарь

---

## 4. Команды бота

| Команда | Описание |
|---------|----------|
| `/start` | Запуск/перезапуск бота |
| `/add [слово]` | Добавить слово в словарь |
| `/words [тема]` | Получить подборку слов по теме |
| `/vocabulary` | Просмотр словаря |
| `/task` | Получить задание сейчас |
| `/stats` | Статистика и прогресс |
| `/settings` | Настройки (время заданий, уровень сложности) |
| `/help` | Справка по командам |
| `/practice` | Свободная практика с ИИ |
| `/import` | Импортировать слова из текста |

---

## 5. Технические требования

### 5.1 Архитектура
- **Фреймворк**: python-telegram-bot или aiogram
- **База данных**: PostgreSQL или MongoDB для хранения:
  - Пользователи
  - Словари пользователей
  - История заданий и ответов
  - Статистика
- **ИИ API**: OpenAI GPT-4, Claude, или Google Gemini
- **Кэширование**: Redis для сессий и временных данных
- **Планировщик**: Celery или APScheduler для ежедневных заданий

### 5.2 Структура базы данных

#### Таблица: Users
```
- id (PK)
- telegram_id (unique)
- username
- language_interface (ru/en)
- learning_language (en)
- level (A1/A2/B1/B2/C1/C2)
- timezone
- daily_task_time
- streak_days
- created_at
- last_active
```

#### Таблица: Vocabulary
```
- id (PK)
- user_id (FK)
- word_original
- word_translation
- transcription
- examples (JSON)
- category
- difficulty_level
- source (manual/suggested/context/import/error)
- times_reviewed
- correct_answers
- last_reviewed
- created_at
- notes (user custom notes)
```

#### Таблица: Tasks
```
- id (PK)
- user_id (FK)
- task_type
- content (JSON)
- correct_answer
- user_answer
- is_correct
- ai_feedback
- completed_at
- created_at
```

### 5.3 API интеграция
- **Telegram Bot API**: Основное взаимодействие с пользователем
- **OpenAI/Claude API**: Генерация и проверка заданий
- **Dictionary API** (опционально): Дополнительные данные о словах

### 5.4 Безопасность
- Шифрование API ключей
- Валидация пользовательского ввода
- Rate limiting для защиты от спама
- Резервное копирование базы данных

---

## 6. Этапы разработки

### Этап 1: MVP (Минимально жизнеспособный продукт)
- [ ] Настройка Telegram бота
- [ ] Подключение базы данных
- [ ] Базовые команды (/start, /add, /vocabulary)
- [ ] Интеграция с ИИ для перевода слов
- [ ] Простое ежедневное задание (перевод 5 слов)
- [ ] Автоматическая проверка ответов

### Этап 2: Расширенный функционал
- [ ] Различные типы заданий
- [ ] Тематические подборки слов (`/words [тема]`)
- [ ] Импорт слов из текста (`/import`)
- [ ] Автоматические предложения слов от бота
- [ ] Добавление слов из контекста диалога
- [ ] Статистика и прогресс
- [ ] Адаптивная сложность
- [ ] Диалоговый режим практики
- [ ] Настройки пользователя

### Этап 3: Оптимизация и масштабирование
- [ ] Улучшение алгоритмов повторения (spaced repetition)
- [ ] "Слово дня" с интересными фактами
- [ ] Экспорт словаря в форматы CSV и Anki
- [ ] Геймификация (достижения, лидерборд)
- [ ] Аудио произношение слов
- [ ] Поддержка других языков
- [ ] Мобильное веб-приложение (Telegram Mini App)

---

## 7. Метрики успеха

- **Вовлеченность**: DAU (Daily Active Users), streak пользователей
- **Эффективность**: Процент правильных ответов, рост словарного запаса
- **Удержание**: Retention rate на 7, 30, 90 дней
- **Удовлетворенность**: NPS, обратная связь пользователей

---

## 8. Риски и ограничения

- **Стоимость ИИ API**: Необходимо оптимизировать количество запросов
- **Зависимость от внешних сервисов**: Telegram API, ИИ API
- **Качество проверки**: ИИ может ошибаться в оценке сложных ответов
- **Мотивация пользователей**: Требуется геймификация для удержания

---

## 9. Будущие возможности

- Поддержка других языков (испанский, немецкий, французский, китайский)
- Групповые задания и соревнования
- Интеграция с внешними ресурсами:
  - Импорт слов из YouTube субтитров по ссылке
  - Анализ статей и веб-страниц
  - Подкасты и аудиокниги
- Голосовые сообщения для практики произношения
- Персональный AI-преподаватель с долгосрочной памятью о прогрессе
- Подготовка к экзаменам (IELTS, TOEFL, etc.)
- Социальные функции:
  - Обмен словарными подборками с другими пользователями
  - Общие челленджи
  - Рейтинг по регионам