65 lines
3.9 KiB
Markdown
65 lines
3.9 KiB
Markdown
# 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 秒静默轮询 |
|
||
|
||
## 实施风险与护栏
|
||
|
||
1. **Runs/Reports 的「导航内容分离」**是绕过 AntD CSS-in-JS 冲突的 hack（见 AGENTS.md 陷阱 3），迁移时必须保留其行为，只统一外壳。
|
||
2. **Campaigns 的独特交互**（时间线、探索区、分析区）不做模式化改造，只统一页面外壳与基础模式。
|
||
3. **keep-alive 架构不动**：所有页面仍按顶级路径挂载，详情仍是页面内部状态。
|
||
4. **只抽取 ≥2 个页面会用的共享件**，防止过度抽象。第一版只抽 `FormDrawer`（表单 Drawer 标准件）与 `usePolling`（活跃态轮询 hook）。
|
||
5. 每票据：一个页面、一次提交、一次 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 dogfood
|
||
- `15d0d12` / `2e78c4b` / `f131657` / `1588972` / `b9011aa` / `5077f08` / `11b1590`：票据 02–08 逐页迁移
|
||
- `0832445`：票据 09，交互标准写入 AGENTS.md
|
||
- `9f25728` / `1fbd2bc`：标准补充与验收归档
|
||
|
||
**基准后的智能评估演进**（反哺标准，已同步 ADR-0005 与 AGENTS.md）：
|
||
- `935f0a1` 列表打开方式对齐操作列按钮
|
||
- `1d2c372` 详情/报告改右侧 Drawer（列表常驻）
|
||
- `22cc437` 抽屉顶栏：返回按钮移除、动作右对齐
|
||
- `01f451c` 详情两列布局 + 报告统计行与维度得分图
|
||
- `804880f` 抽屉顶部内边距修复
|
||
|
||
**验证**：pytest 674 全绿、`tsc --noEmit` 通过；全部变更已部署 t480。
|