249 lines
No EOL
9.1 KiB
Markdown
249 lines
No EOL
9.1 KiB
Markdown
# 🚀 План работы: 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 функциональности |