mnemo_cards/games/WORK_PLAN.md

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

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

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

**Ссылки на документацию:**
- [Архитектура и этапы разработки](flutter_webview_bridge_plan.md#архитектура-пакета)
- [Структура монорепозитория](PROJECT_STRUCTURE.md#общая-структура)

---

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

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

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

---

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

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

**Задачи:**
1. Создать корневую структуру проекта
2. Настроить `melos.yaml` согласно [структуре](PROJECT_STRUCTURE.md#общая-структура)
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` модель (см. [модель сообщения](flutter_webview_bridge_plan.md#модель-сообщения))
2. Реализовать `BridgePayload` абстракцию
3. Создать `PayloadRegistry` для регистрации типов
4. Добавить сериализацию/десериализацию

**Ключевые классы:**
```dart
// 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-пакета:**
```dart
// Регистрация типов
void registerPayloads() {
  BridgePayload.register('ping', (json) => PingPayload.fromJson(json));
  BridgePayload.register('get_user_info', (json) => GetUserInfoPayload.fromJson(json));
}
```

**Ссылка на разделение доступа:** [Таблица доступа](PROJECT_STRUCTURE.md#разделение-доступа)

---

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

**Задачи:**
1. Создать `BridgeWebViewController` (см. [WebView контроллер](flutter_webview_bridge_plan.md#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 пример](flutter_webview_bridge_plan.md#flutter-host-пример)

---

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

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

**Ссылка на реализацию:** [JavaScript Bridge](flutter_webview_bridge_plan.md#javascript-bridge)

**Файлы:**
- `web_app1/web/bridge.js`
- `web_app1/web/index.html`

---

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

**Задачи:**
1. Реализовать `WebBridge` класс (см. [Web Bridge класс](flutter_webview_bridge_plan.md#web-bridge-класс))
2. Настроить обработку сообщений от хоста
3. Создать UI приложения
4. Интегрировать с JavaScript bridge

**Ключевые компоненты:**
- `web_app1/lib/src/web_bridge.dart`
- `web_app1/lib/src/handlers/` - обработчики payload'ов

**Ссылка на пример:** [Flutter Web пример](flutter_webview_bridge_plan.md#flutter-web-пример)

---

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

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

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

**Ссылка на тесты:** [Unit тесты](flutter_webview_bridge_plan.md#unit-тесты)

---

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

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

**Ссылка на документацию:** [README.md](flutter_webview_bridge_plan.md#readmemd)

---

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

### Управление зависимостями
```yaml
# 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'ов
```dart
// Пример 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']));
}
```

### Регистрация в приложениях
```dart
// В 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 функциональности