blog/.spec/specs/archive/2026-10-25_add-blog-launch/spec.md

Phase 4：极客层 P1 + 发布链闭环 + 上线准备 - 项目范围

1. 问题定义

• 项目目标：命令面板 + 贡献热力图（极客层 P1）；gitea webhook→构建→staging 发布闭环；预发布全端验收；一键上线脚本（用户 sudo 执行）与回滚配套
• 目标用户：站长（发布即构建；一条命令上线）
• 核心价值：从"staging 就绪"到"可上线状态"的全部工程准备

2. 假设与待确认

2.1 已确认事实

• gitea heatmap API 匿名可用（调研 05 实测：/api/v1/users/{u}/heatmap，CORS *，返回 {contributions,timestamp}[]）
• gitea admin token 在宿主 init-credentials.txt（webhook 注册用）
• staging 全量内容 21+2 页（zh/en）+ photos-originals
• SearchDialog 已有 Pagefind 懒加载与 / 键入口（面板升级的基座）

2.2 关键假设

• gitea webhook 目标 URL 用 http://127.0.0.1:13020 能回环触达本机接收器（同宿主）
• ESA 对静态资源缓存友好（hash 文件名 + immutable）

2.3 待确认问题

• 上线切换执行者 → 结论：脚本备好，用户 sudo 执行（红线：nginx 属 root 域）

2.4 可选解释与取舍

• 命令面板升级现有 SearchDialog（保 Pagefind 数据面）> 引 cmdk/kbar（拖 React 运行时）-> 选自写扩展
• 热力图构建时拉取 + 仓内缓存兜底 > 运行时拉（静态站纪律）-> 选构建时

2.5 已证伪路径

• 无

3. 功能范围

3.1 核心功能（MVP）

• T1 命令面板（搜索+导航+动作聚合）
• T2 gitea 贡献热力图（构建时+兜底）
• T3 webhook HMAC 闭环（验签+注册+push→build→staging 实测）
• T4 预发布全端验收（渲染矩阵+OG+微信 UA+responsive）
• T5 上线脚本与回滚配套+检查单
• T6 验收归档

3.2 扩展功能

• /terminal 彩蛋、书评索引画廊（Phase 5 二期池）

3.3 不在范围内

• 实际执行上线切换（用户动作）、Halo 停用（Phase 5）

4. 最小实现路径

• 最简单可行方案：面板=SearchDialog 扩展动作层；热力图=lib fetch+缓存 JSON+纯 CSS 组件；webhook=现骨架填 HMAC
• 暂不引入：常驻接收服务（gitea 直接 POST 本机脚本经 systemd-path 或手动验证模式）
• 不做的抽象/配置化：多 webhook 源、面板插件系统

5. 技术决策

• 技术栈：vanilla TS/CSS + gitea API + shell
• 证据协议：evidence: runs
• 本轮允许改动：src/、infra/deploy/、scripts/、.spec/
• 本轮不应触碰：/etc/nginx（脚本只生成不安装）、生产 Halo、content/
• Git integration branch：spec/2026-10-25_add-blog-launch

5.1 验证策略

• 范围级别：package
• 变更对象：面板/热力图组件、webhook 脚本、上线脚本
• 快速检查：pnpm astro build
• 集成检查：面板动作标记与热力图格子产出；webhook 干跑+真实 push 全链；验收矩阵脚本
• 全项目检查：staging 全端验收矩阵 + rollback-dryrun；仅在 nginx 面或部署链变更时升级范围
• 升级触发：只有上线脚本被执行（nginx 实切换）时，才升级为全项目验证并记录（当前包内只备不执行）

6. 成功标准与验证方式

• 面板含 ≥3 动作与全站导航（dist 标记断言） -> verify: task_0001
• 热力图渲染 ≥52 周格子且失败兜底不破构建 -> verify: task_0002
• 真实 push 触发构建并更新 staging 戳 -> verify: task_0003
• 验收矩阵脚本全绿（渲染/OG/微信 UA/responsive） -> verify: task_0004
• 上线脚本 --dry-run 通过且检查单落档 -> verify: task_0005

7. 风险与约束

• webhook 回环接收的安全面（监听面收窄到 127.0.0.1 + HMAC 强制）-> T3 覆盖
• 上线脚本误执行 -> 只生成不安装，--dry-run 默认，真实执行需用户显式 sudo