chore(spec): 归档 fix-site-polish——四缺陷+双轨验证六任务收敛

Spec: 2026-10-25_fix-site-polish Co-authored-by: GLM-5.3
2026-10-25 11:30:40 +08:00
1 parent 86e8009f34
commit 59b7baae51
@@ -0,0 +1,72 @@
+# 上线四缺陷修复 + 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 需上线后同源实测