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