# M20-issue-174：AI 优化记录页视觉升级

- Issue：M20 Follow-up v2 / 优化记录页视觉升级
- 里程碑：M20
- 日期：2026-04-15

## 背景

`issue-173` 已经把 `优化记录` 从 `AI 工作台` 中拆成独立页面，但首版更偏“功能堆叠”：

- 入口关系已经清楚，但页面还不像一个可讲解、可演示的“资料库 / 记录中心”
- 最近优化记录虽然能用，但视觉层级和信息密度还不够稳定
- 历史卡片仍然偏工具态，不够适合作为后续 AI 交互教程中的展示页面

所以这一轮继续只做 M20 范围内的视觉收口，不改接口契约，不推进 SSE，也不进入编辑器内联建议。

## 本次目标

- 把 `/dashboard/ai/optimization-history` 提升为更明确的“优化记录中心”
- 强化页面头部、记录卡片和空态表达，让它更像资料库而不是普通列表页
- 保持当前本地历史 / 缓存体验能力不变，只升级视觉和信息表达

## 实际改动

### 1. 重做优化记录页头部

文件：

- `apps/admin/app/[locale]/dashboard/ai/_ai/optimization-history-shell.tsx`

这次把头部改成更像 archive hero 的结构：

- 增加 `AI Archive` 眉标和更强的主标题区
- 用 radial gradient、玻璃卡片和统计摘要强化“记录中心”气质
- 新增 `记录中心总览` 区块，展示：
  - 本地记录数
  - 影响模块数
  - 最近生成时间与摘要
- 把“返回 AI 工作台 / 刷新记录”动作统一收进 hero 区，减少页面碎片感

同时补了一个实现层修正：

- `archiveStats` 的 `useMemo` 前移，避免 hook 顺序被条件返回打断

### 2. 升级最近优化记录卡片

文件：

- `apps/admin/app/[locale]/dashboard/ai/_ai/components/resume-optimization-history-panel.tsx`

这次不再把记录做成普通列表，而是改成资料卡式布局：

- 面板整体增加更强的边框、背景和阴影，和工作台形成视觉分区
- 标题区增加 `{n} 条记录` 胶囊态计数
- 空态改成更像“档案库未建立”的虚线卡片，而不是普通说明文案
- 记录项改成双列卡片，并加上 `RUN 01` 这类编号，强化“历史批次”感
- hover 状态加入轻微抬升和边框强调，让回看入口更可点
- 模块标签从底层 key 改成中文业务名：
  - `profile` → `个人定位`
  - `experiences` → `工作经历`
  - `projects` → `项目经历`
  - `highlights` → `亮点总结`

## Review 记录

这轮 review 重点看了三件事：

1. 是否仍然只围绕“优化记录页视觉升级”，没有重新扩张到 API 或结果页改造
2. 页面是否比原来更接近“资料库 / 记录中心”，而不是继续堆功能卡
3. 是否保留原有行为能力，包括：
   - 打开结果页
   - 回填到输入区
   - 继续展示缓存报告能力

结论：

- 范围控制符合当前 issue
- 页面信息架构未扩张，但视觉识别度明显更强
- 行为链路保持不变，适合继续沉淀为后续 AI 教程中的展示案例

## 测试与验证

本轮执行：

- `pnpm --filter @my-resume/admin exec vitest run 'app/[locale]/dashboard/ai/_ai/__tests__/optimization-history-shell.spec.tsx'`
- `pnpm --filter @my-resume/admin exec tsc --noEmit`

补充了 `optimization-history-shell` 相关断言，覆盖：

- `记录中心总览`
- `本地记录`
- `1 条记录`
- `RUN 01`
- 中文模块标签 `个人定位 / 项目经历`

## 遇到的问题

- 首次补测试时，`历史中的 AI 优化结果` 同时出现在 hero 摘要和记录卡标题里，导致单元素断言失败。
- 处理方式不是回退 UI，而是把断言改成多元素校验，因为这种重复是页面信息设计的一部分。

## 可继续沉淀为教程的切入点

- 为什么 AI 产品页在“能用”之后，还要单独做一轮 archive / record-center 风格收口
- 如何把“最近优化记录”从功能列表升级成更适合讲解的资料卡页面
- 在不改后端契约的前提下，如何通过页面层级、统计摘要和卡片语言提升 AI 功能的产品完成度
