318 lines
12 KiB
Markdown
318 lines
12 KiB
Markdown
# План реализации чата в 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
|