mnemo_cards/mnemo_cards_web_v2/GAME_TESTS_IMPLEMENTATION_PLAN.md

План реализации игровых тестов в mnemo_cards_web_v2

Анализ текущей архитектуры

mnemo_cards (референс)

• Архитектура: Bloc + Service Locator (GetIt)
• Типы вопросов:
  • SimpleTestQuestionBody: выбор одного варианта из нескольких кнопок
  • InputButtonsTestQuestionBody: ввод слова по буквам с кнопками
• Управление состоянием: TestManager (Cubit) + ActiveTestHolder (Bloc)
• Хранение состояния: TestQuestionState (с подклассами)
• UI: PageView с вопросами, прогресс, результаты

mnemo_cards_web_v2 (текущая)

• Архитектура: Чистая архитектура с yx_scope/yx_state
• Модули: TestsModule, TestsStateManager (StateManager)
• Текущая реализация: базовый TestPage без полноценной игровой механики

Цели реализации

1. Простые тесты: начать с выбора 1 варианта из нескольких (аналог SimpleTest)
2. Архитектура: придерживаться yx_state/yx_scope, не копировать код mnemo_cards
3. Прогрессивная разработка: от простого к сложному

Фазы реализации

Фаза 1: Базовая инфраструктура для игровых тестов

1.1 Расширение модели данных

• Создать domain/models/game_question.dart
• Определить GameQuestion с типами: multipleChoice, inputLetters
• Добавить GameQuestionState для отслеживания прогресса

1.2 Game Session Manager

• Создать domain/services/game_session_manager.dart
• Управление активной игровой сессией
• Отслеживание ответов, времени, прогресса
• Автоматический переход к следующему вопросу

1.3 Game State Manager

• Расширить domain/state/tests_state_manager.dart
• Добавить состояния: playing, questionCompleted, sessionCompleted
• Управление игровым потоком

1.4 Базовые UI компоненты

• presentation/widgets/game/question_display.dart - отображение вопроса
• presentation/widgets/game/answer_options.dart - варианты ответов
• presentation/widgets/game/progress_indicator.dart - прогресс

Фаза 2: Простые тесты с выбором ответа

2.1 Модель данных для Multiple Choice

class MultipleChoiceQuestion extends GameQuestion {
  final String question;
  final String? image;
  final String? audio;
  final List<String> options;
  final String correctAnswer;
  final String word; // связанное слово для статистики
}

2.2 Game Session для Multiple Choice

• Управление выбором ответа
• Валидация правильности
• Автоматический переход через 300мс при правильном ответе
• Визуальная обратная связь (зеленый/красный)

2.3 UI компоненты

• MultipleChoiceWidget - основной виджет вопроса
• Анимации выбора ответа
• Звуковые эффекты (опционально)

Фаза 3: Расширенные возможности

3.1 Статистика и аналитика

• Отправка результатов в statistics_service.dart
• Трекинг правильных/неправильных ответов
• Время ответа на вопрос

3.2 Игровые улучшения

• Таймер на вопрос (опционально)
• Подсказки
• Пропуск вопросов

3.3 UX улучшения

• Анимации переходов
• Звуковое сопровождение
• Темная тема адаптация

Фаза 4: Сложные типы вопросов

4.1 Input Letters (ввод по буквам)

• Аналог InputButtonsTestQuestionBody
• Кнопки с буквами
• Валидация введенного слова

4.2 Match Questions (соответствие)

• Связывание элементов
• Drag & Drop

4.3 Matrix Questions (матрица)

• Более сложные комбинации

Технические решения

Архитектура состояний

GameSessionState
├── sessionNotStarted
├── questionInProgress
│   ├── currentQuestion: GameQuestion
│   ├── selectedAnswer: String?
│   ├── timeElapsed: Duration
│   └── isCorrect: bool?
├── questionCompleted
│   ├── correct: bool
│   └── nextQuestionDelay: Duration
└── sessionCompleted
    ├── results: GameResults
    └── statistics: TestStatisticsDto

Навигация вопросов

• Использовать PageView для swipe навигации
• Блокировать swipe назад после ответа
• Автоматический переход вперед при правильном ответе

Управление ресурсами

• Preload изображений и аудио
• Кэширование через image_cache_service.dart
• Освобождение ресурсов при завершении сессии

Порядок реализации

Шаг 1: Базовая инфраструктура ✅

1. Создать модели данных
2. Реализовать GameSessionManager
3. Расширить TestsStateManager
4. Создать базовые UI компоненты

Шаг 2: Multiple Choice тесты 🔄

1. Создать MultipleChoiceQuestion модель
2. Реализовать логику выбора ответа
3. Создать UI компоненты
4. Интегрировать с существующим TestPage

Шаг 3: Статистика и аналитика

1. Интеграция со StatisticsService
2. Отправка результатов
3. Сохранение прогресса

Шаг 4: UX улучшения

1. Анимации
2. Звуки
3. Темная тема

Шаг 5: Дополнительные типы вопросов

1. Input Letters
2. Match questions
3. Matrix questions

Критерии готовности

Функциональные требования

• ✅ Загрузка тестов из API
• ✅ Отображение вопросов с текстом/изображениями/аудио
• ✅ Выбор ответа из нескольких вариантов
• ✅ Визуальная обратная связь
• ✅ Автоматический переход к следующему вопросу
• ✅ Показ результатов по завершении
• ✅ Отправка статистики на бэкенд

Нефункциональные требования

• ⚡ Быстрая загрузка и навигация
• 🎯 Адаптивный UI для разных экранов
• ♿ Доступность (accessibility)
• 🎨 Соответствие дизайну приложения

Риски и mitigation

Риск 1: Сложность интеграции с существующей архитектурой

Mitigation: Начать с малого, постепенно расширять

Риск 2: Производительность при большом количестве вопросов

Mitigation: Ленивая загрузка, preload ближайших вопросов

Риск 3: UX несоответствия с мобильной версией

Mitigation: Регулярные проверки с дизайнерами, usability testing

Следующие шаги

1. Немедленно: Создать модели данных и базовую инфраструктуру
2. Краткосрочные: Реализовать Multiple Choice тесты
3. Среднесрочные: Добавить статистику и улучшения UX
4. Долгосрочные: Расширить на другие типы вопросов

Тестирование

• Unit тесты для всех сервисов и менеджеров
• Widget тесты для UI компонентов
• Integration тесты для полного игрового потока
• E2E тесты с реальными данными

---

План составлен на основе анализа mnemo_cards и архитектуры mnemo_cards_web_v2. Реализация будет вестись итеративно с постоянным тестированием.