Skip to content

DOCS.md

Latest commit

 

History

History
209 lines (154 loc) · 34.7 KB

DOCS.md

File metadata and controls

209 lines (154 loc) · 34.7 KB
Raw

📚 Go2Study Bot: Документация

🤖 О проекте

Go2Study Bot — это Telegram-бот для изучения математики, построенный на базе адаптивной системы обучения. Бот предоставляет персонализированные тесты, отслеживает прогресс пользователя и помогает закреплять слабые места в знаниях.

✨ Ключевые возможности

  • 🎯 Адаптивное тестирование: Фокус на темах, где пользователь совершает ошибки.
  • 📊 Аналитика прогресса: Подробная статистика для отслеживания обучения.
  • 🔄 Работа над ошибками: Механизмы для повторения и закрепления материала.
  • 👥 Система администрирования: Управление пользователями, темами и вопросами.
  • 🌐 Многоязычность: Поддержка русского и казахского языков.
  • 🤖 AI-генерация: Автоматическое создание вопросов и объяснений с помощью AI.
  • 💡 Оптимизация UI: Ключевые сообщения (например, "Мой прогресс", "Панель администратора", "Помощь") теперь не дублируются в чате, а заменяют собой предыдущее аналогичное сообщение. Это делает интерфейс чище и удобнее. Для этого была добавлена таблица managed_messages и сервис MessageManager.

🏗️ Архитектура системы

Проект имеет модульную структуру с четким разделением ответственности:

  • main.py: Главный файл для запуска бота.
  • src/handlers/: Обработчики команд, колбэков и сообщений от пользователя.
  • src/services/: Основная бизнес-логика (работа с БД, AI, генерация тестов).
  • src/db/: Управление подключением к базе данных, модели и репозитории.
  • src/config/: Константы и конфигурационные файлы.
  • src/utils/: Вспомогательные функции (например, создание клавиатур).

🚀 Развертывание (Deployment)

Проект готов к развертыванию на облачных платформах, таких как Railway.

Основные шаги:

  1. Клонировать репозиторий.
  2. Создать .env файл на основе .env.example и заполнить его своими данными (токен бота, API-ключ для AI, данные для подключения к PostgreSQL).
  3. Использовать Dockerfile: Проект содержит готовый Dockerfile для сборки и запуска в контейнере.
  4. Настроить платформу: На Railway достаточно подключить репозиторий и указать команду запуска. Все необходимые зависимости будут установлены из requirements.txt.

📋 Журнал изменений (Changelog)

Сентябрь 2025

  • Улучшение .gitignore (16.09.2025):
    • Проблема: Директория question_images/, содержащая изображения для вопросов, не была добавлена в .gitignore, что могло привести к раздуванию репозитория.
    • Решение: Директория question_images/ была добавлена в .gitignore для исключения медиафайлов из системы контроля версий. Также были добавлены распространенные расширения для баз данных SQLite (*.sqlite3, *.db3) в качестве превентивной меры.
    • Результат: Репозиторий защищен от случайного добавления изображений и временных файлов баз данных, что обеспечивает его чистоту и оптимальный размер.

Июль 2024

  • Исправлено усечение объяснений (12.07.2024):
    • Проблема: Длинные и правильно отформатированные объяснения, хранящиеся в базе данных, обрезались до одной строки при отображении пользователю.
    • Решение: Убрана избыточная функция очистки _clean_explanation_text, которая ошибочно применялась к текстам из базы данных. Эта функция была предназначена только для первоначальной обработки ответов от AI и некорректно удаляла форматирование (например, строки, начинающиеся с "Шаг...").
    • Результат: Теперь все объяснения из базы данных отображаются в полном объеме, без искажений.
  • Добавлена недостающая зависимость: В requirements.txt добавлен пакет sqlalchemy, чтобы устранить ошибку ModuleNotFoundError при запуске приложения.
  • Исправление ошибки совместимости с Python 3.9: Устранена ошибка TypeError при запуске приложения в Docker-контейнере с Python 3.9. Ошибка была вызвана использованием нового синтаксиса для аннотаций типов (|), который не поддерживается в данной версии. Все вхождения dict | None были заменены на Optional[dict] для обеспечения обратной совместимости.
  • Переход на ImprovedAIService: Вся система переведена на использование нового, улучшенного сервиса ImprovedAIService для генерации AI-контента. Это потребовало рефакторинга main.py, всех обработчиков в админ-панели и сервиса PDFProcessor для корректной передачи зависимостей.
  • Созданы тесты для AI-сервиса: Написаны модульные тесты для ImprovedAIService, которые проверяют корректность парсинга ответов от AI для русского и казахского языков, а также обработку некорректных ответов.
  • Реализован менеджер сообщений: Создан механизм для управления ключевыми сообщениями, чтобы они существовали в единственном экземпляре. Это исправляет дублирование UI-элементов и улучшает UX.
  • Рефакторинг слоя доступа к данным: Проведена унификация работы с базой данных. Все репозитории теперь используют единый базовый класс и менеджер соединений.
  • Исправлена логика для администраторов:
    • Администраторы теперь могут использовать функцию "Пройти снова тест". Их ошибки корректно загружаются, но не влияют на общую статистику студентов.
    • Исправлена неработающая кнопка "Удалить админа" путем добавления недостающих обработчиков в main.py.
  • Добавлена возможность создания суперадмина: Реализован SQL-запрос для ручного добавления суперадминистратора в базу данных.
  • Удалена старая ветка: Очищена история Git путем удаления неактуальной ветки feature/supabase-migration.
  • Commit 7 (Date): Improved the duplicate question detection mechanism by replacing the simple keyword-based search with a more robust fuzzy search using pg_trgm's similarity function. The threshold is set to 60%, which prevents adding obvious duplicates while allowing for slight variations in questions.
  • Commit 6 (Date): Fixed API rate-limiting issue during batch question generation by adding a one-second delay between concurrent requests. This prevents the system from exceeding the API's requests-per-minute quota when creating multiple questions for a new topic.
  • Commit 5 (Date): Solved a critical bug where the question generation process would fail due to API rate limiting (429 errors). Implemented a robust retry mechanism with exponential backoff in the AI service. This prevents system failure when the request limit is exceeded by intelligently re-spacing the API calls.
  • Commit 4 (Date): Fixed a bug where the test generation system would create tests with fewer questions than intended. The root cause was the use of non-unique "ghost" questions. The fix ensures that duplicate questions are correctly identified and skipped during generation. Also added a language parameter to the get_question_by_id function.

Июнь 2024

  • Успешный деплой на Railway: Проект был успешно развернут на платформе Railway с использованием PostgreSQL в качестве базы данных.
  • Исправлена логика тестов: Устранены ошибки в SQL-запросах, что позволило корректно загружать существующие вопросы из базы данных вместо постоянной генерации новых.
  • Рефакторинг и стабилизация:
    • Проведен рефакторинг main.py для упрощения регистрации обработчиков.
    • Улучшена логика автоудаления сообщений: теперь она срабатывает только во время тестов.
    • Исправлены многочисленные ошибки, связанные с обработкой данных пользователя, управлением темами и разделами в админ-панели.

Январь 2024 - Май 2024

  • Миграция на PostgreSQL: Проект успешно переведен с SQLite на Neon/Supabase PostgreSQL.
  • Оптимизация работы с БД: Внедрен механизм "умного" пинга базы данных для экономии ресурсов на бесплатных тарифах.
  • Улучшение качества AI-контента: Улучшены промпты для генерации более качественных и разнообразных вопросов с подробными объяснениями, а также внедрена система дедупликации.
  • Очистка проекта: Удалены устаревшие скрипты, тестовые файлы и документация.
  • Фундаментальные работы: Создана базовая архитектура, система моделей БД, основные обработчики и сервисы.

Нерешенные проблемы и задачи

Участники

  • Beksultan

Улучшение генерации вопросов AI

Дата: 2024-07-11

Проблема

Анализ логов ai_responses.log показал, что AI часто генерировал несколько вопросов в одном ответе и не всегда придерживался заданной темы. Это приводило к большому количеству отклоненных (REJECTED) запросов и неэффективному использованию API.

Решение

  1. Рефакторинг AI Service:

    • В src/services/ai_service_improved.py был внедрен новый, универсальный метод generate_task.
    • Этот метод использует строго структурированный промпт с уникальными маркерами ([QUESTION], [CORRECT_ANSWER] и т.д.) для повышения надежности парсинга.
    • Старые, экспериментальные методы (v2, v3, v4) и их вспомогательные функции были удалены для упрощения кодовой базы.

  2. Обновление логики вызова:

    • В src/services/question_service.py была обновлена логика вызова AI. Теперь она всегда использует новый, надежный метод generate_task.

Результат

  • Повышение качества: AI теперь генерирует более релевантные и качественные вопросы, строго по одной теме за раз.

  • Надежность: Новый парсер, основанный на маркерах, работает значительно надежнее, чем старый на регулярных выражениях.

  • Упрощение кода: Кодовая база стала чище и проще в поддержке.

  • Commit 8 (2025-07-10): Исправлена критическая ошибка AttributeError в QuestionService, которая возникала из-за вызова удаленного метода generate_task_v3. Вызов был заменен на актуальный метод generate_task, что восстановило функциональность генерации AI-вопросов.

  • Commit 9 (2025-07-10): Внедрен механизм повторных попыток с экспоненциальной задержкой в AIService для обработки ошибок 429 (Rate Limit Exceeded). Это повышает надежность генерации вопросов, позволяя системе автоматически восстанавливаться после временных ограничений API.

  • Commit 10 (2025-07-10): Улучшен парсер ответов AI в AIService. Добавлена очистка поля correct_answer от случайных символов (например, *, -), что повышает устойчивость к ошибкам форматирования и увеличивает количество успешно разобранных вопросов.

  • Commit 11 (2025-07-10): Улучшен парсер ответов AI в AIService для обработки некорректного форматирования. Теперь парсер удаляет символы-маркеры (*) и обрабатывает многострочные ответы, повышая надежность и чистоту генерируемых данных.

Сброс проекта

  • Commit 12 (2025-07-11): Проект был возвращен к состоянию коммита c09453773dc1bccab681595443c2a2ab2afe318f. Это решение было принято для отката ряда последовательных изменений, которые привели к полной блокировке API и остановке генерации вопросов. Возврат к предыдущей стабильной версии позволяет восстановить базовую функциональность, несмотря на отказ от недавних улучшений в механизме валидации.

  • Commit 13 (2025-07-11): Исправлена критическая проблема с блокировкой API (Rate Limit Exceeded) путем внедрения asyncio.Semaphore(2) в QuestionService. Это ограничивает количество одновременных запросов к AI до двух, предотвращая массовую отправку запросов, которая приводила к ошибкам. Блокирующие вызовы AI теперь выполняются в отдельных потоках с помощью asyncio.to_thread для предотвращения заморозки приложения.

  • Commit 14 (2025-07-11): Оптимизирован расход дневного лимита API. Логика генерации вопросов в QuestionService изменена так, чтобы создавать ровно необходимое количество запросов, а не избыточное. Это предотвращает быстрое исчерпание дневной квоты (200 запросов/день) и повышает стабильность работы бота.

  • Commit 15 (2025-07-11): Упрощена валидация AI-вопросов в QuestionService. Была удалена избыточная и слишком строгая проверка на соответствие ответа и объяснения (_validate_answer_explanation_consistency), которая отбраковывала валидные вопросы. Это повысит процент успешно сгенерированных заданий.

  • Commit 16 (2025-07-11):

    • Ускорение генерации: В связи с переходом на платный API-тариф, количество одновременных запросов к AI в QuestionService увеличено до 10, что значительно повышает скорость создания тестов.
    • Исправлен баг с вариантами: В ImprovedAIService улучшен парсер для фильтрации "мусорных" вариантов ответа (например, состоящих из одной точки), которые иногда генерировал AI.

  • Commit 17 (2025-07-11): Исправлена ошибка в _clean_explanation_text, из-за которой отбраковывались валидные объяснения от AI, содержащие списки. Это приводило к генерации меньшего количества вопросов, чем требовалось. Теперь парсер корректно обрабатывает такие объяснения, что повышает стабильность и надежность генерации тестов.

  • Commit 18 (2025-07-11): Глобальное улучшение стабильности и качества генерации тестов.

    • Гарантированная генерация: Логика генерации вопросов в QuestionService полностью переработана. Теперь система настойчиво запрашивает вопросы у AI до тех пор, пока не наберет ровно 10 валидных.
    • Улучшенная генерация вариантов: Система больше не добавляет фиктивные варианты. Вместо этого она подбирает релевантные неправильные ответы из базы данных, что значительно повышает качество вариантов.
    • Повышение разнообразия вопросов: В промпт для AI добавлено требование избегать повторяющихся сценариев и персонажей для создания более интересных тестов.
    • Детальное логирование: Улучшена диагностика ошибок парсинга для быстрого выявления проблем в будущем.

  • Commit 19 (2025-07-11): Исправлена критическая ошибка и улучшена логика обработки ответов.

    • Восстановлена умная генерация вариантов: Добавлен недостающий метод get_similar_incorrect_options в слой доступа к данным, что позволило включить механизм подбора релевантных неправильных ответов из базы.
    • Смягчена очистка вариантов: Ослаблена логика очистки в _clean_option_text, чтобы предотвратить удаление валидных вариантов ответа (например, "Невозможно определить"), что повысило процент успешно принимаемых AI-вопросов.

Улучшение стабильности и качества AI-генерации (10.07.2025)

  • Исправлена критическая ошибка SQL: Устранена ошибка for SELECT DISTINCT, ORDER BY expressions must appear in select list в get_similar_incorrect_options, которая возникала при попытке сгенерировать дополнительные варианты ответов.
  • Улучшена логика парсинга: Модифицирован парсер ответов AI для корректной обработки коротких (в том числе односимвольных) вариантов ответа, что предотвращает отбраковку валидных числовых ответов.
  • Усилен промпт для AI: В промпт добавлена более общая инструкция, требующая от AI проявлять креативность и не повторять одних и тех же персонажей или сценарии в нескольких вопросах подряд. Это решает проблему генерации однотипных задач.

Продвинутая генерация вопросов с помощью AI (10.07.2025)

  • Внедрен "умный" промпт: Вместо общих просьб о креативности реализован новый, продвинутый промпт, в котором AI дается роль "опытного методиста".
  • Управление разнообразием через task_type: Добавлен новый параметр task_type ("жизненная ситуация", "числовая прямая" и т.д.), который позволяет напрямую управлять типом создаваемой задачи, гарантируя их структурное разнообразие.
  • Улучшенные творческие ограничения: В промпт добавлены более конкретные примеры желаемых сюжетов (космос, роботы) и негативные ограничения (запрет на "Петю и Васю"), что стимулирует AI создавать более интересный контент.

Повышение надежности AI и самоконтроль (10.07.2025)

  • Внедрена самопроверка (self-verification): В промпт добавлено критически важное правило, требующее от AI перед генерацией ответа проверять, что итоговый результат в пошаговом объяснении точно совпадает со значением в поле [CORRECT_ANSWER]. Это предотвращает "галлюцинации" и внутренние противоречия в ответах.
  • Ограничение на краткость объяснений: Добавлена инструкция, требующая создавать объяснения не более чем в 2-4 шага. Это защищает от слишком длинных, бессвязных ответов, которые могут возникать, когда AI "зацикливается" на сложной задаче.

Улучшение проверки на дубликаты (10.07.2025)

  • Повышен порог схожести (similarity): Порог для нечеткого поиска дубликатов при загрузке вопросов из PDF увеличен с 0.7 до 0.85. Это делает проверку более строгой и предотвращает ложные срабатывания, когда система ошибочно помечала уникальные, но похожие по структуре вопросы как дубликаты.

Отключение нечеткого поиска для PDF (10.07.2025)

Проблема: При загрузке PDF с большим количеством структурно похожих вопросов (например, "Вычислите: ..."), система нечеткого поиска (fuzzy search) ошибочно помечала их как дубликаты, даже если они были уникальными. В результате из 36 вопросов в базу добавлялось только 19.

Решение:

  1. Внедрение флага exact_only: В основной метод проверки дубликатов get_explanation_by_question_text был добавлен флаг exact_only. Если он установлен в True, выполняется только строгая проверка на 100% совпадение текста вопроса, полностью отключая нечеткий поиск.
  2. Сквозная передача флага: Вся цепочка вызовов при обработке PDF, начиная от QuestionsHandler в админ-панели, через PDFProcessor и SyncDatabaseFacade, была модифицирована для передачи флага exact_only=True.
  3. Результат: Теперь при импорте из PDF используется исключительно точное совпадение, что гарантирует добавление всех уникальных вопросов, предоставленных преподавателем, и решает проблему ложного обнаружения дубликатов.

Продвинутый промптинг и самопроверка ИИ (09.07.2025)

Проблема: Иногда ИИ "галлюцинировал" — в пошаговом объяснении все было верно, но в поле [CORRECT_ANSWER] стоял неправильный ответ. Также вопросы были слишком однотипными.

Интеллектуальная генерация вариантов ответов (12.07.2024):

  • Проблема: В тестах появлялись "мусорные" варианты ответов (например, "Вариант 3") и неоднозначные (например, "Невозможно определить"). Это происходило, когда системе не удавалось сгенерировать достаточное количество осмысленных неправильных ответов.
  • Решение:
    • Старый механизм, создававший бесполезные заглушки, полностью удален.
    • Реализована новая функция generate_universal_options, которая подбирает в качестве неправильных ответов реальные, но неверные ответы из других вопросов по той же теме.
    • Если в базе не находится подходящих вариантов, система генерирует числовые вариации (например, для ответа 10 могут быть предложены 12, 8.5 и т.д.).
    • Фильтры AI обновлены, чтобы исключить генерацию неоднозначных фраз.
  • Результат: Качество тестов значительно выросло. Теперь все варианты ответов являются осмысленными и релевантными, что делает процесс обучения более эффективным.
  • Улучшение UI и фильтрация контента (12.07.2024):
    • Проблема 1 (UI): При выходе из теста через кнопку "Выбрать другую тему", сообщение с последним вопросом оставалось на экране, создавая визуальный мусор.
    • Решение 1: Логика обработчика handle_back_to_topics была изменена. Теперь он полностью удаляет сообщение с вопросом (delete_message) вместо того, чтобы просто убирать клавиатуру.

Упрощение и ужесточение валидации вопросов (12.07.2024):

  • Проблема: Система пыталась "исправить" некачественные ответы от AI, у которых не хватало неправильных вариантов, с помощью сложной и ненадежной логики, что приводило к появлению "мусорных" вариантов вроде "Вариант 3".

  • Решение (на основе вашего предложения):

    • Отказ от усложнения: Вместо того чтобы "исправлять" плохие ответы, мы теперь просто их отвергаем.
    • Строгая валидация AI: Любой ответ от AI, не содержащий 3 неправильных варианта, немедленно отбраковывается.
    • Удаление сложного кода: Громоздкая функция generate_universal_options и все связанные с ней вызовы были полностью удалены.
    • Контроль качества для БД: Добавлена проверка, которая отсеивает вопросы из основной базы данных, если у них по какой-либо причине менее 4 вариантов ответа.

  • Результат: Код стал значительно проще, чище и надежнее. Система теперь гарантирует, что все вопросы, попадающие в тест (независимо от источника), соответствуют строгому стандарту качества.

  • Улучшена работа с кэшем тем: Теперь кэш сбрасывается только при необходимости, что уменьшает количество обращений к базе данных.

  • Исправлен редкий баг: Устранена ошибка, когда бот мог зависнуть при генерации объяснений к вопросам в редких случаях.

  • Надежность раздела редактирования тем: Добавлены проверки и улучшена обработка ошибок в разделе редактирования тем для администраторов, что предотвращает падения из-за некорректных данных.

  • Исправлена ошибка KeyError: Устранена ошибка KeyError: 'name' в разделе редактирования тем, возникшая после переименования поля в базе данных. Код обновлен для использования актуального имени поля subtopic_name.

Улучшение управления доступом и кешированием (10.07.2025)

  • Решена проблема с кешем доступа: Устранена проблема, когда пользователь с активированным доступом (has_access=TRUE) не мог войти в бот. Причиной был устаревший отрицательный результат в кеше.
  • Внедрена команда /clear_cache: Добавлена администраторская команда /clear_cache <user_id>, позволяющая принудительно сбрасывать кеш для конкретного пользователя без перезапуска бота.
  • Автоматическая очистка кеша: Улучшена логика работы с кешем. Теперь при любом изменении прав или данных пользователя (добавление, изменение статуса доступа, обновление информации) его кеш сбрасывается автоматически, что предотвращает подобные проблемы в будущем.

Планы на будущее