mnemo_cards/games/ARCHITECTURE.md

🏗️ Архитектура Flutter WebView Bridge

📋 Обзор системы

Flutter WebView Bridge - это система для безопасной коммуникации между Flutter Host приложением и Flutter Web приложениями через WebView. Система обеспечивает типобезопасность, изоляцию payload'ов и простоту использования.

🏛️ Архитектурные принципы

1. Изоляция payload'ов

• Web приложения видят только свои payload'ы
• Host приложение контролирует доступ к payload'ам
• Безопасная архитектура без утечек данных

2. Типобезопасность

• Все payload'ы типизированы
• Компилятор проверяет корректность
• Автодополнение в IDE

3. Модульность

• Переиспользуемые компоненты
• Легкое расширение функциональности
• Четкое разделение ответственности

📦 Структура пакетов

packages/
├── bridge_core/           # Базовые типы и сериализация
├── payloads_shared/       # Общие payload'ы для всех приложений
├── payloads_host/         # Payload'ы только для host приложения
└── payloads_app1/         # Payload'ы только для web_app1

apps/
├── host_app/             # Flutter приложение с WebView
└── web_app1/             # Flutter Web приложение

Изоляция payload'ов

// ✅ web_app1 может использовать:
import 'package:payloads_shared/payloads_shared.dart';
import 'package:payloads_app1/payloads_app1.dart';

// ❌ web_app1 НЕ может использовать:
// import 'package:payloads_host/payloads_host.dart'; // Ошибка компиляции

// ✅ host_app может использовать все:
import 'package:payloads_shared/payloads_shared.dart';
import 'package:payloads_host/payloads_host.dart';
import 'package:payloads_app1/payloads_app1.dart';

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

1. Bridge Core (packages/bridge_core/)

Базовые типы и сериализация для всей системы.

// Базовый класс для всех payload'ов
abstract class Payload {
  String get type;
  Map<String, dynamic> toJson();
}

// Базовый класс для всех ответов
abstract class PayloadResponse {
  String get type;
  Map<String, dynamic> toJson();
}

// Базовый класс для обработчиков
abstract class PayloadHandler<T extends Payload> {
  Future<PayloadResponse> handle(T payload);
}

2. Payloads Shared (packages/payloads_shared/)

Общие payload'ы, доступные всем приложениям.

// Ping/Pong для проверки связи
class PingPayload extends Payload {
  final String message;
  // ...
}

class PongResponse extends PayloadResponse {
  final String message;
  // ...
}

// Информация о пользователе
class UserInfoPayload extends Payload {
  // ...
}

class UserInfoResponse extends PayloadResponse {
  final UserInfoData userInfo;
  // ...
}

3. Payloads Host (packages/payloads_host/)

Payload'ы только для host приложения.

// Административные команды
class AdminCommandPayload extends Payload {
  final String command;
  final Map<String, dynamic> parameters;
  // ...
}

// Нативные диалоги
class NativeDialogPayload extends Payload {
  final String title;
  final String message;
  final String type;
  // ...
}

4. Payloads App1 (packages/payloads_app1/)

Payload'ы только для web_app1.

// Авторизация
class LoginPayload extends Payload {
  final LoginData loginData;
  // ...
}

class LoginResponse extends PayloadResponse {
  final bool success;
  final String message;
  // ...
}

// Quiz система
class QuizPayload extends Payload {
  final QuizResults results;
  // ...
}

class QuizResponse extends PayloadResponse {
  final bool saved;
  final String message;
  // ...
}

🔄 Поток данных

1. Web → Host коммуникация

sequenceDiagram
    participant Web as web_app1
    participant JS as JavaScript Bridge
    participant WebView as Flutter WebView
    participant Host as host_app
    participant Handler as Payload Handler

    Web->>JS: sendPayload(payload)
    JS->>WebView: callHandler('sendPayload', data)
    WebView->>Host: onMessageReceived(data)
    Host->>Handler: handle(payload)
    Handler->>Host: response
    Host->>WebView: sendResponse(response)
    WebView->>JS: callHandler('onResponse', response)
    JS->>Web: onResponse(response)

2. JavaScript Bridge

// Отправка payload'а в host
window.flutter_inappwebview.callHandler('sendPayload', {
  type: 'ping',
  data: { message: 'Hello from Web!' }
});

// Получение ответа от host
window.flutter_inappwebview.callHandler('onResponse', function(response) {
  console.log('Response from host:', response);
});

3. Host обработка

class BridgeWebViewController {
  // Регистрация обработчиков
  void registerHandlers() {
    _bridge.registerHandler<PingPayload>(PingHandler());
    _bridge.registerHandler<UserInfoPayload>(UserInfoHandler());
    // ...
  }

  // Обработка входящих сообщений
  void onMessageReceived(Map<String, dynamic> data) {
    final payload = PayloadFactory.create(data);
    final response = _bridge.handle(payload);
    sendResponse(response);
  }
}

🏗️ Архитектура приложений

Host App (apps/host_app/)

// Структура файлов
lib/
├── src/
│   ├── bridge_webview_controller.dart  # Управление WebView и bridge
│   ├── bridge_webview.dart             # Flutter виджет WebView
│   └── handlers/                       # Обработчики payload'ов
│       ├── payload_handler.dart        # Базовый обработчик
│       ├── ping_handler.dart           # Ping/Pong
│       ├── user_info_handler.dart      # User info
│       ├── admin_command_handler.dart  # Admin commands
│       ├── native_dialog_handler.dart  # Native dialogs
│       ├── login_handler.dart          # Login
│       └── quiz_handler.dart           # Quiz
└── main.dart                           # Точка входа

Web App1 (apps/web_app1/)

// Структура файлов
lib/
├── src/
│   ├── web_bridge.dart                 # Управление связью с host
│   ├── payload_handlers.dart           # Обработчики ответов
│   └── main.dart                       # Точка входа
web/
├── index.html                          # HTML страница
└── bridge.js                           # JavaScript bridge

🔒 Безопасность

1. Изоляция payload'ов

• Web приложения не могут использовать host payload'ы
• Компилятор проверяет доступ к пакетам
• Архитектура предотвращает утечки данных

2. Валидация данных

• Все payload'ы валидируются при создании
• Типобезопасность на уровне компилятора
• Проверка структуры данных

3. Обработка ошибок

• Graceful handling ошибок
• Логирование для отладки
• Fallback механизмы

📈 Производительность

1. Оптимизации

• Минимальные overhead для bridge коммуникации
• Эффективная сериализация JSON
• Кэширование обработчиков

2. Мониторинг

• Логирование времени выполнения
• Метрики производительности
• Отладка медленных операций

🔧 Расширяемость

1. Добавление новых payload'ов

// 1. Создать новый payload в соответствующем пакете
class NewPayload extends Payload {
  final String data;
  // ...
}

// 2. Создать обработчик
class NewPayloadHandler extends PayloadHandler<NewPayload> {
  @override
  Future<PayloadResponse> handle(NewPayload payload) async {
    // Логика обработки
    return NewResponse();
  }
}

// 3. Зарегистрировать обработчик
_bridge.registerHandler<NewPayload>(NewPayloadHandler());

2. Добавление новых приложений

• Создать новый пакет payload'ов
• Создать Flutter Web приложение
• Настроить изоляцию payload'ов
• Добавить в host_app поддержку

🧪 Тестирование

1. Unit тесты

• Тестирование всех payload'ов
• Тестирование обработчиков
• Тестирование сериализации

2. Integration тесты

• Тестирование полного цикла коммуникации
• Тестирование изоляции payload'ов
• Тестирование JavaScript bridge

3. End-to-end тесты

• Тестирование реальных сценариев
• Тестирование производительности
• Тестирование стабильности

📚 Документация

1. API документация

• Описание всех payload'ов
• Примеры использования
• Best practices

2. Руководства

• Быстрый старт
• Интеграция в существующий проект
• Troubleshooting

3. Примеры

• Базовые примеры
• Продвинутые сценарии
• Реальные use cases

---

🎯 Заключение

Архитектура Flutter WebView Bridge обеспечивает:

• ✅ Безопасную коммуникацию между приложениями
• ✅ Типобезопасность на уровне компилятора
• ✅ Изоляцию payload'ов для безопасности
• ✅ Простоту расширения и поддержки
• ✅ Высокую производительность
• ✅ Полное покрытие тестами

Система готова для использования в production проектах.