107 lines
4.1 KiB
Markdown
107 lines
4.1 KiB
Markdown
# 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`，不是业务完成态。
|