# P1R Remaining Domain Completed Approval 审阅版 日期：2026-06-10 ## 结论 推荐把 P1R 下一阶段定义为： ```text 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`。 推荐推进顺序： ```text Meta -> Account -> Market -> Content ``` 理由是 Meta 体量最小、外部依赖最少，适合作为 domain-level completed approval 模板；Account 和 Market 分别牵涉 New-API/FileService、授权/安装/治理投影；Content 最大且跨 AI/Knowledge/Meta/FileService/Export/Import/Parse/Planning 等 owner，适合最后按模板分片验收。 ## 审批主线 ```mermaid flowchart TB Start["当前 HEAD
P1R-7 Events completed approval 已推送"] --> Remaining["剩余 needs_verification domains
Meta / Account / Market / Content"] Remaining --> Review["总审阅版
冻结证据标准与顺序"] Review --> DomainSpec{"按域单独审阅?"} DomainSpec -->|Meta| Meta["P1R-Meta Completed Approval
16 operations"] DomainSpec -->|Account| Account["P1R-Account Completed Approval
33 operations"] DomainSpec -->|Market| Market["P1R-Market Completed Approval
32 operations"] DomainSpec -->|Content| Content["P1R-Content Completed Approval
51 operations"] Meta --> DomainGate["每域执行版 + fresh 双 review
用户批准后才改 coverage"] Account --> DomainGate Market --> DomainGate Content --> DomainGate DomainGate --> Scanner["operation/domain allowlist
scanner + report + gates"] Scanner --> Done{"四域均完成?"} Done -->|否| NextDomain["继续下一个 domain"] Done -->|是| P1RApproval["总 P1R completed approval 候选
仍需单独审批"] ``` ## 已验证事实 ### 工作区与远端 - 正确 worktree：`/Users/qingse/.config/superpowers/worktrees/oh-my-muse/dev-1.0.0`。 - 当前分支：`dev/1.0.0`。 - 写入本文档前已执行： ```bash git status --short --branch git log --oneline -5 git pull --ff-only origin dev/1.0.0 ``` 结果： ```text ## 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： ```text totalOperations 233 completedOperations 101 needsVerificationOperations 132 incompleteOperations 0 genericPersistenceOperations 0 ssePlaceholderOperations 0 missingOperations 0 blockedOperations 0 ``` 当前按 domain 聚合： ```text 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 候选范围： ```text 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 候选范围： ```text 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 候选范围： ```text 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 候选范围： ```text 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，逐类断言： ```text tests > 0 failures = 0 errors = 0 skipped = 0 ``` 如果新增测试类、拆分测试类或修改 `-Dtest` 列表，执行版必须同步更新 XML 计数下限。不得只依赖 Maven exit 0 或 `surefire.failIfNoSpecifiedTests=false`。 ### Allowed diff gate 每个 domain 执行版必须列出允许修改的文件清单，并用同一个 gate 覆盖： ```bash 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 必须为空： ```text 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： ```text /tmp/p1r--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 状态推进仍需要单独用户批准。