# 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。
