mnemo_cards/games/WORK_PLAN.md

🚀 План работы: Flutter WebView Bridge

📋 Обзор проекта

Создание монорепозитория с Melos для реализации двустороннего взаимодействия между Flutter-хостом и Flutter Web-приложениями через WebView.

Ссылки на документацию:

• Архитектура и этапы разработки
• Структура монорепозитория

---

🎯 Цели и приоритеты

Основные цели

1. Изоляция зависимостей - web-приложения видят только нужные payload'ы
2. Типобезопасность - строгая типизация всех сообщений
3. Масштабируемость - легко добавлять новые web-приложения
4. Тестируемость - независимое тестирование компонентов

Критерии готовности

• Все пакеты созданы и настроены в Melos
• Базовое взаимодействие host ↔ web работает
• Система payload'ов функционирует
• Примеры приложений работают
• Тесты покрывают основные сценарии

---

📅 Этапы реализации

Этап 1: Настройка монорепозитория (1 день)

Задачи:

1. Создать корневую структуру проекта
2. Настроить melos.yaml согласно структуре
3. Инициализировать все пакеты с правильными зависимостями
4. Настроить pubspec.yaml для каждого пакета

Результат: Рабочий монорепозиторий с melos bootstrap

Файлы для создания:

games/
├── melos.yaml
├── bridge_core/
├── payloads_shared/
├── payloads_host/
├── payloads_app1/
├── host_app/
└── web_app1/

Здесь и далее, web_app1 - пример приложения на котором тестируется плагин.

Этап 2: Реализация bridge_core (2 дня)

Задачи:

1. Создать BridgeMessage модель (см. модель сообщения)
2. Реализовать BridgePayload абстракцию
3. Создать PayloadRegistry для регистрации типов
4. Добавить сериализацию/десериализацию

Ключевые классы:

// bridge_core/lib/src/models/bridge_message.dart
// bridge_core/lib/src/models/bridge_payload.dart
// bridge_core/lib/src/registry/payload_registry.dart

Зависимости: uuid: ^4.0.0

---

Этап 3: Создание payload-пакетов (1-2 дня)

Задачи:

1. payloads_shared: общие payload'ы (Ping, GetUserInfo)
2. payloads_host: специфичные для хоста (SecretAdmin, ShowNativeDialog)
3. payloads_app1: специфичные для web_app1 (Login, SubmitQuiz)

Структура каждого payload-пакета:

// Регистрация типов
void registerPayloads() {
  BridgePayload.register('ping', (json) => PingPayload.fromJson(json));
  BridgePayload.register('get_user_info', (json) => GetUserInfoPayload.fromJson(json));
}

Ссылка на разделение доступа: Таблица доступа

---

Этап 4: Flutter Host приложение (3-4 дня)

Задачи:

1. Создать BridgeWebViewController (см. WebView контроллер)
2. Реализовать JavaScript handler для приема сообщений
3. Настроить отправку сообщений в WebView
4. Создать UI с WebView виджетом

Ключевые компоненты:

• host_app/lib/src/bridge_webview_controller.dart
• host_app/lib/src/bridge_webview.dart
• host_app/lib/src/handlers/ - обработчики payload'ов

Зависимости: flutter_inappwebview: ^6.0.0

Ссылка на пример: Flutter Host пример

---

Этап 5: JavaScript Bridge (1 день)

Задачи:

1. Создать web/bridge.js для обработки событий
2. Настроить интеграцию с Flutter Web
3. Добавить в HTML оболочку

Ссылка на реализацию: JavaScript Bridge

Файлы:

• web_app1/web/bridge.js
• web_app1/web/index.html

---

Этап 6: Flutter Web приложение (2-3 дня)

Задачи:

1. Реализовать WebBridge класс (см. Web Bridge класс)
2. Настроить обработку сообщений от хоста
3. Создать UI приложения
4. Интегрировать с JavaScript bridge

Ключевые компоненты:

• web_app1/lib/src/web_bridge.dart
• web_app1/lib/src/handlers/ - обработчики payload'ов

Ссылка на пример: Flutter Web пример

---

Этап 7: Интеграция и тестирование (2-3 дня)

Задачи:

1. Настроить все зависимости между пакетами
2. Протестировать полный цикл сообщений
3. Проверить изоляцию payload'ов
4. Написать unit и integration тесты

Тестовые сценарии:

• Ping/Pong между host и web
• Передача пользовательских данных
• Обработка ошибок и таймаутов
• Проверка изоляции payload'ов

Ссылка на тесты: Unit тесты

---

Этап 8: Документация и примеры (1-2 дня)

Задачи:

1. Создать README для каждого пакета
2. Написать примеры использования
3. Документировать API
4. Создать troubleshooting guide

Ссылка на документацию: README.md

---

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

Управление зависимостями

# melos.yaml
name: flutter_webview_bridge_repo
packages:
  - packages/bridge_core
  - packages/payloads_shared
  - packages/payloads_host
  - packages/payloads_app1
  - apps/host_app
  - apps/web_app1

Структура payload'ов

// Пример payload
class GetUserInfoPayload extends BridgePayload {
  final List<String> fields;
  
  GetUserInfoPayload({required this.fields});
  
  @override
  Map<String, dynamic> toJson() => {'fields': fields};
  
  factory GetUserInfoPayload.fromJson(Map<String, dynamic> json) =>
      GetUserInfoPayload(fields: List<String>.from(json['fields']));
}

Регистрация в приложениях

// В main() каждого приложения
void main() {
  registerPayloads(); // Регистрирует только нужные типы
  runApp(MyApp());
}

---

🚨 Риски и митигация

Риск 1: Сложность настройки Melos

Митигация: Начать с простой структуры, постепенно усложнять

Риск 2: Проблемы с WebView на разных платформах

Митигация: Тестировать на Android/iOS/Web с самого начала

Риск 3: Утечки памяти в callback'ах

Митигация: Использовать таймауты и автоматическую очистку

---

📊 Метрики успеха

• melos bootstrap выполняется без ошибок
• Ping/Pong работает между host и web
• Payload'ы изолированы (web_app1 не видит payloads_host)
• Тесты покрывают >80% кода
• Примеры приложений работают на всех платформах

---

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

1. Создать структуру монорепозитория
2. Настроить Melos конфигурацию
3. Начать с bridge_core пакета
4. Постепенно добавлять остальные компоненты

Общее время: 10-15 дней Приоритет: Высокий для core функциональности