前端架构治理演进规划一、背景与目标 1.1 现状分析经过 Phase 1~4 的微前端治理（详见 doc/wujie集

一、背景与目标

1.1 现状分析

经过 Phase 1~4 的微前端治理（详见 doc/wujie集成.md），已完成：

已完成项	成果
微前端框架	iframe → wujie，7 个子应用统一接入
通信协议	postMessage → wujie bus，类型化事件
子应用预加载	preloadChildApps 高/低优先级分级
CSS 统一	UnoCSS → Tailwind CSS 4
Monorepo	pnpm workspace + Turborepo

但微前端只是架构治理的第一步。 当前 7 个子应用之间存在大量重复建设：

重复领域	现状	影响
UI 组件	每个子应用独立封装 Table/Form/Dialog	7 份重复代码，风格不统一
业务组件	客户选择器、产品选择器等各自实现	逻辑不一致，Bug 修一处漏六处
Utils 工具函数	日期格式化、金额计算、权限判断各写一套	维护成本 ×7
Hooks/Composables	useTable、useForm、useDict 各子应用独立	无法共享最佳实践
API 层	接口定义、拦截器、错误处理各自维护	后端改一个字段，前端改 7 处
类型定义	业务实体 TS 类型各子应用独立定义	类型不同步，联调困难

1.2 治理目标

                    ┌─────────────────────────────────┐
                    │        业务应用层（7 个子应用）     │
                    │   mkt / doc / ibs-manage / ...   │
                    └──────────────┬──────────────────┘
                                   │ 消费
                    ┌──────────────┴──────────────────┐
                    │        公共资源层（packages）       │
                    │                                   │
                    │  ┌───────────┐  ┌─────────────┐  │
                    │  │ UI 组件库  │  │ 业务组件库   │  │
                    │  │@cmclink/ui│  │@cmclink/biz  │  │
                    │  └───────────┘  └─────────────┘  │
                    │  ┌───────────┐  ┌─────────────┐  │
                    │  │ Hooks 库  │  │  Utils 库    │  │
                    │  │@cmclink/  │  │@cmclink/     │  │
                    │  │ hooks     │  │ utils        │  │
                    │  └───────────┘  └─────────────┘  │
                    │  ┌───────────┐  ┌─────────────┐  │
                    │  │ API SDK   │  │  类型定义    │  │
                    │  │@cmclink/  │  │@cmclink/     │  │
                    │  │ api       │  │ types        │  │
                    │  └───────────┘  └─────────────┘  │
                    └──────────────┬──────────────────┘
                                   │ 支撑
                    ┌──────────────┴──────────────────┐
                    │        基础设施层                  │
                    │  micro-bridge / vite-config /     │
                    │  tsconfig / eslint-config         │
                    └──────────────────────────────────┘

核心原则：

资源化 — 可复用的代码提取为独立 package
公共化 — 跨子应用共享，单点维护
文档化 — 每个公共包配套使用文档和示例
AI 友好 — 沉淀为 AI Agent 可消费的 Skills/MCP 资源

二、公共资源沉淀规划

2.1 `@cmclink/ui` — 基础 UI 组件库

定位：基于 Element Plus 二次封装的业务通用 UI 组件。

组件	说明	来源
`CmcTable`	统一表格（分页、排序、列配置、导出）	各子应用 useTable + 模板代码
`CmcForm`	统一表单（校验、布局、动态字段）	各子应用表单封装
`CmcDialog`	统一弹窗（确认、表单弹窗、详情弹窗）	各子应用 Dialog 封装
`CmcSearch`	搜索栏（条件组合、折叠展开、快捷搜索）	各子应用搜索区域
`CmcUpload`	文件上传（拖拽、预览、进度、断点续传）	各子应用上传组件
`CmcEditor`	富文本编辑器（统一配置）	各子应用编辑器封装
`CmcDescription`	详情描述列表	各子应用详情页

实施策略：

packages/
└── ui/
    ├── package.json          # @cmclink/ui
    ├── src/
    │   ├── components/       # 组件源码
    │   │   ├── CmcTable/
    │   │   ├── CmcForm/
    │   │   └── ...
    │   ├── composables/      # 组件内部 hooks
    │   └── index.ts          # 统一导出
    └── docs/                 # 组件文档（可选 VitePress）

2.2 `@cmclink/biz` — 业务组件库

定位：与业务强相关的可复用组件，跨产品线共享。

组件	说明	使用方
`CustomerSelector`	客户选择器（搜索、分页、多选）	mkt / doc / commerce-finance
`ProductSelector`	产品选择器	mkt / operation
`PortSelector`	港口选择器	doc / operation
`VesselSelector`	船名航次选择器	doc / operation
`DictSelect`	字典下拉（统一字典管理）	全部子应用
`UserSelector`	用户/员工选择器	全部子应用
`ApprovalFlow`	审批流程组件	多个子应用

2.3 `@cmclink/hooks` — 通用 Composables

定位：跨子应用复用的 Vue 3 组合式函数。

Hook	说明	当前状态
`useTable`	表格数据管理（分页、排序、筛选、刷新）	各子应用独立实现
`useForm`	表单状态管理（校验、提交、重置）	各子应用独立实现
`useDict`	字典数据获取与缓存	各子应用独立实现
`usePermission`	权限判断（按钮级、菜单级）	各子应用独立实现
`useExport`	数据导出（Excel/CSV/PDF）	各子应用独立实现
`useWebSocket`	WebSocket 连接管理	部分子应用实现
`useI18n`	国际化增强（业务术语统一翻译）	各子应用独立实现
`useCrud`	CRUD 操作封装（增删改查一体）	各子应用独立实现

2.4 `@cmclink/utils` — 工具函数库

定位：纯函数工具集，零依赖或仅依赖 lodash-es。

模块	函数示例	说明
`date`	`formatDate`, `diffDays`, `toUTC`	日期处理（统一格式）
`money`	`formatMoney`, `toFixed`, `currencyConvert`	金额计算（精度安全）
`validator`	`isPhone`, `isEmail`, `isTaxNo`	业务校验规则
`formatter`	`formatFileSize`, `formatDuration`	格式化工具
`tree`	`flatToTree`, `treeToFlat`, `findNode`	树结构操作
`auth`	`getToken`, `setToken`, `removeToken`	认证工具
`storage`	`getCache`, `setCache`, `removeCache`	存储封装

2.5 `@cmclink/api` — API SDK

定位：统一的后端接口定义层，前后端类型对齐。

// packages/api/src/modules/customer.ts
import type { Customer, CustomerQuery } from '@cmclink/types'
import { request } from '../request'

/** 客户列表 */
export const getCustomerList = (params: CustomerQuery) =>
  request.get<PageResult<Customer>>('/admin-api/customer/page', { params })

/** 客户详情 */
export const getCustomerDetail = (id: number) =>
  request.get<Customer>(`/admin-api/customer/get?id=${id}`)

价值：

后端改接口 → 只改 @cmclink/api 一处 → 所有子应用自动同步
TypeScript 类型约束 → 编译期发现接口不匹配
可自动生成 → 结合 Swagger/OpenAPI 自动生成 SDK

2.6 `@cmclink/types` — 共享类型定义

定位：业务实体的 TypeScript 类型定义，前后端对齐。

// packages/types/src/customer.ts
export interface Customer {
  id: number
  name: string
  code: string
  contactPerson: string
  phone: string
  email: string
  status: CustomerStatus
  createdAt: string
}

export type CustomerStatus = 'active' | 'inactive' | 'pending'

export interface CustomerQuery {
  name?: string
  code?: string
  status?: CustomerStatus
  pageNo: number
  pageSize: number
}

三、前后端职能对齐

3.1 基础架构团队职责矩阵

职责领域	前端基础架构	后端基础架构	协同点
框架治理	微前端（wujie）、Monorepo	微服务、网关	子应用 ↔ 微服务 1:1 映射
通信协议	wujie bus 事件定义	API 接口规范	事件名 / 接口路径统一命名
类型系统	`@cmclink/types`	Swagger/OpenAPI	自动生成 TS 类型
API 层	`@cmclink/api` SDK	RESTful API 实现	SDK 自动生成
权限体系	前端按钮/菜单权限	后端接口权限	权限码统一定义
国际化	前端翻译资源	后端错误码翻译	翻译 Key 统一管理
监控告警	前端性能/错误上报	后端 APM	全链路 TraceID 打通
CI/CD	前端构建部署	后端构建部署	统一流水线、环境管理

3.2 前后端类型自动同步方案

后端 Swagger/OpenAPI 定义
         │
         ▼
    openapi-typescript / swagger-typescript-api
         │
         ▼
  @cmclink/types（自动生成 TS 类型）
         │
         ▼
  @cmclink/api（自动生成 API SDK）
         │
         ▼
    各子应用直接消费

工具选型：

openapi-typescript：从 OpenAPI 3.0 生成 TypeScript 类型
swagger-typescript-api：从 Swagger 生成完整的 API Client

四、AI 编程能力沉淀

4.1 为什么基础架构要考虑 AI

AI 编程（Copilot、Cursor、Windsurf 等）已成为开发者日常工具。公共资源的质量直接决定 AI 生成代码的质量：

AI 编程痛点	根因	基础架构解法
AI 生成的代码风格不统一	缺乏项目级规范上下文	`.windsurf/rules/` 规范文件
AI 不了解业务组件 API	组件文档缺失或分散	组件库 + JSDoc + 示例
AI 重复造轮子	不知道已有公共函数	`@cmclink/utils` + `@cmclink/hooks`
AI 生成的接口调用不对	不了解后端 API 结构	`@cmclink/api` 类型化 SDK
AI 无法理解项目架构	架构文档不完善	架构决策记录（ADR）

4.2 Agent Skills 沉淀

将项目规范和最佳实践沉淀为 AI Agent 可消费的 Skills：

.windsurf/
├── rules/                    # 已有：27 个专项规范
│   ├── core.mdc
│   ├── vue3-component-standards.mdc
│   ├── typescript-standards.mdc
│   └── ...
├── workflows/                # 工作流定义
│   ├── create-component.md   # 新建组件工作流
│   ├── create-api-module.md  # 新建 API 模块工作流
│   ├── create-page.md        # 新建页面工作流
│   └── migrate-child-app.md  # 子应用迁入工作流
└── skills/                   # AI Skills 定义（规划中）
    ├── cmclink-ui.md         # UI 组件库使用指南
    ├── cmclink-api.md        # API SDK 使用指南
    └── cmclink-patterns.md   # 业务模式最佳实践

Skills 示例 — 新建 CRUD 页面：

---
description: 创建标准 CRUD 页面（列表 + 新增 + 编辑 + 删除）
---

1. 在 `@cmclink/types` 中定义实体类型
2. 在 `@cmclink/api` 中定义接口
3. 使用 `CmcTable` + `CmcSearch` + `CmcForm` 组合
4. 使用 `useCrud` hook 管理状态
5. 使用 `usePermission` 控制按钮权限

4.3 MCP Server 能力规划

MCP（Model Context Protocol） 让 AI Agent 能够直接访问项目资源：

MCP 能力	说明	价值
组件文档查询	AI 查询 `@cmclink/ui` 组件 Props/Slots/Events	生成代码直接使用正确的组件 API
API 接口查询	AI 查询后端接口定义和参数	生成的接口调用代码类型正确
字典数据查询	AI 查询业务字典（状态码、类型码）	生成代码使用正确的枚举值
权限码查询	AI 查询按钮/菜单权限码	生成的权限判断代码准确
代码模板生成	AI 基于模板生成标准化页面	新页面开发效率 ×3

MCP Server 架构：

┌──────────────────────────────────────────────┐
│              AI Agent (Windsurf/Cursor)        │
│                                                │
│  "帮我创建一个客户管理的 CRUD 页面"              │
└──────────────────┬─────────────────────────────┘
                   │ MCP Protocol
┌──────────────────┴─────────────────────────────┐
│            @cmclink/mcp-server                  │
│                                                 │
│  ┌─────────────┐  ┌──────────────────────────┐ │
│  │ 组件文档资源 │  │ API 接口资源              │ │
│  │ (Resources) │  │ (Resources)              │ │
│  └─────────────┘  └──────────────────────────┘ │
│  ┌─────────────┐  ┌──────────────────────────┐ │
│  │ 代码生成工具 │  │ 字典/权限查询工具         │ │
│  │ (Tools)     │  │ (Tools)                  │ │
│  └─────────────┘  └──────────────────────────┘ │
└─────────────────────────────────────────────────┘

五、实施路线图

5.1 短期（1~2 个月）— 基础沉淀

优先级	任务	产出	负责
P0	提取 `@cmclink/utils`	工具函数包	基础架构
P0	提取 `@cmclink/hooks`	通用 Composables 包	基础架构
P0	提取 `@cmclink/types`	共享类型定义包	基础架构 + 后端
P1	完善 `.windsurf/rules/`	AI 规范文件	基础架构
P1	创建 `.windsurf/workflows/`	标准工作流	基础架构

5.2 中期（3~4 个月）— 组件化

优先级	任务	产出	负责
P0	搭建 `@cmclink/ui` 组件库	CmcTable / CmcForm / CmcSearch	基础架构
P0	搭建 `@cmclink/api` SDK	统一 API 调用层	基础架构 + 后端
P1	搭建 `@cmclink/biz` 业务组件库	客户选择器等业务组件	基础架构 + 业务
P1	组件文档站（VitePress）	在线文档 + 示例	基础架构
P2	OpenAPI → TypeScript 自动生成	类型自动同步流水线	基础架构 + 后端

5.3 长期（5~6 个月）— AI 赋能

优先级	任务	产出	负责
P1	`@cmclink/mcp-server`	AI Agent 资源服务	基础架构
P1	AI Skills 沉淀	组件/API/模式使用指南	基础架构
P2	代码模板生成器	标准化页面脚手架	基础架构
P2	全链路 TraceID 打通	前后端监控联动	基础架构 + 后端

六、预期收益

6.1 效率提升

场景	当前耗时	治理后耗时	提升
新建 CRUD 页面	4~8 小时	1~2 小时	4x
修复跨子应用 Bug	改 7 处	改 1 处	7x
新子应用接入	2~3 天	半天	5x
后端接口变更适配	改 7 个子应用	改 1 个 SDK	7x
AI 生成代码可用率	~30%	~80%	2.7x

6.2 质量提升

一致性：所有子应用使用相同的组件和交互模式
可维护性：公共代码单点维护，变更自动传播
类型安全：前后端类型自动同步，编译期发现问题
AI 友好：规范化的代码库让 AI 生成更准确的代码

6.3 团队赋能

新人上手：标准化组件 + 文档 + AI Skills → 快速产出
跨团队协作：公共组件库是团队间的共同语言
技术影响力：沉淀的基础设施可对外输出

七、风险与缓解

风险	影响	缓解措施
公共包变更影响所有子应用	回归范围大	Changesets 版本管理 + 自动化测试
业务组件抽象不当	过度抽象或不够通用	先在 2 个子应用验证，再推广
AI Skills 维护成本	文档过时	与代码同仓库，CI 检查文档同步
团队推广阻力	业务团队不愿迁移	渐进式迁移，新页面优先使用

附录：packages 目录规划

packages/
├── micro-bridge/       # ✅ 已有 — 微前端通信 SDK
├── micro-bootstrap/    # ✅ 已有 — 子应用启动器
├── vite-config/        # ✅ 已有 — 统一 Vite 配置
├── tsconfig/           # ✅ 已有 — 统一 TS 配置
├── ui/                 # 📋 规划 — 基础 UI 组件库
├── biz/                # 📋 规划 — 业务组件库
├── hooks/              # 📋 规划 — 通用 Composables
├── utils/              # 📋 规划 — 工具函数库
├── api/                # 📋 规划 — API SDK
├── types/              # 📋 规划 — 共享类型定义
├── eslint-config/      # 📋 规划 — 统一 ESLint 配置
└── mcp-server/         # 📋 规划 — AI Agent MCP 服务

前端架构治理演进规划