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-P1RRemainingDomainCompletedApproval审阅版.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

17 KiB
Raw Blame History

P1R Remaining Domain Completed Approval 审阅版

日期：2026-06-10

结论

推荐把 P1R 下一阶段定义为：

P1R Remaining Domain Completed Approval

该阶段不是继续 P1R-7，也不是直接进入一个已经存在的 P1R-8 实现阶段；它的目标是为仍处于 dedicated / needs_verification 的四个业务域建立 completed approval 总方案：

  • Meta 16 operations
  • Account 33 operations
  • Market 32 operations
  • Content 51 operations

本审阅版只冻结总路线、审批边界、证据标准和推荐推进顺序。不修改 OpenAPI，不修改 scanner，不修改 coverage report，不修改业务代码，也不把任何剩余业务域推进 completed。

推荐推进顺序：

Meta -> Account -> Market -> Content

理由是 Meta 体量最小、外部依赖最少，适合作为 domain-level completed approval 模板；Account 和 Market 分别牵涉 New-API/FileService、授权/安装/治理投影；Content 最大且跨 AI/Knowledge/Meta/FileService/Export/Import/Parse/Planning 等 owner，适合最后按模板分片验收。

审批主线

flowchart TB
    Start["当前 HEAD<br/>P1R-7 Events completed approval 已推送"] --> Remaining["剩余 needs_verification domains<br/>Meta / Account / Market / Content"]
    Remaining --> Review["总审阅版<br/>冻结证据标准与顺序"]
    Review --> DomainSpec{"按域单独审阅?"}
    DomainSpec -->|Meta| Meta["P1R-Meta Completed Approval<br/>16 operations"]
    DomainSpec -->|Account| Account["P1R-Account Completed Approval<br/>33 operations"]
    DomainSpec -->|Market| Market["P1R-Market Completed Approval<br/>32 operations"]
    DomainSpec -->|Content| Content["P1R-Content Completed Approval<br/>51 operations"]
    Meta --> DomainGate["每域执行版 + fresh 双 review<br/>用户批准后才改 coverage"]
    Account --> DomainGate
    Market --> DomainGate
    Content --> DomainGate
    DomainGate --> Scanner["operation/domain allowlist<br/>scanner + report + gates"]
    Scanner --> Done{"四域均完成?"}
    Done -->|否| NextDomain["继续下一个 domain"]
    Done -->|是| P1RApproval["总 P1R completed approval 候选<br/>仍需单独审批"]

已验证事实

工作区与远端

  • 正确 worktree：/Users/qingse/.config/superpowers/worktrees/oh-my-muse/dev-1.0.0。
  • 当前分支：dev/1.0.0。
  • 写入本文档前已执行：
git status --short --branch
git log --oneline -5
git pull --ff-only origin dev/1.0.0

结果：

## dev/1.0.0...origin/dev/1.0.0
85c5422 test(p1r): 收口 P1R-7 completed approval 门禁
Already up to date.

当前 coverage 状态

当前 docs/superpowers/reports/p1r-api-coverage.json summary：

totalOperations              233
completedOperations          101
needsVerificationOperations  132
incompleteOperations         0
genericPersistenceOperations 0
ssePlaceholderOperations     0
missingOperations            0
blockedOperations            0

当前按 domain 聚合：

account   33 dedicated/needs_verification:33
ai        41 dedicated/completed:41
content   51 dedicated/needs_verification:51
events     1 dedicated/completed:1
knowledge 59 dedicated/completed:59
market    32 dedicated/needs_verification:32
meta      16 dedicated/needs_verification:16

已 completed 的范围：

  • AI 41 operations。
  • Knowledge 59 operations。
  • Events streamEvents / GET /app-api/muse/events 1 operation。

仍未 completed 的范围：

  • P1R-1 Content Real API：51 operations。
  • P1R-2 Meta Real API：16 operations。
  • P1R-3 Account Real API：33 operations。
  • P1R-6 Market Real API：32 operations。

既有阶段结论

P1R 总规格定义的 completed 标准不是“路由存在”或“dedicated Controller 存在”，而是“真实业务行为、状态机、持久化、外部闭环、审计、测试与真实环境验收证据”。

P1R-1 Content 留痕明确：

  • Content 51 operations 已退出 catch-all / generic persistence。
  • 当前状态只是 dedicated / needs_verification。
  • 仍缺真实 PostgreSQL/Flyway 集成、外部 owner facade 与端到端验收。

P1R-2 Meta 留痕明确：

  • Meta 16 operations 已进入 dedicated Controller / Service。
  • 当前状态只是 dedicated / needs_verification。
  • 当时未运行真实 PostgreSQL / Flyway 迁移验证，外部 runtime owner 仍 pending。

P1R-3 Account 留痕明确：

  • Account 33 operations 已进入 dedicated route / service / DTO / DAL。
  • PostgreSQL / Flyway V11 已在同实例 test 库验证。
  • New-API runtime、FileService、导出下载真实交付与跨域 runtime 仍未验收，因此不能 completed。

P1R-6 Market 留痕明确：

  • Market 32 operations 已从 generic persistence 推进到 dedicated / needs_verification。
  • Market completed 不等于治理事件 propagation completed。
  • 仍需证明购买、安装、handoff、授权消费、治理与账户聚合等真实用户流。

P1R-7 completed approval 留痕明确：

  • 只把 events:streamEvents 从 dedicated / needs_verification 推进为 dedicated / completed。
  • 没有把 Market / Account / Content / Meta 推进 completed。
  • 没有把总 P1R 写成 completed。

推断

  • 当前主线瓶颈已经从“事件流是否可见”转为“剩余业务域是否具备真实业务 completed 证据”。
  • 下一阶段不应再扩展 P1R-7 source owner propagation；P1R-7 已完成的是 Events SSE operation-level approval。
  • 剩余四域不能用一次总批准直接推进 completed，因为它们的外部依赖、状态机、数据面和用户旅程差异较大。
  • 最稳妥路线是先冻结总标准，再按 domain 分批写审阅版 / 执行版 / fresh review / 用户批准 / scanner-report-gate 修改。

假设

  • 用户希望继续 P1R 主线，而不是切换到前端 P2/P3 或新功能开发。
  • 用户仍要求 coverage completed 必须基于真实证据和单独批准，不能由 dedicated gate、review PASS 或文档推断自动推进。
  • 后续每个 domain 的 completed approval 都允许修改 scanner、coverage report 和 coverage gate，但必须先通过该 domain 的执行版 review，并在用户明确批准后执行。

推荐方案

方案 A：按 domain 分批 completed approval

每个剩余业务域单独走：

  1. 审阅版：冻结该 domain 的 operation 列表、证据缺口、非目标、审批边界。
  2. fresh spec/scope review + fresh quality/feasibility review。
  3. 执行版：列出可验证证据、scanner/report/gate 修改方式、allowed-diff、rollback。
  4. fresh execution spec review + fresh execution quality review。
  5. 用户明确批准该 domain completed 状态推进。
  6. 修改 scanner / coverage gate / report。
  7. 运行 focused tests、P1R gates、真实环境或 _test gate、protected diff、allowed-diff。
  8. fresh implementation 双 review。
  9. 用户批准后提交和 push。

推荐选择该方案。

理由：

  • 保持最小审批面。
  • 每个 domain 的缺口可以独立验证。
  • 不会因为某个 domain 证据充分而误推进其它 domain。
  • 与 AI / Knowledge / Events 的既有 approval 模型一致。

方案 B：一次性总 P1R completed approval

一次性把 Content / Meta / Account / Market 全部纳入一个总执行版，并统一推进 completed。

不推荐。

理由：

  • 132 个 remaining operation 风险面过大。
  • Content / Account / Market 的外部链路差异明显，容易出现证据稀释。
  • 一次性 scanner/report 修改难以证明每个 operation 的证据归属。
  • 任何一个 domain 的 blocker 都会阻塞整批推进。

方案 C：按 operation 极细粒度推进

对剩余 132 个 operation 逐个 operation-level approval。

暂不推荐作为主线默认方案。

理由：

  • 最精确，但成本过高。
  • 对 Meta 这种小域会造成过度流程开销。
  • 更适合在某个 domain 内存在少数高风险 operation 不能与其它 operation 一起批准时局部采用。

推荐推进顺序

第一阶段：Meta Completed Approval

候选范围：

meta 16 dedicated/needs_verification

推荐先做 Meta，因为：

  • operation 数量最少。
  • 主要围绕 MetaSchema、保护节点、功能链治理。
  • 外部依赖比 Account / Market / Content 少。
  • 更适合建立 completed approval 的 domain 模板。

Meta 审阅版必须重点证明：

  • V10 或后续 Meta migration 在真实 _test 库可执行。
  • MetaSchema draft / validate / impact preview / publish / activate / rollback / deprecate / gray-rules 有真实状态机、版本约束和审计证据。
  • 保护节点不能被降级为用户可替换槽位。
  • 管理端权限、tenant 隔离和错误码路径可验。
  • 没有把 Content / Account / Market 连带推进。

第二阶段：Account Completed Approval

候选范围：

account 33 dedicated/needs_verification

Account 必须在 completed 前补足：

  • New-API binding / recheck / quota request / integration call 的真实 runtime 或明确验收替代边界。
  • call attribution 基于真实 integration call / correlation 的查询与归因证据。
  • FileService 或对象存储导出下载真实交付证据。
  • security event / acknowledge / profile / entitlement / usage / purchase / license / publish projection 的 owner 与 tenant 隔离。
  • P1R-7e Account quota adjustment Events propagation 只能作为事件可见证据，不能替代 Account API completed 证据。

第三阶段：Market Completed Approval

候选范围：

market 32 dedicated/needs_verification

Market 必须在 completed 前补足：

  • 资产发布、审核、驳回、下架、召回、申诉的真实状态机和审计。
  • 购买、安装、bind-precheck、handoff、目标 owner 授权消费链路。
  • Account projection 与 Market installation / purchase / license 的一致性。
  • P1R-7d Market governance Events propagation 只能作为治理事件可见证据，不能替代 Market API completed 证据。
  • needs_recheck 仍不能作为 SourceStatus 值误用。

第四阶段：Content Completed Approval

候选范围：

content 51 dedicated/needs_verification

Content 放最后，因为它覆盖面最大：

  • 作品、章节、Block、结构编辑、来源归因。
  • planning、style check、candidate confirm/discard。
  • import / parse / batch confirm / parse retry。
  • export / export task / download。
  • meta projection。
  • suggestion merge。
  • admin risk action / import task / export task / work governance。

Content completed 前必须证明：

  • 核心写命令、幂等、revision、owner guard、审计和 DTO 响应。
  • import / parse / export / download 的真实文件或对象存储闭环。
  • AI suggestion / Knowledge draft / Meta projection / FileService 等外部 owner 边界。
  • P1R-7f saveBlock source owner propagation 只覆盖一个事件切片，不能替代全部 Content 51 operations completed。

非目标

  • 不修改 docs/api-contracts/**/openapi.yaml。
  • 不修改 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 任何 operation 推进 completed。
  • 不把总 P1R 标记为 completed。
  • 不把 P1R-7 source owner propagation evidence 当作业务域 completed 证据。

全域 anti-fake-green 基线

后续任一 domain completed approval 都必须继承以下硬基线。执行版不得把这些基线留给 implementer 临场决定。

XML 防空跑

每个 domain 执行版必须列出所有 required test class，并为每个 class 指定最低 tests 数。

最终验证必须读取对应 Surefire XML，逐类断言：

tests > 0
failures = 0
errors = 0
skipped = 0

如果新增测试类、拆分测试类或修改 -Dtest 列表，执行版必须同步更新 XML 计数下限。不得只依赖 Maven exit 0 或 surefire.failIfNoSpecifiedTests=false。

Allowed diff gate

每个 domain 执行版必须列出允许修改的文件清单，并用同一个 gate 覆盖：

git -c core.quotePath=false diff --name-only
git -c core.quotePath=false diff --cached --name-only
git -c core.quotePath=false ls-files --others --exclude-standard

最终 git status --short --untracked-files=all 只能出现 allowed 路径。中文路径必须使用 core.quotePath=false，避免八进制转义导致误判。

Protected diff gate

在用户明确批准真实 coverage 状态推进前，以下文件 staged 与 unstaged diff 必须为空：

docs/api-contracts/account/openapi.yaml
docs/api-contracts/ai/openapi.yaml
docs/api-contracts/content/openapi.yaml
docs/api-contracts/events/openapi.yaml
docs/api-contracts/knowledge/openapi.yaml
docs/api-contracts/market/openapi.yaml
docs/api-contracts/meta/openapi.yaml
muse-cloud/scripts/p1r-audit-api-coverage.py
docs/superpowers/reports/p1r-api-coverage.json
docs/superpowers/reports/p1r-api-coverage.md

执行版必须内联 git diff --quiet -- ... 与 git diff --cached --quiet -- ... 命令。若某个 domain 的 completed approval 需要修改 scanner/report/gate，必须先在执行版写明允许路径、修改时机和回滚策略，并在用户批准后才允许真实 worktree 修改。

Scanner 与 coverage report 时机

执行版 fresh 双 review 前，只允许在 /tmp 隔离副本运行 coverage scanner：

/tmp/p1r-<domain>-completed-approval-scan.*

隔离 scanner 只能用来预验证目标 summary、目标 operation/domain 状态和负向保护。真实 worktree 运行 python3 muse-cloud/scripts/p1r-audit-api-coverage.py --check 并改写 docs/superpowers/reports/**，必须同时满足：

  1. domain 执行版 fresh spec/scope review PASS。
  2. domain 执行版 fresh quality/feasibility review PASS。
  3. 用户明确批准该 domain 的 completed 状态推进。
  4. allowed-diff gate 已把 scanner/report/test 允许路径列明。

真实 _test / 外部验收最低标准

每个 domain 审阅版必须先说明 completed 证据所需的真实运行态最低标准：

  • 如果涉及新增或既有 migration，必须指定真实 PostgreSQL _test Flyway 验证，包含目标 schema version、关键表、索引、约束、trigger 和非法 insert 拒绝。
  • 如果涉及外部服务，例如 New-API、RAGFlow、FileService、对象存储或导出下载，必须指定成功路径、失败路径、超时、重试或 fail-closed 边界。
  • 如果外部服务暂不可用，必须把该 operation 或该切片保持 needs_verification，不能以 mock、bare fake、空成功或固定样例数据替代 completed 证据。
  • 如果某个 domain 只能部分 operation 满足 completed 证据，执行版必须采用 operation-level approval，而不是 domain-level approval。

Implementation review 复核项

每个 domain 的 implementation review 必须复核：

  • scanner approval 模型没有扩大到非目标 domain 或未来 operation。
  • report 中新增 completed 的 operation 与用户批准范围完全一致。
  • 非目标 domain 仍保持原状态。
  • OpenAPI 与业务实现 diff 符合执行版 allowed list。
  • focused tests、P1R gates、XML 防空跑、真实 _test 或外部验收、allowed-diff、protected diff 均有 fresh 输出。

后续审阅版必须包含

每个 domain 的 completed approval 审阅版都必须包含：

  1. 当前 operation 清单和 coverage 状态。
  2. 已有 dedicated 实现证据。
  3. 已有外部或端到端证据。
  4. 明确缺口：数据库、外部服务、状态机、权限、审计、失败路径、重试补偿。
  5. 非目标 operation 或跨域链路。
  6. 推荐 approval 粒度：domain-level 或 operation-level。
  7. scanner/report/gate 的修改边界。
  8. protected 文件清单，必须覆盖 7 个 OpenAPI：
    • docs/api-contracts/account/openapi.yaml
    • docs/api-contracts/ai/openapi.yaml
    • docs/api-contracts/content/openapi.yaml
    • docs/api-contracts/events/openapi.yaml
    • docs/api-contracts/knowledge/openapi.yaml
    • docs/api-contracts/market/openapi.yaml
    • docs/api-contracts/meta/openapi.yaml
  9. review gate：
    • fresh spec/scope review
    • fresh quality/feasibility review
  10. 用户批准点：执行版双 PASS 后，仍必须由用户单独批准真实 coverage 状态推进。
  11. 本文“全域 anti-fake-green 基线”的继承方式；如需例外，必须在审阅版列出理由和替代验证。

验收标准

本总审阅版可以视为完成的条件：

  1. 文件写入 docs/agent-specs/2026-06-10-P1RRemainingDomainCompletedApproval审阅版.md。
  2. .agent 记录下一阶段状态。
  3. git diff --check 通过。
  4. OpenAPI、scanner、coverage report 无 diff。
  5. 文档只定义总路线，不进入执行版或实现。

待确认项

  1. 是否确认下一阶段正式命名为 P1R Remaining Domain Completed Approval。
  2. 是否确认推荐顺序为 Meta -> Account -> Market -> Content。
  3. 是否确认下一步先写 Meta completed approval 审阅版，而不是直接进入执行版或实现。
  4. 是否确认每个 domain 的 completed 状态推进仍需要单独用户批准。