334 lines
16 KiB
Markdown
334 lines
16 KiB
Markdown
# P1R Meta Remaining 5 Completed Approval 审阅版
|
||
|
||
日期：2026-06-10
|
||
|
||
## 结论
|
||
|
||
推荐把 Meta 剩余 5 个 `dedicated / needs_verification` operation 作为下一段 completed approval 候选，但当前不建议直接推进 `completed`。
|
||
|
||
本审阅版只冻结范围、证据缺口、推荐审批粒度和后续执行版要求。不修改 OpenAPI，不修改 scanner，不修改 coverage report，不修改业务代码，不把剩余 5 个 Meta operation 或其它 domain 推进 `completed`。
|
||
|
||
推荐审批策略：
|
||
|
||
```text
|
||
operation-level approval for Meta remaining 5
|
||
```
|
||
|
||
原因是 MetaSchema 11 个 operation 已完成 operation-level approval；剩余 5 个 operation 分属 ProtectionNode 和 FunctionChain，证据形态不同。如果改成 Meta domain-level approval，会把两类治理读模型和功能链写命令一次性绑定，风险比继续 operation-level approval 更高。
|
||
|
||
## 审批路径
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
Start["当前 coverage<br/>Meta 11 completed + 5 needs_verification"] --> Review["本审阅版<br/>冻结剩余 5 个 operation 范围"]
|
||
Review --> FreshReview["fresh spec/scope review<br/>fresh quality/feasibility review"]
|
||
FreshReview --> ExecDoc["执行版<br/>列出证据、门禁、allowed diff"]
|
||
ExecDoc --> ExecReview["执行版 fresh 双 review"]
|
||
ExecReview --> UserApproval{"用户明确批准<br/>剩余 5 个 operation completed?"}
|
||
UserApproval -->|否| Stop["保持 needs_verification"]
|
||
UserApproval -->|是| Implement["只按执行版允许路径修改<br/>scanner / gate / report / 必要测试"]
|
||
Implement --> Verify["focused tests + P1R gates<br/>Flyway _test + XML 防空跑<br/>protected / allowed diff"]
|
||
Verify --> ImplReview["fresh implementation 双 review"]
|
||
ImplReview --> FinalApproval{"用户批准提交和 push?"}
|
||
FinalApproval -->|否| LocalOnly["保留本地 evidence"]
|
||
FinalApproval -->|是| Commit["提交并 push"]
|
||
```
|
||
|
||
## 已验证事实
|
||
|
||
### 工作区与当前状态
|
||
|
||
- 正确 worktree：`/Users/qingse/.config/superpowers/worktrees/oh-my-muse/dev-1.0.0`。
|
||
- 当前分支：`dev/1.0.0`。
|
||
- 当前本地与 `origin/dev/1.0.0` 对齐。
|
||
- 当前 HEAD：
|
||
|
||
```text
|
||
16e9f4e test(p1r): 收口 Meta completed approval 门禁
|
||
```
|
||
|
||
当前 coverage summary：
|
||
|
||
```text
|
||
totalOperations 233
|
||
completedOperations 112
|
||
needsVerificationOperations 121
|
||
incompleteOperations 0
|
||
genericPersistenceOperations 0
|
||
ssePlaceholderOperations 0
|
||
```
|
||
|
||
Meta 当前状态：
|
||
|
||
```text
|
||
meta dedicated/completed:11
|
||
meta dedicated/needs_verification:5
|
||
```
|
||
|
||
### 本轮候选 operation
|
||
|
||
本审阅版只覆盖以下 5 个 Meta operation：
|
||
|
||
| operationId | method/path | 当前状态 |
|
||
| --- | --- | --- |
|
||
| `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` |
|
||
|
||
非候选范围：
|
||
|
||
- 已 completed 的 MetaSchema 11 个 operation。
|
||
- Account 33、Market 32、Content 51。
|
||
- 总 P1R completed。
|
||
- 任何 OpenAPI 合同修改。
|
||
- 任何 Meta 业务实现补丁。
|
||
|
||
### 已有 dedicated 实现证据
|
||
|
||
ProtectionNode 已有 dedicated Controller / Service：
|
||
|
||
- `AdminProtectionNodeController`
|
||
- `ProtectionNodeService`
|
||
- `ProtectionNodeServiceImpl`
|
||
|
||
`AdminProtectionNodeController` 使用 `/muse/governance/protection-nodes` 类级路由，覆盖 list/detail 两个 operation，且使用 `@PreAuthorize("@ss.hasPermission('muse:meta:query')")`。Controller 调用 `MetaApiVersionGuard.requireVersion(...)`，缺少 `X-API-Version` 时不回退到旧合同兜底结果。
|
||
|
||
`ProtectionNodeServiceImpl` 只读取 `muse_meta_protection_node` 持久化事实和 `policySnapshot` 中的 `chainKey` 轻量关联，不调用 `MuseContractPersistenceService`。查询只返回 `status='active'` 的保护节点；detail 不存在时抛出 `META_PROTECTION_NODE_NOT_FOUND`。
|
||
|
||
FunctionChain 已有 dedicated Controller / Service：
|
||
|
||
- `AdminFunctionChainController`
|
||
- `FunctionChainService`
|
||
- `FunctionChainServiceImpl`
|
||
|
||
`AdminFunctionChainController` 使用 `/muse/governance/function-chains` 类级路由，覆盖 list / impact-preview / activate 三个 operation，且绑定管理端权限：
|
||
|
||
- 查询：`muse:meta:query`
|
||
- 影响预览与激活：`muse:meta:function-chain`
|
||
|
||
`FunctionChainServiceImpl` 已覆盖：
|
||
|
||
- active version 读取。
|
||
- open slot 与 protection node count 计算。
|
||
- preview commandId / requestHash 幂等预占与成功回放。
|
||
- targetVersion 解析。
|
||
- validation result 和 impact preview 持久化。
|
||
- activate commandId / requestHash 幂等回放。
|
||
- published-only 激活。
|
||
- expected active version 冲突检测。
|
||
- validationResult / impactPreview 同源校验。
|
||
- protection boundary violation 阻断。
|
||
- active version 原子更新。
|
||
- governance audit 与 command succeeded 记录。
|
||
|
||
### 已有保护边界证据
|
||
|
||
`FunctionChainGuard` 与 `MetaProtectionNodeGuard` 已声明保护节点不能被替换或降级：
|
||
|
||
- `requireActivationAllowed(...)` 只允许 `published` 状态激活。
|
||
- `requireNoProtectionBoundaryViolation(...)` 在影响预览发现保护边界违规时抛出 `META_PROTECTION_NODE_IMMUTABLE`。
|
||
- `MetaProtectionNodeGuard.requireNotReplaced(...)` 禁止把 canonical 保护节点换成其它节点。
|
||
- `MetaProtectionNodeGuard.requireNotDowngraded(...)` 禁止不可替换保护节点降级为可替换。
|
||
- `MetaProtectionNodeGuard.requireFunctionChainNodePreservesProtection(...)` 统一 FunctionChain 编排下的保护边界语义。
|
||
|
||
`FunctionChainServiceImpl` 的 activation 流程在写 active version 前会调用 `requireProtectionBindingsPreserved(...)`，并基于 active / target version 的 node binding diff 阻断保护节点移除、解绑或降级。
|
||
|
||
### 已有 SQL 与测试证据
|
||
|
||
V10 migration 已包含 FunctionChain 和 ProtectionNode 相关结构：
|
||
|
||
- `muse_meta_function_chain_version`
|
||
- `muse_meta_function_chain_slot`
|
||
- `muse_meta_function_chain_node`
|
||
- `uk_muse_meta_function_chain_version_active`
|
||
- `muse_meta_protection_node` 结构化字段追加
|
||
- 对应 `updated_at` trigger
|
||
|
||
当前只有静态 SQL gate：
|
||
|
||
- `P1rMetaMigrationSqlTest`，3 个 `@Test`。
|
||
|
||
与剩余 5 个 operation 直接相关的现有测试：
|
||
|
||
| 测试类 | `@Test` 数量 |
|
||
| --- | ---: |
|
||
| `ProtectionNodeServiceTest` | 3 |
|
||
| `FunctionChainServiceTest` | 12 |
|
||
| `AdminProtectionNodeControllerTest` | 7 |
|
||
| `AdminFunctionChainControllerTest` | 7 |
|
||
| `FunctionChainGuardTest` | 4 |
|
||
| `MetaProtectionNodeGuardTest` | 5 |
|
||
|
||
`P1rMetaRealApiGateTest` 当前明确要求：
|
||
|
||
- Meta 16 个 operation 都必须是 `dedicated`。
|
||
- MetaSchema 11 个 operation 必须是 `completed`。
|
||
- FunctionChain / ProtectionNode 5 个 operation 必须保持 `needs_verification`。
|
||
- Meta 仍不是 16/16 completed。
|
||
|
||
### 保护面当前无 diff
|
||
|
||
本审阅版写入前已只读检查：
|
||
|
||
```bash
|
||
git -c core.quotePath=false diff --name-only -- docs/api-contracts muse-cloud/scripts docs/superpowers/reports
|
||
```
|
||
|
||
输出为空，说明 OpenAPI、scanner、coverage report 当前无 unstaged diff。
|
||
|
||
## 推断
|
||
|
||
- ProtectionNode 的两个 operation 是治理读模型，完成证据主要来自真实持久化、版本头、权限、active 过滤、detail not-found、结构化字段和非 generic fallback。
|
||
- FunctionChain 的三个 operation 是治理读写混合，完成证据必须覆盖幂等、状态机、active partial unique、保护节点不可降级、validation / impact preview 同源校验、审计和命令回放。
|
||
- 这 5 个 operation 可以继续 operation-level approval；不需要把 `meta` 加入 domain-level completed 白名单。
|
||
- 如果执行版能证明 V10 真实 `_test`、FunctionChain active 唯一约束、ProtectionNode 结构化字段、XML 防空跑和 P1R mixed gates，剩余 5 个 operation 才具备进入用户批准点的条件。
|
||
|
||
## 假设
|
||
|
||
- 用户希望继续 P1R 主线，并优先收口 Meta 剩余 operation，而不是切到 Account / Market / Content。
|
||
- 用户仍要求 completed 状态推进必须单独批准，不能由 dedicated gate、review PASS 或文档结论自动推进。
|
||
- 如果真实 `_test` 或 focused tests 发现 FunctionChain / ProtectionNode 证据不足，用户接受继续保持对应 operation `needs_verification`。
|
||
|
||
## 主要缺口
|
||
|
||
### 缺口 1：真实 Flyway `_test` 尚未证明 V10 FunctionChain / ProtectionNode 约束
|
||
|
||
现有 `P1rMetaMigrationSqlTest` 只做静态 SQL 文本检查。后续执行版必须新增真实 PostgreSQL `_test`，最低验证：
|
||
|
||
- schema version 到达至少 V10。
|
||
- `muse_meta_function_chain_version`、`muse_meta_function_chain_slot`、`muse_meta_function_chain_node` 真实存在。
|
||
- `muse_meta_function_chain_version` 的 `(tenant_id, chain_id, version_no)` unique 生效。
|
||
- `uk_muse_meta_function_chain_version_active` partial unique 生效，同 tenant / chain 不能有两个 active 版本。
|
||
- `muse_meta_protection_node` 的结构化字段真实存在。
|
||
- FunctionChain / ProtectionNode 相关 `updated_at` trigger 可执行。
|
||
- 代表性非法 insert 被拒绝，例如重复 active function chain version、缺少必填字段、重复 chain version。
|
||
|
||
### 缺口 2：FunctionChain 影响预览仍使用 Meta owner 自有影响摘要
|
||
|
||
`FunctionChainServiceImpl` 当前对外部 AI runtime / New-API / SSE 影响使用固定 0 和 `externalRuntime=pending` 摘要，没有接入真实外部 owner。
|
||
|
||
这不一定阻塞 completed，但执行版必须明确 completed 口径：
|
||
|
||
- 如果 `previewFunctionChainImpact` 的完成定义是 Meta owner 自有链路影响预览，则必须证明 pending 摘要是设计边界，不是伪成功。
|
||
- 如果完成定义要求真实外部 runtime 影响，则 `previewFunctionChainImpact` 必须继续保持 `needs_verification`。
|
||
|
||
### 缺口 3：FunctionChain activation 需要强证据证明保护边界不可绕过
|
||
|
||
已有 `FunctionChainGuard` 与 `MetaProtectionNodeGuard`，但 completed approval 需要当前代码的 XML 证据和 P1R gate 明确覆盖：
|
||
|
||
- `published` 以外版本不能激活。
|
||
- expected active version 不匹配时拒绝。
|
||
- validation result 与 impact preview 不同源时拒绝。
|
||
- impact preview 包含 protection boundary violation 时拒绝。
|
||
- active 版本切换时旧 active 被关闭，新 active 唯一。
|
||
- commandId / requestHash 成功回放不重复写审计或状态。
|
||
|
||
### 缺口 4：ProtectionNode 查询需要证明不是静态配置或 generic fallback
|
||
|
||
执行版必须要求测试证明：
|
||
|
||
- list 从 `muse_meta_protection_node` 读取 active 节点。
|
||
- `chainKey` 过滤来自 `policySnapshot` 中的 `chainKey`。
|
||
- detail 返回结构化治理字段。
|
||
- missing node 返回 `META_PROTECTION_NODE_NOT_FOUND`。
|
||
- Controller 缺版本头或未知版本时不调用 Service。
|
||
- Controller 不注入 `MuseContractPersistenceService`。
|
||
|
||
### 缺口 5：coverage gate 仍明确禁止剩余 5 个 operation completed
|
||
|
||
`P1rMetaRealApiGateTest` 当前是正确的防误升门禁。执行版必须把 gate 修改分成两步：
|
||
|
||
1. 用户批准前：保持剩余 5 个 operation 为 `needs_verification`。
|
||
2. 用户批准后：只把这 5 个 operation 推进 `completed`，并断言 Account / Market / Content 仍保持 `dedicated / needs_verification`。
|
||
|
||
### 缺口 6：需要 XML 防空跑证据
|
||
|
||
后续执行版必须列出 required test classes，并读取 Surefire XML 证明：
|
||
|
||
```text
|
||
tests > 0
|
||
failures = 0
|
||
errors = 0
|
||
skipped = 0
|
||
```
|
||
|
||
最低应覆盖：
|
||
|
||
- `ProtectionNodeServiceTest`
|
||
- `FunctionChainServiceTest`
|
||
- `AdminProtectionNodeControllerTest`
|
||
- `AdminFunctionChainControllerTest`
|
||
- `FunctionChainGuardTest`
|
||
- `MetaProtectionNodeGuardTest`
|
||
- `P1rMetaRealApiGateTest`
|
||
- `P1rApiCoverageReportTest`
|
||
- 新增或修订的 Meta Flyway `_test`
|
||
|
||
## 推荐审批粒度
|
||
|
||
推荐继续 operation-level approval：
|
||
|
||
```text
|
||
APPROVED_COMPLETED_OPERATIONS += {
|
||
"meta:listProtectionNodes",
|
||
"meta:getProtectionNode",
|
||
"meta:listFunctionChains",
|
||
"meta:previewFunctionChainImpact",
|
||
"meta:activateFunctionChainVersion"
|
||
}
|
||
```
|
||
|
||
不推荐本轮把 `meta` 加入 completed domain allowlist，原因：
|
||
|
||
- MetaSchema 11 已经走 operation-level approval。
|
||
- 剩余 5 个 operation 的证据集中在 FunctionChain / ProtectionNode，不需要覆盖未来 Meta 新 operation。
|
||
- operation-level approval 能精确防止未来 Meta operation 误继承 completed。
|
||
|
||
## 非目标
|
||
|
||
- 不修改 `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。
|
||
- 不把 MetaSchema 11 个 operation 的 completed 证据扩写成剩余 5 个 operation 的证据。
|
||
|
||
## 后续执行版必须包含
|
||
|
||
1. 剩余 5 个 operation 的完整清单与目标状态。
|
||
2. 用户批准前和批准后的允许修改文件清单。
|
||
3. scanner approval 模型：只允许新增 5 个 operation-level approval。
|
||
4. `P1rMetaRealApiGateTest` 从“剩余 5 个必须 needs_verification”改为“剩余 5 个批准后必须 completed”的策略。
|
||
5. `P1rApiCoverageReportTest` summary 从 `completed=112 / needsVerification=121` 到 `completed=117 / needsVerification=116` 的修改策略。
|
||
6. 真实 PostgreSQL Flyway `_test`：FunctionChain / ProtectionNode 相关表、索引、约束、trigger 和非法 insert 拒绝。
|
||
7. FunctionChain focused tests：list、preview、activate、replay、conflict、validation / impact preview 同源、protection boundary、audit。
|
||
8. ProtectionNode focused tests：list、detail、active filter、chainKey filter、missing node、结构化字段、版本头和权限。
|
||
9. P1R mixed gates：coverage report gate、Meta gate、Account / Market / Content 非目标 gate。
|
||
10. XML 防空跑：逐类读取 surefire XML 并断言 tests > 0。
|
||
11. protected diff gate：覆盖 7 个 OpenAPI、scanner 和 coverage report。
|
||
12. allowed-diff gate：覆盖 unstaged / staged / untracked，并使用 `core.quotePath=false`。
|
||
13. implementation review 复核项：新增 completed 只覆盖剩余 5 个 operation，Meta 最终 16/16 completed，Account / Market / Content 不变。
|
||
14. rollback 策略：撤回 scanner allowlist、coverage report、gate test 和新增 `_test`，恢复剩余 5 个 operation 为 `dedicated / needs_verification`。
|
||
|
||
## 验收标准
|
||
|
||
本审阅版可以视为完成的条件：
|
||
|
||
1. 文件写入 `docs/agent-specs/2026-06-10-P1RMetaRemaining5CompletedApproval审阅版.md`。
|
||
2. `.agent` 记录 Meta 剩余 5 个 operation completed approval 审阅版状态。
|
||
3. `git diff --check` 通过。
|
||
4. OpenAPI、scanner、coverage report 无 diff。
|
||
5. 本审阅版通过 fresh spec/scope review 和 fresh quality/feasibility review。
|
||
|
||
## 待确认项
|
||
|
||
1. 是否确认下一段优先处理 Meta 剩余 5 个 operation，而不是 Account / Market / Content。
|
||
2. 是否确认继续使用 operation-level approval，不把 `meta` 加入 domain-level completed allowlist。
|
||
3. 是否确认用户批准前不得修改 scanner、coverage report、coverage gate 或 Meta 业务代码。
|
||
4. 是否确认真实 Flyway `_test` 是剩余 5 个 operation completed approval 的硬门槛。
|