- 新建 项目进度与路线-总览-2026-06-21(取代06-17版),刷新A/B矩阵+增量交付+下一步+§9实施记录 - README 索引刷新到06-21;旧总览+14份过时/已完成文档加状态横幅;落地路线图回写里程碑 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
104 lines
9.8 KiB
Markdown
104 lines
9.8 KiB
Markdown
> 📌 **落地状态以总览为准(2026-06-21)**:本文「未开始/未实现」等表述已过时——L1 主题(amis-theme.css §10-15 密度/按钮/弹窗)、L2 行选中、设计中心 DesignCenterPage 已上线。当前落地状态见 [总览-2026-06-21](项目进度与路线-总览-2026-06-21.md) B4。
|
||
|
||
# EIP4 组件设计体系 — 设计文档
|
||
|
||
> 日期:2026-06-15 状态:设计已成形(brainstorm 共识),具体数值/形态待真实数据校准
|
||
> 范围:跨 `eip4-web`(前端壳 + 主题 + 运行时渲染器)与 `eip4-platform/platform-converter`(schema 产出)
|
||
> 缘起:从"editGrid 添加按钮位置"升级为"全站 UI/UE 达不到生产级 → 立一套合理好用的组件体系"
|
||
|
||
---
|
||
|
||
## 1. 背景与目标
|
||
|
||
- 现状:1238+ 业务页由元数据驱动、转换器产出 amis schema 渲染。功能正确,但跑的是 **amis 默认皮肤 + 仅做了功能正确、未做视觉/交互打磨**,整体观感"达不到生产级"。
|
||
- 已有资产:`claude-design-设计输入包/` 已把 1500+ 页归纳为 **11 种页面模式**,给出目标审美(**飞书多维表格 / 钉钉宜搭的密度感**)、效率优先原则、**design tokens 主题化**要求、amis 组件边界约束。**规格不缺,缺的是落成生产级实现。**
|
||
- 目标:建立一套**组件设计体系**,让自动转换出来的页面达到生产级;优先把"渲染出来的 App 质量"拉起来。
|
||
|
||
## 2. 设计原则(顶层,约束所有后续决策)
|
||
|
||
1. **分组件定夺**:多数组件**保真换肤**(只现代化视觉、交互流程不变、用户 0 学习成本);只对明确"不好用"的(树编辑、列表选中)才**现代化重做交互**。
|
||
2. **双约束:老兼容 + 新 UX(核心)**:框架**同时具备两套行为**,不是二选一。
|
||
- 默认 = 保真:老系统怎么操作,新系统就怎么操作 → 老页面零风险。
|
||
- 现代化 = 按页可覆盖:哪页升级、升成什么样,**拿那一页的真实数据/字段量看了再定**,逐页覆盖。
|
||
- 开关落在转换器配置层(每模板可标注),天然支持"交付不同客户换不同档位"。
|
||
3. **效率优先于装饰**:密度、键盘操作、批量操作 > 留白与动效(参考飞书/宜搭密度)。
|
||
4. **Token 主题化**:全部视觉决策用 design tokens 组织,换色不换骨架。
|
||
5. **数据驱动校准**:具体宿主形态、密度数值、交互细节**不在设计阶段写死**,对着真实重型页校准。
|
||
|
||
## 3. 路线决策:A — Token/主题先行,逐级升级
|
||
|
||
四层"代价阶梯",**绝大多数组件停在 L1 即可**;越往下代价越大、用得越少:
|
||
|
||
| 层 | 机制 | 改什么 | 代价/风险 | 覆盖 |
|
||
|---|---|---|---|---|
|
||
| **L1 Token/主题** | 扩 `eip4-web/src/shell/theme.css` + `amis-theme.css`(CSS 变量/覆盖) | 全局密度、间距、字号、圆角、颜色、组件态(hover/选中/禁用)、表格/表单/弹窗视觉规范 | **零 SDK 重建、零回归、随时回退** | 约 80% 的"很差",全 11 模式观感 |
|
||
| **L2 Schema 约定** | 改转换器 `UiTypeMapper` / `TemplateToAmisConverter` 产出 | 用 amis 已有能力把组件配"对"(列表选中模式、picker 列、子表工具栏、审批时间线结构、**表单宿主策略**) | 改 Java + 重转重导,低风险 | 能用 schema 表达的交互 |
|
||
| **L3 运行时渲染器** | 宿主 `amisRequire('amis')` 注册自定义 React 渲染器(`AmisRenderer.tsx` 已有注册通道) | amis schema 表达不出来的交互(如树的现代化行内编辑) | 在 app 代码内,**不动 bundle** | 少数硬交互 |
|
||
| **L4 fork SDK** | 改 amis 源码 + 重建 `public/sdk-local/sdk.js` | amis 内核级限制(如 editGrid 按钮进表头工具栏 ⊞ 同排) | **最重**:踩源码漂移坑、需全站回归 | 最后一档手术刀,单点动用 |
|
||
|
||
**现状基础(非从零)**:`theme.css`(壳层 tokens:主色 `#2B5CE6`、`--text`/`--line`/`--surface-2`…)+ `amis-theme.css`(316 行,把壳层 token 映射到 amis cxd 变量,含深色模式,经 `main.tsx` 在 `sdk.css` 后加载)。但现有 316 行**主要只对齐了品牌色**,未做密度/间距/字号/组件态/交互体系化打磨 → 这是 L1 主战场。
|
||
|
||
> ⚠️ **L4 源码漂移坑(已核实)**:线上 `public/sdk-local/sdk.js` 的 InputTable 与 `amis-fork` 源码已不一致(线上缺 `tableContentClassName`/`showFooterAddBtn` 等标记,是更旧/不同实现)。从 amis-fork 重建会换成另一个 amis 版本 → 全站 883 页回归风险。**故 L4 一律单独立项、单点动用,绝不为换肤动它。**
|
||
|
||
## 4. 11 模式 × 组件处置表(含 5 个痛点归位)
|
||
|
||
| 痛点 / 模式 | 对应模式 | 现状问题 | 处置层 | 定性 |
|
||
|---|---|---|---|---|
|
||
| **①树的编辑** | M3 树 / M9 树选择窗 | 加节点走弹窗表单、无拖拽、无属性抽屉 | **L2+L3** | **现代化重做**:行内增改名 + 拖拽排序 + 选中节点右侧属性 Drawer |
|
||
| **②列表选中** | M1 列表(60%) | 勾选/行高亮弱、单选双击与批量勾选语义混 | **L1+L2** | **现代化**:双击=查看、勾选+工具栏=批量、选中行强高亮、固定操作列 |
|
||
| **③各种选择框** | M8 选择窗 / M9 树选择窗 + picker | 弹窗朴素、无"已选区"、单/多选不清 | **L1+L2** | **保真换肤+配置**:搜索框+简化列表+已选计数+确定/取消,统一所有"放大镜"字段 |
|
||
| **④审批页面** | M11 审批 + 待办中心 | 无时间线、无当前节点操作区、待办中心未独立 | **L1+L2(+特建)** | **现代化**:表单+审批时间线+同意/驳回/转办;待办中心独立页(批量同意、移动端卡片) |
|
||
| **⑤其余归纳** | M2 主子表 / M4 树+列表 / M5 日历 / M6 组合 / M7 表单 / M10 报表 | 默认皮肤、密度松、缺合计行/分组小计规范 | **L1 为主** | **保真换肤**:统一密度/间距/字号/状态色/表格规范 |
|
||
|
||
> 11 模式定义见 `claude-design-设计输入包/03-页面模式规格-11种模板.md`;组件边界见 `02-设计约束-amis组件边界.md`。
|
||
|
||
## 5. 表单宿主策略(CRUD 新增/编辑 — 内容多时不挤)
|
||
|
||
**问题**:M2 主子表/M7 表单在 ERP 高字段密度下,全塞进居中 Dialog 必然憋屈。
|
||
|
||
**根因修复(L1,任何宿主都先做)**:分组折叠(基本信息/明细/附件,可折叠,而非一堵字段墙)+ 统一栅格间距(tokens,2/3 列响应式)+ 吸顶标题 + 吸底操作条(保存/提交常驻、body 内滚动)+ 主子表子表各自带工具栏。
|
||
|
||
**宿主策略(L2,可配置、数据驱动、不现在写死)**:
|
||
- 候选宿主:amis `dialog` / `drawer` / `page`(整页路由) / `wizard`(分步) 均可用,无需 fork。
|
||
- **默认 = 保真**(老系统怎么弹就怎么弹);**升级 = 按页覆盖**,阈值/覆盖名单是参数。
|
||
- 候选分级规则(**待真实数据校准,非定论**):轻量(≤~12 字段)→Dialog;中等→右侧宽 Drawer;重型(主子表/多 Tab/ERP 密集)→整页路由(左锚点导航+吸底操作条)。
|
||
- 转换器已知每模板字段数 + 是否主子表,可据此自动判定宿主,并允许逐页覆盖。
|
||
|
||
## 6. 设计工具 IA(Thread B,本期 A 之后再做)
|
||
|
||
- 现状:`PageRenderPage.tsx` 给**每个页面**(管理员可见)挂一颗「设计」按钮,打开 F4-L1 低代码设计器(`amis-editor` 三屏,`DesignerPage.tsx`)。
|
||
- 用户主张:**应有一个独立的"设计中心"模块集中管理/设计所有功能页**,而不是每页一颗散落的设计按钮。
|
||
- 处置:**记录为 Thread B**,主线 A(组件体系)落到生产级后再做。届时方向 = 收敛为集中式设计中心(页面列表 + 进入设计 + 版本/overlay 管理),逐步弱化/移除每页设计按钮。
|
||
|
||
## 7. 待真实数据校准清单(Open Decisions — 不在本文档写死)
|
||
|
||
1. 表单宿主分级阈值(字段数边界)+ 哪些模板进"现代化覆盖名单"——拿合同管理(主子表)、设备台账(列表)、某审批单等真实页校准。
|
||
2. L1 密度数值(行高、字号阶、间距阶、表格紧凑度)——对照飞书/宜搭与老系统截图定标。
|
||
3. 树编辑现代化版的具体交互(行内 vs Drawer 属性面板的边界)。
|
||
4. 列表选中的单选/多选/双击语义在各业务页是否统一。
|
||
5. editGrid 按钮入表头(⊞ 同排)是否值得动 L4 —— 默认**保留现左对齐工具栏兜底**,仅当成硬需求时单独立项。
|
||
|
||
## 8. 分期建议(先后顺序,数值待校准)
|
||
|
||
1. **P0**:L1 design tokens + amis 主题体系化(密度/间距/字号/组件态),先在 **M1 列表**(60%)定下密度基调 → 立刻全站观感提升。
|
||
2. **P1**:M1 列表选中现代化 + M8/M9 选择框统一(换肤+配置)。
|
||
3. **P2**:M2 主子表表单宿主策略 + 根因修复(分组折叠/吸底条)。
|
||
4. **P3**:M3/M9 树编辑现代化(L2→L3)。
|
||
5. **P4**:M11 审批 + 待办中心。
|
||
6. **P5**:M7 表单(移动端样张)、M10 报表、其余模式收尾。
|
||
7. **后续**:Thread B 设计中心;按需 L4 单点项(editGrid 表头按钮等)。
|
||
|
||
## 9. 验收口径("生产级"怎么算)
|
||
|
||
- 对照老系统截图:功能 parity 不丢(默认保真档)。
|
||
- 对照飞书多维表格/钉钉宜搭:密度、状态反馈、键盘/批量效率达现代水平。
|
||
- 双端:同一 schema 桌面 + 移动响应式降级(crud→卡片、多列→单列)成立。
|
||
- 每个模式有一张"对照样张"(老 vs 新)+ 真实数据走查通过。
|
||
|
||
## 10. 非目标(YAGNI)
|
||
|
||
- 不重写 amis(不走自定义组件库先行 B 路线)。
|
||
- 不为换肤重建 SDK(L4 仅单点)。
|
||
- 不在本期做自由画布式表单、无限嵌套子表、单元格内迷你图表(违反 amis 组件边界约束)。
|
||
- 自定义组件(甘特/地图/组织架构图)每个单独立项,本期不铺开。
|