tg_bot_language/TZ.md

Техническое задание: 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.)
• Социальные функции:
  • Обмен словарными подборками с другими пользователями
  • Общие челленджи
  • Рейтинг по регионам