# 上线四缺陷修复 + E2E 全功能测试与视觉复核 - 项目范围

<!-- spec-format: 2 -->

## 1. 问题定义
- **项目目标**：修复用户实测四缺陷（明暗切换失效/图库显示问题/评论不可用/书评字体不符），并以 Playwright E2E ×30 项 + 视觉模型四轮截图复核形成质量闭环
- **目标用户**：站长与读者（上线质量兜底）
- **核心价值**：从"能上线"到"上线即良好"，E2E+视觉复核方法论入库可复用

## 2. 假设与待确认

### 2.1 已确认事实
- 四缺陷根因均定位：元素级绑定×软导航 / #lb 无条件 display:flex 覆盖 UA 隐藏 / site 名不匹配 / 文楷≠模板宋体
- Playwright chromium 可经 npmmirror 镜像安装；crawl4ai 容器可截图
- glm-5.3-flash 子代理具备看图能力

### 2.2 关键假设
- Artalk E2E fetch 失败为测试环境跨域（127.0.0.1 页面拉 wait4x.online API），生产同源不受影响——上线后以生产页实测闭环

### 2.3 待确认问题
- [x] 金句引文是否保留文楷 → 结论：保留（宋正文×文楷金句层次）

### 2.4 可选解释与取舍
- E2E(Playwright)+视觉模型双轨 > 纯人工/纯脚本：功能与视觉两面各自盲区互补 -> 选双轨
- 图库高度改行跨度单一来源+object-fit cover > 修 aspect-ratio 与 span 的协同计算：根治双约束竞争 -> 选前者

### 2.5 已证伪路径
- SVGElement instanceof HTMLElement 守卫（点图标即失效）；verify 命令重跑生成器（Phase 2 已证）

## 3. 功能范围

### 3.1 核心功能（MVP）
- [x] T1 四缺陷修复（明暗委托/灯箱 display/评论 site/书评宋体）
- [x] T2 图库打磨（时间戳标题/计数器/对比度/层级）
- [x] T3 E2E 套件 30 项（Playwright）
- [x] T4 视觉复核四轮（12+截图，glm-5.3-flash）
- [x] T5 视觉问题修复三轮（网格高度源/导航 i18n/热力图末列/en 版面平权）
- [x] T6 收官（en 列表英文标题 + 归档推送上线）

### 3.2 扩展功能
- 无

### 3.3 不在范围内
- 新功能、Phase 5 二期池

## 4. 最小实现路径
- 最简单可行方案：根因级小修（每项 <20 行）+ 双轨验证闭环
- 暂不引入：视觉回归基线系统、CI 集成
- 不做的抽象/配置化：多主题引擎、截图差异算法

## 5. 技术决策
- 技术栈：现有 Astro 站 + Playwright + c4ai 截图 + glm-5.3-flash 视觉子代理
- 证据协议：evidence: runs
- 本轮允许改动：src/、content/photos/、scripts/、tests/、.spec/
- 本轮不应触碰：infra 生产面（nginx/容器）、content/posts
- Git integration branch：`spec/2026-10-25_fix-site-polish`

### 5.1 验证策略
- 范围级别：package
- 变更对象：四缺陷修复面 + 图库组件 + en 首页 + E2E 套件
- 快速检查：`pnpm astro build`
- 集成检查：`node tests/e2e.mjs`（30 项全 PASS 为准）
- 全项目检查：视觉复核截图集终审"可上线"；仅在布局骨架或发布链变更时升级范围
- 升级触发：只有改动网格骨架/发布链/生产面时，才升级验证范围并记录理由

## 6. 成功标准与验证方式
- [x] E2E 30/30 PASS（含软导航回归项） -> verify: task_0003
- [x] 视觉终审"可上线"（双帧像素级闭环） -> verify: task_0004
- [x] 四缺陷线上不复现（staging 断言：宋体/灯箱默认关/site 对齐/委托切换） -> verify: task_0001

## 7. 风险与约束
- 全页截图不必然触发懒加载（E2E 已加滚动预热）；生产 Artalk 需上线后同源实测