diff --git a/TZ.md b/TZ.md new file mode 100644 index 0000000..598ddf2 --- /dev/null +++ b/TZ.md @@ -0,0 +1,296 @@ +# Техническое задание: 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.) +- Социальные функции: + - Обмен словарными подборками с другими пользователями + - Общие челленджи + - Рейтинг по регионам