@vnb/mfe-events 0.0.1-rc.1

package/README.md

@@ -0,0 +1,850 @@
+# @vnb/mfe-events
+
+> 微前端事件通信插件 — Shell 与子应用间的统一事件协议
+
+适用于 Module Federation、Native Federation、iframe 等多种微前端架构。支持类型安全的事件总线、跨应用通知、iframe 消息代理等核心功能。
+
+---
+
+## 特性
+
+- **三层事件域**：`EvtShl`（Shell 内部）、`EvtMfe`（跨应用）、`EvtApp`（子应用内部）
+- **类型安全**：TypeScript 泛型约束，编译时检查事件名和 payload 类型
+- **自动传输层适配**：MF/NF 用 `CustomEvent`，iframe 用 `postMessage`，Shell 内部用内存 EventTarget
+- **插件化注册**：子应用只需一行代码注册，即可接收 Shell 推送
+- **通知系统**：内置 DOM toast 渲染，支持自定义渲染器
+- **CDN 支持**：UMD 构建，可直接 `<script>` 引入
+
+---
+
+## 安装
+
+### npm（推荐）
+
+```bash
+npm install @vnb/mfe-events
+```
+
+**Module Federation 共享配置**（子应用侧）：
+
+```javascript
+// webpack.config.js / ModuleFederationPlugin
+shared: {
+  '@vnb/mfe-events': { singleton: true, eager: true, requiredVersion: false }
+}
+```
+
+**Native Federation 共享配置**（子应用侧）：
+
+```json
+// angular.json 或 federation.config.json
+{
+  "shares": {
+    "@vnb/mfe-events": { "singleton": true, "eager": true, "requiredVersion": false }
+  }
+}
+```
+
+### CDN（不支持构建工具时）
+
+```html
+<!-- 引入 UMD 构建 -->
+<script src="https://wynn-mfe-events.surge.sh/index.umd.js"></script>
+<!-- <script src="https://unpkg.com/@vnb/mfe-events/dist/index.umd.js"></script> -->
+ 
+<script>
+  const { mfeEventPlugin, mfeBus, EvtMfe, EvtShl } = window.MfeEvents;
+
+  mfeEventPlugin.register({
+    appId: 'my-app',
+    handlers: {
+      [EvtMfe.ThemeUpdate]: (data) => console.log('theme:', data.theme),
+      [EvtMfe.LocaleUpdate]: (data) => console.log('locale:', data.locale),
+    }
+  });
+</script>
+```
+
+UMD 构建同时暴露 `window.MfeEvents` 和 `window.__MFE_EVENT_PLUGIN__`。
+
+---
+
+## 架构
+
+### 三层事件域
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      Shell 基座                              │
+│                                                             │
+│  shlBus.emit(EvtShl.TabOverflow, {...})    ← Shell 内部     │
+│                    ↓                                        │
+│  mfeEventPlugin.emit(EvtMfe.ThemeUpdate, {...})  ← 广播     │
+│                    ↓                                        │
+│  mfeEventPlugin.emitTo('mma', EvtMfe.RouteNavigate, {...})  ← 定向  │
+└──────────────────────┬──────────────────────────────────────┘
+                       │
+         ┌─────────────┴─────────────┐
+         │ CustomEvent               │ postMessage
+         ↓                           ↓
+┌──────────────────┐      ┌──────────────────┐
+│ Module Federation │      │     iframe        │
+│ Native Federation │      │                  │
+│ mfeBus.on(event)  │      │ mfeBus.on(event) │
+└──────────────────┘      └──────────────────┘
+```
+
+### 传输层选择
+
+| 场景 | 传输方式 | 代码路径 |
+|------|---------|---------|
+| Shell 内部 | 内存 EventTarget | `new Bus(new MemoryTransport())` |
+| MF/NF 子应用 → Shell | `window.CustomEvent` | `new Bus(new WindowTransport())` |
+| iframe 子应用 → Shell | `window.postMessage` | `new Bus(new PostMessageTransport())` |
+| Shell → iframe | `iframe.contentWindow.postMessage` | `new IframeProxyTransport(iframe)` |
+
+`mfeBus` 在初始化时自动检测环境选择合适的传输层。Shell 内部的 `shlBus` 永远不会触碰 `window`，完全隔离。
+
+---
+
+## 快速接入
+
+### 子应用接入（Angular/Vue/React 通用）
+
+```typescript
+import mfeEventPlugin, { mfeBus } from '@vnb/mfe-events';
+import { EvtMfe } from '@vnb/mfe-events';
+
+// 1. 注册 → 接收 Shell 推送的事件
+mfeEventPlugin.register({
+  appId: 'my-app',        // 必须与 Shell 配置的 appId 一致
+  type: 'mf',             // 'mf' | 'iframe'
+  handlers: {
+    // Shell → App：Shell 导航到指定路径
+    [EvtMfe.RouteNavigate]: (data) => {
+      // data.path: string，例如 '/booking/123'
+      router.navigateByUrl(data.path);
+    },
+
+    // Shell → App：主题切换
+    [EvtMfe.ThemeUpdate]: (data) => {
+      // data.theme: 'light' | 'dark'
+      document.documentElement.dataset.theme = data.theme;
+    },
+
+    // Shell → App：语言切换
+    [EvtMfe.LocaleUpdate]: (data) => {
+      // data.locale: string，例如 'zh-CN'
+      i18n.setLocale(data.locale);
+    },
+
+    // Shell → App：认证登出
+    [EvtMfe.AuthLogout]: () => {
+      clearAuthState();
+      router.navigate('/login');
+    },
+
+    // Shell → App：Token 刷新
+    [EvtMfe.AuthTokenUpdate]: (data) => {
+      // data: { token: string; user?: User; permissions?: string[] }
+      updateToken(data.token);
+    },
+
+    // Shell → App：认证过期
+    [EvtMfe.AuthExpired]: () => {
+      clearAuthState();
+      router.navigate('/login');
+    },
+  },
+});
+
+// 2. 向 Shell 上报路由变化（子应用内部导航时必须调用）
+router.afterEach((to) => {
+  mfeBus.emit(EvtMfe.RouteChange, {
+    appId: 'my-app',
+    path: to.fullPath,   // 完整路径，如 '/booking/123'
+  });
+});
+
+// 3. 向 Shell 上报应用就绪
+mfeBus.emit(EvtMfe.LifecycleAppReady, { appId: 'my-app' });
+
+// 4. 向 Shell 上报应用卸载（可选，但推荐）
+window.addEventListener('unload', () => {
+  mfeBus.emit(EvtMfe.LifecycleAppUnmount, { appId: 'my-app' });
+});
+
+// 5. 使用通知（所有子应用共享 Shell 的通知系统）
+mfeEventPlugin.success('保存成功');
+mfeEventPlugin.info({ message: '详情信息', title: '提示', duration: 5000 });
+mfeEventPlugin.warning('请注意，此操作不可撤销');
+mfeEventPlugin.danger('操作失败，请重试');
+
+// 6. 销毁时注销
+mfeEventPlugin.unregister('my-app');
+```
+
+### Shell 端接入
+
+```typescript
+import mfeEventPlugin, { mfeBus, shlBus } from '@vnb/mfe-events';
+import { EvtMfe, EvtShl } from '@vnb/mfe-events';
+
+// Shell 不需要 register() — 子应用自己注册
+// Shell 只需要：监听、发送、通知
+
+// 1. 监听子应用上报的事件（子应用调用 register() 后自动可收）
+mfeBus.on(EvtMfe.RouteChange, (data) => {
+  // data: { appId: string; path: string }
+  console.log(`${data.appId} 路由变化:`, data.path);
+});
+
+mfeBus.on(EvtMfe.LifecycleAppReady, (data) => {
+  console.log(`${data.appId} 就绪`);
+});
+
+mfeBus.on(EvtMfe.Error, (data) => {
+  console.error(`${data.source} 错误:`, data.message);
+});
+
+// 2. 定向发送（子应用必须已 register()，否则 emitTo 静默失败）
+mfeEventPlugin.emitTo('mma', EvtMfe.RouteNavigate, { path: '/chairman' });
+
+// 3. 广播（所有子应用均可收到）
+mfeEventPlugin.emit(EvtMfe.ThemeUpdate, { theme: 'dark' });
+mfeEventPlugin.emit(EvtMfe.LocaleUpdate, { locale: 'zh-CN' });
+
+// 4. 生命周期
+mfeEventPlugin.shellReady();
+
+// 5. 认证快捷方法
+mfeEventPlugin.authLogin({ userId: '1', name: 'Admin' });
+mfeEventPlugin.authLogout('user');
+mfeEventPlugin.tokenUpdate({ token: 'xxx', permissions: ['read', 'write'] });
+mfeEventPlugin.authExpired();
+
+// 6. 通知
+mfeEventPlugin.success('操作成功');
+
+// 7. Shell 内部通信（shlBus，不碰 window）
+shlBus.on(EvtShl.TabOverflow, (data) => {
+  showTabOverflowDialog(data);
+});
+```
+
+---
+
+## 事件协议
+
+### 事件命名规范
+
+```
+{scope}:{domain}-{action}
+```
+
+- `scope`：`shl`（Shell内部）、`mfe`（跨应用）、`app`（子应用内部）
+- `domain`：状态域（theme、locale、auth、route、lifecycle、notify）
+- `action`：动词（update、change、navigate、show、close）
+
+### 跨应用事件（EvtMfe）
+
+| 常量 | 值 | 方向 | 说明 | Payload |
+|------|-----|------|------|---------|
+| **ThemeUpdate** | `mfe:theme-update` | Shell → App | 主题切换 | `{ theme: 'light' \| 'dark' }` |
+| **LocaleUpdate** | `mfe:locale-update` | Shell → App | 语言切换 | `{ locale: string }` |
+| **BreakpointUpdate** | `mfe:breakpoint-update` | Shell → App | 响应式断点/横竖屏变化（Shell 基于 `window.matchMedia` 监听并广播，子应用收到后同步更新布局，如侧边栏收起、表格横向滚动等） | `{ current: string; orientation: 'portrait' \| 'landscape' }` |
+| **StateUpdate** | `mfe:state-update` | Shell → App | 全局状态同步 | `{ state: AppState; prev: AppState \| null }` |
+| **ShellReady** | `mfe:shell-ready` | Shell → App | Shell 初始化完成 | `{}` |
+| **Error** | `mfe:error` | App → Shell | 子应用错误上报 | `{ source: string; message: string; stack?: string }` |
+| **Raw** | `mfe:raw` | Any | 自定义透传事件（子应用间通信） | `{ type: string; payload: any; source: string; ts: number }` |
+| **Custom** | `mfe:raw` | Any | `Raw` 的别名，完全等价 | `{ type: string; payload: any; source: string; ts: number }` |
+| **AuthLogin** | `mfe:auth-login` | Shell → App | 用户登录 | `{ user: User; token: string }` |
+| **AuthLogout** | `mfe:auth-logout` | Shell → App | 用户登出 | `{ reason?: 'user' \| 'timeout' \| 'error' }` |
+| **AuthTokenUpdate** | `mfe:auth-token-update` | Shell → App | Token 刷新 | `{ token: string; user?: User; permissions?: string[] }` |
+| **AuthTokenClear** | `mfe:auth-token-clear` | Shell → App | Token 清除 | `{}` |
+| **AuthPermissionUpdate** | `mfe:auth-permission-update` | Shell → App | 权限变更 | `{ permissions: string[] }` |
+| **AuthExpired** | `mfe:auth-expired` | Shell → App | 认证过期 | `{}` |
+| **RouteNavigate** | `mfe:route-navigate` | Shell → App | Shell 指定子应用导航到路径 | `{ path: string }` |
+| **RouteRefresh** | `mfe:route-refresh` | Shell → App | 强制子应用重新请求当前路由数据，保留路由位置（`emitTo` 定向） | `{ path: string }` |
+| **RouteChange** | `mfe:route-change` | App → Shell | 子应用上报路由变化 | `{ appId: string; path: string }` |
+| **LifecycleAppClose** | `mfe:lifecycle-app-close` | Shell → App | Shell 关闭子应用 | `{ appId: string }` |
+| **LifecycleAppReady** | `mfe:lifecycle-app-ready` | App → Shell | 子应用初始化完成 | `{ appId: string }` |
+| **LifecycleAppUnmount** | `mfe:lifecycle-app-unmount` | App → Shell | 子应用即将卸载 | `{ appId: string }` |
+| **NotifyShow** | `mfe:notify-show` | Any | 显示通知 | `NotificationConfig` |
+| **NotifyClose** | `mfe:notify-close` | Any | 关闭指定通知 | `{ id: string }` |
+| **NotifyCloseAll** | `mfe:notify-close-all` | Any | 关闭所有通知 | `{}` |
+
+### Shell 内部事件（EvtShl）
+
+仅 Shell 内部使用，通过 `shlBus` 通信，不经过 `window`。
+
+| 常量 | 值 | 说明 | Payload |
+|------|-----|------|---------|
+| **TabOverflow** | `shl:tab-overflow` | 标签页超出时触发 | `{ appId: string; label: string; openIds: string[] }` |
+| **TabClose** | `shl:tab-close` | 标签页关闭 | `{ appId: string }` |
+| **RouteReuse** | `shl:route-reuse` | 路由复用策略变更 | `{ route: string; strategy: 'attach' \| 'detach' }` |
+| **AuthSync** | `shl:auth-sync` | 认证状态同步 | `{ token: string; user: User }` |
+| **StateSync** | `shl:state-sync` | 全局状态同步 | `{ state: AppState; prev: AppState \| null }` |
+| **AppMounted** | `shl:app-mounted` | 子应用挂载完成 | `{ appId: string; container: HTMLElement }` |
+| **AppUnmounted** | `shl:app-unmounted` | 子应用卸载完成 | `{ appId: string }` |
+
+### 子应用内部事件（EvtApp）
+
+用于子应用内部模块间通信，不跨应用。
+
+```typescript
+import { EvtApp } from '@vnb/mfe-events';
+
+const eventName = EvtApp('mma', 'booking-created');
+// → 'app:mma:booking-created'
+
+mfeBus.emit(eventName, { bookingId: '123' });
+```
+
+### 类型定义
+
+以下类型均可从 `@vnb/mfe-events` 导入：
+
+```typescript
+import type { User, AppState, NotificationConfig } from '@vnb/mfe-events';
+
+// 用户信息
+interface User {
+  userId: string;
+  username: string;
+  email?: string;
+  roles?: string[];
+}
+
+// 全局状态
+interface AppState {
+  theme: 'light' | 'dark';
+  locale: string;
+  user: User | null;
+  permissions: string[];
+  features: Record<string, boolean>;
+}
+
+// 通知配置
+interface NotificationConfig {
+  type: 'success' | 'info' | 'warning' | 'danger';
+  message: string;
+  title?: string;
+  duration?: number;        // 默认 3000ms，0 = 不自动关闭
+  buttons?: Array<{
+    text: string;
+    role?: 'primary' | 'sticky';
+    handler?: () => void;
+  }>;
+}
+```
+
+---
+
+## API 参考
+
+### mfeEventPlugin（单例）
+
+```typescript
+import mfeEventPlugin from '@vnb/mfe-events';
+```
+
+#### 注册与注销
+
+> **注意**：`register()` 仅子应用调用。Shell 不需要注册，直接用 `on()`/`emit()`/`emitTo()` 即可。
+
+```typescript
+// 子应用注册（子应用侧调用）
+mfeEventPlugin.register({
+  appId: 'my-app',           // 必填，子应用唯一标识
+  type: 'mf',                // 选填，'mf' | 'iframe'，默认 'mf'
+  handlers: {                // 必填，事件处理函数映射
+    [EvtMfe.RouteNavigate]: (data) => { /* data: { path: string } */ },
+    [EvtMfe.ThemeUpdate]: (data) => { /* data: { theme: 'light' | 'dark' } */ },
+    // ...
+  },
+  fallback: (config) => {    // 选填，独立运行时（无 Shell）的兜底通知渲染器
+    myToast.show(config);
+    return { close: () => myToast.hide(config.id) };
+  }
+});
+
+// iframe 子应用注册（Shell 侧调用，因为 Shell 持有 iframe 引用）
+mfeEventPlugin.registerIframe(
+  'my-iframe-app',           // appId
+  iframeElement,             // HTMLIFrameElement
+  'https://parent-origin'    // 选填，targetOrigin
+);
+
+// 子应用注销（子应用侧调用）
+mfeEventPlugin.unregister('my-app');
+```
+
+#### 发送事件
+
+```typescript
+// 定向发送（只发给指定子应用）
+mfeEventPlugin.emitTo('mma', EvtMfe.RouteNavigate, { path: '/booking' });
+mfeEventPlugin.emitTo('mma', EvtMfe.RouteRefresh, { path: '/chairman' });
+
+// 广播（发给所有子应用）
+mfeEventPlugin.emit(EvtMfe.ThemeUpdate, { theme: 'dark' });
+mfeEventPlugin.emit(EvtMfe.LocaleUpdate, { locale: 'en-US' });
+mfeEventPlugin.emit(EvtMfe.ShellReady, {});
+```
+
+#### 通知
+
+```typescript
+// 快捷方式（推荐）
+mfeEventPlugin.success('保存成功');                         // 3s 自动关闭
+mfeEventPlugin.success('已保存', '提示');                   // 带标题
+mfeEventPlugin.info({ message: '详情', title: '信息', duration: 5000 });
+mfeEventPlugin.warning('请确认操作', undefined, { duration: 0 }); // 手动关闭
+mfeEventPlugin.danger('操作失败');
+
+// 完整配置
+const { close } = mfeEventPlugin.notify({
+  type: 'success',
+  message: '数据已保存',
+  title: '成功',
+  duration: 5000,
+  buttons: [
+    { text: '查看', role: 'primary', handler: () => navigate('/list') },
+    { text: '取消', handler: () => {} },
+  ],
+});
+
+// 关闭单个
+close();
+
+// 按 id 关闭
+mfeEventPlugin.close('mfe-1');
+
+// 关闭所有
+mfeEventPlugin.closeAll();
+```
+
+#### 独立运行兜底（子应用侧）
+
+子应用独立运行时（无 Shell 基座），通知渲染流程：
+
+1. `success()/info()...` → `notify()`
+2. 若 Shell 调用过 `useRenderer()` → Shell 接管渲染
+3. 若无 Shell 且子应用注册时传了 `fallback` → `fallback` 渲染
+4. 否则 → DOM 内置 toast 渲染
+
+```typescript
+// 子应用注册时传入 fallback
+mfeEventPlugin.register({
+  appId: 'my-app',
+  handlers: { ... },
+  fallback: (config) => {
+    // 独立运行时使用自己的通知组件
+    MyToast.show({ id: config.id, type: config.type, message: config.message });
+    return { close: () => MyToast.hide(config.id) };
+  }
+});
+```
+
+#### 响应式断点更新（Shell 侧）
+
+Shell 基于 `window.matchMedia` 监听视口断点和横竖屏变化，通过 `emit()` 广播给所有子应用：
+
+```typescript
+// Shell 端 BreakpointService（伪代码，框架无关）
+import { mfeEventPlugin, EvtMfe } from '@vnb/mfe-events';
+
+const queries = {
+  xs: window.matchMedia('(max-width: 767px)'),
+  sm: window.matchMedia('(min-width: 768px) and (max-width: 1023px)'),
+  lg: window.matchMedia('(min-width: 1024px)'),
+};
+
+function compute() {
+  if (queries.xs.matches) return 'xs';
+  if (queries.sm.matches) return 'sm';
+  return 'lg';
+}
+
+// 监听断点变化，广播给所有子应用
+queries.xs.addEventListener('change', () => {
+  mfeEventPlugin.emit(EvtMfe.BreakpointUpdate, {
+    current: compute(),
+    orientation: window.matchMedia('(orientation: portrait)').matches ? 'portrait' : 'landscape',
+  });
+});
+
+// 子应用收到后同步更新布局（如侧边栏收起、表格横向滚动等）
+```
+
+```typescript
+// 子应用端
+mfeEventPlugin.register({
+  appId: 'my-app',
+  handlers: {
+    [EvtMfe.BreakpointUpdate]: (data) => {
+      // data.current: 'xs' | 'sm' | 'lg'
+      // data.orientation: 'portrait' | 'landscape'
+      document.documentElement.dataset.breakpoint = data.current;
+      document.documentElement.dataset.orientation = data.orientation;
+    },
+  },
+});
+```
+
+#### 自定义通知渲染器（Shell 侧）
+
+Shell 可以接管通知渲染，使用自己的 UI 组件。
+
+```typescript
+import { mfeEventPlugin, EvtMfe } from '@vnb/mfe-events';
+import { MyToastContainer } from './components/ToastContainer';
+
+// 注册自定义渲染器
+mfeEventPlugin.useRenderer(
+  // render: 收到通知配置时调用
+  (config) => {
+    MyToastContainer.show({
+      id: config.id,
+      type: config.type,
+      message: config.message,
+      title: config.title,
+      duration: config.duration,
+      onClose: () => mfeEventPlugin.close(config.id),
+    });
+  },
+  // close: 关闭指定通知
+  (id) => MyToastContainer.hide(id),
+  // clear: 关闭所有通知
+  () => MyToastContainer.clear()
+);
+```
+
+#### 生命周期
+
+```typescript
+// 通知所有子应用 Shell 已就绪（Shell 初始化完成后调用一次）
+mfeEventPlugin.shellReady();
+
+// 查询 Shell 就绪状态
+const ready = mfeEventPlugin.isShellReady();  // boolean
+```
+
+#### 认证快捷方法
+
+```typescript
+// 广播登录事件
+mfeEventPlugin.authLogin({ userId: '1', username: 'admin', roles: ['admin'] });
+
+// 广播登出事件
+mfeEventPlugin.authLogout();                              // reason: 'user'
+mfeEventPlugin.authLogout('timeout');                     // reason: 'timeout'
+mfeEventPlugin.authLogout('error');                       // reason: 'error'
+
+// 广播 Token 刷新
+mfeEventPlugin.tokenUpdate({
+  token: 'new-jwt-token',
+  user: { userId: '1', username: 'admin', roles: ['admin'] },
+  permissions: ['read', 'write'],
+});
+
+// 广播 Token 清除
+mfeEventPlugin.tokenClear();
+
+// 广播权限更新
+mfeEventPlugin.permissionUpdate(['read', 'write', 'delete']);
+
+// 广播认证过期
+mfeEventPlugin.authExpired();
+
+// 广播语言切换
+mfeEventPlugin.locale('zh-CN');
+```
+
+---
+
+### mfeBus / shlBus
+
+```typescript
+import { mfeBus, shlBus } from '@vnb/mfe-events';
+```
+
+#### Bus 方法
+
+```typescript
+// 发送事件
+mfeBus.emit(EvtMfe.RouteChange, { appId: 'my-app', path: '/booking' });
+shlBus.emit(EvtShl.TabOverflow, { appId: 'mma', label: 'MMA', openIds: ['mma', 'mrbs'] });
+
+// 订阅事件，返回取消函数
+const off = mfeBus.on(EvtMfe.ThemeUpdate, (data) => {
+  console.log('theme changed to:', data.theme);
+});
+
+// 订阅一次
+const offOnce = mfeBus.once(EvtMfe.ShellReady, () => {
+  console.log('Shell is ready!');
+});
+
+// 取消订阅
+off();
+offOnce();
+```
+
+---
+
+### Transport 类（高级用法）
+
+```typescript
+import { MemoryTransport, WindowTransport, PostMessageTransport, IframeProxyTransport } from '@vnb/mfe-events';
+```
+
+| 类 | 用途 | 构造参数 |
+|---|------|---------|
+| `MemoryTransport` | Shell 内部通信 | 无 |
+| `WindowTransport` | MF/NF 同Tab通信 | 无 |
+| `PostMessageTransport` | iframe 子应用通信 | `{ targetWindow?, targetOrigin? }` |
+| `IframeProxyTransport` | Shell → iframe 代理 | `iframe: HTMLIFrameElement, targetOrigin?: string` |
+
+---
+
+## 框架集成示例
+
+### Angular 子应用
+
+```typescript
+// app.component.ts 或专用初始化文件
+import { mfeEventPlugin, mfeBus, EvtMfe } from '@vnb/mfe-events';
+import { Router } from '@angular/router';
+
+@Injectable({ providedIn: 'root' })
+export class MfeEventsService {
+  private router = inject(Router);
+
+  init() {
+    mfeEventPlugin.register({
+      appId: 'mma',
+      type: 'mf',
+      handlers: {
+        [EvtMfe.RouteNavigate]: (data) => this.router.navigateByUrl(data.path),
+        [EvtMfe.ThemeUpdate]: (data) => document.documentElement.dataset['theme'] = data.theme,
+        [EvtMfe.AuthLogout]: () => this.handleLogout(),
+        [EvtMfe.AuthTokenUpdate]: (data) => this.updateToken(data.token),
+        [EvtMfe.AuthExpired]: () => this.handleLogout(),
+      },
+    });
+
+    this.router.events.pipe(filter(e => e instanceof NavigationEnd)).subscribe((e) => {
+      const url = (e as NavigationEnd).urlAfterRedirects;
+      mfeBus.emit(EvtMfe.RouteChange, { appId: 'mma', path: url });
+    });
+
+    mfeBus.emit(EvtMfe.LifecycleAppReady, { appId: 'mma' });
+  }
+
+  private handleLogout() {
+    localStorage.clear();
+    this.router.navigate(['/login']);
+  }
+
+  private updateToken(token: string) {
+    localStorage.setItem('token', token);
+  }
+}
+```
+
+### Vue 子应用
+
+```typescript
+// main.ts
+import { createApp } from 'vue';
+import App from './App.vue';
+import { mfeEventPlugin, mfeBus, EvtMfe } from '@vnb/mfe-events';
+
+const app = createApp(App);
+
+app.mount('#app');
+
+mfeEventPlugin.register({
+  appId: 'mrbs',
+  type: 'mf',
+  handlers: {
+    [EvtMfe.RouteNavigate]: (data) => router.push(data.path),
+    [EvtMfe.ThemeUpdate]: (data) => document.documentElement.dataset.theme = data.theme,
+    [EvtMfe.AuthLogout]: () => { localStorage.clear(); router.push('/login'); },
+    [EvtMfe.AuthTokenUpdate]: (data) => localStorage.setItem('token', data.token),
+    [EvtMfe.AuthExpired]: () => { localStorage.clear(); router.push('/login'); },
+  },
+});
+
+router.afterEach((to) => {
+  mfeBus.emit(EvtMfe.RouteChange, { appId: 'mrbs', path: to.fullPath });
+});
+
+mfeBus.emit(EvtMfe.LifecycleAppReady, { appId: 'mrbs' });
+```
+
+### React 子应用
+
+```typescript
+// index.tsx
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import App from './App';
+import { mfeEventPlugin, mfeBus, EvtMfe } from '@vnb/mfe-events';
+
+mfeEventPlugin.register({
+  appId: 'frontend',
+  type: 'mf',
+  handlers: {
+    [EvtMfe.RouteNavigate]: (data) => navigate(data.path),
+    [EvtMfe.ThemeUpdate]: (data) => document.documentElement.dataset.theme = data.theme,
+    [EvtMfe.AuthLogout]: () => { localStorage.clear(); navigate('/login'); },
+    [EvtMfe.AuthTokenUpdate]: (data) => localStorage.setItem('token', data.token),
+    [EvtMfe.AuthExpired]: () => { localStorage.clear(); navigate('/login'); },
+  },
+});
+
+const navigate = (path: string) => window.history.pushState(null, '', path);
+
+window.addEventListener('popstate', () => {
+  mfeBus.emit(EvtMfe.RouteChange, { appId: 'frontend', path: window.location.pathname });
+});
+
+mfeBus.emit(EvtMfe.LifecycleAppReady, { appId: 'frontend' });
+
+ReactDOM.createRoot(document.getElementById('root')!).render(<App />);
+```
+
+---
+
+## 常见问题
+
+### 事件收不到
+
+1. 确认 `appId` 与 Shell 配置一致（区分大小写）
+2. 确认 Federation 配置中有 `@vnb/mfe-events` 且 `singleton: true`
+3. 确认使用的是事件常量 `EvtMfe.XXX` 而非硬编码字符串
+4. 控制台检查 `window.__MFE_EVENT_PLUGIN__` 是否存在
+5. 如果是 iframe，确认调用了 `mfeEventPlugin.registerIframe()`
+6. 如果是动态加载场景，`emitTo` 调用时子应用尚未注册，会在控制台看到警告：`emitTo: app not registered`
+
+### emitTo 报 app not registered
+
+动态加载时，如果 Shell 在子应用注册之前就调用了 `emitTo`，消息会丢失。控制台会输出：
+
+```
+[mfe-events] emitTo: app not registered: "mma" (event: mfe:route-navigate)
+```
+
+解决方案：确保子应用先调用 `register()`，再让 Shell 发 `emitTo`。或者在子应用 `LifecycleAppReady` 之后，再由子应用主动请求数据（而不是等 Shell push）。
+
+### 通知不显示
+
+1. 确认调用的是 `mfeEventPlugin.success/warning/danger()` 而非直接 dispatch 事件
+2. 如果 Shell 侧注册了 `useRenderer()`，通知会由 Shell 渲染，子应用侧看到的是 Shell 的 UI
+3. 检查 `duration` 是否为 `0`（需手动 `close()`）
+
+### iframe 子应用收不到事件
+
+1. 确认 Shell 侧调用了 `mfeEventPlugin.registerIframe(appId, iframeEl, targetOrigin)`
+2. 确认 `targetOrigin` 与 iframe 的 `src` origin 匹配（生产环境建议明确指定）
+3. 检查浏览器控制台是否有 postMessage 相关的 CSP 警告
+
+### TypeScript 编译报错找不到 `@vnb/mfe-events`
+
+```bash
+npm install @vnb/mfe-events --save
+```
+
+如果使用本地文件路径，确保 `tsconfig.json` 的 `paths` 配置正确：
+
+```json
+{
+  "compilerOptions": {
+    "paths": {
+      "@vnb/mfe-events": ["../packages/mfe-events/src"]
+    }
+  }
+}
+```
+
+### 如何上报自定义错误到 Shell
+
+```typescript
+try {
+  await fetch('/api/data');
+} catch (err) {
+  mfeBus.emit(EvtMfe.Error, {
+    source: 'my-app',
+    message: err.message,
+    stack: err.stack,
+  });
+}
+```
+
+### 子应用之间如何通信
+
+子应用之间**直接通信**，不需要 Shell 中转。`mfeBus` 基于 `window.CustomEvent`，所有 MF/NF 子应用共享同一个 window 通道：
+
+```typescript
+// 子应用 A：审批完成后通知其他子应用
+import { mfeBus, EvtMfe } from '@vnb/mfe-events';
+
+mfeBus.emit(EvtMfe.Raw, {
+  type: 'approval-done',
+  payload: { orderId: '123', approvedBy: 'admin' },
+  source: 'app-a',
+  ts: Date.now(),
+});
+```
+
+```typescript
+// 子应用 B：监听审批结果，刷新数据
+import { mfeBus, EvtMfe } from '@vnb/mfe-events';
+
+mfeBus.on(EvtMfe.Raw, (data) => {
+  if (data.type === 'approval-done') {
+    refreshOrderList(data.payload.orderId);
+  }
+});
+```
+
+> **注意**：iframe 子应用之间的通信需要 Shell 中转（iframe 之间无法直接 postMessage）。
+
+---
+
+## 类型安全
+
+`@vnb/mfe-events` 提供完整的 TypeScript 类型支持。事件名和 payload 类型在编译时检查：
+
+```typescript
+import { mfeBus, mfeEventPlugin, EvtMfe } from '@vnb/mfe-events';
+
+// ✅ 类型安全：data 被推断为 { theme: 'light' | 'dark' }
+mfeBus.on(EvtMfe.ThemeUpdate, (data) => {
+  document.documentElement.dataset.theme = data.theme;
+});
+
+// ✅ 类型安全：EvtMfe.RouteNavigate 的 data 是 { path: string }
+mfeEventPlugin.emitTo('mma', EvtMfe.RouteNavigate, { path: '/chairman' });
+
+// ❌ 编译错误：缺少 required field `path`
+mfeEventPlugin.emitTo('mma', EvtMfe.RouteNavigate, {});
+
+// ❌ 编译错误：invalid payload type
+mfeEventPlugin.emitTo('mma', EvtMfe.RouteNavigate, { path: 123 });
+```
+
+---
+
+## 更新日志
+
+See [CHANGELOG](./CHANGELOG.md) for version history.
+
+---
+
+## 许可证
+
+MIT