cms-website/docs/adr/ADR-018-主题与构建决策.md

ADR-018：主题与构建决策（Astro 选型/渲染信任链/分页不做/P0 发布门禁偏离/编码路径贯穿/预览回环与 CSP/报告写序）

• 状态：已采纳（Plan 4 Task 9 收尾，阶段 4；实现锚点 themes/pilot-minimal/ · apps/api/src/modules/build/ · apps/api/src/modules/publish/publish.service.ts · apps/preview-server/server.mjs；验收证据 docs/evidence/phase4-preview.md——真实 hesupipe 190 页浏览器预览，23 断言 + 6 截图全过）

决策一：Astro 5.18 选型与依赖布局（MIT）

1. 主题引擎 = Astro 5（锁定 5.18.x minor，实装 5.18.2）：静态优先（零客户端运行时）、[...slug].astro 单入口 + getStaticPaths 读输入目录的路由模型与"route-manifest 是唯一权威"的落盘规则天然咬合、文件级布局组件（BaseLayout/SeoHead/RichText）贴合六类页面分派。许可证 MIT（前置事实 6 的版本纪律复查通过），依赖只进 themes/pilot-minimal/package.json（根 workspace 不引入——构建工具不污染 API/测试面）。真实数据规模实测：190 页纯 astro 构建 4.9-7.5s。
2. vitest 双版本并存（根 2.1.9 / 主题 3.2.7）：主题测试要 import .astro 必须挂 astro 的 vite 插件（getViteConfig），astro 5.18 携 vite 6——根 vitest 2.x 系不兼容，故主题包独立 devDependency vitest@^3.2。两套 runner 各跑各的 package（根 vitest.config.ts 不含 themes，主题自有 vitest.config.ts），pnpm test 串联（382 + 26 = 408）。不把根升 3.x：根栈（pg 临时库 globalSetup/长时集成用例）在 2.1.9 上稳定，为一个子包升根属无收益风险面。
3. 主题五禁的结构保证：渲染数据唯一入口 src/lib/load-render-data.ts（只读 SF_BUILD_INPUT 目录）——不查库/不调 API/不读源快照/无 seed/构建期断网由入口单一性 + 集成测试五禁断言（含 DATABASE_URL 置空、fetch/net stub）共同锁定。

决策二：渲染信任链——bodyHtml 不二次清洗

4. 主题端 set:html 直出，不清洗（RichText.astro）：bodyHtml 的信任链是三段接力——① Plan 2 适配器 HTML 白名单清洗（ADR-009，入库存的就是清洗产物）；② Plan 4 Task 2 快照物化期 URL 重写（rewriteBodyHtml——仅做媒体 URL 到根相对 public_path 的映射改写，命中面以 media ready 集合为界，未命中保留原样 + issue）；③ 主题经 load-render-data 唯一入口消费。三段之外无第四个写方，主题端再清洗是冗余面（且会破坏与 source_rendered 的逐字节对拍——Plan 5 SEO 三方 diff 的比较基准）。禁"顺手加固"：任何在主题层加清洗/改写的行为都属破坏信任链，须先升版本评审。

决策三：分页 V1 一律不做——路由登记义务随迁移移交

5. 列表页单页全列（/news/ 129 条、taxonomy 列表同；Pagination.astro 保留为禁用态接口组件）：分页路由（/news/page/2/ 等）不在 route_registry——未登记路由即不可达，硬做分页会自破门禁①死链（分页链接指向无路由路径）。V1 不做的完整语义：主题不做、管线不造、门禁不查。移交义务：Plan 5 起做分页必须先扩路由登记（route_registry 造行 → routes.json → dist → manifest 全链），路由登记是分页的前置义务而非主题层决定——该义务随迁移移交 Plan 5+，触发时连门禁死链白名单一并定。

决策四：P0 发布门禁偏离（前置事实 8②）

6. V1 publish 不读导入报告文件做 P0 阻断（publish.service.ts 头注记）：spec §8 语义是发布前拒绝未解决 P0 issue，但 import issue 只落报告文件（artifacts/）、无 DB 查询源——publish 要阻断只能重读报告 JSON，而真实数据 206 条 issue 现状下严格门禁会反堵发布（其中大量是源数据固有形态而非阻断级问题）。真实防线不缺位：missing 媒体等在 build/gate 层有实物防线（artifact-completeness/死链/SEO 门禁 + validation_runs 落库）。Plan 5 SEO 三方 diff 时重审——届时 issue 分级（P0-P3）落地，publish 门禁改读 DB 化的 issue 源。

决策五：编码路径贯穿规则 + 资产键编码归一（236f3dc 修补）

7. 全程编码原样（字节精确）：routes.json → dist 文件路径 → route-manifest → preview 匹配，四层对百分号编码路径（真实 54 条如 /%e5%85%b3%e4%ba%8e%e6%88%91%e4%bb%ac/）不解码不归一。理由：解码归一是歧义面（编码大小写/二次编码/非法序列），V1 无消费方需要解码形态；Windows/NTFS 下 '%' 是合法文件名字符，编码原样落盘无障碍。解码归一归 SP3 验证器（届时作为校验规则而非数据改写）。
8. 资产键例外——URL 线形归一（验收内实证修补 236f3dc）：route-manifest 资产行 exact_key 若用文件名本体（裸全角括号/顿号/间隔号），浏览器对非 ASCII 一律百分号编码后发请求，裸键永不命中 → 预览破图（生产面 nginx 先解码不受影响）。修补：pipeline.toManifestRoute 把 exact_key 归一为 URL 线形（可打印 ASCII 原样、其余 UTF-8 百分号编码大写 hex），target_file 仍盘上裸名、DB/渲染快照域不变。配套不变量：manifest 全键纯 ASCII（e2e 断言 ⑦c）。同源修补：预览 Location 头 ASCII 化（asciiLocation()——RFC 9110 头域是 ASCII，裸全角会 ERR_INVALID_CHAR 崩 500）。

决策六：预览零依赖 + host 白名单收紧（比 spec 更严）

9. 零新依赖：预览服务器 apps/preview-server/server.mjs 纯 node:http（.mjs 不进 TS 链，类型面由相邻 server.d.mts 供给）——匹配器（exact_key + query_key）、MIME 表、流式文件服务（createReadStream 直 pipe，64MB RSS 平坦实测）全手写；route-manifest 是唯一输入。
10. host 白名单比 spec §12.2 更严：spec 允许"除非显式指定"其他地址，实现收紧为只允许 127.0.0.1/localhost——库级在服务构造点即拒（先于监听），CLI 级先于一切（含 DB 访问前）拒绝。理由：预览产物带 X-Robots-Tag: noindex 但无鉴权，回环纪律是唯一防线；"显式指定对外地址"没有正当用例，留口子只会被误用。要对外 = 走部署器（Plan 7 的领域）。
11. 安全面全套：穿越预检先于 URL 解析（new URL 会规范化点段——实测洞）、realpath + lexical 双检防 junction 逃逸、目录即 404 禁列表、仅 GET/HEAD、全响应 noindex。

决策七：CSP style-src 'unsafe-inline'（Astro scoped 样式兼容）

12. 预览 CSP = default-src 'self'; style-src 'self' 'unsafe-inline'：Astro 5 静态产物把 scoped 样式内联为 <style> 元素（无外部样式表），default-src 'self' 会拦掉全部内联样式——页面在浏览器裸奔（HTTP 级测试看不见，浏览器时刻才显影，Task 8 实证）。只放开样式面：脚本/连接/图片等仍走 default-src 'self'。不换 Astro 配置规避（external stylesheet 会改变产物形态与可复现面），接受这一条最小放行并在此记档。

决策八：报告 HTML 先写——两域对齐

13. build 报告与 import 报告同序：HTML 先写（report-html.ts + build.service 落盘点）：build.json 在则 build.html 必在——HTML 渲染失败时磁盘不留"JSON 新终态 + HTML 旧终态"的窄窗口（Plan 3 移交项⑤的兑现，两个域从此同纪律）。HTML 渲染面全动态文本转义、静态骨架无 script（Plan 2 Task 6 模板纪律）。

• 理由：主题层"最薄可信渲染"（信任链三段接力 + 唯一入口）、预览层"最窄暴露面"（零依赖 + 回环 + 只读两文件）、门禁层"实物防线优先于台账阻断"（P0 偏离的真实防线论证）——三条线索共同把复杂度压在数据侧（快照冻结），消费侧全部薄层。
• 权衡/陷阱：① 分页不做意味着 /news/ 129 条单页——真实站可浏览性达标（验收过），但内容量再涨一个量级前 Plan 5 必须落路由登记义务；② P0 发布门禁偏离是有意欠账——issue DB 化前 publish 无阻断，靠 build/gate 层兜底，Plan 5 重审时若引入 publish 阻断须先做 issue 分级落库；③ 编码路径"原样"与资产键"归一"并存不矛盾——前者是四层贯穿的不解码纪律，后者是键的构造规则（进 manifest 前就写成 URL 线形），排查时先分清键在哪一层；④ vitest 双版本是过渡态——根升 3.x 的时机是 vitest 2.x 出安全分支停维护或根需要 vite 6 特性时，届时一次性迁移并复跑全套。