5.7 KiB
5.7 KiB
Phase 5f：SEO 解封与功能优化批 + 美化首批 - 项目范围
1. 问题定义
- 项目目标：①解除生产全站 noindex 封印并补齐 SEO 基建（事故级：上线至今搜索引擎不可见）②修双语暗伤（localePath 双 en/canonical/尾斜杠）③构建期内容 lint+生产冒烟防线 ④reader 纯文本模式 ⑤美化首批 K-Q（流距 token 化/灰阶补档/首屏 tagline/图库质感/微交互/代码块窗条/书评纸面板，全部经视觉模型裁定定案）
- 目标用户：站长（写作/发布/被搜索到）与读者（阅读质感/双语导航正确性）
- 核心价值：站点从"隐身可用"到"可被发现+有质感"；发布链自带质检
2. 假设与待确认
2.1 已确认事实
- noindex 来源=/etc/nginx/snippets/esa-origin-ssl.conf:11（我已 curl+grep 实锤）；robots.txt 生产 404；ESA 头缓存 30 天
- localePath 在 en→en 场景产出 /en/en/...（404）
- Artalk 评论数端点已实测（GET /api/v2/comments?site_name=wait4x.online&limit=0 → count）
- 美化七问已由 glm-5.3-flash:max 逐图裁定（docs/research/08 §6）
2.2 关键假设
- nginx sudo 与 ESA 控制台由用户操作（本包只备好仓库侧与操作单）
- 视觉裁定为终态依据；实现与裁定冲突时以裁定为准并在完成总结记录
2.3 待确认问题
- 美化两案之争 → 视觉模型裁定完成（08 文档 §6），无悬案
- 本批范围 → 用户 2026-10-26 全批（A/B/C/E+K-Q；R 热力图暗色与 S 并入 N 后的下一批）
2.4 可选解释与取舍
- 纸面板=全边框圆角卡（裁定）优于通栏 hairline——保留标题区外置结构
- 代码块窗条仅 ≥4 行块；三点换灰阶（红线优先于 macOS 梗）
- 图库亮色直贴/暗色 4% 衬底（双模式分判）
2.5 已证伪路径
- 首屏 banner 化/大字标语（视觉裁定否决——克制红线）
- 热力图亮色换绿（裁定否决——全页最大色块压灰阶骨架）
- 页面标题 27→22px（裁定否决——层级锚点，要轻减字重不减号）
3. 功能范围
3.1 核心功能（MVP）
- T1 SEO 仓库侧三件：robots.txt 新建 + /admin 局部 noindex 预案 + 用户操作单（nginx/ESA）
- T2 localePath 双 en 修复 + 自指 canonical + 尾斜杠归一
- T3 构建期内容 lint（断链/图片/frontmatter/双语配对）+ 生产冒烟脚本 + build.sh 守卫挂载
- T4 reader 纯文本模式（html.reader 单 class + 命令面板 reader + r 键 + localStorage）
- T5 代码块窗条（P 卡：≥4 行灰阶窗+mono 标题+灰阶三点，单行裸 pill）
- T6 书评纸面板（Q 卡：圆角米灰纸卡+暗色暖棕+hairline 边框防长文竖线感）
- T7 版式基底（K/L/O 卡：正文流距 token 化+灰阶补档+暗色 hairline 降档+微交互曲线统一+focus ring 收尾）
- T8 首屏 tagline + 图库质感（M/N 卡：IdCard 身份语≤20 字+图库圆角统一+暗色 4% 衬底）
3.2 扩展功能
- 无（R 热力图暗色补救列下一批）
3.3 不在范围内
- nginx/ESA 实际操作（用户侧）；draft 路由 D、评论数 F、EXIF 卡 G、title H（本月批后续包）
4. 最小实现路径
- 最简单可行方案：token 值级 CSS 改动为主 + locale.ts 单函数修 + 两个构建脚本；无新依赖
- 暂不引入：blur-up 占位（需管线）、独立设置面板
- 不做的抽象：主题引擎化/样式体系重构（tokens 增量演化）
5. 技术决策
- 技术栈：既有 Astro+tokens 体系；lint 用 node 脚本（复用 build-perf 目录与守卫模式）
- 证据协议：evidence: runs
- 本轮允许改动：src/lib/locale.ts、src/layouts/BaseLayout.astro、src/styles/{tokens,global}.css、src/components/{CommandPalette,IdCard*}.astro、src/components/geek/Keyboard.astro、GalleryPage.astro、prose 相关组件、public/robots.txt、scripts/build-perf/、infra/deploy/build.sh、tests/e2e.mjs
- 本轮不应触碰：nginx/ESA（用户）、Header/Footer 结构、sw.js（无涉）、热力图组件
- Git integration branch：
spec/2026-10-26_blog-5f
5.1 验证策略
- 范围级别：package
- 变更对象：SEO 基建文件、locale 工具、构建链 lint 挂载、reader/美化涉及的样式与组件
- 快速检查：
pnpm astro build - 集成检查：
node tests/e2e.mjs（33 项）+ 本包新增断言（canonical/localePath/reader/窗条/纸面板 computed-style） - 全项目检查：生产 Lighthouse SEO≥95（依赖用户 nginx/ESA 完成后复测入档）；移动溢出密集扫描（美化改动面涉及布局 token 时）
- 升级触发：若 T7 灰阶补档波及 Header/导航布局，升级为全站密集扫描并记录
6. 成功标准与验证方式
- dist 每页含自指 canonical 且 en 页无 /en/en/ -> verify: task_0002
- robots.txt 产物存在且含 Sitemap 行 -> verify: task_0001
- 人为断链能让 build 输出 FAIL 清单（warn 一周策略首版即 fail 可议） -> verify: task_0003
- reader 触发后 .bg-glow 隐藏/ICP 可见/刷新保持 -> verify: task_0004
- 多行代码块有窗条与灰阶三点、单行无 -> verify: task_0005
- 书评正文为圆角纸卡（computed border-radius+背景） -> verify: task_0006
- 流距 token 生效（h2 前后距为变量值）+focus ring 统一 -> verify: task_0007
- 首屏 tagline 渲染≤20 字+图库圆角统一 -> verify: task_0008
7. 风险与约束
- 灰阶红线：所有美化以 08 §6 裁定为终态依据
- build.sh 引用新脚本守卫先行（车道纪律）；lint 首版 fail 可降 warn 一周（发布链安全优先）
- 多车道并行：T2/T3（op-gitea）、T5/T6（op-artalk）、T1/T4/T7/T8（orchestrator）；共享文件按 boundary 划界，global.css/tokens 仅 orchestrator 动