97 lines
4.2 KiB
Markdown
97 lines
4.2 KiB
Markdown
# P1R2 元治理规格计划留痕
|
||
|
||
## 任务背景
|
||
|
||
本次进入 P1R-2 Meta Real API spec + plan 阶段，目标是先完成 Meta 域真实业务 API 的事实盘点、规格和执行计划，不进入代码实现。
|
||
|
||
P1R-2 的核心不是继续增强 `MuseContractPersistenceService`，也不是把通用持久化响应包装成 Meta 业务结果，而是把 Meta 域从“通用持久化可响应”推进到“真实 Meta 治理 API 可验收”的规格和计划阶段。
|
||
|
||
## 执行位置
|
||
|
||
```text
|
||
/Users/qingse/.config/superpowers/worktrees/oh-my-muse/dev-1.0.0
|
||
```
|
||
|
||
分支：
|
||
|
||
```text
|
||
dev/1.0.0
|
||
```
|
||
|
||
说明：`/Users/qingse/Sync/local-git/oh-my-muse` 当前不是本阶段真实工作面，核验时位于 `feature/p1-muse-cloud-backend-20260524` 且有未跟踪文件。`dev/1.0.0` 已由上面的 superpowers worktree 占用。
|
||
|
||
## 已验证事实
|
||
|
||
P1R 覆盖矩阵中 Meta 域当前状态：
|
||
|
||
```text
|
||
16 generic_persistence / incomplete
|
||
```
|
||
|
||
Meta 16 个 operation 全部来自 `docs/api-contracts/meta/openapi.yaml`，当前没有 `dedicated / needs_verification`、`catch_all`、`sse_placeholder` 或 `missing`。
|
||
|
||
当前 Meta 模块事实：
|
||
|
||
- `muse-module-meta-server` 只有 `AdminMuseMetaContractController`。
|
||
- 该 Controller 使用 wildcard 路由接管 `meta-schemas`、`protection-nodes`、`function-chains`。
|
||
- 当前请求统一委托 `MuseContractPersistenceService.handle(...)`。
|
||
- 当前没有 Meta 专用 Controller、Service、DTO、DO、Mapper、command/audit 服务和状态机。
|
||
|
||
当前 DDL 事实：
|
||
|
||
- V3 已有 `muse_meta_schema`、`muse_meta_schema_version`、`muse_meta_field`、`muse_meta_visibility_policy`、`muse_meta_protection_node`、`muse_meta_function_chain`。
|
||
- V3 不足以覆盖 validation result、impact preview、gray rule、FunctionChain version/slot/node relation、Meta command/audit。
|
||
- MetaSchema active 唯一约束不能按 `tenant_id + schema_key` 过度约束，应按 `tenant_id + schema_id`，因为 V3 允许 `(domain, scope, target_type, schema_key)` 组合唯一。
|
||
|
||
## 本阶段产物
|
||
|
||
- 规格：`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`
|
||
|
||
## Review 结果
|
||
|
||
本阶段使用 fresh subagent 做了两轮文档 review。
|
||
|
||
第一轮 review 未通过，阻塞点包括：
|
||
|
||
- `blocked` 状态没有 OpenAPI/coverage 可执行入口。
|
||
- Meta wildcard catch-all 路由退役顺序不清。
|
||
- Task 1 clean worktree 预期未考虑新增 review 文档。
|
||
- DDL active 唯一约束 identity 与 V3 不一致。
|
||
- rollback/deprecate 缺少 OpenAPI required 字段落地要求。
|
||
- `previewMetaSchemaDraftImpact` 缺少等价幂等键。
|
||
- 权限和 `code/data/msg` controller 验收不够明确。
|
||
|
||
修正后第二轮 review 通过：
|
||
|
||
- P1R-2 收口状态统一为 `dedicated / needs_verification`，禁止 `completed` 和 coverage `blocked` 收口。
|
||
- 增加 Task 9，专门退役 Meta 合同兜底路由，并要求 route ownership 测试证明 16 个路径不再调用 `MuseContractPersistenceService`。
|
||
- `validateMetaSchemaDraft` / `previewMetaSchemaDraftImpact` 确认为使用 `schemaKey + draftVersion + actor + draftHash` 的等价幂等键，不静默改 OpenAPI。
|
||
- rollback/deprecate/publish/activate/gray/function-chain activate 均补齐 commandId、reason、version、validationResultId、impactPreviewId、权限、同源校验和 audit 要求。
|
||
- 计划补充 `P1rMetaMigrationSqlTest` 聚焦验证 V10 迁移 SQL 和 active 唯一索引边界。
|
||
|
||
## 当前阶段边界
|
||
|
||
本阶段只完成规格和计划，没有实现代码。
|
||
|
||
未修改：
|
||
|
||
- `docs/api-contracts/meta/openapi.yaml`
|
||
- `docs/superpowers/reports/p1r-api-coverage.*`
|
||
- `muse-cloud/scripts/**`
|
||
- `muse-cloud/muse-module-meta/**` 实现代码
|
||
|
||
当前不应把任何 Meta operation 标为 `completed`。
|
||
|
||
## 下一步
|
||
|
||
进入 P1R-2 实现前，应从 `docs/superpowers/plans/2026-05-27-P1R-2-meta-real-api.md` Task 1 开始，按 fresh subagent + 两轮 review 执行。
|
||
|
||
实现阶段完成口径：
|
||
|
||
- Meta 16 个 operation 退出 `generic_persistence`。
|
||
- Meta 16 个 operation 全部为 `dedicated / needs_verification`。
|
||
- Content 51 个 operation 保持 `dedicated / needs_verification`。
|
||
- 不修改脚本掩盖缺口。
|
||
- 不把 Meta 标为 `completed`。
|