跳到主要内容

ADR-0005：UI 技术架构——antd 守 CRUD，设计器域自研

  • 状态：已接受（2026-08-01）
  • 决策者：项目维护者（授权 AI 评估）

背景​

前端现状：antd v5 + Ant Design Pro + UmiJS Max，全部 CRUD 页面已建成且 E2E 绿。第 2 轮启动时重新评估 UI 架构是否适配「最好的开源 ERD 工具」目标。

评估证据​

  • antd 的甜区（表单/表格/弹窗/树）= 本项目 CRUD 页面的全部需求，已投资、测试覆盖、贡献者熟悉（尤其中文社区）
  • 实测痛点仅两项：v5 哈希类名使 Playwright 类选择器失效（已用 role/语义选择器化解，反成最佳实践）；Tabs 内容区 auto 高度导致过一次画布塌陷（已修）
  • 设计器域（画布节点/字段连接点/命令面板/上下文工具条）组件形态 antd 完全不覆盖，硬套反而失真
  • 全量迁移（shadcn/Mantine/Tailwind 重写）只改变 CRUD 外观，不改变用户价值，回归成本以周计，ROI 为负

决策​

双域架构：

  1. CRUD/外壳域（登录、项目列表、设置、导出等）：保持 antd v5 + Pro 组件，不迁移、不换肤
  2. 设计器域（画布及一切画布内 UI）：自研设计系统——scss + 自定义 React 组件（ReactFlowRelation/TableNode 为先例），样式归 *.scss 同目录管理，禁止在画布内引入 antd 组件（例外：Modal/message 等全局反馈类）
  3. 不引入 Tailwind：自定义样式体量尚小，scss 足够；R2 阶段（命令面板等大 surface）复审

后果​

  • 正面：各领域用最优工具；设计器代码对人和 AI 都最直接可读（无主题穿透/无哈希类名战争）；CRUD 零回归风险
  • 代价：两套样式范式并存 → 用目录边界约束（pages/design/** 自研，其余 antd）， linter 不加额外规则
  • 复审触发器：设计器自定义组件超过 15 个 / 出现命令面板类复杂 surface → 重评 Tailwind

进展（2026-08-01）​

  • ✅ 已清除全部 @mui/* 直连依赖与源码引用（对话框 Divider/Button/Grid/图标 → antd）
  • 📋 仍残留 @blueprintjs/*（设计器侧栏菜单/部分导出触发器），后续切片收敛或保留为设计器过渡层