@fulgurjs/federation 5.9.2 → 6.0.0

package/docs//346/262/231/347/256/261/350/276/271/347/225/214/345/256/241/350/256/241.md

@@ -1,45 +0,0 @@
-# 沙箱边界审计（CSS / 全局变量 / 公共依赖）
-
-> 日期 2026-09-16 ｜ 实测脚本 `e2e/sandbox-audit.mjs`、`e2e/sandbox-audit2.mjs` ｜ 环境 dev（admin+bpm+lowcode 三应用联邦）
-
-## 结论
-
-**联邦没有沙箱，也不需要沙箱**——这是与 qiankun 的根本架构差异。qiankun 用 JS Proxy 假 window + 样式隔离做「隔离共存」；@fulgurjs/federation（与 webpack MF 一致）做「**同 realm 共存 + 依赖级隔离**」：所有联邦模块与宿主跑在同一个 window/同一个 CSSOM 里，靠**共享依赖单例协商**防止最大的互扰源（双 Vue 运行时），而不是靠沙箱隔开。
-
-## 实测数据（admin 宿主 + bpm + lowcode 联邦加载前后对比）
-
-### 1. 全局变量（window）
-
-- 联邦加载前后 window 新增键**仅 17 个**，且全部可解释：
-  - `mainAppProps`/`mainRouter`：宿主→子应用的桥接对象（对齐乾坤 mainAppProps 语义，by design）
-  - `__VUE_I18N_*`/`__INTLIFY_*` 5 个：vue-i18n 的编译期 feature flags（库本身行为）
-  - `Prism`/`Sortable`：lowcode 设计器引入的第三方库全局
-  - `exports`/`fs`/`stream`/`util`/`chokidar` 等：lowcode 某设计器依赖把 Node 风格 CJS 包装漏到 window（**原版乾坤下同样存在**，属子应用依赖自身的脏行为，与联邦无关）
-- 联邦运行时唯一注册面：`window.__FULGURJS_SCOPE__`（值 `['default']`）与 `__FULGURJS_INFO__`——无全局散落
-- **未发现子应用覆盖宿主关键全局**
-
-### 2. CSS
-
-- 样式表数量：登录后基线 249 → 联邦加载后 470（+221，子应用页面样式按需注入，**expose chunk 的 CSS 自动加载**，fixtures B-17 用例覆盖）
-- `:root --el-color-primary` 基线与加载后均为 `#409eff`——admin(element-plus 2.14.3)/bpm(2.9.1)/lowcode(2.10.2) **三版本 element-plus CSS 共存**，主色变量未被破坏
-- 风格主战场：Vue SFC scoped 样式（data-v hash）天然隔离；组件库 CSS 类名前缀（.el-/.avue-/.vxe-）天然分区
-- **已知理论边界**：多版本组件库 CSS 同挂 `:root` 变量，后加载覆盖先加载——当前三版本变量值一致故无实际影响；若未来某版本改了变量默认值，以「最后加载为准」，这是同 realm CSSOM 的固有权衡（webpack MF 同样如此）
-
-### 3. 公共方法/依赖实例
-
-| 类别 | 机制 | 实测证据 |
-|------|------|---------|
-| **shared 键**（vue/pinia/vue-router） | loadShare 协商单例，"已加载优先" | 联邦页面组件与宿主同为一份 Vue（双 Vue 曾致 'ce' 崩溃，修复后全站 0 报错即为单例实证）；pinia/vue-router singleton 冲突警告显示协商发生且取宿主实例 |
-| **非 shared 依赖**（lodash-es、axios、avue…） | 各子应用自带副本，模块作用域隔离 | 互不干扰；缺点是体积冗余（联邦的固有权衡） |
-| **子应用全局注册**（全局组件/指令/字典） | federatedBoot **显式**注册进宿主 app 实例，失败显式报错（H3） | lowcode 组件数 335→686 的注册面清晰可见 |
-
-## 三、给你的心智模型
-
-| 维度 | qiankun | @fulgurjs/federation |
-|------|---------|--------------------|
-| JS 运行环境 | Proxy 假 window 沙箱 | **同一 window，无沙箱** |
-| CSS | 可选严格隔离/重写 scoped | **同一 CSSOM，无隔离**（靠 scoped 样式+类名前缀+依赖版本对齐） |
-| 公共依赖 | 子应用各自打包（或 externals） | **shared 单例协商**（更强：运行时版本协商+双版本共存） |
-| 适用代价 | 隔离带来适配成本（全局桥、样式穿透、性能损耗） | 无沙箱要求依赖收敛（本案例已全量验证） |
-
-**一句话**：联邦不做"防你犯错的隔离"，做"让你们共享一切的编排"。全局变量要按团队约定加前缀；全局样式要 scoped 或带业务前缀；这三条纪律在 testbed 真实工程里已全部落实并实测无互扰。

package/docs//350/277/201/347/247/273/346/214/207/345/215/227.md

@@ -1,179 +0,0 @@
-# 迁移指南：qiankun 微前端 → @fulgurjs/federation
-
-> 本指南以 testbed/mes-zc（admin 宿主 + bpm/lowcode 子应用，21+6 页，真实工程）为案例。
-
-## 一、概念映射
-
-| qiankun | @fulgurjs/federation |
-|---------|--------------------|
-| 主应用 registerMicroApps | 宿主 `federation({ remotes })` |
-| 子应用 entry（HTML） | remote entry（dev: `@fulgurjs-entry.js` 中间件 / prod: `fulgurjs-remoteEntry.js`） |
-| 子应用生命周期 mount/unmount | 页面级 exposes（组件即入口，无生命周期样板）；启动期初始化 = 远程 `federation({ setup })`（setup/onSession，见三C 节） |
-| 主子应用 window 隔离/沙箱 | 无沙箱：同 realm 直渲染（`window.xxx` 全局桥自然可用） |
-| props 传递（qiankun 传参） | 组件 props（路由通道 = params+query 合并；弹窗通道 = 显式 v-bind） |
-| 公共依赖 externals/主应用共享 | `shared`（singleton 协商，"已加载优先"） |
-| `qiankun` 运行时 + single-spa | `@fulgurjs/federation/runtime`（运行时内核 20KB 级，无 single-spa） ；整站级跨框架嵌入（Vue 宿主挂 React 子应用或反向）用 5.3.0 `/bridge` 契约（`defineBridgeApp` ≈ qiankun 的 bootstrap/mount/unmount 生命周期导出，README §8.2）|
-
-应用代码统一从 `@fulgurjs/federation/runtime` 导入。Vite 配置继续从 `@fulgurjs/federation` 导入插件；**接入配置 = 每项目一份 `fulgurjs.config.ts`**（默认导出直接是 `federation()` 选项，vite.config.ts 只需 `import fulgurjsConfig from './fulgurjs.config'` + `federation(fulgurjsConfig)` 一次注册，见 README「每项目一份配置」节）。升级自 3.x 时，将 `virtual:fulgurjs-api` 替换为物理子路径；`remoteSchema` 仍按具名导入，开发态由插件填充，构建态为空清单。
-
-## 二、迁移步骤（真实案例顺序）
-
-1. **子应用装插件 + 每项目一份 fulgurjs.config.ts + exposes**：项目根新建 `fulgurjs.config.ts`（默认导出 `satisfies FederationOptions`），把原菜单路由表逐页映射为 `exposes`（`./pages/bpm/task/todo` 对应路由 `bpm/task/todo`）；vite.config.ts 删除一切 `loadRepoConfig/federationOptionsForApp/父目录配置` 写法，改为导入本项目配置并 `federation(fulgurjsConfig)` 注册一次（4.1.0 聚合配置已在 5.0.0 删除，传入旧形状会得到中文迁移错误）。
-2. **shared 声明**：vue/pinia/vue-router 设 singleton；**不要**把业务库（element-plus/avue/dayjs 等）放 shared——插件会在预构建与构建期自动处理其内部对 shared 键的引用（UMD/CJS-only 依赖支持）。
-3. **宿主装插件 + remotes + 页面数据唯一源**：宿主自己的 `fulgurjs.config.ts` 声明 `remotes` 与 `exposes`，并以具名导出 `hostPages` 提供页面核对数据（与运行时页面真源 `src/fulgurjs/host/pages.data.ts` 同一份数据模块，供 `fulgurjs explain/check-pages`）；菜单 URL 通道由 `resolveFulgurjsPageFromPath` 按路由表解析 spec（`admin/src/fulgurjs/host/pages.ts`）。
-4. **全局环境迁移**：子应用依赖宿主的全局（用户/字典 store、i18n、全局组件、全局样式）→ 在子应用 `federation({ setup })` 声明初始化入口文件：默认导出 `setup(context)` 应用级执行一次（全局组件/样式/locale），可选具名导出 `onSession(context)` 按宿主 sessionKey 去重同步用户/权限/字典（换账号自动重跑）；宿主正常 `loadRemote` 页面即可，**无需手写「loadRemote 启动器并调用」**；失败必须显式报错（H3，MFU-011~014）。
-   > 「expose 一个普通 TS 启动器 + 宿主手动 loadRemote 调用」只是普通 expose 的通用用法（不是插件 API，无去重/重试语义）；初始化请一律用 `setup`/`onSession`。
-5. **路由参数**：页面组件用 `defineProps` 声明参数（id/taskId 等）；宿主路由通道把 params+query 作为 props 传入。
-6. **跨应用弹窗**：原 iframe 嵌子应用页 → `fulgurjsPageComponent(spec)` 直渲染 + props（见 FormDetailsModal）；真外链（数据驱动 URL、AMIS 站点）保留 iframe。
-7. **公共依赖坑**：
-   - 子应用 axios 的响应解包形状要和后端一致（jeecg `{success,result}` vs yudao `{code,data}`）
-   - 子应用全局注册（指令/组件）失败必须显式报错，禁止"忽略继续"
-   - 修改态表单禁用逻辑、页面门控（currentStep 等）保持原版语义
-
-## 三、验收清单（从本案例提炼）
-
-- [ ] 21+ 页双环境（dev 双 server / prod NGINX）路由级渲染一致
-- [ ] 每页写操作闭环（新增/编辑/删除/发布/导出导入/审批）与原版逐项一致
-- [ ] 控制台零报错（21 页 × 2 环境）
-- [ ] 零 iframe（跨应用页面与弹窗；PDF/外链/数据驱动 URL 除外）
-- [ ] 零兜底：联邦不可用显式报错（杀 remote 故障注入）
-- [ ] 装后可用：npm pack → 干净项目 dev+prod（e2e/h7-install-test.sh）
-
-> **目录约定说明**：联邦相关产物统一收在 **`src/fulgurjs/`** 一个文件夹（每个应用一份，内附 README 说明归属）——`types/`（插件每次 dev 自动生成的远程 exposes 类型直连，**勿手改**；运行时类型由包的 `/runtime` 子路径直接解析；无 src 布局回退根目录 `.fulgurjs/types/`）与按角色划分的代码子目录：远程应用为 `exposes/`（供外部加载的组件/方法模块）+ `setup.ts`（`federation({ setup })` 声明的初始化入口），宿主应用为 `host/`（桥接 bridge.ts + 页面数据 pages.data.ts + 装配 pages.ts）。这些均为项目侧手工维护文件——`fulgurjs init` 只生成配置起步模板，不生成、不重建它们；目录可按团队习惯重组，只要配置里的映射与调用点跟着改。
-
-## 三B、首次使用避坑清单（真实迁移踩坑实录，全文见仓库 README「避坑指南」节）
-
-| # | 坑 | 症状 | 解法 |
-|---|-----|------|------|
-| 1 | 插件升级后未清 `.vite` | 页面渲染回旧逻辑 / 门面签名漂移 404 | `rm -rf node_modules/.vite` + 重启 dev + 换浏览器 profile |
-| 2 | pnpm 装 tarball 软链断链 | `Cannot find module '@fulgurjs/federation'` | 重新 `pnpm add -D <tgz>` 并验证目录可达 |
-| 3 | UMD/CJS 依赖被移出预构建 | dev 裸 CJS 白屏、`Cannot destructure property 'node'` | 放回 `optimizeDeps.include`（插件自动外部化 shared 键） |
-| 4 | 给 shared 依赖加 ESM 别名 | 构建期 `xxx.default.extend is not a function` | **build 必删**（prod rollup 双重 interop，2026-09-16 二次定案）；dev 侧若该依赖已移出预构建（如 element-plus），其 CJS 子路径需 dev 专用别名兜住（`command==='serve'` 才注入） |
-| 5 | env 同步脚本回写 | 手改的 `.env.*` 被「还原」 | 改同步脚本的源头（如 `.env.backend`） |
-| 6 | 项目构建自身 env 缺键 | `Cannot read properties of undefined (reading 'split')`（如 VITE_BUILD_COMPRESS） | 按项目构建要求补齐 env 键 |
-| 7 | 登录异步链未完成就断言 | e2e 偶发被弹回登录页 | 等「登录表单消失」而非固定秒数；后台慢链 ≥15s |
-| 8 | 多版本组件库 CSS | 后加载覆盖 `:root` 变量 | 主流版本变量一致则无感；升级时留意 |
-| 9 | 后端缺端点 | 404/401 资源报错 | 代理/NGINX 层加诚实空响应垫片（不伪造业务数据） |
-| 10 | 远程页面（exposes 目标文件）静态导入 `@fulgurjs/federation/runtime` | 直接静态导入 | 插件自动把该导入改写为惰性单例代理——远程页面写法与宿主完全一致（详见下节三B-1） |
-
-### 三B-1、远程页面如何取宿主运行时
-
-exposes 目标文件（被宿主跨源加载的远程页面/组件）**可以直接静态导入**
-`@fulgurjs/federation/runtime`——插件自动把远程页面里的该导入改写为**惰性单例代理**：
-求值期零副作用、调用期转发页面级运行时单例。宿主与远程写法完全一致，无需区分。
-
-```ts
-// 远程页面内，与宿主页面写法完全一致
-import { loadRemote } from '@fulgurjs/federation/runtime'
-```
-
-组件直渲染推荐用 `@fulgurjs/federation/runtime` 子路径的 `remoteComponent`——
-`defineAsyncComponent + loadRemote` 的标准封装，加载失败显式错误占位（错误码+根因+修法），无任何兜底：
-
-```ts
-import { remoteComponent } from '@fulgurjs/federation/runtime'
-const FederatedBusinessForm = remoteComponent('demo-host/FormRouterPage')
-```
-
-`(globalThis as any).__FULGURJS_RUNTIME__` 直取全局单例仅剩"独立访问远程页 vs 联邦加载"的
-realm 检测等特殊场景，常规集成无需使用。
-
-## 三C、跨应用传值：AppContext
-
-原 qiankun `props` / `globalState` / `window.*` 裸口子，统一收编为 context 一等公民通道（对标乾坤 props，带类型与错误契约）：
-
-```ts
-// 宿主桥（admin/src/fulgurjs/host/bridge.ts）——登录态同步（可多次调用，幂等 merge）
-import { provideAppContext, clearAppContext } from '@fulgurjs/federation/runtime'
-provideAppContext({
-  user, getToken, store, hostApp, locale,   // 只传有真实消费的键（token 一律 getToken() 拉取）
-  sessionKey: 's-101-…',              // 非敏感登录代次 ID：每次成功登录/重登生成新值（禁用 token 充当）
-  events: { main: mainEvents },       // 方法池：宿主提供 main.*，子应用反向注册 bpm.* / lowcode.*
-  // 项目扩展位：自定义键按需自行提供（如 baseUrl）
-})
-// 退出登录：clearAppContext()（清 context + 作废远程会话信号/onSession 去重）
-
-// 远程初始化（xxx/src/fulgurjs/setup.ts，经 vite federation({ setup }) 声明）——显式校验消费
-import { requireAppContext } from '@fulgurjs/federation/runtime'
-const { store, user, hostApp } = requireAppContext('store', 'user', 'hostApp')
-// 缺键 → [fulgurjs:CC-001]（三段式，指向宿主桥）；独立直开远程页 → [fulgurjs:CC-002]
-
-// 页面读点（替代 window.mainAppProps?.xxx）
-import { getAppContext } from '@fulgurjs/federation/runtime'
-const dict = getAppContext().events?.main?.getDictItems?.('sex')
-```
-
-要点：
-
-- **时序契约**：bridge（provide）→ 远程 setup/onSession（require）→ 页面模块返回；违反即在初始化处显式失败（CC-001 / MFU-013），无静默；
-- **数据语义**：传输层快照 + 函数引用，非响应式（与乾坤 props 同语义）。"实时"两通道 = ①函数引用拉取（`getToken()` / `events.main.*` 每次执行宿主最新闭包）②宿主 pinia 共享响应式（`useUserStore(ctx.store)`）；**同页换账号不依赖页面刷新**——宿主重新 provide 最新 context + 新 sessionKey，远程 onSession 检测到新代次自动重跑；
-- **嵌套对象（events）是引用共享**：子应用挂属性即时可见（同 realm 直引用）；
-- **方法引用两条通道**：高频热路径（token/字典/文件 URL、反向注册）走 context 函数引用；低频/重逻辑跨应用调用走 exposes 方法模块——远程 `src/fulgurjs/exposes/api.ts` 导出纯函数（不挂 Vue 组件），对面 `await loadRemote('remote/api')`；
-
-## 三D、页面卸载清理清单
-
-乾坤 `unmount` 会强制子应用清理 window 级资源；联邦**组件级**卸载不会自动清——以下资源必须在页面组件 `onUnmounted` 里自行摘除，否则切走再切回会重复注册/重复触发：
-
-| 资源 | 清理方式 |
-|---|---|
-| `context.events.bpm.xxx = fn` 反向注册 | `onUnmounted(() => { delete getAppContext().events?.bpm?.xxx })` |
-| `window.addEventListener(...)` | 记住函数引用，`onUnmounted` 里 `removeEventListener` |
-| `setInterval` / `setTimeout` | `onUnmounted` 里 `clearInterval` / `clearTimeout` |
-| `window.__FULGURJS_INFO__.errors.push(...)` 之外的自挂全局 | 同理显式删除 |
-
-```ts
-import { onUnmounted } from 'vue'
-const onBpmEvent = (e: unknown) => { /* ... */ }
-getAppContext().events!.bpm!.formEvent = onBpmEvent
-onUnmounted(() => {
-  const events = getAppContext().events
-  if (events?.bpm?.formEvent === onBpmEvent) delete events.bpm.formEvent
-})
-```
-
-> 轻量提醒而非插件机制：绝大多数页面只有数据请求（随组件销毁自然结束），无需任何清理；有上述全局副作用的页面按清单逐项过一遍即可。
-
-## 三E、乾坤融合三件套 + 联邦诊断面板（项目侧能力，手工落位）
-
-配置面总览（详细行为与示例见 README §9.1；**均为项目侧文件**——`fulgurjs init` 不生成它们，插件配置面无 `host.prefetch` 字段，旧文档该说法已订正）：
-
-| 能力 | 配置项 | 类型 | 默认值 | 配置位置 |
-|---|---|---|---|---|
-| 页面保活（多 tab 状态保留） | `keepAlive` | `boolean` | `false` | 页面数据条目（`src/fulgurjs/host/pages.data.ts`） |
-| 页面加载骨架屏 | —（内置，无配置项） | — | delay 200ms 的骨架占位 | 页面工厂内置（`pages.ts`） |
-| 空闲预载 | `PREFETCH_REMOTES`（宿主桥常量） | `string[]` | `[]`（关闭整远程预载，按需加载） | `src/fulgurjs/host/bridge.ts` 顶部 |
-| 联邦诊断面板 | —（内置页面） | — | 常驻 | 路由 `/fulgurjs-demo`（prod 为 `/main/fulgurjs-demo`） |
-
-```ts
-// 保活：按页开启（默认全关——重型组件缓存成本高）
-{ route: '/flowable/bpm/task/todo', name: 'BpmTodoTask', title: '待办任务', keepAlive: true }
-
-// 空闲预载三态（bridge.ts）——默认关闭整远程预载（按需加载；四层语义见 README §9.1.3）：
-const PREFETCH_REMOTES: string[] = []                         // 默认：关闭（首访联邦页只下载该页所需）
-const PREFETCH_REMOTES: string[] = ['mes-bpm']                // 显式预热整个远程（下载完整 expose 清单，不执行）
-// 单页预取（推荐：只预取明确下一步页面，低优先级只下载不执行）
-// idle(() => preloadRemote('mes-bpm/pages/bpm/task/todo', { mode: 'prefetch' }))
-```
-
-边界：保活缓存上限 max=8（LRU）；骨架屏 delay 200ms 防闪、失败走内置错误占位（错误码+根因+修法）；预载失败 MFU-007（fulgurjs:error 事件，不阻断业务）；保活页的 window 级监听/定时器按「三D 清理清单」处理。
-
-**IDE 提示**：`src/fulgurjs/types/*.d.ts` 为插件自动生成的跨工程类型直连（勿手改）——VSCode 打开这些生成物时可能显示大片"找不到模块 '@/...'"（Volar 以推断项目检查工程外 .vue 所致），命令行 `vue-tsc --noEmit` 走本应用 tsconfig 为 0 错误，构建不受影响；升级插件后 context 导入报 ts(2307) 时 `Restart TS Server` 清缓存。
-
-## 四、乾坤下线顺序
-
-1. 联邦模式全量验收（本清单）
-2. `QIANKUN_OPEN=false` 固化，保留一个版本周期回滚能力
-3. 删除 qiankun 注册层（admin/src/qiankun/apps.ts 等）与 single-spa 依赖
-4. 子应用可独立部署 ⇄ 宿主消费双形态长期保留
-
-## 五、5.0.0 删除的旧 API 与替代写法
-
-5.0.0 是有意的破坏性清理（插件尚无外部用户时收敛公开面）。旧 API 传入时一律得到中文的「当前值 → 原因 → 迁移写法」错误，不会被静默接受：
-
-| 已删除（5.0.0） | 替代写法 |
-|---|---|
-| `@fulgurjs/federation/config` 子路径（`defineRepoConfig` / `loadRepoConfig` / `federationOptionsForApp` / `RepoConfig` 等聚合类型） | 每个应用根目录一份 `fulgurjs.config.ts`，默认导出直接 `satisfies FederationOptions`；`host.pages`/`remotePrefixes`/`deriveSpec` 改具名导出 `hostPages` |
-| CLI `--app <应用名>`（聚合配置选择器） | 在各应用根目录直接运行 `fulgurjs explain` / `fulgurjs check-pages`；传 `--app` 会报中文错误 |
-| check-pages 旧聚合形态的本地 dist 回退 | `--manifest <远程>=<路径\|URL>` 或 `--site <URL>`（显式来源失败如实报「无法验证」，不假装通过） |
-| `federation()` 选项：`remoteType`、`library`、`automaticAsyncBoundary`、`dataPrefetch`、`usedExports`、`ignoreUnusedSharedExports` | 直接删除该字段：remoteEntry 恒为 ESM、TLA 异步边界恒开、tree-shaking 由打包器原生完成；需要预载时运行时调用 `preloadRemote()`（`/runtime` 导出）。传入任何值（含历史合法值）报 `CFG-011` |
-| 旧「expose 启动器 + 宿主手动调用」初始化范式 | `federation({ setup })`：默认导出 `setup(context)` 应用级一次 + 具名导出 `onSession(context)` 会话级去重 |