# UI 一致性重构 — Spec（grill 共识沉淀）

日期：2026-08-05 ｜ 状态：已确认，开始实施

## 背景

管理后台 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`、提交前本地校验 |
| 详情 | 页面内部视图切换（不加新路由），顶部「返回 + 标题 + 状态 Tag + 动作按钮」 |
| 危险操作 | 统一 `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。