3230382d0f
将 Content 域 51 个 operation 从合同兜底推进到 dedicated / needs_verification，补齐专用 Controller、Application Service、DTO、持久化、facade 边界、幂等、审计和阶段门禁。 同时保留 P1R-1 口径：当前不宣称 completed，后续仍需真实外部 owner 和集成验收推进。
146 lines
5.4 KiB
Markdown
146 lines
5.4 KiB
Markdown
# 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 接通和数据库集成验证。
|
||
|
||
## 执行位置
|
||
|
||
```text
|
||
/Users/qingse/.config/superpowers/worktrees/oh-my-muse/dev-1.0.0
|
||
```
|
||
|
||
分支：
|
||
|
||
```text
|
||
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 域结果：
|
||
|
||
```text
|
||
51 dedicated needs_verification
|
||
```
|
||
|
||
含义：
|
||
|
||
- Content 51 个 operation 均已有专用入口。
|
||
- Content 域没有 `catch_all`、`generic_persistence`、`sse_placeholder` 或 `missing` 残留。
|
||
- 没有任何 Content operation 被提前标记为 `completed`。
|
||
|
||
## 验证记录
|
||
|
||
P1R 覆盖脚本：
|
||
|
||
```bash
|
||
python3 muse-cloud/scripts/p1r-audit-api-coverage.py --check
|
||
```
|
||
|
||
结果：通过，Content 51 个 operation 全部为 `dedicated / needs_verification`。
|
||
|
||
Content 模块全量测试：
|
||
|
||
```bash
|
||
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 门禁测试：
|
||
|
||
```bash
|
||
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。
|
||
|
||
基础卫生检查：
|
||
|
||
```bash
|
||
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` 推进到后续完成口径。
|