zizi-al/oh-my-muse
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
oh-my-muse/docs/agent-specs/2026-06-10-P1RMetaCompletedApproval审阅版.md
zizi 16e9f4ee72 test(p1r): 收口 Meta completed approval 门禁 
只推进 11 个 MetaSchema 管理 operation 到 dedicated/completed，保留 FunctionChain 与 ProtectionNode 的 5 个 operation 为 dedicated/needs_verification。同步 scanner approval 白名单、coverage report、P1R gate 测试和阶段留痕，避免把 Meta 扩写成整域 completed。
2026-06-10 17:09:01 +08:00

312 lines
15 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# P1R Meta Completed Approval 审阅版
日期：2026-06-10
## 结论
推荐把 Meta 作为剩余业务域 completed approval 的第一候选，但当前 Meta 仍不是 `completed`。
本审阅版只冻结 Meta completed approval 的范围、证据缺口、推荐审批粒度和后续执行版要求。不修改 OpenAPI，不修改 scanner，不修改 coverage report，不修改业务代码，不把 Meta 或其它 domain 推进 `completed`。
推荐审批策略：
```text
Meta domain-level approval candidate
```
前提是后续执行版能一次性证明 Meta 16 个 operation 的真实运行态、数据迁移、状态机、权限、审计、幂等和失败路径证据。如果任一 operation 无法满足 completed 证据，必须退回 operation-level approval，不能整域推进。
## 审批路径
```mermaid
flowchart TB
Start["当前 coverage<br/>Meta 16 dedicated / needs_verification"] --> Review["本审阅版<br/>冻结 Meta completed 证据标准"]
Review --> FreshReview["fresh spec/scope review<br/>fresh quality/feasibility review"]
FreshReview --> ExecDoc["执行版<br/>列出测试、迁移、scanner/report/gate 修改"]
ExecDoc --> ExecReview["执行版 fresh 双 review"]
ExecReview --> UserApproval{"用户明确批准<br/>Meta completed 推进?"}
UserApproval -->|否| Stop["保持 needs_verification"]
UserApproval -->|是| Implement["只按执行版允许路径修改<br/>scanner / gate / report / 必要测试"]
Implement --> Verify["focused tests + P1R gates<br/>真实 Flyway _test + XML 防空跑<br/>allowed/protected diff"]
Verify --> ImplReview["fresh implementation 双 review"]
ImplReview --> FinalApproval{"用户批准提交和 push?"}
FinalApproval -->|否| LocalOnly["保留本地 evidence"]
FinalApproval -->|是| Commit["提交并 push"]
```
## 已验证事实
### 工作区与远端
- 工作区：`/Users/qingse/.config/superpowers/worktrees/oh-my-muse/dev-1.0.0`。
- 分支：`dev/1.0.0`。
- 当前远端：`origin/dev/1.0.0`。
- 本轮已执行 `git pull --ff-only origin dev/1.0.0`，结果为 `Already up to date.`。
- 当前 HEAD：
```text
85c5422 test(p1r): 收口 P1R-7 completed approval 门禁
```
### 当前 coverage 状态
当前 `docs/superpowers/reports/p1r-api-coverage.json` summary：
```text
totalOperations 233
completedOperations 101
needsVerificationOperations 132
incompleteOperations 0
genericPersistenceOperations 0
ssePlaceholderOperations 0
missingOperations 0
blockedOperations 0
```
Meta 当前状态：
```text
meta_count 16
implementationStatus dedicated:16
completionStatus needs_verification:16
```
Meta 16 个 operation：
| operationId | method/path | 当前状态 |
| --- | --- | --- |
| `listMetaSchemas` | `GET /admin-api/muse/governance/meta-schemas` | `dedicated / needs_verification` |
| `getMetaSchema` | `GET /admin-api/muse/governance/meta-schemas/{schemaKey}` | `dedicated / needs_verification` |
| `getMetaSchemaVersion` | `GET /admin-api/muse/governance/meta-schemas/{schemaKey}/versions/{version}` | `dedicated / needs_verification` |
| `saveMetaSchemaDraft` | `POST /admin-api/muse/governance/meta-schemas/{schemaKey}/drafts` | `dedicated / needs_verification` |
| `validateMetaSchemaDraft` | `POST /admin-api/muse/governance/meta-schemas/{schemaKey}/drafts/{draftVersion}/validate` | `dedicated / needs_verification` |
| `previewMetaSchemaDraftImpact` | `POST /admin-api/muse/governance/meta-schemas/{schemaKey}/drafts/{draftVersion}/impact-preview` | `dedicated / needs_verification` |
| `publishMetaSchemaDraft` | `POST /admin-api/muse/governance/meta-schemas/{schemaKey}/drafts/{draftVersion}/publish` | `dedicated / needs_verification` |
| `activateMetaSchemaVersion` | `POST /admin-api/muse/governance/meta-schemas/{schemaKey}/versions/{version}/activate` | `dedicated / needs_verification` |
| `rollbackMetaSchemaVersion` | `POST /admin-api/muse/governance/meta-schemas/{schemaKey}/versions/{version}/rollback` | `dedicated / needs_verification` |
| `deprecateMetaSchemaVersion` | `POST /admin-api/muse/governance/meta-schemas/{schemaKey}/versions/{version}/deprecate` | `dedicated / needs_verification` |
| `setMetaSchemaGrayRules` | `POST /admin-api/muse/governance/meta-schemas/{schemaKey}/versions/{version}/gray-rules` | `dedicated / needs_verification` |
| `listProtectionNodes` | `GET /admin-api/muse/governance/protection-nodes` | `dedicated / needs_verification` |
| `getProtectionNode` | `GET /admin-api/muse/governance/protection-nodes/{nodeKey}` | `dedicated / needs_verification` |
| `listFunctionChains` | `GET /admin-api/muse/governance/function-chains` | `dedicated / needs_verification` |
| `previewFunctionChainImpact` | `POST /admin-api/muse/governance/function-chains/{chainKey}/impact-preview` | `dedicated / needs_verification` |
| `activateFunctionChainVersion` | `POST /admin-api/muse/governance/function-chains/{chainKey}/versions/{version}/activate` | `dedicated / needs_verification` |
### 已有 dedicated 实现证据
Meta 已有 dedicated Controller：
- `AdminMetaSchemaController`
- `AdminProtectionNodeController`
- `AdminFunctionChainController`
这三个 Controller 均使用 `/muse/governance/...` 类级路由，方法级 `@GetMapping` / `@PostMapping` 覆盖 Meta 16 个 operation，并通过 `@PreAuthorize` 绑定管理端权限。
这三个 Controller 都调用 `MetaApiVersionGuard.requireVersion(...)` 校验 `X-API-Version`，缺少版本头时不回退到旧合同兜底结果。
Meta 已有 dedicated Service / Guard / DAL：
- `MetaSchemaServiceImpl`
- `MetaSchemaValidationServiceImpl`
- `MetaSchemaImpactPreviewServiceImpl`
- `ProtectionNodeServiceImpl`
- `FunctionChainServiceImpl`
- `MetaCommandServiceImpl`
- `MetaAuditServiceImpl`
- `MetaVersionStateGuard`
- `MetaProtectionNodeGuard`
- `FunctionChainGuard`
- Meta DO / Mapper / Convert 文件
Meta 旧合同兜底路由已有退役测试：
- `AdminMuseMetaContractControllerTest.should_notKeepGenericMetaContractControllerOnClasspath`
### 已有状态机、幂等、审计与失败边界证据
`MetaSchemaServiceImpl` 已覆盖：
- save draft
- publish
- activate
- rollback
- deprecate
- gray rules
- command reservation
- command replay
- governance audit
`MetaCommandServiceImpl` 已覆盖：
- `reserveCommand(...)`
- `recordSucceeded(...)`
- request hash
- operation / actor / target envelope 校验
- 未完成 command 冲突
- succeeded command replay
`MetaAuditServiceImpl` 已把治理审计写入 `muse_meta_governance_audit`，并有测试证明审计不是复用 command `resultSnapshot` 冒充。
`MetaSchemaImpactPreviewServiceImpl` 依赖 `MetaImpactFacade`；默认 `UnavailableMetaImpactFacade` 在没有真实外部 owner bean 时抛出 `META_EXTERNAL_OWNER_UNAVAILABLE`，不是空成功。
### 已有 SQL 与测试证据
Meta 已有 migration：
- `muse-cloud/sql/muse/V10__extend_meta_real_api_schema.sql`
V10 追加：
- `muse_meta_command`
- `muse_meta_governance_audit`
- `muse_meta_validation_result`
- `muse_meta_impact_preview`
- `muse_meta_gray_rule`
- `muse_meta_function_chain_version`
- `muse_meta_function_chain_slot`
- `muse_meta_function_chain_node`
- `uk_muse_meta_schema_version_active_schema_id`
- `muse_meta_protection_node` 结构化字段
Meta 已有静态 SQL gate：
- `P1rMetaMigrationSqlTest`，3 个 `@Test`。
Meta 已有 coverage gate：
- `P1rMetaRealApiGateTest`，4 个 `@Test`。
该 gate 当前明确禁止 Meta operation 标记为 completed，并要求 Meta 保持 `dedicated / needs_verification`。
Meta 模块现有测试清单包含 16 个测试类，按源码 `@Test` 统计共 165 个测试方法；P1R Meta gate 额外包含 7 个测试方法。
## 推断
- Meta 是剩余四个业务域中最适合先走 completed approval 的候选，因为 operation 数量最少，主要围绕 Meta owner 自有治理事实，外部依赖比 Account / Market / Content 少。
- Meta 可以作为 domain-level approval 候选，但只有在后续执行版补齐真实 `_test`、XML 防空跑、审批后 coverage gate 和运行态失败路径证据后才成立。
- 当前 `P1rMetaRealApiGateTest` 的旧口径会阻止 Meta completed；后续用户批准前不能修改该 gate，用户批准后必须把它改成“只允许 Meta 16 个 operation completed，且不连带其它 domain”的审批后门禁。
## 假设
- 用户确认先从 Meta 推进剩余业务域 completed approval。
- 后续执行版允许在 fresh 双 review 与用户明确批准之后，修改 scanner、coverage report、`P1rMetaRealApiGateTest`、`P1rApiCoverageReportTest` 和必要的 Meta completed approval gate 测试。
- 如果真实 `_test` 或外部 owner fail-closed 证据证明某个 Meta operation 不满足 completed，用户接受把 Meta 从 domain-level approval 降级为 operation-level approval。
## 主要缺口
### 缺口 1：真实 Flyway `_test` 尚未覆盖 V10
当前只有 `P1rMetaMigrationSqlTest` 静态读取 V10 SQL。它证明 SQL 文本包含关键表、索引和字段，但不证明真实 PostgreSQL 可以执行，也不证明约束、partial unique index、trigger 和非法写入拒绝实际生效。
后续执行版必须新增真实 PostgreSQL `_test`，最低验证：
- schema version 到达 V10 或当前全量迁移目标中包含 V10。
- V10 追加表真实存在。
- `muse_meta_command` 的 `(tenant_id, command_id)` unique 生效。
- `muse_meta_schema_version` 的 active partial unique index 使用 `(tenant_id, schema_id)` 且同 schema 不能有两个 active 版本。
- `muse_meta_function_chain_version` 的 active partial unique index 生效。
- `muse_meta_protection_node` 结构化字段真实存在。
- V10 表的 `updated_at` trigger 可执行。
- 代表性非法 insert 被拒绝，例如重复 commandId、重复 active schema version、重复 active function chain version、必填字段为空。
### 缺口 2：当前 P1R gate 仍明确禁止 Meta completed
`P1rMetaRealApiGateTest.should_not_mark_meta_operations_as_completed` 和 `should_keep_current_meta_operations_dedicated_and_needs_verification` 当前是正确的防误升门禁。
后续执行版必须把 gate 修改分成两步：
1. 用户批准前：保持该 gate 不变，证明 Meta 仍未 completed。
2. 用户批准后：改为 completed approval gate，精确断言 Meta 16 个 operation 为 `dedicated / completed`，并断言 Account / Market / Content 仍为 `dedicated / needs_verification`。
### 缺口 3：外部 owner impact preview 需要明确 completed 口径
`MetaSchemaImpactPreviewServiceImpl` 调用 `MetaImpactFacade`。默认 `UnavailableMetaImpactFacade` 抛出 `META_EXTERNAL_OWNER_UNAVAILABLE`。
这说明当前系统没有伪造外部 owner 成功，但也意味着 completed approval 必须选择清楚：
- 如果 `previewMetaSchemaDraftImpact` 要算 completed，必须证明有真实 `MetaImpactFacade` 或明确接受 fail-closed 是该 operation 的完成口径。
- 如果真实外部 owner 不可用且该 operation 需要成功预览外部影响，必须保持该 operation `needs_verification`，不能把 bare mock 或空 summary 当 completed。
### 缺口 4：需要把 165 个 Meta 测试变成可审计 XML 证据
历史留痕记录 Meta 模块全量测试曾通过 165 个测试，但 completed approval 执行必须重新运行当前代码，并读取 Surefire XML 逐类证明：
```text
tests > 0
failures = 0
errors = 0
skipped = 0
```
后续执行版必须列出 required test classes 和最低测试数，不能只写 Maven exit 0。
### 缺口 5：scanner/report 修改必须是审批后动作
Meta completed approval 需要修改 scanner 的 completed allowlist 或 approval 模型，并重生成 coverage report。
这些动作只能在执行版 fresh 双 review 且用户明确批准后执行。用户批准前 protected diff 必须证明以下文件没有 staged/unstaged diff：
- `muse-cloud/scripts/p1r-audit-api-coverage.py`
- `docs/superpowers/reports/p1r-api-coverage.json`
- `docs/superpowers/reports/p1r-api-coverage.md`
## 推荐审批粒度
推荐先按 domain-level approval 设计 Meta 执行版：
```text
approved_completed_domains += {"meta"}
```
但执行版必须提供降级机制：
- 如果全部 16 个 operation 证据闭合，允许 domain-level approval。
- 如果 `previewMetaSchemaDraftImpact` 或其它高风险 operation 因外部 owner 不满足 completed 标准，必须降级为 operation-level approval。
- 降级时 scanner/report/gate 只能推进证据满足的 operation，不得把 Meta 整域加入 completed domain allowlist。
## 非目标
- 不修改 `docs/api-contracts/meta/openapi.yaml`。
- 不修改任何其它 OpenAPI 文件。
- 不修改 `muse-cloud/scripts/p1r-audit-api-coverage.py`。
- 不修改 `docs/superpowers/reports/p1r-api-coverage.json`。
- 不修改 `docs/superpowers/reports/p1r-api-coverage.md`。
- 不修改 Meta 业务实现代码。
- 不推进 Account / Market / Content completed。
- 不推进总 P1R completed。
- 不把 P1R-7 Events completed approval 或 source owner propagation evidence 当作 Meta completed 证据。
## 后续执行版必须包含
1. Meta 16 operation 的完整清单与目标状态。
2. 允许修改文件清单；至少区分用户批准前和批准后。
3. scanner approval 模型：domain-level Meta 或 operation-level fallback，二选一并写明触发条件。
4. `P1rMetaRealApiGateTest` 从禁止 completed 到审批后 completed gate 的修改策略。
5. `P1rApiCoverageReportTest` summary 期望从 `completed=101 / needsVerification=132` 到目标值的修改策略。
6. 真实 PostgreSQL Flyway `_test`：目标 schema version、V10 表、索引、约束、trigger、非法 insert 拒绝。
7. Meta focused tests：16 个测试类逐类 XML 计数下限。
8. P1R mixed gates：包含 Meta gate、coverage report gate，以及用于证明非目标 domain 不被推进的 Account / Market / Content gate。
9. `/tmp/p1r-meta-completed-approval-scan.*` 隔离 scanner 预验证。
10. 真实 worktree scanner/report 重生成只允许在执行版双 PASS 和用户批准后执行。
11. protected diff gate，必须覆盖 7 个 OpenAPI、scanner 和 coverage report。
12. allowed-diff gate，必须覆盖 unstaged / staged / untracked，并使用 `core.quotePath=false`。
13. implementation review 复核项：新增 completed 只覆盖用户批准范围；非目标 domain 状态不变；XML 防空跑和 `_test` 证据完整。
14. rollback 策略：撤回 scanner allowlist、coverage report、gate test 和新增 `_test`，恢复 Meta 为 `dedicated / needs_verification`。
## 验收标准
本审阅版可以视为完成的条件：
1. 文件写入 `docs/agent-specs/2026-06-10-P1RMetaCompletedApproval审阅版.md`。
2. `.agent` 记录 Meta completed approval 审阅版状态。
3. `git diff --check` 通过。
4. OpenAPI、scanner、coverage report 无 diff。
5. 本审阅版通过 fresh spec/scope review 和 fresh quality/feasibility review。
## 待确认项
1. 是否确认 Meta 作为剩余业务域 completed approval 第一候选。
2. 是否确认先按 Meta domain-level approval 设计执行版，并保留 operation-level fallback。
3. 是否确认用户批准前不得修改 scanner、coverage report、coverage gate 或 Meta 业务代码。
4. 是否确认真实 Flyway `_test` 是 Meta completed approval 的硬门槛。
Reference in New Issue View Git Blame Copy Permalink