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
```dart
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. Реализация будет вестись итеративно с постоянным тестированием.*