2026-10-21 22:34:57 +08:00
# SiteForge 纵向切片 · Plan 4：发布、主题与静态预览（阶段 4 / 快线第 3 步）实施计划
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** hesupipe 真实数据第一次在浏览器亮起来：`content:publish` （显式发布）→ 冻结 Render Snapshot → pilot-minimal 主题渲染六类页面 → Astro 静态构建（媒体本地化）→ 最小门禁 → 本地 Preview Server 按真实路由响应。验收 = 快线"第 10 天演示标准"（六类页面可浏览、真实内容、图片本地化、SEO 基线、200/404、sitemap、移动端无明显破版）。
**Architecture:** 依据快线 §8-§9、V2 spec §8（发布）/§9（主题与 Render Snapshot） （ ）
**Tech Stack:** Astro 5（新依赖，进 themes/pilot-minimal 包）+ 既有栈。预览服务器零新依赖（Node http + route-manifest 匹配）。
**边界（不做）** ：双构建 Hash 一致性（可复现性归 Plan 5/7）、SEO 三方 diff（
---
## 前置事实（执行者必读）
1. **Plan 3 移交清单 9 项** （Plan 3 文末）+ 五条既定事实：① `/products/` 被 basic_page 占据——产品列表演示用 `/product-category/*` （ `/products/` 内容页走通用模板；② 19 条 `?p=` 无路由不进构建；③ is_primary first-import-wins；④ 五列锚点查询三份拷贝（本计划 publish 复用 content-writer 的或抽共享 helper——**抽共享 helper**，第 4 个消费方触发 Plan 3 审查既定条件）；⑤ JSON/HTML 双写窄窗口——build 报告落盘改 HTML 先写或接受（顺手修）。
2. **数据现状** （临时库已 DROP——本计划验收时重建）：192 entry（ （ （ `storage/incoming/hesupipe-media/` （ ） （ （
3. **发布语义** （
4. **Render Snapshot 六文件** （
5. 既有纪律全套：TDD/临时库/四段 typecheck/身份断言/cms 只读/artifacts 与 storage 不入库。
6. 版本纪律：新依赖 Astro 锁 minor；许可证 MIT 记 ADR-018。
2026-10-21 22:46:30 +08:00
7. **路径形态事实（评审实测）** ：真实 hesupipe 有 **54 条百分号编码中文 permalink** （如 `/%e5%85%b3%e4%ba%8e%e6%88%91%e4%bb%ac/` ，多为 page/news）且 **0 条 .html permalink** （该规则仅夹具用）。**编码路径贯穿规则钉死**：routes.json→dist 文件路径→route-manifest→preview 匹配**全程编码原样（字节精确）**，V1 不做解码归一（Windows/NTFS '%' 合法；解码归一属 SP3 验证器）。`.html` 规则保留但标注"仅夹具防御"。
8. **发布补充钉死** ：① `--actor` 参数（CLI 必传或缺省 `super_admin@cli` ， **P0 门禁决策** ： **不读报告文件做 P0 阻断** （
2026-10-21 22:34:57 +08:00
## 仓库结构增量
```text
themes/pilot-minimal/ # Astro 项目（独立 package.json：
theme.manifest.ts # contracts.ThemeManifest 实现
src/layouts/BaseLayout.astro
src/components/ # SeoHead/SiteHeader/SiteFooter/Breadcrumbs/RichText/ResponsiveMedia/ProductCard/NewsCard/Pagination/NotFound
src/pages/[...slug].astro # 六类页面按 render data 分派（getStaticPaths 读输入目录）
src/lib/load-render-data.ts # 只读输入目录（SF_BUILD_INPUT 环境变量）
apps/api/src/modules/publish/ # publish.service（零装饰器）+ module
apps/api/src/modules/build/ # build.service 扩展（已有 spawn 构建骨架？无——Plan 1 只建了 build 触发占位？核实：无 build 模块，本计划新建）
apps/preview-server/ # 预览服务器（Node http，零依赖）
scripts/sf.ts # + content:publish / build:create / preview:start
```
---
### Task 1: content:publish 命令（显式发布）
**Files:** `apps/api/src/modules/publish/{publish.service.ts,publish.module.ts}` ； `content:publish` ； `tests/integration/publish.test.ts`
- [ ] 失败测试（临时库，mini 全链 register→import 后）：① dry-run：列出 current 非空且 published≠current 的 192 条（mini 3 条）清单（typeKey/slug/修订对）+ 汇总计数，零写入；② confirm（ （
2026-10-21 22:46:30 +08:00
- [ ] 实现：`publishSiteContent(db,{siteKey, dryRun, confirmToken, actor})` ——查询起点 `entry_locales.current_revision_id IS NOT NULL AND (published_revision_id IS NULL OR published_revision_id != current_revision_id)` （事务批量 UPDATE）；dry-run token=随机；**actor 按 --actor 传入、缺省 super_admin@cli **（前置事实 8）；P0 门禁按前置事实 8 决策不做（ADR-018 记偏离）；五列锚点共享 helper 顺手抽 `apps/api/src/modules/import/anchors.ts` （三写入器改 import——零行为变更由既有测试守护）
2026-10-21 22:34:57 +08:00
- [ ] 绿 → commit `feat(publish): 显式发布命令（dry-run/confirm/审计/站点配置首版）`
### Task 2: Render Snapshot 物化 + build job
**Files:** `apps/api/src/modules/build/{build.service.ts,render-snapshot.ts,build.module.ts}` ； `build:create` ； `tests/integration/build-snapshot.test.ts`
2026-10-21 22:46:30 +08:00
- [ ] 失败测试（临时库，publish 后）：① build_jobs 行（queued→snapshotting→**validating(空)→succeeded**——dist 尚空；Task 6 接真实构建时**新建 build job**而非改行——build_input_snapshots 有不可变触发器）+ build_input_snapshots 行（三哈希/site_config_revision_id/theme_key='pilot-minimal'）；② 六文件物化：site.json（ ） （ ： ） （ ） （ （ ： ） **ADR-010 双修订测试** ：发布 A→导入改内容 current=B→快照 content.json 仍为 A（
2026-10-21 22:34:57 +08:00
- [ ] 实现：一致性读取（单事务 repeatable read 或快照时点标记——简化：顺序读取+记录行数基线，差异检查）；媒体实体路径解析用 register 快照 metadata 的 storageRoot+storage_path（ `storage/snapshots/media_bundle/…` 已存在的 content-addressed 副本）+ incoming 副本兜底
- [ ] 绿 → commit `feat(build): 冻结 Render Snapshot 物化与 build job`
### Task 3: pilot-minimal 主题骨架 + 布局组件
**Files:** `themes/pilot-minimal/` （ ； `themes/pilot-minimal/test/manifest.test.ts`
- [ ] 失败测试：theme.manifest 满足 contracts 的 isThemeManifest（
- [ ] 实现：Astro 5 项目（dependencies 仅 astro）；BaseLayout（ ： ） （ ） ） （
- [ ] 绿 → commit `feat(theme): pilot-minimal 骨架与布局组件`
### Task 4: 六类页面路由与渲染
**Files:** `themes/pilot-minimal/src/pages/[...slug].astro` + 模板分派；Test `themes/pilot-minimal/test/render-cases.test.ts` （Astro 构建级测试：六类夹具数据 → 构建产物断言）
2026-10-21 22:46:30 +08:00
- [ ] 失败测试（六夹具页 = 真实 hesupipe 抽样数据的脱敏化形状——home（ （ `/%e5%85%b3%e4%ba%8e%e6%88%91%e4%bb%ac/` ）、product-category 列表、product 详情、news 列表 /news/、news 详情 .html（仅夹具防御——真实 0 条））：构建产物存在且含关键内容（title/slug 渲染进 HTML、产品参数/新闻正文、图片 src=根相对；**编码路径产物按编码原样落盘**）；404.html 存在
- [ ] 实现：getStaticPaths 读 SF_BUILD_INPUT 的 routes.json（ `/` →home； `/product-category/*` 或 `/category/*` →列表（taxonomy.json 查 term+content.json 过滤关联内容）；内容页按 typeKey（product→详情含参数表+相册、news_article→正文+日期、basic_page→富文本）；/news/ 特判 news-list。分页：**V1 一律不做**（ ）
2026-10-21 22:34:57 +08:00
- [ ] 绿 → commit `feat(theme): 六类页面渲染与路由分派`
### Task 5: 构建管线（astro 构建 + 媒体落盘 + sitemap/robots）
**Files:** `build.service.ts` 扩展（spawn astro build→媒体复制→sitemap→产物登记）；Test `tests/integration/build-pipeline.test.ts`
2026-10-21 22:46:30 +08:00
- [ ] 失败测试（小夹具全链）：① spawn `pnpm --filter pilot-minimal build` （ `<path>index.html` ； `.html` 后缀→字面文件（仅夹具）；**百分号编码路径→编码原样目录结构**（Astro 产物若不符则构建后按 manifest 重命名/移动对齐——manifest 的 target_file 是唯一权威）；② 媒体复制：assets.json 逐条复制到 dist 的 public_path（跳过 quarantined）；sha256 抽检；③ sitemap.xml（ ） （ **route-manifest.json 生成与字段面断言** （ ： **DATABASE_URL 置空跑构建仍成功** + **无网证明** ：构建进程内 stub global fetch 抛错仍成功——spec §10.4 明文要求）
2026-10-21 22:34:57 +08:00
- [ ] 实现：build.service 编排（快照→astro→媒体→sitemap→登记）；产物落 `artifacts/jobs/<buildJobId>/{input,dist,manifests}`
- [ ] 绿 → commit `feat(build): astro 构建管线与媒体落盘`
### Task 6: 最小门禁 + 完整 build 状态机
**Files:** `apps/api/src/modules/build/gates.ts` ； `build:validate` ； `tests/integration/build-gates.test.ts`
- [ ] 失败测试（夹具产物注入错误逐项触发）：① 内部死链：dist 内 a[href]/img[src] 内部目标全命中（页面或 assets）——注入坏链 → fail；② sitemap 一致：sitemap 条目=实际 indexable html 集；③ SEO 基线：每 html 有 title/meta description/canonical（指向 origin+自身路径）/恰一 H1；④ 大小写冲突：dist 路径 lowercase 无重复；⑤ 产物完整性：route-manifest 的 target_file 全存在。全过 → validation_runs 行 PASS
2026-10-21 22:46:30 +08:00
- [ ] 实现：门禁引擎（纯函数读 dist+manifests → issues 按 P0/P2 分级——P0 阻断 P2 报告；**HTML 解析用 parser 复用清洗管线，禁纯正则** spec §13.4）；build 状态机补 validating→succeeded/failed； （
2026-10-21 22:34:57 +08:00
- [ ] 绿 → commit `feat(build): 最小门禁与状态机闭环`
### Task 7: Preview Server
**Files:** `apps/preview-server/{server.mjs,package.json}` ； `preview:start` ； `tests/integration/preview-server.test.ts`
2026-10-21 22:46:30 +08:00
- [ ] 失败测试（真实 http 请求小夹具构建产物）：① html 行 200+Content-Type；② redirect 行 301+Location（ （ `X-Robots-Tag: noindex` ；⑥ 绑定 127.0.0.1；⑦ 路径穿越拒绝（../ 与编码形式）；⑧ **gone 行 410** （夹具手构——真实数据暂无）+ 目录列表禁用 + HTML 响应基础 CSP 头（self-only）
2026-10-21 22:34:57 +08:00
- [ ] 实现：Node http 服务器读 dist+route-manifest.json（
- [ ] 绿 → commit `feat(preview): 路由驱动的本地预览服务器`
### Task 8: 真实 hesupipe 端到端（验收——浏览器时刻）
**Files:** `docs/evidence/phase4-preview.md` ；可能 `scripts/e2e-real.mjs` （编排复验）
- [ ] 临时库重建全链：register（副本复用）→ import → **publish（ → build → validate → preview:start
2026-10-21 22:46:30 +08:00
- [ ] 验收断言（快线 §8.7 第 10 天标准逐条）：① 六类页面 HTTP 200 且内容来自真实数据（首页/一个内容页（含一条编码路径页）/产品分类列表/产品详情含参数/新闻列表/新闻详情）；② 图片本地化抽检 10 张（dist 内存在+页面引用根相对）；③ 每页 title/description/canonical 抽检 5 页；④ 404 与 301 行为（?attachment_id= 抽检）；⑤ sitemap.xml 条目数=indexable html 数；⑥ 移动端 375px + **桌面 1440px** 截图无明显破版（Playwright MCP 各 3 页存证据——快线 §8.7 原文双端）；⑦ 全量 URL 冒烟：route-manifest html 行全 200（ **redirect 全量 1746 逐条 301+Location 校验** （回环零成本）
2026-10-21 22:34:57 +08:00
- [ ] 耗时记录（快照物化/astro 构建/媒体复制/门禁分解——对照 Plan 3 基线 51.8s）；差异如实分析。证据文档 + commit `test(evidence): 阶段4端到端预览验收` ；临时库 DROP；
### Task 9: 收尾
- [ ] ADR-018（
- [ ] 移交 Plan 5 清单：SEO 三方 diff（ ）
- [ ] commit + push 由用户执行
2026-10-21 22:46:30 +08:00
> 组件清单省略注记：快线 §8.2 的 ProductGrid/NewsList 由模板内联网格实现、TaxonomyList V1 无消费场景（首页不做分类导航）——避免与 §8.2 对照误判遗漏。
2026-10-21 22:34:57 +08:00
## 验收（对照快线 §8.7 + V2 §15 阶段 4 子集）
- [ ] 显式发布可用且导入产物发布前不可见（published 指针语义）
- [ ] Render Snapshot 冻结六文件 + 构建五禁（无库无网无 seed）
- [ ] 六类页面真实数据渲染 + 图片本地化
- [ ] Preview 200/301/404/noindex/回环
- [ ] 最小门禁五项全绿
- [ ] 真实 hesupipe 端到端验收 + 移动端截图证据
