oh-my-muse/docs/agent-specs/2026-06-10-P1RRemainingDomainCompletedApproval审阅版.md

# 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<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`。
- 写入本文档前已执行：

```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-<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 状态推进仍需要单独用户批准。