# 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` 推进到后续完成口径。