CrossBridge 需求规格说明书 (Requirements Specification)

版本: 1.0 (根据原始需求整理) 状态: 已实现

1. 项目背景与目标

1.1 背景

在复杂的企业级 Web 应用中，经常面临多域名、多页面（Multi-page）、多 Tab 协作以及 iframe 嵌套的场景。现有的单一通信方案（如仅用 postMessage 或 BroadcastChannel）难以满足混合场景下的统一通信需求。

1.2 目标

开发一个名为 CrossBridge 的通用通信 SDK，旨在能够统一管理主项目与子项目、父页面与子页面、跨域页面之间的数据流通，屏蔽底层通信细节，提供类似 mitt 的事件驱动开发体验。

---

2. 详细功能需求

2.1 复杂通信场景支持

插件必须能够自动识别并支持以下通信场景：

1. 一级域名相同的跨 Tab 通信

   • 场景: console-dev1.e-tudou.com 与 agentos-dev1.e-tudou.com。
   • 要求: 两个独立的浏览器 Tab 页能够互发消息。

2. 完全跨域的通信

   • 场景: app-a.com 与 app-b.com。
   • 要求: 支持不同一级域名之间的双向通信。

3. iframe 嵌套通信

   • 场景: 主页面加载多个 iframe（同域或跨域）。
   • 要求: 父子页面互通，且父页面能特定指定发送给某个 iframe。

4. 混合场景 (核心补充)

   • 场景 A: 一个页面既是某个 iframe 的父页面，又是另一个 Tab 的兄弟页面。
   • 场景 B (多层嵌套): 页面 A 嵌入页面 B，页面 B 又嵌入页面 C (A -> B -> C)。此时 B 既是 A 的 Child，又是 C 的 Parent。
   • 要求: 插件需支持单页面的多重角色 (Hybrid)，中间层页面 (如 B) 需同时具备向上通信和向下管理的能力。

2.2 消息队列与延迟消费 (关键需求)

• 痛点: 主页面发送消息时，子页面（iframe）可能尚未加载完成，导致消息丢失。
• 需求:
  • 实现消息队列机制 (Message Queue)。
  • 支持延迟消费 (Delayed Consumption)：消息先暂存，待目标页面上线并建立连接后，自动投递历史消息。
  • 参考 RabbitMQ 的设计思想。

2.3 页面角色与 ID 管理

• 页面标识: 每个通过插件连接的页面（Tab 或 iframe）都必须有一个唯一的 pageId。
• 角色管理:
  • Parent: 管理者，通常是加载 iframe 的主应用。
  • Child: 被嵌入者。
  • Standalone: 独立运行的 Tab 页。
• 定向发送: 支持 sendTo(pageId, ...)，精确控制消息发送给谁，而不是盲目广播。

2.4 事件驱动与接口

• 事件系统: 必须集成或兼容 mitt 等事件库。
• 自定义事件: 支持用户定义任意事件名称（不局限于插件预设事件）。
• API 风格: 提供 on, emit, off 等标准事件 API。

2.5 单页使用支持

• 独立运行: 支持在任何单个 HTML 页面（如 index.html）中直接引入使用，无需依赖大型框架构建。
• 自动检测: 在 iframe 环境下自动识别为 Child 角色。

---

3. 非功能需求

3.1 性能要求

• 高频传输: 支持高频率的数据更新（如实时状态同步），不能造成 UI 卡顿。
• 智能路由: 能够根据目标页面的位置（同域/跨域），自动选择性能最优的通信方式（如能用 SharedWorker 就不用 WebSocket）。

3.2 可靠性

• 消息不丢失: 在网络波动或页面刷新时，重要消息应能持久化（通过 LocalStorage 或 IndexedDB）。
• 自动重连: WebSocket 或 Worker 断开后应尝试自动重连。

3.3 兼容性

• 支持现代主流浏览器 (Chrome 80+, Firefox 75+, Safari 13+)。
• 不考虑 IE 兼容性。

---

4. 技术约束与选型建议

根据需求，推荐采用以下技术栈组合（已在架构设计中采纳）：

• SharedWorker: 用于同域多 Tab 高效通信。
• PostMessage: 用于父子 iframe 通信及跨域桥接。
• BroadcastChannel: 轻量级同域广播。
• WebSocket: 用于完全跨域的实时通信中继。
• IndexedDB/LocalStorage: 用于消息持久化存储。