blog/.spec/specs/archive/2026-10-25_fix-site-polish/spec.md

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

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 待确认问题

• 金句引文是否保留文楷 → 结论：保留（宋正文×文楷金句层次）

2.4 可选解释与取舍

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

2.5 已证伪路径

• SVGElement instanceof HTMLElement 守卫（点图标即失效）；verify 命令重跑生成器（Phase 2 已证）

3. 功能范围

3.1 核心功能（MVP）

• T1 四缺陷修复（明暗委托/灯箱 display/评论 site/书评宋体）
• T2 图库打磨（时间戳标题/计数器/对比度/层级）
• T3 E2E 套件 30 项（Playwright）
• T4 视觉复核四轮（12+截图，glm-5.3-flash）
• T5 视觉问题修复三轮（网格高度源/导航 i18n/热力图末列/en 版面平权）
• 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. 成功标准与验证方式

• E2E 30/30 PASS（含软导航回归项） -> verify: task_0003
• 视觉终审"可上线"（双帧像素级闭环） -> verify: task_0004
• 四缺陷线上不复现（staging 断言：宋体/灯箱默认关/site 对齐/委托切换） -> verify: task_0001

7. 风险与约束

• 全页截图不必然触发懒加载（E2E 已加滚动预热）；生产 Artalk 需上线后同源实测