3.9 KiB
3.9 KiB
UI 一致性重构 — Spec（grill 共识沉淀）
日期：2026-08-05 ｜ 状态：已完结（2026-08-06 归档）
背景
管理后台 9 个业务页面约 4000 行，交互模式不一致：Runs/Reports 不用 PageWrapper、表单容器混用 Drawer/Modal、Files 删除无确认、空态/加载态/反馈方式各页不同。智能评估 v1.0 交付后，其页面模式成为事实上的最新标准。
决策清单（grill 结论）
| # | 决策 | 结论 |
|---|---|---|
| 1 | 重构目标 | 交互层为主、视觉层顺带、信息架构不动 |
| 2 | 一致性基准 | 以智能评估页为标准，其他页面向它对齐 |
| 3 | 实施策略 | 先沉淀共享组件，再逐页迁移；每页一票一提交一验证 |
| 4 | 范围 | 9 个业务页面；排除 Login、OpenClaw（AI 助手嵌入应用） |
| 5 | 行为边界 | 交互对齐优先：不一致处按标准修正，不增删业务功能、不动 API |
| 6 | 迁移顺序 | IntelligentEvals → Targets → Files → ModelConfigs → Scenarios → Runs → Reports → Campaigns |
| 7 | 交互标准 | 见下表 |
| 8 | 验收 | 每票 tsc + t480 走查 + keep-alive 不回归；前 3 票后组件稳定检查点；基准页重走 P0 全流程；最终全量走查 |
交互标准（唯一基准）
| 模式 | 标准 |
|---|---|
| 页面骨架 | PageWrapper inline fullHeight，标题 + 描述 + extra 区（刷新按钮 + 主操作按钮） |
| 列表 | Table + rowKey="id"；空态用 Empty（带文案）；加载用 Table 自带 loading |
| 分页 | 超过 20 行才分页，否则 pagination={false} |
| 表单 | Drawer 宽 640、layout="vertical"、底部 footer（取消/主按钮）、destroyOnClose、提交前本地校验 |
| 详情 | 页内视图切换或右侧 Drawer 弹出（不加新路由，列表常驻）；顶栏左「标题 + 状态 Tag」、右动作按钮；Drawer 内容自滚动（body padding 0 + 根容器 16px 内边距） |
| 危险操作 | 统一 Popconfirm（含删除、取消等不可逆动作），禁用 window.confirm 和无确认删除 |
| 反馈 | 错误统一由 axios 拦截器弹 message.error；成功由动作函数显式 message.success |
| 轮询 | 活跃态（外部会变化的状态）5 秒静默轮询 |
实施风险与护栏
- **Runs/Reports 的「导航内容分离」**是绕过 AntD CSS-in-JS 冲突的 hack（见 AGENTS.md 陷阱 3），迁移时必须保留其行为，只统一外壳。
- Campaigns 的独特交互（时间线、探索区、分析区）不做模式化改造，只统一页面外壳与基础模式。
- keep-alive 架构不动：所有页面仍按顶级路径挂载，详情仍是页面内部状态。
- 只抽取 ≥2 个页面会用的共享件，防止过度抽象。第一版只抽
FormDrawer（表单 Drawer 标准件）与usePolling（活跃态轮询 hook）。 - 每票据：一个页面、一次提交、一次 t480 部署走查。
票据规划
见 .scratch/ui-consistency/issues/。依赖链：01 → 02/03（检查点）→ 04–08 → 09。
归档收口（2026-08-06）
交付：9 张票据全部完成并验收勾选（issues/01–09），t480 全页走查通过（golden path + keep-alive 切 tab）。
实施提交：
d4c254e票据 01：FormDrawer/usePolling 基准件 + IntelligentEvals dogfood15d0d12/2e78c4b/f131657/1588972/b9011aa/5077f08/11b1590：票据 02–08 逐页迁移0832445：票据 09，交互标准写入 AGENTS.md9f25728/1fbd2bc：标准补充与验收归档
基准后的智能评估演进（反哺标准，已同步 ADR-0005 与 AGENTS.md）：
935f0a1列表打开方式对齐操作列按钮1d2c372详情/报告改右侧 Drawer（列表常驻）22cc437抽屉顶栏：返回按钮移除、动作右对齐01f451c详情两列布局 + 报告统计行与维度得分图804880f抽屉顶部内边距修复
验证：pytest 674 全绿、tsc --noEmit 通过；全部变更已部署 t480。