微前端工程化治理方案（评审稿）

文档版本：v1.0
文档状态：评审中
作者：yaowb
日期：2026-02-25
适用范围：主应用 + 所有 Wujie 子应用（含后续新增子应用）

---

1. 背景与问题定义

当前父子应用改造已取得阶段成果（基础接入、路由同步、刷新恢复、预取优化），但从规模化协作视角，仍存在以下结构性问题：

1. 重复实现多：多个子应用重复维护入口生命周期、通信桥接、路由恢复、缓存清理等逻辑。
2. 公共资产分散：类型、工具、hooks、API 适配层存在“局部共享 + 局部复制”，升级成本高。
3. 质量防线偏人工：缺少体系化质量门禁与架构约束自动化，代码质量依赖 reviewer 经验。
4. 可观测性不足：白屏、慢切换、路由恢复失败等体验问题缺少统一量化指标。
5. 组织机制未平台化：跨团队协作、架构决策、技术债治理缺少固定机制。

上述问题会带来如下影响：

• 新子应用接入周期偏长，且质量不稳定。
• 同类问题在不同子应用重复出现，修复成本线性上升。
• 架构演进缺乏统一抓手，团队效率和稳定性提升受限。

---

2. 治理目标与成功标准

2.1 总体目标

围绕“平台化 + 标准化 + 自动化 + 度量化”，建立可复制的前端工程化治理体系，实现：

1. 新子应用低成本、低风险接入。
2. 主子应用通信、路由、缓存行为一致。
3. 质量风险前移到 CI 阶段自动阻断。
4. 体验问题可量化、可追踪、可持续优化。

2.2 成功标准（建议评审通过后纳入季度 OKR）

1. 重复代码治理：子应用入口重复逻辑行数下降 ≥ 70%。
2. 接入效率：新子应用从初始化到可运行时间 ≤ 1 人日。
3. 稳定性指标：深链刷新恢复成功率 ≥ 99.9%。
4. 性能指标：子应用切换 P95 耗时 < 1.5s。
5. 质量指标：核心模块缺陷逃逸率季度下降 ≥ 40%。

---

3. 设计原则

1. Golden Path（黄金路径）优先：提供默认正确做法，降低个体决策成本。
2. 平台抽象优先于业务复制：重复出现 2 次以上的跨应用逻辑进入平台层。
3. Policy as Code：架构规范尽量自动化落地，避免纯文档约束。
4. 可回滚、可渐进：每一阶段可独立交付、可验证、可回滚。
5. 度量驱动改进：所有治理工作必须绑定指标，不做“感受式优化”。

---

4. 治理范围与边界

4.1 本次治理范围

1. 子应用运行时能力统一（生命周期、路由恢复、通信、预取、缓存清理）。
2. 公共资源工程化（types / utils / hooks / api-client / ui）。
3. CI 质量门禁与架构规则自动校验。
4. 前端可观测性与体验 SLO 体系。
5. 组织协作机制（RFC、架构评审、技术债预算）。

4.2 非本次治理范围

1. 一次性重构所有存量业务页面。
2. 一次性统一全部历史技术栈版本。
3. 一次性替换所有业务域模型与接口协议。

---

5. 目标治理架构

5.1 平台层能力布局

建议形成如下基础包矩阵：

1. @cmclink/micro-runtime：子应用运行时 SDK（生命周期、路由恢复、bus 同步、预取、缓存联动）。
2. @cmclink/micro-bridge：事件协议与跨应用通信类型定义。
3. @cmclink/types：跨应用共享领域类型、事件类型、接口 DTO。
4. @cmclink/api-client：基于 OpenAPI 生成 client + 类型。
5. @cmclink/ui：Design Token + 基础组件规范。

5.2 目标交付形态

1. 标准模板：create-cmclink-child-app 脚手架。
2. 标准入口：统一 main.ts 接入模式（可配置化）。
3. 标准协议：事件常量与 payload 类型单一来源。
4. 标准流水线：质量门禁 + 架构扫描 + E2E 冒烟。
5. 标准看板：性能、稳定性、质量周报自动生成。

---

6. 重点工作包（5 大方向）

6.1 工作包 A：建设前端平台层（减少重复代码）

A.1 建设内容

1. 提供 bootstrapChildApp(config)：
   • 封装 __WUJIE_MOUNT / __WUJIE_UNMOUNT / __WUJIE.mount()
   • shared 数据注入
   • 路由恢复（含多级回退）
   • bus 事件接入与注销
2. 提供可选能力开关：
   • enableRouteRecover
   • enableRoutePrefetch
   • enableKeepAliveSync
3. 提供默认约定（Convention over Configuration）：
   • APP_NAME、APP_ID、LAST_ROUTE_KEY 命名规范

A.2 预期收益

• 子应用入口样板代码显著减少。
• 同类问题（白屏、路由不一致）集中治理，减少重复踩坑。

A.3 交付物

1. packages/micro-runtime 包
2. 接入模板仓库
3. 迁移指南与 FAQ

---

6.2 工作包 B：公共资源工程化治理

B.1 建设内容

1. 公共资源分层迁移（参考《公共基础资源迁移方案》）：
   • 类型统一到 @cmclink/types
   • 通用工具统一到 @cmclink/utils
   • 通用 hooks 统一到 @cmclink/hooks
2. 建设 API 代码生成链路：
   • OpenAPI -> TS 类型 -> API Client
3. 建立 Design Token 规范：
   • 色板、间距、字号、状态色、阴影、圆角等

B.2 预期收益

• 降低跨应用升级与修复成本。
• 保证跨团队代码语义与风格一致。

B.3 交付物

1. 公共包迁移清单与完成率看板
2. OpenAPI 生成脚本及 CI 校验
3. 设计系统规范文档与组件资产清单

---

6.3 工作包 C：质量体系与门禁自动化

C.1 建设内容

1. 质量门禁分层：
   • 必过门禁：lint + typecheck（按变更范围）+ unit + build
   • 核心链路门禁：E2E 冒烟（深链刷新、主子路由同步、标签缓存清理）
2. 架构规则自动化：
   • 禁用旧桥接 API 扫描（utils/microApp / utils/iframe-bridge）
   • 挂载点一致性扫描（APP_ID vs index.html）
   • 事件名硬编码扫描（强制从协议常量导入）
3. CODEOWNERS + 评审清单：
   • 平台层与关键基础模块强制架构 owner 审核

C.2 预期收益

• 将“经验问题”转化为“规则问题”，提高可复制性。
• 降低线上回归概率，减少人工巡检成本。

C.3 交付物

1. CI Pipeline 质量门禁配置
2. 架构扫描脚本
3. 评审检查清单（PR 模板）

---

6.4 工作包 D：可观测性与体验 SLO

D.1 建设内容

1. 统一埋点标准：
   • 子应用 mount 耗时
   • 首屏可交互时间（TTI）
   • 路由恢复来源命中率（iframe/mainRoute/session）
2. 错误分级告警：
   • 路由恢复失败
   • matched=0
   • chunk 预取失败
   • bus 通信超时
3. 建立 SLO/SLI：
   • 切换耗时 P95 < 1.5s
   • 深链恢复成功率 > 99.9%

D.2 预期收益

• 白屏与慢切换问题可量化闭环。
• 通过趋势看板驱动迭代优先级。

D.3 交付物

1. 埋点规范与 SDK 封装
2. 告警规则与分级响应机制
3. 周度体验质量看板

---

6.5 工作包 E：组织机制与工程文化

E.1 建设内容

1. 架构委员会（Guild）机制：
   • 双周架构例会
   • 跨应用重大变更 RFC 审议
2. 分级能力认证：
   • L1：可完成子应用标准接入
   • L2：可处理跨应用治理改造
   • L3：可维护平台层能力
3. 技术债预算制度：
   • 每迭代固定 15%~20% 容量用于治理

E.2 预期收益

• 架构决策透明化与可追溯。
• 团队质量能力从“个体英雄”转向“组织能力”。

E.3 交付物

1. RFC 模板 + ADR 归档机制
2. 技术债台账与清理节奏
3. 团队能力地图与培训计划

---

7. 分阶段推进计划（90 天）

7.1 Phase 1（0~30 天）：止血与标准化起步

目标

建立最低可用治理闭环，优先消除高频风险。

关键任务

1. 发布统一事件协议（事件名、payload、版本）
2. 上线旧桥接扫描规则
3. 上线挂载点一致性扫描
4. 建立核心 E2E 冒烟用例

验收标准

1. 新增 PR 100% 通过架构扫描
2. 核心路径 E2E 覆盖率达到约定阈值

7.2 Phase 2（30~60 天）：平台化落地

目标

将高重复逻辑沉淀为平台能力并在存量子应用验证。

关键任务

1. 发布 @cmclink/micro-runtime v1
2. 至少 2 个子应用迁移到 runtime 标准接入
3. 发布子应用脚手架模板

验收标准

1. 迁移应用入口重复代码下降 ≥ 70%
2. 新子应用初始化到可运行 ≤ 1 人日

7.3 Phase 3（60~90 天）：提效与度量

目标

补齐 API 工程化、可观测与治理看板，形成持续改进机制。

关键任务

1. 接入 OpenAPI 生成链路
2. 建立前端体验与稳定性看板
3. 发布季度工程质量评分卡

验收标准

1. 关键接口类型覆盖率显著提升
2. 切换性能与恢复成功率达到 SLO 目标

---

8. 度量指标体系（建议纳入评审附件）

8.1 交付效率指标

1. 子应用接入周期（人日）
2. 平均 PR 合并周期（小时）
3. 平台能力复用率（接入项目数 / 总项目数）

8.2 质量稳定性指标

1. 线上缺陷逃逸率
2. 回归缺陷重复率
3. 架构扫描违规数（周）

8.3 体验性能指标

1. 子应用切换耗时（P50/P95）
2. 深链刷新恢复成功率
3. 首屏可交互时间（TTI）

---

9. 风险识别与应对

风险	表现	应对策略	责任角色
平台能力推进慢	各应用仍各自实现	强制新项目走黄金路径	前端架构组
存量改造阻力大	业务担心影响交付	渐进迁移 + 双轨运行 + 可回滚	业务团队 + 架构组
规则过严影响效率	PR 阻塞变多	分级门禁 + 豁免审批机制	工程效能组
指标不可用	数据缺失或口径不一	先统一埋点协议再上看板	监控平台负责人

---

10. 资源投入建议

10.1 角色建议

1. 架构 Owner（1 名）
2. 平台研发（2 名）
3. 各业务线对接人（每线 1 名）
4. QA 自动化（1 名）

10.2 迭代容量建议

1. 每迭代固定 15%~20% 容量用于治理。
2. 平台层版本升级采取“月度窗口 + 灰度发布”策略。

---

11. 与现有文档的关系

1. 本文档为治理总纲，面向评审与决策。
2. 迁移细节参考：docs/architecture/子应用迁移详细设计（Wujie适配）.md
3. 公共资源拆分参考：docs/公共基础资源迁移方案.md

---

12. 评审结论建议项

评审会上建议明确以下决策项：

1. 是否同意以 @cmclink/micro-runtime 作为子应用标准接入层。
2. 是否同意在 CI 强制启用旧桥接扫描与挂载点校验。
3. 是否同意将 SLO（切换耗时、刷新恢复成功率）纳入季度考核。
4. 是否同意按 90 天计划推进并设置阶段验收门。

---

附录 A：评审检查清单

• 目标是否清晰、可量化
• 范围边界是否明确
• 分阶段计划是否可执行
• 资源投入是否匹配
• 风险与回滚方案是否完整
• 指标口径是否可采集、可验证