@hhfenpm/micro-app 1.0.4 → 1.0.5

package/README.md

@@ -1,6 +1,6 @@
 # @hhfenpm/micro-app
 
-微前端通信桥接和状态同步工具，支持父子应用之间的通信、状态同步和生命周期管理。
+基于 iframe + postMessage 的微前端工具：父子应用**通信桥接**、**Vuex 状态同步**、**生命周期**与**路由同步**。
 
 ## 安装
 
@@ -10,202 +10,200 @@ npm install @hhfenpm/micro-app
 yarn add @hhfenpm/micro-app
 ```
 
-## 功能特性
+## 能力概览
 
-- 🔗 **通信桥接**：支持父子应用之间的方法调用和通信
-- 🔄 **状态同步**：自动同步 Vuex store 状态
-- 🎯 **生命周期管理**：支持微前端生命周期（mount、update、unmount）
-- 🛣️ **路由同步**：自动同步子应用路由到父应用
-- ⚙️ **可配置**：支持自定义处理器、状态映射等
+| 能力 | 说明 |
+|------|------|
+| **通信桥接** | 子应用通过 `vm.$base.命名空间.方法(params)` 调用父应用方法，支持 Promise |
+| **状态同步** | 父子应用 Vuex `base` 模块双向同步 |
+| **生命周期** | 父应用调用 `mount/update/unmount`，子应用通过 `window.__MICRO_APP_LIFECYCLE__` 响应 |
+| **路由同步** | 子应用路由变化同步到父应用 URL（需子应用调用 `store.attachRouterSync(router)`） |
 
-## 使用方式
+---
 
-### 1. 初始化通信桥接
+## 一、Bridge（通信桥接）
 
-#### 父应用
+### 父应用
+
+父应用需提供 `handlers`：`{ 命名空间: { 方法名: 函数 } }`。可使用内置 `createRegisterHandlers` 生成 `ui`（Element UI 等）和 `cs`（Electron）两个命名空间：
 
 ```javascript
-import { initBridge } from '@hhfenpm/micro-app'
-import Vue from 'vue'
+import { initBridge, createRegisterHandlers } from '@hhfenpm/micro-app'
 
 const vm = new Vue({ /* ... */ })
 
-// 创建处理器（项目特定）
-const handlers = {
-  elementUI: {
-    $message: (...args) => vm.$message(...args),
-    // ... 其他 Element UI 方法
-  },
-  electron: {
-    // ... Electron 方法
-  },
-}
+// getElectron：返回 electron 模块，无则 () => ({}) 或 () => require('@/utils/electron')
+const getElectron = () => ({}) // 或 () => require('@/utils/electron')
+const toHandlers = createRegisterHandlers(getElectron)
 
-// 初始化桥接
 initBridge({
   isParent: true,
   vm,
-  handlers,
+  handlers: toHandlers(vm),
   iframeSelector: '#microApp', // 可选，默认 '#microApp'
 })
 ```
 
-#### 子应用
+`createRegisterHandlers(getElectron)` 返回 `(vm) => ({ ui, cs })`：
+
+- **ui**：`$message`、`$success`、`$warning`、`$error`、`$notify`、`$confirm`、`$alert`、`$prompt`、`$loading`
+- **cs**：Electron 能力（由 `getElectron()` 提供，缺失的方法为 noop）
+
+### 子应用
 
 ```javascript
 import { initBridge } from '@hhfenpm/micro-app'
-import Vue from 'vue'
 
 const vm = new Vue({ /* ... */ })
 
-// 初始化桥接
-initBridge({
-  isParent: false,
-  vm,
-})
+initBridge({ isParent: false, vm })
 
-// 使用 $base 调用父应用方法
-vm.$base.elementUI.$message('Hello from child app')
-vm.$base.electron.show()
+// 调用父应用：vm.$base.命名空间.方法(params)，返回 Promise
+vm.$base.ui.$message('来自子应用')
+vm.$base.ui.$confirm('确认？').then(ok => { /* ... */ })
+vm.$base.cs.show()
 ```
 
-### 2. 使用核心功能
+---
+
+## 二、Core（子应用 URL / 部署检测）
+
+根据「路径 → 模块名」映射、以及「启用模块列表」，计算当前路由是否命中某子应用、其入口 URL、是否已部署。
 
 ```javascript
 import { createMicroAppCore } from '@hhfenpm/micro-app'
 
-// 定义模块路由映射
-const ModelMap = () => ({
-  'module1': ['/module1', '/m1'],
-  'module2': ['/module2'],
+const modelMap = () => ({
+  'disease-analysis': ['/disease-analysis', '/ds-consult'],
+  'health': ['/health-manage'],
 })
 
-// 创建核心功能实例
 const core = createMicroAppCore({
-  modelMap: ModelMap,
-  enabledModules: () => window.GLOBAL_CONFIG?.microApp || null,
+  modelMap,
+  enabledModules: () => window.GLOBAL_CONFIG?.microApp || null, // 可选，不传则用 GLOBAL_CONFIG.microApp
 })
 
-// 使用
-const module = core.microAppModule('/module1')
-const src = core.microAppSrc('/module1')
-const deployed = await core.microAppDeployed('module1')
+// 根据路径得到模块名，未命中或未启用则为 null
+const module = core.microAppModule('/disease-analysis')  // 'disease-analysis'
+
+// 子应用完整 URL（含 hash）
+const src = core.microAppSrc('/disease-analysis')
+
+// 是否已部署（HEAD /module 可访问）
+const ok = await core.microAppDeployed('disease-analysis')
 ```
 
-### 3. 使用状态同步插件
+---
+
+## 三、Store 插件（状态同步）
+
+在 Vuex 中注册 `baseSyncPlugin`，并在**子应用**中调用 `store.attachRouterSync(router)` 以同步路由。
+
+### 父应用
 
 ```javascript
 import Vuex from 'vuex'
 import { baseSyncPlugin } from '@hhfenpm/micro-app'
+import base from './store/modules/base' // 需含 base/SYNC_STATE
+
+const store = new Vuex.Store({
+  modules: { base },
+  plugins: [baseSyncPlugin({ isParent: true, iframeSelector: '#microApp' })],
+})
+```
+
+### 子应用
+
+```javascript
+import { baseSyncPlugin } from '@hhfenpm/micro-app'
+import base from './store/modules/base'
 
-// 创建 Vuex Store
 const store = new Vuex.Store({
-  modules: {
-    base: {
-      namespaced: true,
-      state: {
-        patient_id: null,
-      },
-      mutations: {
-        SYNC_STATE(state, payload) {
-          Object.assign(state, payload)
-        },
-      },
-    },
-  },
-  plugins: [
-    baseSyncPlugin({
-      isParent: false, // 子应用设为 false
-      iframeSelector: '#microApp',
-    }),
-  ],
+  modules: { base },
+  plugins: [baseSyncPlugin({ isParent: false, iframeSelector: '#microApp' })],
 })
 
-// 子应用附加路由同步
 import router from './router'
-store.attachRouterSync(router)
+store.attachRouterSync(router) // 必调，用于把子应用路由同步到父应用
 ```
 
-### 4. 生命周期管理
+`base` 模块需提供 `base/SYNC_STATE` mutation，用于接收并合并同步过来的 state。
+
+---
 
-#### 子应用
+## 四、生命周期
+
+### 子应用
+
+在子应用入口注册：
 
 ```javascript
-// 注册生命周期钩子
 window.__MICRO_APP_LIFECYCLE__ = {
-  mount(payload) {
-    console.log('微前端已挂载', payload)
-  },
-  update(payload) {
-    console.log('微前端已更新', payload)
-  },
-  unmount(payload) {
-    console.log('微前端已卸载', payload)
-  },
+  mount(payload) { /* 挂载后 */ },
+  update(payload) { /* 更新时，如路由变化 */ },
+  unmount(payload) { /* 卸载前 */ },
 }
 ```
 
-#### 父应用
+### 父应用
+
+由 `baseSyncPlugin` 在 store 上挂载 `callMicroAppLifeCycle`，在 iframe 加载完成、路由变化、子应用切换时调用：
 
 ```javascript
-// 调用生命周期
-store.callMicroAppLifeCycle('mount', { /* payload */ })
-store.callMicroAppLifeCycle('update', { /* payload */ })
-store.callMicroAppLifeCycle('unmount', { /* payload */ })
+store.callMicroAppLifeCycle('mount', { route: '/xxx' })
+store.callMicroAppLifeCycle('update', { route: '/yyy' })
+store.callMicroAppLifeCycle('unmount')
 ```
 
-## API 文档
-
-### Bridge
+---
 
-#### `initBridge(options)`
+## API 一览
 
-初始化通信桥接。
+| 接口 | 说明 |
+|------|------|
+| `initBridge({ isParent, vm, iframeSelector?, handlers? })` | 初始化桥接；父应用传 `handlers`，子应用可访问 `vm.$base` |
+| `createRegisterHandlers(getElectron?)` | 返回 `(vm) => ({ ui, cs })`，用作 `handlers` |
+| `createMicroAppCore({ modelMap, enabledModules? })` | 返回 `{ microAppModule, microAppSrc, microAppDeployed }` |
+| `baseSyncPlugin({ isParent, iframeSelector? })` | Vuex 插件，并挂载 `store.attachRouterSync`、`store.callMicroAppLifeCycle` |
 
-**参数：**
-- `options.isParent` (boolean): 是否为父应用
-- `options.vm` (Object): Vue 实例
-- `options.iframeSelector` (string): iframe 选择器，默认 `'#microApp'`
-- `options.handlers` (Object): 处理器对象（父应用需要）
+### 参数说明
 
-### Core
+- **initBridge**
+  - `isParent`: 是否父应用
+  - `vm`: Vue 实例（子应用会在其上挂 `vm.$base`、`vm.$baseReady`）
+  - `iframeSelector`: 父应用 iframe 选择器，默认 `'#microApp'`
+  - `handlers`: 仅父应用需要，`{ [namespace]: { [method]: (params)=>any } }`
 
-#### `createMicroAppCore(options)`
+- **createRegisterHandlers**
+  - `getElectron`: `() => electronModule`，可选；异常或未传时 `cs` 使用 noop
 
-创建微前端核心功能实例。
+- **createMicroAppCore**
+  - `modelMap`: `() => ({ [moduleName]: path[] })`，必填
+  - `enabledModules`: `() => string[]` 或 `string[]`，可选；缺省时从 `window.GLOBAL_CONFIG.microApp` 读取
 
-**参数：**
-- `options.modelMap` (Function): 模块路由映射函数，返回 `{ [moduleName]: string[] }`
-- `options.enabledModules` (Array|Function): 启用的模块列表或获取模块列表的函数
+- **baseSyncPlugin**
+  - `isParent`: 是否父应用
+  - `iframeSelector`: 默认 `'#microApp'`
 
-**返回：**
-- `microAppModule(path)`: 根据路径获取模块名
-- `microAppSrc(path)`: 生成完整 URL
-- `microAppDeployed(module)`: 检测模块是否已部署
+---
 
-### Store
-
-#### `baseSyncPlugin(options)`
-
-创建状态同步插件。
+## 注意事项
 
-**参数：**
-- `options.isParent` (boolean): 是否为父应用
-- `options.iframeSelector` (string): iframe 选择器
+1. **同源**：postMessage 仅在同源下使用，需校验 `event.origin`。
+2. **base 模块**：`baseSyncPlugin` 通过 `base/SYNC_STATE` 同步；`base` 的 state 结构需与约定一致。
+3. **子应用必调**：`store.attachRouterSync(router)`，否则子应用路由不会回写到父应用 URL。
+4. **Proxy**：`vm.$base` 依赖 Proxy，不支持 IE11。
 
-## 浏览器兼容性
+---
 
-- 现代浏览器（Chrome, Firefox, Safari, Edge）
-- 需要支持 `postMessage` API
-- 需要支持 `Proxy` API（IE 11 不支持）
+## 兼容性
 
-## 注意事项
+- 现代浏览器（Chrome、Firefox、Safari、Edge）
+- 依赖 `postMessage`、`Proxy`
+- Vue 2.6+ / 3.x，Vuex 3.x / 4.x（peerDependencies）
 
-1. **安全性**：消息通信会检查 `origin`，确保只在同源窗口间通信
-2. **状态同步**：状态同步使用深拷贝，避免引用污染
-3. **生命周期**：子应用需要注册 `window.__MICRO_APP_LIFECYCLE__` 对象
-4. **路由同步**：子应用需要调用 `store.attachRouterSync(router)` 附加路由同步
+---
 
-## 许可证
+## 许可
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hhfenpm/micro-app",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "微前端通信桥接和状态同步工具，支持父子应用通信、状态同步、生命周期管理",
   "main": "dist/index.js",
   "module": "dist/index.esm.js",