2025-11-11 02:55:41 +03:00

12 KiB

Raw Blame History

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

📋 Обзор

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

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

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

Чат с LLM - Общение пользователя с ИИ через сервер
Поддержка медиа - Текст и аудио (включая голосовые сообщения)
Чистая архитектура - Соблюдение паттернов проекта
Адаптивный UI - Работа на всех устройствах
Реактивное состояние - 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 компонентов
Интеграционные тесты
Тестирование аудио функциональности
Кросс-браузерная совместимость

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

Аудио обработка

// 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

@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 интеграция

// Отправка сообщения
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
Модели: сериализация/десериализация

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 дополнительно

Пользовательские метрики

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

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

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

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

12 KiB Raw Blame History Unescape Escape