docs(memory): 记录 P1R-0 基线门禁收口

2026-05-26 08:58:34 +08:00 · 2026-05-26 08:58:34 +08:00 · 6db7ce58a3
commit 6db7ce58a3
parent 25c12b9ddd
1 changed files with 235 additions and 0 deletions
--- a/docs/memorys/2026-05-26-P1R0基线门禁收口.md
+++ b/docs/memorys/2026-05-26-P1R0基线门禁收口.md
@ -0,0 +1,235 @@
+# P1R0 基线门禁收口留痕
+
+## 任务背景
+
+本次执行 `docs/superpowers/plans/2026-05-25-P1R-0-baseline-gate.md`，目标是为 P1R 真实 API 改造建立可重复运行的基线门禁。
+
+P1R-0 不负责实现真实业务 API，不修改生产 Controller、Service、Mapper 或 DDL。它只回答：
+
+- OpenAPI 合同里到底有多少 operation。
+- 当前 `muse-cloud/` 后端对每个 operation 是真实专用入口、catch-all 合同入口、通用持久化入口、SSE 占位入口，还是缺入口。
+- 哪些 operation 绝不能在 P1R-0 阶段被误判为完成。
+- 后续 P1R-1 到 P1R-7 应该基于哪份机器可读矩阵继续推进。
+
+## 计划原始目标
+
+计划要求新增一套 API 覆盖矩阵门禁：
+
+- 新增 `muse-cloud/scripts/p1r-audit-api-coverage.py`。
+- 解析 `docs/api-contracts/*/openapi.yaml`。
+- 扫描 `muse-cloud/` Java 源码。
+- 生成：
+  - `docs/superpowers/reports/p1r-api-coverage.json`
+  - `docs/superpowers/reports/p1r-api-coverage.md`
+- 新增 Maven 测试：
+  - `muse-cloud/muse-server/src/test/java/cn/iocoder/muse/server/framework/api/P1rApiCoverageReportTest.java`
+- 保证 P1R-0 不把 catch-all、generic persistence、SSE placeholder、missing 这类非真实实现标记为完成。
+
+## 实际完成内容
+
+P1R-0 在独立 worktree 中完成：
+
+```text
+/Users/qingse/.config/superpowers/worktrees/oh-my-muse/feature-p1r-0-baseline-gate
+```
+
+分支：
+
+```text
+feature/p1r-0-baseline-gate
+```
+
+关键提交：
+
+```text
+97f1f3a chore(p1r): 生成 API 覆盖基线矩阵
+7d35ce7 fix(p1r): 修正 API 覆盖矩阵识别规则
+4084fce fix(p1r): 收紧 API 覆盖矩阵路由匹配
+0d16c21 fix(p1r): 修正 API 覆盖矩阵必填与入口归属
+9a32e3d fix(p1r): 强化覆盖矩阵完成状态校验
+83d7df1 test(p1r): 增加 API 覆盖矩阵门禁
+19e673c fix(p1r): 对齐基线门禁验证规则
+```
+
+实际产物：
+
+- 审计脚本：`muse-cloud/scripts/p1r-audit-api-coverage.py`
+- JSON 报告：`docs/superpowers/reports/p1r-api-coverage.json`
+- Markdown 报告：`docs/superpowers/reports/p1r-api-coverage.md`
+- Maven 门禁：`muse-cloud/muse-server/src/test/java/cn/iocoder/muse/server/framework/api/P1rApiCoverageReportTest.java`
+- 规格与计划命令同步更新：
+  - `docs/superpowers/specs/2026-05-25-P1R-0-baseline-gate-design.md`
+  - `docs/superpowers/plans/2026-05-25-P1R-0-baseline-gate.md`
+
+## 关键结果
+
+最终报告统计：
+
+```text
+totalOperations=233
+completedOperations=0
+catchAllOperations=36
+genericPersistenceOperations=180
+ssePlaceholderOperations=2
+missingOperations=0
+```
+
+`completedOperations=0` 是预期结果。P1R-0 是基线审计，不跑领域真实验收，所以不能宣称任何 operation 已完成。
+
+非真实实现状态规则已经统一到脚本、Maven 测试、规格和计划：
+
+- `catch_all`
+- `generic_persistence`
+- `sse_placeholder`
+- `missing`
+
+这些 implementationStatus 对应的 completionStatus 只能是：
+
+- `incomplete`
+- `blocked`
+
+不能是 `completed`，也不能是 `needs_verification`。
+
+## Maven 行为结论
+
+计划原始命令是：
+
+```bash
+cd muse-cloud
+mvn -o test -pl muse-server -am -Dtest=P1rApiCoverageReportTest
+```
+
+实测该命令会失败在上游模块，例如 `muse-common`：
+
+```text
+No tests matching pattern "P1rApiCoverageReportTest" were executed!
+```
+
+根因：
+
+- `-pl muse-server -am` 会把 `muse-server` 的上游 reactor 模块一起拉入构建。
+- `-Dtest=P1rApiCoverageReportTest` 是全局 surefire 参数。
+- 上游模块没有这个测试类，默认会因为“指定测试不存在”失败。
+
+正确行为不是修改父 POM。父 POM 全局关闭 `failIfNoSpecifiedTests` 会改变全仓测试语义，容易掩盖测试名拼写错误。
+
+正确的局部命令是：
+
+```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 -Dsurefire.failIfNoSpecifiedTests=false
+```
+
+含义：
+
+- 运行环境必须是 Java 21。
+- 上游 reactor 模块没有 `P1rApiCoverageReportTest` 不应失败。
+- 真正需要执行目标门禁测试的是 `muse-server`。
+
+## 验证记录
+
+执行过的验证：
+
+```bash
+python3 muse-cloud/scripts/p1r-audit-api-coverage.py --check
+```
+
+结果：
+
+```text
+Generated docs/superpowers/reports/p1r-api-coverage.json
+Generated docs/superpowers/reports/p1r-api-coverage.md
+```
+
+报告一致性验证：
+
+```bash
+python3 - <<'PY'
+import json
+from pathlib import Path
+report = json.loads(Path("docs/superpowers/reports/p1r-api-coverage.json").read_text())
+summary = report["summary"]
+count = len(report["operations"])
+assert summary["totalOperations"] == count, (summary["totalOperations"], count)
+assert summary["completedOperations"] == 0, summary["completedOperations"]
+for op in report["operations"]:
+    assert op["completionStatus"] != "completed", op["operationId"]
+    if op["implementationStatus"] in {"catch_all", "generic_persistence", "sse_placeholder", "missing"}:
+        assert op["completionStatus"] in {"incomplete", "blocked"}, op["operationId"]
+print("P1R-0 report consistency OK:", count, "operations")
+PY
+```
+
+结果：
+
+```text
+P1R-0 report consistency OK: 233 operations
+```
+
+脚本负例验证：
+
+- 将内存中的 non-real operation 临时改成 `needs_verification`。
+- 调用 `validate_report(report)`。
+- 结果按预期失败，说明脚本会拒绝 non-real `needs_verification`。
+
+输出：
+
+```text
+P1R-0 negative validate_report OK: adminCreateCallAttributionJob
+```
+
+Maven 门禁：
+
+```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 -Dsurefire.failIfNoSpecifiedTests=false
+```
+
+结果：
+
+```text
+Running cn.iocoder.muse.server.framework.api.P1rApiCoverageReportTest
+Tests run: 5, Failures: 0, Errors: 0, Skipped: 0
+BUILD SUCCESS
+```
+
+## 当前集成状态
+
+截至本留痕创建时：
+
+- P1R-0 已在 `feature/p1r-0-baseline-gate` 分支完成并提交。
+- 用户曾要求合并到 `main`，但随后中断该回合并改为“进行总结留痕”。
+- 因此当前记录只确认 P1R-0 分支完成，不确认已经合并到 `main`。
+- 主工作区 `/Users/qingse/Sync/local-git/oh-my-muse` 当时仍在 `feature/p1-muse-cloud-backend-20260524`，且有其他未提交或未跟踪内容，不能当作干净 main 合并面。
+
+后续如果要继续合并，需要重新执行：
+
+```bash
+cd /Users/qingse/.config/superpowers/worktrees/oh-my-muse/feature-p1r-0-baseline-gate
+git status --short
+git branch --show-current
+```
+
+确认干净后，再按实际 base 分支执行 merge / PR 流程。
+
+## 下个阶段
+
+下个阶段是：
+
+```text
+P1R-1 Content Real API spec + plan
+```
+
+P1R-1 不应该继续做基线扫描，而应该基于 P1R-0 报告开始真实业务 API 改造设计。
+
+建议步骤：
+
+1. 从 `docs/superpowers/reports/p1r-api-coverage.json` 筛出 Content 域 operation。
+2. 分清哪些 Content operation 仍是 `catch_all` 或 `generic_persistence`。
+3. 写 P1R-1 Content Real API 规格，明确真实 Controller、Service、DTO、持久化、幂等、权限和审计闭环。
+4. 写 P1R-1 执行计划。
+5. 再进入实现，不要直接从 catch-all 适配拼接到另一个临时 spec。
+
+P1R-1 的核心目标是把 Content 域从“合同可响应”推进到“真实业务 API 可验收”。