mnemo_cards/games/mnemo_cards_game_api/PROJECT_STRUCTURE.md

📦 Flutter WebView Bridge — структура проекта

Проект разделён на независимые пакеты (монорепозиторий с Melos), чтобы:

• отделить зависимости между host, web и payloads;
• изолировать доступ к данным (web видит только нужное);
• упростить масштабирование и тестирование.

---

🗂️ Общая структура

├── games/
│   ├── bridge_core/             # Общие типы и сериализация
│   ├── payloads_shared/         # Payload'ы, общие для всех
│   ├── payloads_host/           # Только для host-приложения
│   ├── payloads_app1/           # Только для web_app1
│   ├── host_app/                # Flutter Host App (с WebView)
│   ├── web_app1/                # Flutter Web-приложение 1
├── melos.yaml                   # Конфигурация монорепозитория

---

📦 Описание пакетов

bridge_core/

Содержит:

• BridgeMessage — модель сообщения
• BridgePayload — абстракция типа данных
• PayloadRegistry — карта "type" → fromJson

Используется всеми остальными пакетами.

---

payloads_shared/

Содержит payload'ы, используемые и в host, и в web-приложениях.
Пример: GetUserInfoPayload, PingPayload.

Импортируется и в host_app, и в web_app1, web_app2.

---

payloads_host/

Содержит payload'ы, специфичные для хост-приложения.
Пример: SecretAdminCommand, ShowNativeDialogPayload.

Импортируется только в host_app.

---

payloads_app1/

Содержит payload'ы, специфичные для web-приложения 1.
Пример: LoginRequestPayload, SubmitQuizPayload.

Импортируется только в web_app1 и host_app.

---

host_app/

Flutter-приложение с WebView.

• Имеет доступ ко всем payloads_* пакетам
• Обрабатывает все события
• Реализует BridgeWebViewController

---

web_app1/

Flutter Web-приложение, встроенное в WebView.

• Импортирует только нужные payloads_*
• Регистрирует только свои payload'ы
• Не видит лишнего

---

🔐 Разделение доступа

Пакет	Видит payloads_shared	Видит payloads_host	Видит payloads_app1
host_app	✅	✅	✅
web_app1	✅	❌	✅
web_app2	✅	❌	❌

---

⚙️ Melos

Файл melos.yaml в корне:

name: flutter_webview_bridge_repo
packages:
  - packages/**

Запуск:

melos bootstrap

---

📥 Регистрация payload'ов

Каждый payload-пакет содержит:

void registerPayloads() {
  BridgePayload.register('type_name', (json) => MyPayload.fromJson(json));
}

В main() у приложения:

void main() {
  registerPayloads();
  runApp(MyApp());
}

---

📌 Пример использования

// Web-приложение
GetUserInfoPayload(fields: ['name']).toMessage().sendToHost();

// Хост-приложение
hostBridge.registerHandler('get_user_info', (msg) {
  final payload = GetUserInfoPayload.fromJson(msg.data);
  ...
});

---