# P1R-2 元治理真实 API 收口

日期：2026-05-28

## 背景

P1R-2 Meta Real API 的规格和计划已存在：

- 规格：`docs/superpowers/specs/2026-05-27-P1R-2-meta-real-api-design.md`
- 计划：`docs/superpowers/plans/2026-05-27-P1R-2-meta-real-api.md`

本次执行 Task 10：覆盖审计、扫描规则纠偏、报告再生成、Meta gate test 和最终留痕。

## Task 4-9 实现摘要

- Task 4：新增 `AdminMetaSchemaController`，MetaSchema list/detail/version 进入 dedicated Controller 和 Service。
- Task 5：MetaSchema draft 保存、校验、影响预览进入 dedicated Controller、Service、DTO 和测试。
- Task 6：MetaSchema publish/activate/rollback/deprecate/gray-rules 进入 dedicated command 流程，保留 `needs_verification`。
- Task 7：新增 `AdminProtectionNodeController`，ProtectionNode list/detail 进入 dedicated 查询入口。
- Task 8：新增 `AdminFunctionChainController`，FunctionChain list/impact-preview/activate 进入 dedicated 入口。
- Task 9：P1R-2 Meta 合同兜底路由已从完成路径退役，并有 route ownership 测试覆盖。

## Task 10 报告状态

首次运行：

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

结果：退出码 0，生成 `docs/superpowers/reports/p1r-api-coverage.json` 和 `.md`。

审计脚本输出的 Meta 状态仍为：

```text
generic_persistence/incomplete 10
missing/incomplete             6
```

原因：脚本的保守扫描规则只匹配单个注解里的路由字面量，不能合并 Meta Controller 的类级 `@RequestMapping("/muse/governance/...")` 和方法级 `@GetMapping/@PostMapping`。

已纠偏：`muse-cloud/scripts/p1r-audit-api-coverage.py` 改为识别类级 `@RequestMapping` base path，并与方法级 `@GetMapping`、`@PostMapping`、`@PutMapping`、`@PatchMapping`、`@DeleteMapping`、`@RequestMapping(method=...)` 合并后再匹配 OpenAPI path。该变更只是 Spring 路由扫描规则纠偏，不硬编码 Meta 16 个 operation，不把 generic fallback 算 dedicated。

最终报告状态：

```text
Meta    16 dedicated / needs_verification
Content 51 dedicated / needs_verification
```

全局 summary：

```text
totalOperations=233
completedOperations=0
needsVerificationOperations=67
incompleteOperations=166
genericPersistenceOperations=164
ssePlaceholderOperations=2
missingOperations=0
blockedOperations=0
```

没有把 Meta 或 Content operation 标为 `completed`。

## 验证结果

扫描规则纠偏验证：

- 修复前真实 audit 再生成结果：Meta 为 `generic_persistence/incomplete 10`、`missing/incomplete 6`，Content 为 `dedicated/needs_verification 51`，completed 为 `0`。
- 修复后真实 audit 再生成结果：Meta 为 `dedicated/needs_verification 16`，Content 为 `dedicated/needs_verification 51`，completed 为 `0`。

Meta gate TDD 过程：

- 新增 `P1rMetaRealApiGateTest` 后先运行单类测试，当前报告下按预期失败，失败点为 Meta operation 仍是 `missing`。
- 报告对账后重跑单类测试通过。

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,P1rMetaRealApiGateTest \
  -Dsurefire.failIfNoSpecifiedTests=false
```

结果：通过，14 个测试，0 failures，0 errors。

Meta 模块全量测试：

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

结果：通过，165 个测试，0 failures，0 errors。

## 残余风险

- 未运行真实 PostgreSQL / Flyway 迁移验证，V10 仍需要真实数据库验收。
- 外部 runtime owner 仍 pending，AI / New-API / SSE / Content / Knowledge 等跨 owner 闭环不能标为 completed。
- `p1r-audit-api-coverage.py` 已做 class+method mapping 扫描规则纠偏；后续若引入更复杂的 Spring 表达式、常量路径或自定义组合注解，仍需要单独评审扫描器覆盖范围。
- 当前 coverage 状态只是 `needs_verification`，不是业务完成态。