# M9 / issue-44 开发日志：web 公开简历页视觉基线升级

- Issue：#78
- 里程碑：M9 体验基线与主题边界：从可用到可继续设计
- 分支：`fys-dev/feat-m9-issue-44-web-visual-baseline`
- 日期：2026-03-26

## 背景

`issue-42` 解决了共享主题基线，`issue-43` 收住了后台首页结构，但公开简历页仍然偏“验证态页面”：

- 页面结构已经能读到真实已发布内容
- 语言切换、主题切换、导出入口也都能用
- 但视觉主次、阅读节奏和信息题头还不够像一页真正的公开简历

如果在这个阶段继续只加功能、不拉阅读体验，后续做模板化、主题化和视觉升级时会再次回到“边跑边补结构”的状态。

## 本次目标

- 升级公开简历页的视觉基线与阅读节奏
- 在 `light / dark` 下都保持清晰层次
- 基于真实已发布数据增加更明确的题头与阅读信号区
- 不进入多模板系统，不新增内容字段

## 非目标

- 不实现 Figma 级精修
- 不扩展新的内容模块
- 不实现多模板切换
- 不抽新的共享组件到 `packages/ui`

## TDD / 测试设计

这轮重点是“公开页的展示结构是否变得更完整”，因此测试优先保护壳层结构和现有交互语义。

### 1. 公开页壳层结构测试

补充：

- `apps/web/components/published-resume-shell.spec.tsx`

新增验证：

- 新的“公开简历速览”区块存在
- “标准双语公开版”题头存在
- 切到英文后，对应的 Overview / Edition 文案也会切换

这样做可以保证视觉基线升级不是只写 CSS，而是确实给页面加上了新的信息层次。

### 2. 现有交互回归

继续保护：

- 语言切换
- 主题切换
- 导出链接
- 空状态

这样即使把页面结构和 hero 布局改掉，也能保证原有功能语义不漂移。

### 3. 工程级验证

执行：

- `pnpm --filter @my-resume/web test`
- `pnpm --filter @my-resume/web typecheck`
- `pnpm --filter @my-resume/web build`
- Playwright 实际打开公开页，验证标题、信号区、标准版说明和语言 / 主题切换

## 实际改动

### 1. 为公开页增加“履历信号区”

更新：

- `apps/web/components/published-resume-shell.tsx`
- `apps/web/components/published-resume/published-resume-utils.ts`

本次在 hero 下方增加了一组“履历信号区”，用于把最重要的几个阅读信号前置：

- 职业经历数量
- 代表项目数量
- 技能分组数量
- 发布状态

它的意义不是加更多功能，而是让访问者在进入页面后更快建立整体认知。

### 2. 把 hero 重组成更像公开成品的题头

更新：

- `apps/web/components/published-resume/published-resume-hero.tsx`

主要变化：

- 把语言 / 主题切换收进右侧控制区
- 新增“标准双语公开版”说明卡
- 把导出入口和版本说明与 hero 主文案形成更明确的主次关系

这样后，hero 不再只是“标题 + 一排按钮”，而是更像公开简历的题头和说明栏。

### 3. 用 CSS 把页面从“验证态卡片页”拉成“编辑感更强的公开简历”

更新：

- `apps/web/app/globals.css`

主要视觉方向是“带一点编辑感的公开档案页”，所以这轮样式重点放在：

- 页面背景网格与轻微纹理感
- 更大的标题比例和更明确的题头层次
- signal cards 的卡片节奏
- section card 顶部细线和 timeline 左侧强调线
- 右侧信息栏的更稳定布局

目标不是追求花哨，而是让页面看起来更像“经过设计的公开简历”，而不是“功能验证页”。

### 4. 保持现有交互语义不变

虽然布局和样式变化较大，但这轮刻意没有改动这些对外语义：

- 语言切换仍在当前页面内完成
- 主题切换仍由共享主题 provider 驱动
- 导出链接仍走 `apps/server`
- 公开页仍只读取已发布内容

这让视觉升级保持在展示层，不回头污染业务边界。

## Review 记录

### 是否符合当前 Issue 与里程碑目标

符合。

本次只做：

- 公开页视觉基线升级
- 阅读节奏整理
- 题头与信号区增强

没有越界去做：

- 多模板系统
- 新内容模块
- 新接口
- 共享组件抽离

### 是否存在可抽离的组件、公共函数、skills 或其他复用能力

当前先不抽新共享组件，原因是：

- `issue-45` 会专门处理 `packages/ui` 的最小共享展示组件沉淀
- 这轮重点仍是先把公开页的视觉基线和信息节奏做出来

不过本轮已经沉淀出几类后续可观察的结构：

- hero 说明卡
- signal cards
- 编辑感较强的 section / timeline 视觉语言

如果 `admin / web` 后续都开始复用其中一部分，再在 `issue-45` 统一抽离更稳。

### 本次最重要的边界判断

本次没有把“视觉升级”误做成“模板系统起步”。我们只做了一版更完整的公开页基线，让：

- 页面可读性变好
- 阅读节奏更明确
- 多模板系统继续留在后续 issue

这保证了当前教程节奏仍然是小步推进，而不是一下子铺满。

## 自测结果

已执行：

- `pnpm --filter @my-resume/web test`
- `pnpm --filter @my-resume/web typecheck`
- `pnpm --filter @my-resume/web build`
- Playwright 实际打开公开页，验证 hero、signal 区、语言切换与主题切换

结果：全部通过。

人工验证结果：

- 实际打开 `http://127.0.0.1:5555/`
- 页面实际出现：
  - `付寅生`
  - `标准双语公开版`
  - `公开简历速览`
- 切到英文后，对应文案切换为：
  - `Yinsheng Fu`
  - `Standard Bilingual Edition`
  - `Public Resume Overview`
- 深色主题切换也能继续生效

补充说明：

- 构建时仍有现存 Tailwind `content` 配置告警，但不是本轮引入的问题，当前不影响功能和构建结果。

## 遇到的问题

### 1. 展示层改动容易只停在 CSS 上

问题：

如果只改样式，不给页面增加更清楚的信息层次，读者只能感受到“看起来不一样了”，但不容易理解这轮到底提升了什么。

处理：

- 把“履历信号区”和“标准双语公开版”说明卡也一起纳入页面结构
- 再用测试保护这些新层次的存在

### 2. 展示层 issue 需要更贴近真实页面的证据

问题：

只靠 build 和测试，不足以证明视觉层升级真的落到了页面上。

处理：

- 增加 Playwright 实际打开页面的验证
- 用真实页面结果确认标题、信号区和语言 / 主题切换都成立

## 可沉淀为教程/博客的点

- 为什么展示层升级不应只写 CSS，而要同时补“阅读信号”
- 如何在不做模板系统的前提下，把公开页先升级到“可展示”的程度
- 展示层任务里，为什么要开始补“展示连续通路”的证据
- 如何把主题切换、导出入口和公开阅读节奏放进同一页而不显得杂乱

## 后续待办

- 继续推进 `M9 / issue-45`：最小共享展示组件沉淀
- 继续推进 `M9 / issue-46`：M9 教程大纲与里程碑收束
- 后续如进入模板化，再把当前 signal / hero / section 语言进一步抽成模板级结构
