zizi 3230382d0f feat(p1r): 推进 Content 真实 API 收口

将 Content 域 51 个 operation 从合同兜底推进到 dedicated / needs_verification，补齐专用 Controller、Application Service、DTO、持久化、facade 边界、幂等、审计和阶段门禁。

同时保留 P1R-1 口径：当前不宣称 completed，后续仍需真实外部 owner 和集成验收推进。

2026-05-27 02:24:48 +08:00

5.4 KiB

Raw Blame History

P1R1 内容真实 API 收口留痕

任务背景

本次执行 docs/superpowers/plans/2026-05-26-P1R-1-content-real-api.md，目标是从 P1R-0 的覆盖矩阵进入第一个真实业务域改造阶段：把 Content 域 51 个 operation 从合同兜底入口推进到专用 Controller、Service、DTO、持久化、owner guard、幂等、审计和错误响应可验收的状态。

P1R-1 的完成口径不是把 operation 标为 completed。当前阶段只确认 Content 域已退出 catch-all / generic persistence / SSE placeholder，并进入 dedicated / needs_verification，后续仍需要更强的端到端验收、真实外部 owner 接通和数据库集成验证。

执行位置

/Users/qingse/.config/superpowers/worktrees/oh-my-muse/dev-1.0.0

分支：

dev/1.0.0

计划目标

P1R-1 要完成：

读取 docs/superpowers/reports/p1r-api-coverage.json，筛出 Content 域 51 个 operation。
分清 catch_all、generic_persistence、sse_placeholder、missing 等非真实实现状态。
为 Content 域补真实 API 规格与执行计划。
逐组实现专用 app/admin Controller、Application Service、DTO、Mapper/DO、外部 facade 边界、owner guard、commandId 幂等、审计和错误码。
删除 Content 域 catch-all 合同入口。
更新覆盖矩阵和阶段门禁，确保未经验收的 operation 不能误标为 completed。

实际完成内容

核心产物：

规格：docs/superpowers/specs/2026-05-26-P1R-1-content-real-api-design.md
计划：docs/superpowers/plans/2026-05-26-P1R-1-content-real-api.md
覆盖报告：
- docs/superpowers/reports/p1r-api-coverage.json
- docs/superpowers/reports/p1r-api-coverage.md
Content 阶段门禁：
- muse-cloud/muse-server/src/test/java/cn/iocoder/muse/server/framework/api/P1rContentRealApiGateTest.java

主要代码范围：

App Content 专用入口：核心 CRUD、结构编辑、来源归因、planning、import/parse、export/download、meta projection。
Admin Content 专用入口：作品列表、详情、章节摘要、导入任务、导出任务、风险治理动作。
Application Service：幂等、审计、owner guard、版本校验、状态流转和 facade 编排。
Content 持久化：import/export/planning/governance 等 DO、Mapper 和 V9 Flyway 追加脚本。
外部 owner 边界：AI、Meta、Knowledge、FileService 默认不可用时返回 blocked，不伪造成功。

已删除的关键兜底入口：

AppMuseContentContractController
AdminMuseContentContractController

OpenAPI 例外变更：

用户已批准将 RiskActionRequest.required 从 [commandId, action, reason] 调整为 [commandId, action, reason, expectedVersion]，用于匹配 adminRiskAction 的服务端版本冲突校验。

当前覆盖结果

P1R 审计后 Content 域结果：

51 dedicated    needs_verification

含义：

Content 51 个 operation 均已有专用入口。
Content 域没有 catch_all、generic_persistence、sse_placeholder 或 missing 残留。
没有任何 Content operation 被提前标记为 completed。

验证记录

P1R 覆盖脚本：

python3 muse-cloud/scripts/p1r-audit-api-coverage.py --check

结果：通过，Content 51 个 operation 全部为 dedicated / needs_verification。

Content 模块全量测试：

cd muse-cloud
JAVA_HOME=$(/usr/libexec/java_home -v 21) PATH="$JAVA_HOME/bin:$PATH" \
  mvn -o test -pl muse-module-content/muse-module-content-server -am \
  -Dsurefire.failIfNoSpecifiedTests=false

结果：通过，204 tests，0 failures。

P1R 门禁测试：

cd muse-cloud
JAVA_HOME=$(/usr/libexec/java_home -v 21) PATH="$JAVA_HOME/bin:$PATH" \
  mvn -o test -pl muse-server -am \
  -Dtest=P1rApiCoverageReportTest,P1rContentRealApiGateTest \
  -Dsurefire.failIfNoSpecifiedTests=false

结果：通过，10 tests，0 failures。

基础卫生检查：

git diff --check
git status --short -- muse-cloud/scripts

结果：

git diff --check 通过。
muse-cloud/scripts/** 无改动。

重要修复点

Admin risk action 收口时修复过以下问题：

幂等 envelope 使用 targetType=work、targetId=workId，不再用未生成的 actionId 作为幂等目标。
RiskActionReqVO.expectedVersion 改为必填，OpenAPI 同步 required。
adminRiskAction 校验 action、targetScope 和 targetIds。
chapter/block target 会校验归属 workId。
expectedVersion 校验前用 selectByIdForUpdate 锁定作品，降低并发 TOCTOU 风险。
admin chapter summary 的 wordCount 改为聚合 block word_count。

残余风险

当前状态是 needs_verification，不是业务完成态 completed。
测试主要覆盖 Mockito/MockMvc 和覆盖矩阵门禁，还没有真实 PostgreSQL/Flyway 集成测试。
外部 owner facade 多数仍是边界合同和 blocked 行为，AI、Meta、Knowledge、FileService 的真实闭环需要后续阶段接入。
没有在本留痕中确认提交或推送；当前只是工作树收口状态。

下一阶段

下一阶段应从 needs_verification 推进到更强验收，而不是继续补扫描脚本：

补真实 DB/Flyway 集成测试。
针对 Content 自有事实 operation 做端到端合同验收。
接通或明确排期外部 owner facade。
将符合验收条件的 operation 从 needs_verification 推进到后续完成口径。

5.4 KiB Raw Blame History Unescape Escape