cloud-web-corejs 1.1.0-dev.6 → 1.1.0-dev.61

package/docs/qiankun/346/216/245/345/205/245/345/215/217/350/256/256.md

@@ -0,0 +1,298 @@
+# qiankun 微前端接入协议
+
+> 适用对象：接入本体系的 **主应用**（引包 / 未引包・异构技术栈均可）与 **子应用**（引包）。
+> 配套实现方案：`docs/qiankun微前端改造-实现方案.md`。本文是对外的最小接入契约，实现细节以方案文档为准。
+
+---
+
+## 1. 核心约定（一段话版本）
+
+菜单的**访问路径**（`route || url`）形如 `/micro/{appCode}/...` 时归属子应用：固定前缀 `micro` 之后的那一段命中应用注册表里的 `appCode`，该菜单就由对应子应用渲染；不带 `/micro/` 前缀的一律归主应用。**表单菜单的唯一识别标识是 `type === 5`**。`base` 是保留段，表示组件在 `cloud-web-corejs` npm 包内（任何引包应用都能渲染，不表达归属）。qiankun 的 activeRule 直接由 appCode 推导（`#/micro/{appCode}`），因此菜单路径无需任何改写即可触发子应用装载。
+
+访问路径的四段语义：
+
+```
+/micro/mkweb/base/user/user/list
+ └─┬──┘ └─┬─┘ └┬─┘ └──────┬─────┘
+ 微前端   归属   来源     组件路径
+ 固定前缀 appCode base=包内  剥掉前三段后的余量
+```
+
+**为什么用固定前缀而不是"首段即 appCode"**：主应用自身的一级视图目录（`/user`、`/pmd`、`/yx`……）与 appCode 处在同一命名空间时会互相劫持——注册一个与视图目录同名的 appCode 会吞掉主应用整棵子树，而新增一个视图目录又会反向撞掉已在运行的 appCode。`/micro/` 让两者结构性隔离，不需要维护保留字清单。
+
+## 2. 应用注册表
+
+- **载体**：逻辑参数，编码 `micro_app_registry`。
+- **获取**（需登录态，与业务接口同一套 token）：
+
+```
+POST {BASE_API}/user/logic_param/getParamValue
+Body: { "paramCode": "micro_app_registry" }
+返回: objx 字段为 JSON 字符串
+```
+
+- **JSON 结构**（数组）：
+
+```json
+[
+  {
+    "appCode": "appA",                    // 必填，^[A-Za-z][A-Za-z0-9_-]*$
+    "appName": "营销子应用",               // 展示名，缺省用 appCode
+    "entry": "//xxx.com/appA/",           // 必填，非空字符串（见下方说明）
+    "enabled": true                       // 停用置 false，无需删条目
+  }
+]
+```
+
+- **appCode 命名禁区**：不得为 `base`（组件来源命名空间）、`micro` 或 `micro_debug`（前缀自身）。因为 appCode 活在 `/micro/` 命名空间内，**无需再回避各应用 `@/views` 一级目录名**。
+- **`entry` 只能是字符串，不分环境**。曾经支持 `{ development, production }` 对象写法，已废弃——注册表存在后端逻辑参数里，本身就按环境分库，主应用连哪个后端就拿到哪份注册表，再按前端 `NODE_ENV` 分一次是重复机制。本机联调走 2.1 的 `/micro_debug/` 命名空间，显式且不依赖构建环境。写成对象会被 `validateRegistry` 判为非法条目并跳过。
+- **`entry` 必须指向 `index.html` 的真实所在目录**，`/mkweb/` 这类前缀不能省，原因见 4.1。建议用协议相对地址（`//host/...`）跟随主应用的 http/https。
+- 校验参考实现：`cloud-web-corejs/src/utils/menuAdapter.js` 的 `validateRegistry`（非法条目跳过并显式报错，请勿静默吞掉）。
+
+### 2.1 本机调试（切换命名空间，无状态）
+
+**前置：逻辑参数 `micro_debug_enabled` 必须为 `true`**，默认关闭。见本节末尾的安全说明。
+
+把地址里的 `/micro/` 改成 `/micro_debug/`，该子应用即从**本机约定端口**装载，其余一切不变：
+
+```
+正式：http://主应用域名/sys/index.html#/micro/mkweb/base/user/user/list
+调试：http://主应用域名/sys/index.html#/micro_debug/mkweb/base/user/user/list
+                                        ^^^^^^^^^^^  → http://localhost:17527/
+```
+
+两个命名空间**归属相同、菜单相同、组件解析完全相同，只有 entry 不同**。因此：
+
+- **联调不用改数据库**——菜单表里还是 `/micro/mkweb/...`，主应用下发 props 时才把路径换到调试命名空间；
+- **不需要和子应用的 `settings.appCode` 对暗号**——appCode 仍是 `mkweb`，菜单照常派发；
+- **调试态不落任何存储**，路径本身就是开关。关掉调试 = 把 `/micro_debug/` 改回 `/micro/`，或直接关标签页。分享链接不会让别人莫名其妙进入调试态，也不存在"几天前的调试残留导致线上白屏"。
+
+同一个 appCode 的正式态与调试态是**两个独立保活实例**（容器 `#Appmicro-mkweb` 与 `#Appmicro-mkweb_micro_debug`），可以同时开着两个页签对比。首次装载调试实例时控制台有 ⚠ 告警。
+
+| 项 | 约定值 |
+|---|---|
+| 调试 entry | `http://localhost:17527/`（包内常量 `DEBUG_ENTRY`） |
+
+**开关：逻辑参数 `micro_debug_enabled`（默认关闭）**
+
+```
+POST {BASE_API}/user/logic_param/getParamValue
+Body: { "paramCode": "micro_debug_enabled" }
+```
+
+| 值 | 含义 |
+|---|---|
+| `true` | 开启（忽略大小写与首尾空格） |
+| 其余一切——不存在 / 空 / `false` / 认不出的值 | **关闭**（默认；取值失败、超时也回落到这里） |
+
+只认 `true` 一个字面量、其余一律关闭，是有意的安全默认：认不出就不放行，不会因为写了个形近值（`1`、`on`、`是`）而把某个环境悄悄放开。开关是全局的，不区分应用。
+
+**为什么单独一条参数、而不是放注册表字段或 `settings.js`**：
+- 不放 `settings.js` —— 那是构建期常量、发版即锁死，同一份产物部署到测试和生产就区分不了；逻辑参数按环境分库，运维改值即刻生效，不用重新发版。
+- 不放注册表 —— 注册表描述"有哪些应用"，是相对静态的结构；调试开关是环境级运维动作，两者生命周期不同。分开之后开关调试不必编辑注册表 JSON，少一类把注册表改坏的风险，两个参数还能配不同的操作权限。
+
+主应用在登录后**并行**取这两条参数（`Promise.all`，互不依赖），不额外增加串行耗时。
+
+> ⚠ **默认关闭是安全要求，不是保守**：`/micro_debug/` 会让当前页面去加载**访问者本机 17527 端口**的代码，并经 props 把 token 交给它。正常情况那是开发者自己的 devServer，但只要有恶意程序占住这个端口，一条链接就能让它拿到该环境的登录态。**生产环境不应配置 `micro_debug_enabled`**（或显式置 `0`）。
+>
+> 关闭状态下的表现：全部应用都没开时**连路由都不注册**，`/micro_debug/...` 直接落 404；有别的应用开着而当前这个没开，则命中通配路由并在控制台报错说明原因，不会静默白屏。
+
+> **端口是固定的，不可配**。这是无状态设计的代价：没有存储也没有查询参数，就没有地方放"用哪个端口"。要调的子应用把 devServer 端口设成 17527 即可（`vue.config.js` 里写死，不要用 `--port` 覆盖）。
+> 调试 entry **只写端口、不带应用前缀**，这样一个约定值对所有子应用通用（各应用 `WEB_PREFIX` 不同：`/sys`、`/mkweb`……）。代价是子应用 devServer 必须把根路径做成 `publicPath` 的别名，见 4.1。
+
+**调试直达（免配菜单）**：调试命名空间装载的子应用会收到 `props.microDebug = true`，据此追加一条按访问路径解析组件的兜底路由（剥归属前缀 → `/base` 命名空间 → `loadView`，解析不出落提示页）。因此联调期可以直接用 URL 打开**尚未配置菜单**的页面：
+
+```
+http://主应用域名/sys/index.html#/micro_debug/mkweb/base/user/positon/list
+```
+
+> 正式命名空间**不会**收到该标记——菜单即权限边界，不能让任意路径都打得开组件。
+> 派发模式下子应用路由完全来自 `props.menus`，没有这条兜底时访问未配菜单的路径会由子应用自身跳 404（表现为主应用已把地址交出去、页面却是 404）。
+
+## 3. 菜单识别与派发（主应用职责）
+
+1. 登录后并行获取：全量菜单 `POST {BASE_API}/user/menu/currentList` + 上述注册表。
+2. 对每条菜单：取访问路径 `route || url`（忽略查询串）；首段为 `micro`（或 `micro_debug`）且第二段命中注册表 `appCode` → 归属该子应用；其余（无微前端前缀 / `appCode` 未命中）→ 主应用。菜单表里只会出现 `micro`，`micro_debug` 由主应用在下发 props 时临时改写，不落库。
+3. **表单菜单（`type === 5`）与普通菜单走同一归属规则**，代码层面不做任何特殊处理。但**表单渲染器在 npm 包内**（`@base/views/user/form/view/list`），未引包子应用没有这个组件，所以「表单菜单只挂在引包子应用名下」是一条**配置纪律**，由配置人保证。曾用注册表字段 `hasCorejs` 做过强制校验，已移除——见下方说明。
+
+> **为什么不用代码强制**：校验的兜底动作只能是「退回主应用渲染」，而这恰恰违背本方案的前提（表单依赖归属应用的私有代码，主应用代渲染必然行为错乱）。且未引包子应用根本不跑本包，配置错了在联调第一天就会暴露，不会潜伏到线上。字段本身还引入了更隐蔽的故障：漏写即视同"不能渲染表单"，菜单被静默改道。
+> 将来若确实需要能力校验，正确形态是**由子应用自己声明能力**（它才知道自己能渲染什么），而不是在注册表里让配置人替它猜。
+4. 归属子应用的菜单：主应用不为其生成本地组件路由，只保证 URL 进入 `#/micro/{appCode}/...` 后有一条通配路由不落 404；菜单原路径即可触发 activeRule。调试命名空间全局只需一条 `/micro_debug/:appCode/*`，不按应用展开。
+5. 参考实现（零依赖纯函数，可 deep-import）：
+   `cloud-web-corejs/src/utils/menuAdapter.js` → `isFormMenu / resolveOwner / dispatchMenus / validateRegistry / resolveEntry`。
+
+## 4. 子应用注册（主应用职责）
+
+| 项 | 约定 |
+|---|---|
+| name | `appCode`（调试实例为 `{appCode}@micro_debug`，与正式实例各自保活） |
+| entry | 注册表 `entry` 原样；调试实例固定 `http://localhost:17527/` |
+| activeRule | hash 前缀匹配：`#/micro/{appCode}` 及其 `/...`、`?...` 形态；调试实例同理匹配 `#/micro_debug/{appCode}` |
+| container | 主应用自定（引包主应用固定 `#Appmicro`） |
+| 注册范围 | 全部 `enabled` 应用（qiankun 惰性加载，无需按菜单筛选） |
+
+引包主应用：**零代码配置**——`microMainEnabled` 默认开启，配好第 2 节的逻辑参数注册表即自动完成本节与第 3 节（包内已实现）；注册表未配置时无任何宿主行为。不想当宿主的应用在自身 `settings.js` 显式置 `microMainEnabled: false`。
+未引包主应用：按本文自行调用 `registerMicroApps` + `start()`。
+
+> **沙箱红线**：`start()` 保持默认沙箱（ProxySandbox），**严禁配置 `sandbox: { loose: true }`**。
+> loose 模式下子应用对 window 的写入穿透到真实 window，`window.$vueRoot`、前缀常量等会被主子互相覆盖，本协议的隔离结论全部失效。
+
+> **互访形态**：`microMainEnabled` 默认开启，任何引包应用（含子应用）独立运行时天然是宿主——所在环境配置了注册表即可装载其他应用实现互访。宿主逻辑会**自动排除注册表中与自身 `appCode` 相同的条目**（防自嵌套）。代价自评估：任意两应用间需互放 CORS（同域网关则无此项）、系统出现多个等价入口；不想参与互访的应用置 `microMainEnabled: false` 退出。被 qiankun 挂载时宿主行为始终强制关闭，不会出现嵌套装载。
+
+### 4.1 entry 与 publicPath 的绑定关系
+
+**entry 必须指向子应用 `index.html` 的真实所在目录**，不能随意省略路径段。原因：qiankun 取 entry 的目录作为 `__INJECTED_PUBLIC_PATH_BY_QIANKUN__` 注入子应用，`public-path.js` 用它覆盖 `__webpack_public_path__`，此后**所有懒加载 chunk 都从这里取**。本体系的视图全是 `() => import()`，entry 与真实 publicPath 不一致时首页能出、点第一个菜单必 404。
+
+各应用 `publicPath = WEB_PREFIX + "/"`，而 `WEB_PREFIX` 各不相同（`/sys`、`/mkweb`……），所以正式注册表的 `entry` 要带各自前缀，例如 `//xxx.com/mkweb/`。
+
+**但调试默认值要保持通用**，不能写死某个应用的前缀。做法是给子应用 devServer 加根路径别名，把不带前缀的请求改写到 `publicPath` 下（`vue.config.js` → `devServer.setupMiddlewares`，包内模板已含）：
+
+```
+/                 ->  /mkweb/          （entry 从根拿 index.html）
+/js/app.js        ->  /mkweb/js/app.js （注入 publicPath 为根，懒加载 chunk 回落到真实位置）
+/mkweb/...        ->  原样              （已带前缀不改写）
+/ws               ->  原样              （dev-server 自身端点放行）
+```
+
+这样调试入口统一写 `http://localhost:17527/`，一个默认值对所有子应用通用；仅开发服务器生效，生产部署路径不变，原带前缀的地址同时照常可用。
+
+> 不要试图改用 `publicPath: "/"` 达到同样效果：`WEB_PREFIX` 由 `utils/vab.js` 注入为 `window.WEB_PREFIX`，ace/tinymce 等静态资源路径（`window.WEB_PREFIX + "/base/..."`）与登录流程的前缀比对都依赖它，跟着改会连带打断开发环境登录跳转。
+
+## 5. props 下发协议（主 → 子，mount 时）
+
+```js
+{
+  appCode: "appA",              // 子应用编码
+  menus: [ /* 菜单行数组 */ ],   // 归属该子应用的菜单子集（currentList 原始行结构）
+  token: "...",                 // 登录 token。存 sessionStorage 按 origin 隔离，跨域/跨端口主应用
+                                // 必须显式下发；引包子应用 mount 时写入自身登录态实现免登，
+                                // token 失效则自动回落到子应用登录页
+  lang: "zh",                   // 当前语言（localStorage "i18n-lang"）
+  userInfo: {                   // 登录信息快照（注册时快照，非实时）
+    userId: "...",
+    loginAccount: "...",
+    name: "...",
+    nickName: "...",
+    companyCode: "...",
+    companyInfoId: "...",
+    roles: [],
+    userFlag: null
+  },
+  mainAdapter: {                // 主应用回调，子应用跳主应用路由的唯一合法通道
+    navigate(path) {},          // 跳转主应用路由
+    openTab(path) {},           // 打开主应用页签
+    closeTab(view) {}           // 关闭当前/指定页签
+  }
+}
+```
+
+> **`lang` 与 `userInfo` 主要服务于未引包子应用**——它们没有本包的 i18n 机制，也没有 `getInfo2` 可调，只能靠这两个 props 拿到语言和登录态。
+> **引包子应用有意不消费它们**：语言读同源共享的 localStorage `i18n-lang`（下方说明），登录态用 token 自行调 `getInfo2` 填 `user` store。两者都是比"注册时快照"更权威、不会过期的来源；再存一份 props 副本只会让业务代码读到哪个全看运气。所以包内看不到消费方是设计结果，不是遗漏，请勿据此删除这两个字段。
+
+**运行期变化——语言为整页刷新语义，无需广播**：主应用切语言 = 后端 switchLanguage + 写 localStorage `i18n-lang` + `location.reload()`；reload 后子应用随页面重挂，启动时读取**同源共享**的 localStorage（qiankun 沙箱不隔离 localStorage），语言天然一致。登出同理由主应用真正卸载子应用覆盖。`initGlobalState` 作为**预留机制**，当前无必须事件；将来出现真实运行期事件时按以下信封启用，不再另行设计：
+
+```js
+// 主应用 initGlobalState 初始状态
+{ event: null }
+// 广播：setGlobalState({ event: { type: "xxx", payload: {...}, seq: 自增 } })
+// seq 保证同 type 连发也触发变更；event 字段所有权归主应用，子应用只读；
+// 子应用 mount 时 props.onGlobalStateChange(handler, true) 挂监听，unmount 由 qiankun 自动清理
+```
+
+**保活协议**：主应用以 `loadMicroApp` 保活模式装载子应用——切走只隐藏容器不卸载，切回显示。**登出时主应用必须真正卸载全部保活子应用**（引包主应用已内置：resetToken → unmountAllMicroApps；异构主应用自行调用各实例 `unmount()`），否则换账号后切回子应用会复活上一个用户的实例。子应用需导出 `update(props)` 生命周期并响应 `props.microActive`：`false` = 容器已隐藏，暂停自身路由对 URL 变化的响应（否则会与主应用互相回写 URL）；`true` = 容器恢复显示，恢复路由响应并把当前 hash 同步为自身当前路由。引包子应用无需自行实现（包内已内置）；异构子应用若不实现 `update`，隐藏期间其路由仍在监听，浏览器前进/后退可能引发 URL 互踩，须自行处理。
+**刷新协议**：页签"刷新"按钮由主应用渲染，但子应用页面不在主应用 `router-view` 内——主应用那套 `delCachedView` + `/redirect` 重建对它无效，走一圈只是容器隐藏再显示、实例毫发无损，表现为**点刷新没反应**。因此主应用检测到当前路由 `meta.isMicroApp` 时改为下发 `update({ microRefresh: <时间戳> })`，由子应用**原地销毁重建**当前页组件。时间戳保证连续点击每次都是新值。异构子应用响应该字段即可；不响应则刷新按钮在该应用页面上无效果。
+
+> ⚠ **子应用重建时不得跳 `/redirect`**（主应用自身刷新用的那一招）：主子共用同一个浏览器 hash，跳 `/redirect` 会被主应用 `afterEach` 判成"离开子应用路由"，容器随即隐藏并下发 `microActive: false` 暂停子应用路由，重建被掐断——表现和不实现 `update` 一样，点刷新没反应。引包侧的做法是自增一个序号，由 `AppMain` 用 `v-if` 开关销毁重建组件，全程不碰 URL；异构子应用同理，用框架自身的强制重挂机制（如改 `key`）即可。
+
+**异构子应用推荐做法**：qiankun 挂载时路由用 **memory 模式**（vue-router 4 `createMemoryHistory` / react-router `MemoryRouter`），子应用完全不读写浏览器 URL，天然满足暂停要求——只需在 `mount` 与 `microActive: true` 时把当前 hash 剥掉 `/{appCode}` 前缀后同步为自身路由。参考工程：`vue3-qiankun-child-demo`（Vue 3 + vue-router 4 最小接入示例）。
+
+**自治嵌入模式（menus 不下发）**：主应用 props 里 `menus` 传 `null` 或不传（**非数组**）时，引包子应用进入自治模式——自拉全量菜单、保留自身侧边栏/页签壳，整站运行在容器内，登录也由子应用自己的登录页完成（token 存 sessionStorage，**按 origin 隔离**，跨端口/域的主应用无法复用既有登录态）。适合异构/未引包主应用把整个平台当"整站组件"嵌入、不关心菜单派发的场景，主应用零后端对接。注意语义区分：`menus: []`（空数组）＝ 标准派发模式但无菜单；`menus: null / 缺省` ＝ 自治模式。参考工程：`vue3-qiankun-main-demo`（Vue 3 异构主应用，自治嵌入 cloud-web-corejs）。
+
+## 6. 引包子应用接入步骤
+
+新建引包工程请优先使用 [子应用模板与接入契约](./child-app/README.md)，其中包含完整的应用文件和构建配置。下述片段仅说明微前端接入，不是完整脚手架。
+
+1. **统一版本**：`cloud-web-corejs` 升级到基准版本（接入硬性前置）。
+2. **声明身份**：自身 `settings.js` 填 `appCode`（与注册表一致）。
+3. **入口导出生命周期**（新模板使用资源内置入口）：
+
+```js
+// main.js
+export * from "cloud-web-corejs/src/index.next.js";
+```
+
+旧工程的 `src/index.js` 入口仍兼容，但要求应用提供旧版 styles/icons；切换新入口需同步使用模板的 Sass/SVG 配置。
+
+4. **打包配置**（vue.config.js）：
+
+```js
+const packageName = require("./package.json").name;
+const prefixConfig = require("./src/prefixConfig.js");
+module.exports = {
+  devServer: {
+    headers: { "Access-Control-Allow-Origin": "*" }, // qiankun 跨域拉取
+    // 根路径别名：让调试 entry 免写应用前缀（见 4.1），仅开发服务器生效
+    setupMiddlewares: (middlewares) => {
+      const base = prefixConfig.WEB_PREFIX;
+      const passThrough = ["/ws", "/sockjs-node", "/webpack-dev-server", "/__"];
+      middlewares.unshift({
+        name: "qiankun-root-alias",
+        middleware: (req, res, next) => {
+          const url = req.url || "/";
+          const skip
+            = url.startsWith(base + "/")
+            || url === base
+            || passThrough.some((p) => url.startsWith(p));
+          if (!skip) {
+            req.url = base + (url === "/" ? "/" : url);
+          }
+          next();
+        },
+      });
+      return middlewares;
+    },
+  },
+  configureWebpack: {
+    output: {
+      library: `${packageName}-[name]`,
+      libraryTarget: "umd",
+      chunkLoadingGlobal: `webpackJsonp_${packageName}`, // webpack5 字段（webpack4 用 jsonpFunction）
+    },
+  },
+};
+```
+
+> **package.json 的 `name` 必须各应用唯一**——webpack5 默认 chunk 注册全局名派生自它，
+> 从模板复制工程不改 name 会导致主子 chunk 互相吞掉对方模块，
+> 报错形如 `Cannot find module './node_modules/webpack-dev-server/client/...'`。
+
+> **index.html 里 webpack 注入点之后不得再有任何 `<script>`**（含 `</body>` 之后的外链 SDK）——
+> import-html-entry 取 html 最后一个 script 的导出当生命周期来源，尾部脚本会劫持入口判定，
+> 报错 `You need to export lifecycle functions in xxx entry`（即使 main.js 导出正确）。
+> 外链 SDK 一律放在 body 内靠前位置或 `<head>`。
+
+5. **菜单配置**：普通私有页面访问路径为 `/micro/{appCode}/xx/xx`；包内页面为 `/micro/{appCode}/base/xx/xx`，也可用 `url=/base/xx/xx` 配合 `route=/micro/{appCode}/base/xx/xx`。表单菜单使用 `type === 5`，归属同样由 `route || url` 的 `/micro/{appCode}/` 前缀决定，表单编码和其他字段按实际后端契约填写。
+6. **独立运行零改动**：`window.__POWERED_BY_QIANKUN__` 为假时走原有完整流程（自拉菜单、自建路由、自带壳）。
+
+## 7. 部署 / 运维前置
+
+- 子应用 nginx/网关放开对主应用域名的 CORS（qiankun 以 fetch 拉取子应用 entry 与静态资源）。
+- token cookie 的域必须覆盖主、子应用。
+- 各应用 `VUE_APP_BASE_API` / 接口前缀指向同一套网关。
+
+## 8. 禁止事项
+
+1. **跨应用组件引用**：A 应用的表单/脚本不得打开 B 应用的页面或弹框（qiankun 沙箱下不可实现，表单设计规范同步约束）。
+2. **子应用直接操作主应用 router/store**：跳主应用路由一律走 `props.mainAdapter`。
+3. **appCode 撞名**：见第 2 节命名禁区，注册前先核对各应用 `@/views` 一级目录。
+4. **静默吞掉注册表校验错误**：非法条目必须显式报错（控制台/监控），否则故障表现为"子应用打不开"极难排查。
+5. **流程/表单设计器类菜单配到子应用名下**：流程设计（activiti-explorer）经 iframe 以 `window.parent.xxx` 回调宿主页面，qiankun 沙箱内的赋值对真实 window 不可见，此类页面在子应用内必然失效——**必须归属主应用**。涉及菜单：流程管理配置（wf_obj_config）、表单模板的流程设计入口（form_template 各 list）。移动端原生壳回调（`window.fileUpload`）同理。
+6. **`window.onxxx =` 直赋值注册事件**：沙箱代理上收不到真实事件，一律使用 `addEventListener`（沙箱会在卸载时自动清理）。
+
+## 9. 兜底行为（体系内已实现，异构接入方对齐语义即可）
+
+- **"归属别家"的判定依据 = 访问路径首段命中注册表里的 appCode**（2026-07-17 修正：不能用"首段 ≠ 自身 appCode"判定——主应用 appCode 为空会把一切加载失败误判成别家）。注册表未配置/不可用时永远不出"去主平台"文案。
+- 应用独立运行点到别家菜单（首段命中注册表且非自身）：提示页"该菜单归属应用「xx」，当前应用未部署对应页面，请在主平台中访问"（非异常，不弹错）。
+- 主应用侧（appCode 为空）出现归属子应用的菜单走到本地加载：提示"检查应用注册表与子应用部署"（本应委派 qiankun 渲染，视为注册/部署异常）。
+- 其余组件加载失败（含菜单指向不存在的组件、注册表解析失败）：提示"页面组件加载失败，请检查菜单配置或应用注册表"。
+- 边界：**没有路由的 URL 仍走全局 `*` → 404 页**；兜底提示页只出现在"菜单存在但组件加载失败"的路由上。

package/docs/qiankun/350/257/246/346/203/205/346/211/277/350/275/275/345/255/220/345/272/224/347/224/250/345/257/271/346/216/245/346/270/205/345/215/225.md

@@ -0,0 +1,111 @@
+# qiankun 详情承载 · 子应用对接清单
+
+> 对象：被主应用（或另一引包应用）通过 `micro-view-host` 在弹框内装载、用来渲染**本子应用私有详情页**的子应用工程。
+> 背景与整体设计：`docs/qiankun动态详情页承载方案.md`（§5 契约）。归属/命名空间：`docs/qiankun接入协议.md`。
+> 一句话：当主应用要在弹框里打开一张**归属你、且组件在你 bundle 里**的单据详情页时，会 `loadMicroApp` 你的应用并下发一组约定 props；你需要在 `mount` 里认出这个模式，把目标详情页渲染出来，并把详情页的「刷新 / 关闭 / 回调」桥接回主应用。
+
+---
+
+## 1. 触发方式
+
+主应用的 `micro-view-host` 组件对归属你的 remote 详情页调用：
+
+```
+loadMicroApp({
+  name: "<yourAppCode>@detailhost-<uniqueId>",   // 唯一实例名，与路由保活实例(name=appCode)隔离
+  entry: "<注册表里你的 entry>",
+  container: <弹框内的独立容器 div>,
+  props: { …见第 2 节… }
+})
+```
+
+与既有「路由驱动整站装载」是**两条独立通道**：整站装载走 `#/micro/<appCode>/...` 路由 + 保活；详情承载是弹框内的一次性实例，关框即 `unmount`。二者可能**同一个 appCode 同时存在多个实例**（一个保活整站 + 若干详情弹框）。
+
+## 2. 你会收到的 props
+
+| prop | 类型 | 含义 |
+|---|---|---|
+| `microDetailHost` | `true` | **模式标志**：为 `true` 时进入「详情承载」分支，**不要**渲染整站壳（无侧边栏/页签/登录/URL 读写） |
+| `appCode` | string | 你的 appCode |
+| `targetPath` | string | 已剥掉 `/micro/<appCode>` 的**子应用内路径**（如 `/user/bill/edit` 或 `/base/user/x`） |
+| `bizParams` | object | 业务字段整包：`objTypeCode`/`formCode`/`dataId`/`_dataId`/`objId`/`param`/`queryParam` 等，**展开**绑给详情页 |
+| `viewMeta` | object | 承载元数据：`{ visibleKey, defaultShowWfContent, viewType }`，按需绑给详情页 |
+| `initialOutParam` | any | `outParam` 初值（对应旧 `:outParam.sync` 的入向） |
+| `token` | string | 主应用当前 token——**必须写入你的鉴权态**，否则详情页内接口 401 |
+| `lang` | string | 当前语言——设置你的 i18n locale |
+| `onReload` | function | 上行回调，见第 4 节 |
+| `onHandleCallback` | function | 同上 |
+| `onClose` | function | 同上 |
+| `onUpdateOutParam` | function | 同上 |
+| `onEmit` | function | 同上 |
+
+> 字段与函数名的权威来源：`src/components/micro-view-host/contract.js`（`DETAIL_HOST_MODE`、`DETAIL_HOST_CALLBACKS`、`buildDetailHostProps`）。**函数能直接传**是因为 `loadMicroApp` 的 props 与你同一个 JS realm——直接调用即可，无需事件总线。
+
+## 3. mount 里要做的事
+
+> **引包应用（`main.js` 为 `export * from "cloud-web-corejs/src/index"`）此分支已由 corejs 内置**——corejs `src/index.js` 的 `mount()` 已实现 `if (props.microDetailHost) return mountDetailHost(props)`，你**无需重写**，升级到含该实现的 corejs 版本即可。本节仅供：① 自定义了 `mount`（未纯 re-export corejs）的应用；② 异构技术栈子应用。引包应用只需过一遍第 6 节验收（尤其确认自己的私有详情页在承载态下行为正常）。
+
+```
+export async function mount(props) {
+  if (props.microDetailHost) {
+    return mountDetailHost(props);   // ← 详情承载分支（corejs 已内置）
+  }
+  return mountFullSite(props);       // ← 既有整站分支（不变）
+}
+```
+
+`mountDetailHost(props)` 需：
+
+1. **同步鉴权与语言**：用 `props.token` 写入你的 token 存储（`setToken`），`props.lang` 设 i18n locale——详情页里的接口/文案依赖它。
+2. **解析目标组件**：用 `props.targetPath` 解析出你 bundle 内的组件。可直接复用包内 helper：
+   `(await loadViewComponentAsync(props.targetPath, { appCode: props.appCode })).component`
+   （旧同步 `loadViewComponent` 已废弃并会抛错；必须等待异步解析完成后再渲染。）
+   （`targetPath` 无 `/micro/` 前缀，会解析成你的 `@/views` 或包内 `@base/views`。）
+3. **渲染**：在 `container` 里 new 一个**独立 Vue 实例**（**router 建议用 memory 模式或不建 router**，绝不读写浏览器 URL），把组件渲染出来，绑定：
+   - `v-bind="props.bizParams"`（展开业务字段）
+   - `viewMeta` 里的 `visibleKey`/`defaultShowWfContent`/`viewType`（按详情页原有 prop 名）
+   - `:outParam` 初值 = `props.initialOutParam`
+   - 注入 **parentVue shim**（第 4 节）
+4. **保存实例句柄**，供 `unmount` 用。
+
+`unmount(props)` 需销毁该 Vue 实例、清空容器。**支持并发多实例**：每次 `mount` 用各自的容器与实例，不共享会互相踩的全局单例。
+
+## 4. parentVue shim（关键，决定详情页不用重写）
+
+现存详情页靠 `getTarget(this)` 走 `$parent` 链、`parentVue.$baseReload()`、`_handleCallback(flag)`、`this.$emit(...)`、`:outParam.sync` 与父级通信。跨应用后这些够不到主应用。**做法：合成一个 shim 对象注入给详情页，让它落在 `getTarget/parentVue` 能命中的位置，方法转调 props 回调**：
+
+| 详情页里的调用 | shim 转调 |
+|---|---|
+| `parentVue.$baseReload()` / `getTarget(this).$baseReload()` | `props.onReload()` |
+| `this.$emit(name, ...args)`（父级 `v-on="listeners"` 那批） | `props.onEmit(name, ...args)` |
+| `_handleCallback(flag)`（flag ∈ 1..4） | `props.onHandleCallback(flag)` |
+| 关闭当前弹框 / `window.close` / `window.opener` 语义 | `props.onClose()` |
+| `outParam` 变化（旧 `.sync` 出向） | `props.onUpdateOutParam(v)` |
+
+主应用侧 `micro-view-host` 已把这些 props 回调对应 emit 成 `@reload`/`@handle-callback`/`@close`/`@update-out-param`/`@bridge-emit`，主应用弹框据此接回原有 handler。**你只需保证详情页调到 shim。**
+
+> 详情页侧的最小改造（若无法完全靠 shim 落位）：① `getTarget(this)` 能命中 shim；② 承载态短路 `window.opener` 直连，改走 `onClose`/`onEmit`。见方案 §5.6。
+
+## 5. 不要做的事
+
+- ❌ 渲染整站壳（侧边栏 / 页签 / 登录页）——`microDetailHost` 模式只出详情页本身。
+- ❌ 读写浏览器 URL / hash——详情承载不是导航；用 memory 路由或无路由。
+- ❌ 依赖全局单例（同一个 store/router 实例被多个详情弹框共享）——必须容忍并发多实例。
+- ❌ 直接摸主应用 router / DOM——跨应用只走 props 回调。
+
+## 6. 验收清单（联调时逐条过）
+
+- [ ] `props.microDetailHost` 为真时只渲染详情页，无整站壳、无 URL 变化。
+- [ ] `targetPath` 能正确解析到目标组件（`/base/...` → 包内；`/user/...` → 你的私有页）。
+- [ ] 详情页内接口带上 `props.token`、文案按 `props.lang`。
+- [ ] `bizParams`/`viewMeta`/`initialOutParam` 正确绑到详情页（对照旧弹框 `v-bind="param"` 等）。
+- [ ] 详情页「提交/驳回/…」触发 `onHandleCallback(flag)`，主应用弹框收到 `@handle-callback` 并按 flag 关框/刷新。
+- [ ] 详情页刷新触发 `onReload`；关闭触发 `onClose`；`outParam` 变化触发 `onUpdateOutParam`。
+- [ ] 同一 appCode **同时**开着「整站保活实例」+「≥2 个详情弹框实例」互不串扰。
+- [ ] 关框 `unmount` 后容器清空、无内存/监听泄漏，可重复开关。
+
+## 7. 参考
+
+- 主应用侧宿主实现：`src/components/micro-view-host/index.vue` + `contract.js`。
+- 归属/组件路径解析：`src/utils/menuAdapter.js`、`src/utils/resolveViewComponent.js`。
+- 整体方案与逐处站点：`docs/qiankun动态详情页承载方案.md`。

package/package.json

@@ -1,10 +1,21 @@
 {
   "name": "cloud-web-corejs",
   "private": false,
-  "version": "1.1.0-dev.6",
+  "version": "1.1.0-dev.61",
   "scripts": {
+    "build:ace-resources": "node build/build-ace-resources.js",
+    "build:tinymce-resources": "node build/build-tinymce-resources.js",
+    "build:luckysheet-resources": "node build/build-luckysheet-resources.js",
+    "build:activiti-resources": "node build/build-activiti-resources.js",
+    "check:resource-tools": "node --test tests/resources/*.test.js",
+    "check:package-size": "node build/check-package-size.js",
+    "create:child": "node bin/create-child-app.js",
+    "check:child-app": "node build/check-child-app.js",
+    "check:child-browser": "node build/check-child-browser.js",
     "dev": "vue-cli-service serve",
     "dev:micro": "vue-cli-service serve --port 17527",
+    "check:package-resources": "node build/check-package-resources.js",
+    "check:minimal-consumer": "node build/check-minimal-consumer-build.js",
     "lint": "eslint --ext .js,.vue src",
     "build:prod": "vue-cli-service build",
     "build:stage": "vue-cli-service build --mode staging",
@@ -13,7 +24,7 @@
     "new": "plop",
     "svgo": "svgo -f src/icons/svg --config=src/icons/svgo.yml",
     "test:unit": "jest --clearCache && vue-cli-service test:unit",
-    "test:ci": "npm run lint && npm run test:unit",
+    "test:ci": "npm run check:resource-tools && npm run check:package-resources && npm run check:package-size && npm run check:minimal-consumer && npm run lint && npm run test:unit",
     "updateCorejs": "npm install cloud-web-corejs --registry https://registry.npmjs.org",
     "publishDev": "npm publish --tag dev"
   },
@@ -123,6 +134,13 @@
     "npm": ">= 3.0.0"
   },
   "files": [
+    "bin/core-resources.js",
+    "resource-tools",
+    "bin/create-child-app.js",
+    "templates/child-app",
+    "docs/child-app",
+    "docs/qiankun接入协议.md",
+    "docs/qiankun详情承载子应用对接清单.md",
     "src/components/advancedSearchDialog",
     "src/components/baseAlert",
     "src/components/baseAttachment",
@@ -175,7 +193,6 @@
     "src/components/bizTab",
     "src/api",
     "src/views/bd",
-    "src/views/demo",
     "src/views/support",
     "src/views/user",
     "src/views/mobile/user",
@@ -183,7 +200,9 @@
     "src/mixins",
     "src/directive",
     "src/store",
-    "src/resources/js",
+    "src/core-resources",
+    "src/styles",
+    "src/icons",
     "src/lang/index.js",
     "src/lang/locale/en/login.js",
     "src/lang/locale/zh/login.js",
@@ -192,6 +211,12 @@
     "src/router",
     "src/permission.js",
     "src/index.js",
+    "src/index.next.js",
+    "src/index.sync.js",
+    "src/boot-assets.legacy.js",
+    "src/boot-assets.next.js",
+    "src/app-bootstrap.js",
+    "src/app-bootstrap.sync.js",
     "src/public-path.js",
     "src/microRouter",
     "src/App.vue"

package/resource-tools/index.js

@@ -0,0 +1,126 @@
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+const hash = data => crypto.createHash("sha256").update(data).digest("hex");
+const fail = message => { throw new Error(`[core-resources] ${message}`); };
+function safePath(root, relative) {
+  if (typeof relative !== "string" || !relative || relative.includes("\\") ||
+      relative.split("/").some(p => !p || p === "." || p === "..") || path.isAbsolute(relative)) {
+    fail(`Unsafe path: ${relative}`);
+  }
+  const full = path.join(root, relative);
+  // Reject symlinks in every existing ancestor, including the destination root.
+  for (let current = full; ; current = path.dirname(current)) {
+    if (fs.existsSync(current) || (() => { try { return fs.lstatSync(current).isSymbolicLink(); } catch (_) { return false; } })()) {
+      if (fs.lstatSync(current).isSymbolicLink()) fail(`Symlink: ${current}`);
+    }
+    if (path.dirname(current) === current) break;
+  }
+  return full;
+}
+function readChecked(root, record, key = "file") {
+  const full = safePath(root, record[key]);
+  if (!fs.existsSync(full) || !fs.statSync(full).isFile()) fail(`Missing file: ${full}`);
+  const data = fs.readFileSync(full);
+  if (data.length !== record.size || hash(data) !== record.sha256) fail(`Integrity mismatch: ${full}`);
+  return data;
+}
+function assertExactTree(root, expected) {
+  const found = [];
+  function walk(directory, prefix = "") {
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      const relative = prefix + entry.name;
+      const full = safePath(root, relative);
+      if (entry.isDirectory()) walk(full, relative + "/");
+      else if (entry.isFile()) found.push(relative);
+      else fail(`Unsupported generated entry: ${relative}`);
+    }
+  }
+  walk(root);
+  if (JSON.stringify(found.sort()) !== JSON.stringify([...expected].sort())) fail(`Unexpected generated files: ${root}`);
+}
+function plan(root) {
+  const configPath = path.join(root, "core-resources.config.js");
+  delete require.cache[configPath];
+  const config = require(configPath);
+  if (config.schemaVersion !== 1) fail("Unsupported config schemaVersion");
+  const runtime = { schemaVersion: 1, features: {} };
+  const records = [];
+  for (const [feature, option] of Object.entries(config.features || {})) {
+    if (!["codeEditor", "richText", "spreadsheet", "workflowDesigner"].includes(feature)) fail(`Unknown feature: ${feature}`);
+    if (option === false) continue;
+    const upstreamVersions = { codeEditor: "1.11.0", richText: "4.9.2", spreadsheet: "2.1.13", workflowDesigner: "5.17.0" };
+    if (!option || typeof option !== "object" || !option.package || !option.version) fail(`${feature}: package/version/profile required`);
+    const packageRoot = path.dirname(require.resolve(`${option.package}/package.json`, { paths: [root] }));
+    const pkg = JSON.parse(fs.readFileSync(safePath(packageRoot, "package.json")));
+    const manifest = JSON.parse(fs.readFileSync(safePath(packageRoot, "resources.json")));
+    const coreVersion = require("../package.json").version;
+    if (pkg.version !== option.version || manifest.version !== option.version || manifest.schemaVersion !== 1 ||
+        manifest.feature !== feature || manifest.compatibleCore !== coreVersion || manifest.upstreamVersion !== upstreamVersions[feature]) {
+      fail(`${feature}: incompatible artifact, expected exact version ${option.version} / Core ${coreVersion}`);
+    }
+    const profile = manifest.profiles[option.profile];
+    if (!profile) fail(`${feature}: unknown profile ${option.profile}`);
+    safePath(root, manifest.basePath.replace(/\/$/, ""));
+    runtime.features[feature] = { version: option.version, profile: option.profile, modes: profile.modes, locales: profile.locales, basePath: manifest.basePath };
+    const featureStart = records.length;
+    for (const record of manifest.files) {
+      // Validate even unselected records, so malformed manifests never pass silently.
+      safePath(packageRoot, record.file);
+      safePath(root, record.target);
+      if (!record.profiles.includes(option.profile)) continue;
+      if (records.some(r => r.target === record.target)) fail(`Duplicate target: ${record.target}`);
+      const appPath = safePath(path.join(root, "public"), record.target);
+      if (fs.existsSync(appPath)) fail(`Application public collision: ${record.target}`);
+      records.push({ ...record, data: readChecked(packageRoot, record) });
+    }
+    if (records.length === featureStart) fail(`${feature}: empty artifact`);
+  }
+  const snapshot = { runtime, files: records.map(({ target, size, sha256 }) => ({ target, size, sha256 })) };
+  return { runtime, records, snapshot, id: hash(JSON.stringify(snapshot)) };
+}
+function prepare(root, checkOnly = false) {
+  root = path.resolve(root);
+  const result = plan(root);
+  const generations = safePath(root, ".core-resources/generations");
+  const destination = safePath(generations, result.id);
+  if (!fs.existsSync(destination)) {
+    if (checkOnly) fail("Resources not prepared; run resources:prepare");
+    fs.mkdirSync(generations, { recursive: true });
+    const staging = fs.mkdtempSync(path.join(generations, ".stage-"));
+    fs.mkdirSync(path.join(staging, "public"));
+    for (const record of result.records) {
+      const target = safePath(path.join(staging, "public"), record.target);
+      fs.mkdirSync(path.dirname(target), { recursive: true });
+      fs.writeFileSync(target, record.data, { flag: "wx" });
+    }
+    fs.writeFileSync(path.join(staging, "ownership.json"), JSON.stringify(result.snapshot));
+    fs.renameSync(staging, destination);
+  }
+  const ownership = safePath(destination, "ownership.json");
+  if (fs.readFileSync(ownership, "utf8") !== JSON.stringify(result.snapshot)) fail(`Modified ownership: ${destination}`);
+  const directory = safePath(destination, "public");
+  assertExactTree(destination, ["ownership.json", ...result.records.map(r => "public/" + r.target)]);
+  for (const record of result.records) readChecked(directory, record, "target");
+  return { ...result, directory };
+}
+class ResourcesPlugin {
+  constructor(root) { this.root = root; }
+  apply(compiler) {
+    const prepared = prepare(this.root, true);
+    new compiler.webpack.DefinePlugin({ __CORE_RESOURCES__: JSON.stringify(prepared.runtime) }).apply(compiler);
+    compiler.hooks.thisCompilation.tap("CoreResources", compilation => {
+      compilation.hooks.processAssets.tap({ name: "CoreResources", stage: compiler.webpack.Compilation.PROCESS_ASSETS_STAGE_ADDITIONS }, () => {
+        const current = prepare(this.root, true);
+        if (current.id !== prepared.id) fail("Configuration changed; restart dev/build");
+        for (const record of current.records) {
+          if (compilation.getAsset(record.target)) fail(`Build asset collision: ${record.target}`);
+          // Vendor artifacts are already minified and hash-locked. Terser must
+          // not rewrite them (or extract license comments into another file).
+          compilation.emitAsset(record.target, new compiler.webpack.sources.RawSource(record.data), { minimized: true });
+        }
+      });
+    });
+  }
+}
+module.exports = { prepare, plan, safePath, readChecked, ResourcesPlugin };