mnemo_cards/mnemo_cards_web_v2/CHAT_PLAN.md

# План реализации чата в mnemo_cards_web_v2

## 📋 Обзор

Добавление функциональности чата для общения пользователя с LLM через сервер. Поддержка текста и аудио сообщений (включая голосовые).

**Дата создания:** November 8, 2025  
**Приоритет:** HIGH  
**Оценка времени:** 60-80 часов  
**Архитектура:** Clean Architecture, yx_scope/yx_state

---

## 🎯 Цели проекта

1. **Чат с LLM** - Общение пользователя с ИИ через сервер
2. **Поддержка медиа** - Текст и аудио (включая голосовые сообщения)
3. **Чистая архитектура** - Соблюдение паттернов проекта
4. **Адаптивный UI** - Работа на всех устройствах
5. **Реактивное состояние** - State management через yx_state

---

## 📁 Архитектурный обзор

### Clean Architecture слои:
```
├── domain/
│   ├── models/           # ChatMessage, AudioMessage, ChatSession
│   ├── services/         # ChatService, AudioService
│   └── state/            # ChatStateManager
├── presentation/
│   ├── pages/            # ChatPage
│   └── widgets/          # MessageBubble, AudioPlayer, etc.
└── di/
    └── user_scope/
        └── modules/      # ChatModule
```

---

## 📋 Детальный план реализации

### Фаза 1: Инфраструктура и модели данных (12-16 часов)

#### 1.1 Модели данных (4-6 часов)
- **ChatMessage** - Базовое сообщение чата
- **AudioMessage** - Аудио сообщение с метаданными
- **ChatSession** - Сессия чата
- **ChatParticipant** - Участник (пользователь/ассистент)
- **MessageStatus** - Статусы сообщений (отправлено, доставлено, ошибка)

#### 1.2 HTTP интеграция (4-6 часов)
- Расширение `HttpRepositoryV2` методами чата:
  - `POST /api/v2/chat/messages` - Отправка текстового сообщения
  - `POST /api/v2/chat/audio` - Отправка аудио сообщения
  - `GET /api/v2/chat/messages/{sessionId}` - Получение истории
  - `POST /api/v2/chat/sessions` - Создание сессии
- Обработка ошибок и таймаутов

#### 1.3 State management (4-4 часов)
- **ChatStateManager** - Управление состоянием чата
- Состояния: loading, loaded, error
- Реактивные обновления сообщений
- Управление активной сессией

### Фаза 2: Сервисы и бизнес-логика (16-20 часов)

#### 2.1 ChatService (6-8 часов)
- Отправка текстовых сообщений
- Получение ответов от LLM
- Управление сессиями чата
- Кэширование сообщений
- Обработка ошибок сети

#### 2.2 AudioService (6-8 часов)
- Запись аудио через Web Audio API
- Воспроизведение аудио сообщений
- Конвертация форматов (WebM/WAV → подходящий для сервера)
- Управление микрофоном (разрешения, состояние)
- Обработка голосовых команд

#### 2.3 DI интеграция (4-4 часов)
- **ChatModule** - Модуль для UserScope
- Регистрация сервисов в контейнере
- Зависимости: HttpRepositoryV2, AudioService

### Фаза 3: UI компоненты (20-24 часов)

#### 3.1 Базовые компоненты чата (8-10 часов)
- **MessageBubble** - Пузырь сообщения (текст/аудио)
- **MessageList** - Список сообщений с виртуализацией
- **ChatInput** - Поле ввода с прикреплением файлов
- **AudioRecorder** - Кнопка записи голосовых сообщений
- **AudioPlayer** - Воспроизведение аудио сообщений

#### 3.2 ChatPage (8-10 часов)
- Основная страница чата
- AppBar с информацией о сессии
- Сообщения + input внизу
- Обработка состояний загрузки/ошибок
- Адаптивный layout (мобильный/десктоп)

#### 3.3 Навигация и роутинг (4-4 часов)
- Добавление маршрута `/chat` в AppRouter
- Кнопка чата в bottom navigation или sidebar
- Переход к чату из других страниц

### Фаза 4: Аудио функциональность (8-12 часов)

#### 4.1 Запись аудио (4-6 часов)
- Web Audio API интеграция
- MediaRecorder для захвата
- Визуализация уровня звука
- Обработка разрешений микрофона
- Отправка на сервер

#### 4.2 Воспроизведение аудио (4-6 часов)
- HTML5 Audio для воспроизведения
- Кастомные контролы (play/pause/progress)
- Обработка ошибок загрузки
- Кэширование аудио файлов

### Фаза 5: Интеграция и полировка (8-12 часов)

#### 5.1 Backend endpoints (4-6 часов)
- Реализация серверных эндпоинтов
- Интеграция с LLM API
- Обработка аудио файлов
- Хранение истории чата

#### 5.2 Тестирование и QA (4-6 часов)
- Unit тесты для всех сервисов
- Widget тесты для UI компонентов
- Интеграционные тесты
- Тестирование аудио функциональности
- Кросс-браузерная совместимость

---

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

### Аудио обработка
```dart
// Web Audio API для записи
final stream = await navigator.mediaDevices.getUserMedia({'audio': true});
final recorder = MediaRecorder(stream);

// Конвертация для отправки
final audioBlob = await recorder.stop();
final audioFile = File.fromRawPath(audioBlob);
```

### State management
```dart
@freezed
class ChatState with _$ChatState {
  const factory ChatState.loading() = ChatStateLoading;
  const factory ChatState.loaded({
    required List<ChatMessage> messages,
    required ChatSession session,
  }) = ChatStateLoaded;
  const factory ChatState.error(String message) = ChatStateError;
}
```

### HTTP интеграция
```dart
// Отправка сообщения
final response = await _httpRepository.sendMessage(
  sessionId: session.id,
  content: message.text,
  type: MessageType.text,
);

// Получение ответа
final llmResponse = ChatMessage.fromJson(response.data);
```

---

## 📱 UI/UX требования

### Адаптивный дизайн
- **Мобильный**: Полноэкранный чат, клавиатура поверх
- **Десктоп**: Sidebar или отдельное окно
- **Планшет**: Оптимизированный layout

### Аудио UX
- Визуальная обратная связь при записи
- Волновая форма для аудио сообщений
- Длительность и размер файла
- Возможность отмены записи

### Сообщения
- Разные стили для пользователя/ассистента
- Статусы доставки
- Тайминги сообщений
- Поддержка markdown в ответах LLM

---

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

### Unit тесты
- ChatService: отправка/получение сообщений
- AudioService: запись/воспроизведение
- ChatStateManager: state transitions
- Модели: сериализация/десериализация

### Widget тесты
- MessageBubble: рендеринг разных типов
- ChatInput: ввод текста и аудио
- MessageList: виртуализация и скролл

### Интеграционные тесты
- Полный флоу отправки сообщения
- Аудио запись и отправка
- Обработка ошибок сети

---

## 🚀 Roadmap реализации

### Неделя 1-2: Фаза 1 (Инфраструктура)
- День 1-2: Модели данных
- День 3-4: HTTP интеграция
- День 5: State management
- День 6-7: DI и модули

### Неделя 3-4: Фаза 2 (Сервисы)
- День 8-10: ChatService
- День 11-13: AudioService
- День 14: Интеграция сервисов

### Неделя 5-6: Фаза 3 (UI)
- День 15-18: UI компоненты
- День 19-21: ChatPage
- День 22: Навигация

### Неделя 7-8: Фаза 4-5 (Аудио + Полировка)
- День 23-25: Аудио функциональность
- День 26-28: Backend интеграция
- День 29-30: Тестирование
- День 31-32: Финальная полировка

---

## 📊 Критерии приемки

### Функциональные требования
- ✅ Отправка текстовых сообщений
- ✅ Получение ответов от LLM
- ✅ Запись голосовых сообщений
- ✅ Воспроизведение аудио ответов
- ✅ История сообщений сохраняется
- ✅ Обработка ошибок сети

### Нефункциональные требования
- ✅ Адаптивный дизайн (мобильный/десктоп)
- ✅ Производительность (виртуализация списка)
- ✅ Доступность (WCAG 2.1 AA)
- ✅ Безопасность (HTTPS, валидация данных)

### Качество кода
- ✅ 80%+ тестового покрытия
- ✅ Соблюдение clean architecture
- ✅ Type-safe код (freezed)
- ✅ Документация всех публичных API

---

## 🔄 Зависимости и риски

### Внешние зависимости
- **Backend API**: Эндпоинты чата должны быть готовы
- **LLM интеграция**: Доступ к модели ИИ
- **Web Audio API**: Поддержка в целевых браузерах

### Технические риски
- **Аудио совместимость**: Разные браузеры поддерживают разные кодеки
- **Производительность**: Большие аудио файлы
- **Сетевая надежность**: Обработка обрывов соединения

### МитIGATION стратегии
- Progressive enhancement для аудио
- Offline-first подход для сообщений
- Graceful degradation при ошибках

---

## 📈 Метрики успеха

### Технические метрики
- **Время ответа**: <2s для текстовых сообщений
- **Аудио качество**: 128kbps минимум
- **Test coverage**: >80%
- **Bundle size**: <500KB дополнительно

### Пользовательские метрики
- **Сообщения/сессия**: Среднее количество сообщений
- **Время сессии**: Среднее время использования чата
- **Аудио использование**: Процент голосовых сообщений

---

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

1. **Создать todo-список** для фазы 1
2. **Начать с моделей данных** (ChatMessage, AudioMessage)
3. **Реализовать HTTP интеграцию** в HttpRepositoryV2
4. **Создать ChatStateManager** с базовым состоянием
5. **Написать unit тесты** для первых компонентов

---

**Статус плана:** ✅ Готов к реализации  
**Следующий шаг:** Создание todo-списка и начало фазы 1