阶段五迭代 0：落盘准入与规划文档

[Hugo-DDT]

变更

• 将阶段五准入清单移动到 docs/taget/阶段五准入清单.md
• 新增阶段五 S5-00～S5-09 目标任务、接口契约、数据结构、Feature Flag、依赖和验收标准
• 仅包含阶段五文档，不实现业务代码、数据库迁移或 OpenAPI 变更

验证

• API verify：78/78
• Web typecheck：通过
• Web Vitest：85/85
• Web production build：通过
• API client check：通过
• 两套 Compose config：通过
• compose:verify：通过
• git diff --check：通过

范围说明

• 基于 codex/s4-01 的阶段四基线创建，待阶段四 PR 合并后可将本 PR rebase 或改基准合入 main。
• 工作树中既有的 AGENTS.md、完整开发计划修改和阶段四文档删除状态未包含在本提交。

[Hugo-DDT]

按最新要求，阶段准入清单与阶段任务文件仅保留在本地，不进入 GitHub。

[Copilot]

🔵 Needs a closer look

Synchronize the authoritative development plan or explicitly defer this document until that plan is merged.

Pull request overview

This PR adds Phase 5 planning and admission documentation without business-code, migration, or OpenAPI changes.

Changes:

• Adds S5-00–S5-09 tasks, contracts, dependencies, feature flags, and acceptance criteria.
• Adds the Phase 5 admission checklist and validation records.

File summaries

File	Summary
docs/taget/阶段五准入清单.md	Phase 5 admission criteria and baseline validation records
docs/taget/第五阶段目标任务.md	Phase 5 task planning and implementation contracts; phase numbering conflicts with the authoritative plan

Review details

Suppressed comments (15)

docs/taget/第五阶段目标任务.md:7

• 该阶段划分与仓库当前的权威计划不一致：docs/HaoBlog 完整开发计划.md:545-551 仍将阶段 5 定义为 AI 基础、阶段 7 定义为创新体验，并把音乐/PWA/404 放到 V1.1；本 PR 又没有提交那份计划的同步修改。合并后会出现两套阶段编号，后续实施者无法判断 S5-01～S5-09 是否取代原阶段 5。请同步权威计划，或明确本文件必须等那份修改一起合入后才生效。

This issue also appears in the following locations of the same file:

• line 45
• line 77
• line 94
• line 108
• line 334
  docs/taget/第五阶段目标任务.md:77

• 这里承诺 GET /api/v1/public/site 增加 featureFlags，但公开接口契约没有定义字段形状或固定 key，只有后面的表格列出名称。由于 S5-01 要求 OpenAPI 与生成客户端一致，后续实现无法据此生成稳定的 DTO 和非法/未知 flag 校验；请明确固定对象（或数组）的 schema、默认值以及未知字段行为。
  docs/taget/第五阶段目标任务.md:95
• S5-02 要求单击节点显示摘要，但 KnowledgeGraphNode 只有 label、href、weight 和 publishedAt，且文档明确禁止为此拉取全文，因此没有可用于面板的受限摘要字段。请增加带长度上限的可选 summary/description，或把验收标准改为只显示现有字段。
  docs/taget/第五阶段目标任务.md:112
• 这里的响应没有表示图谱数据版本的字段，只有 generatedAt；而前文和 S5-01 又要求稳定 ETag/304。若 generatedAt 按请求生成，它会使每次响应都产生新 ETag；若它要充当版本，契约没有定义其稳定性。请明确稳定 revision/generatedAt 语义，并规定 ETag 基于规范化图数据而不是请求时间计算。
  docs/taget/第五阶段目标任务.md:79
• 此处同时标成 Nuxt Server Route/静态边界，但后文要求服务端按运行时配置拉取、校验并在上游失败时回退；静态资源无法执行这一信任边界，浏览器直取上游也会绕过 host/授权校验。请固定为服务端清单路由（或明确构建期生成），并定义上游超时与缓存行为。
  docs/taget/第五阶段目标任务.md:81
• /sw.js 位于站点根路径；若注册时未显式指定 scope，Service Worker 默认可控制整个 /，包括 /articles、/studio 和 /api，这与本文件要求只覆盖工具箱的边界冲突。请要求以 scope: '/tools/' 注册或把脚本放到 /tools/ 下，并在验收中检查 registration.scope。
  docs/taget/第五阶段目标任务.md:295
• 这里将音乐 UI 约定为 role="region"，但 HaoBlog 的设计硬约束要求终端、AI 抽屉和音乐播放器采用 role="dialog"、aria-modal 与 aria-live。按当前文字实现会漏掉播放器的模态/焦点语义，S5-08 也无法据此验收；请明确播放器交互面板的 dialog、aria-modal、焦点恢复和 live 区域。
  docs/taget/第五阶段目标任务.md:130
• 该结构允许 OTHER_AUTHORIZED 条目的 attributionUrl 为 null，但下方又要求每首曲目必须有授权说明或归属链接；当前 schema 没有授权说明字段，因此非法清单可以通过“必填字段”校验却无法向用户展示授权依据。请让相应许可证的证据字段必填，或为 OTHER_AUTHORIZED 增加明确的授权说明字段。
  docs/taget/第五阶段目标任务.md:334
• 按现有工具页实现，/tools 的目录数据来自 /api/v1/public/tools，请求失败时会回退为空列表；这里又禁止缓存 API 响应，只允许静态资源/页面壳缓存。这样离线打开或客户端导航到 /tools 时无法保证目录和五个内置工具仍可用。请定义版本化的静态工具目录/快照（以及动态工具 chunk 的缓存），或明确缓存完整的 /tools SSR 快照，同时保持不缓存用户输入和写 API。
  docs/taget/第五阶段目标任务.md:292
• 仅校验 OSS/CDN 的 HTTPS host 不能保证频谱可用：跨源 <audio> 接入 MediaElementSource 还要求音频响应提供允许当前站点的 CORS header，并由播放器设置合适的 crossOrigin；否则播放可能正常但 Web Audio 分析会被浏览器跨源策略阻断。请把 CORS 要求加入 manifest/来源契约和验收，或限制为同源音频。
  docs/taget/第五阶段目标任务.md:45
• 这里禁止新增迁移并把 flags 放到服务端配置，但完整开发计划规定 site_setting 是 Feature Flag 的存储源（docs/HaoBlog 完整开发计划.md:505），当前 schema/实体也只有 comments_enabled（V10__comment_model_and_flags.sql:1-3、SiteSetting.java:14）。在 clean checkout 上没有定义这七个 flag 的配置键、持久化来源或更新入口，无法同时满足两份契约；请选择 env/application config 作为新的 canonical source 并同步主计划，或把现有 site_setting 扩展纳入迁移和管理接口。
  docs/taget/第五阶段目标任务.md:78
• 这里把 ETag 列入“图谱 JSON”的内容清单，但下面的 KnowledgeGraphResponse 没有 etag 字段，而现有站点契约将 ETag 放在 HTTP 响应头并配合 304。请明确 ETag 仅通过 HTTP 响应头提供，否则实现者会在 JSON body 与 headers 之间形成两种不兼容的契约。
  docs/taget/第五阶段目标任务.md:77
• GET /api/v1/public/site 当前响应使用 public, max-age=0, s-maxage=60, must-revalidate（PublicSiteController.java:24-26）。把 kill-switch flags 放进同一份响应并要求保留该缓存语义后，共享缓存仍可能在关闭后最多 60 秒继续下发 true，与现有“可即时关闭”的约束冲突。请定义独立的不可缓存/版本化 flag 投递或明确 TTL/purge 语义，不要直接继承站点内容缓存。
  docs/taget/第五阶段目标任务.md:115
• 这里仅给出“默认上限”并把实际值留到后续观测，但 S5-01 又要求冻结契约，S5-02/S5-08 还依赖硬上限和可复现资源预算。客户端和验收无法知道真实最大节点、边及响应体大小，超限截断也无法按同一边界复现。请固定 hard max（至少包括节点/边、字符串、响应体和权重范围）并定义超限行为，运行观测只用于验证而不是让上限漂移。
  docs/taget/第五阶段目标任务.md:135
• 这里把清单规模写成“建议最多 30 首”，但 S5-05 验收要求条目上限；Nuxt 服务端还要先读取外部 manifest。若没有固定的服务端条数、响应体和字段长度上限，膨胀的清单可能在校验前消耗不受控的内存和带宽。请把这些限制定义为服务端硬拒绝/截断规则，客户端校验仅作第二道防线。

• Files reviewed: 2/2 changed files
• Comments generated: 0
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.