oh-my-muse/docs/archive/2026-06-14-P1RAccountRemaining21解锁审阅版.md

# P1R Account Remaining 21 解锁审阅版

日期：2026-06-14

## 结论

不建议继续把 Account 剩余 21 个 `dedicated / needs_verification` operation 当作“只补 approval 证据”的任务推进。

当前剩余 21 个 operation 已经不是简单缺 HTTP+DB `_test` 或 mixed gate 的问题，而是集中落在五类真实闭环缺口：

- New-API runtime / quota request / integration correlation。
- FileService / export task / download bytes。
- call attribution source / usage source fact。
- Market purchase / license / publish projection。
- security event acknowledge 的 session revoke 合同。

推荐把下一阶段定义为：

```text
P1R Account Remaining 21 Unlock
```

该阶段应先补真实 owner 边界、外部 runtime 或明确可验收替代合同，再回到 operation-level completed approval。不得用 dedicated controller、unit test、fail-closed 行为或文档结论直接把剩余 21 个 operation 推进 `completed`。

```mermaid
flowchart TB
    Current["当前 Account<br/>12 completed / 21 needs_verification"] --> Split["剩余 21 分组"]
    Split --> NewApi["New-API / quota / integration<br/>9 ops"]
    Split --> Export["FileService / export / download<br/>3 ops"]
    Split --> Usage["usage / attribution<br/>4 ops"]
    Split --> Market["Market projection<br/>4 ops"]
    Split --> Security["security ack / session revoke<br/>1 op"]
    NewApi --> Unlock["先补真实闭环或验收替代"]
    Export --> Unlock
    Usage --> Unlock
    Market --> Unlock
    Security --> Unlock
    Unlock --> Approval["再写切片执行版 + fresh 双 review<br/>用户批准后才改 coverage"]
```

## 当前事实状态

工作区：

```text
/Users/qingse/.config/superpowers/worktrees/oh-my-muse/dev-1.0.0
```

当前 HEAD：

```text
3a27e7e test(p1r): 收口 Account Security Events completed approval 门禁
```

当前 coverage summary：

```text
233	147	86	0	0	0
```

当前按 domain 聚合：

```text
account   total=33 completed=12 needsVerification=21
ai        total=41 completed=41 needsVerification=0
content   total=51 completed=14 needsVerification=37
events    total=1  completed=1  needsVerification=0
knowledge total=59 completed=59 needsVerification=0
market    total=32 completed=4  needsVerification=28
meta      total=16 completed=16 needsVerification=0
```

Account 已 completed 的 12 个 operation：

```text
account:getCurrentUser
account:getProfile
account:updateProfile
account:adminListAccountUsers
account:adminGetUserEntitlements
account:getAppEntitlements
account:adminGetBalanceSnapshots
account:getAppBalanceSnapshots
account:adminCreateQuotaAdjustment
account:adminListQuotaAdjustments
account:appListSecurityEvents
account:appGetSecurityEvent
```

Account 剩余 21 个 operation：

```text
account:adminCreateCallAttributionJob
account:adminGetCallAttributionJob
account:adminGetIntegrationCallByCorrelation
account:adminListNewApiBindings
account:adminListPurchaseRecords
account:adminListUsageRecords
account:adminCreateNewApiBinding
account:adminCreateQuotaRequest
account:appDownloadExport
account:appCreateExportTask
account:appGetExportTask
account:appGetIntegrationCallByCorrelation
account:appListLicenses
account:getAppNewApiBinding
account:appRecheckNewApiBinding
account:appListPublishRecords
account:appListPurchases
account:appCreateQuotaRequest
account:appGetQuotaRequest
account:appAcknowledgeSecurityEvent
account:getAppUsage
```

## 非目标

本审阅版不做以下事情：

- 不修改 OpenAPI。
- 不修改 scanner 或 coverage report。
- 不修改 Account 业务实现、SQL migration 或测试代码。
- 不把 Account 加入 domain-level completed allowlist。
- 不推进 Account 33/33 completed。
- 不推进 Market、Content 或总 P1R completed。
- 不把 fail-closed、dedicated gate PASS、unit test PASS 或历史 review PASS 当作 completed 证据。

## 剩余 21 分组与阻塞

### 1. New-API / quota request / integration correlation

覆盖 9 个 operation：

```text
account:adminListNewApiBindings
account:adminCreateNewApiBinding
account:getAppNewApiBinding
account:appRecheckNewApiBinding
account:adminCreateQuotaRequest
account:appCreateQuotaRequest
account:appGetQuotaRequest
account:adminGetIntegrationCallByCorrelation
account:appGetIntegrationCallByCorrelation
```

已验证事实：

- `AccountNewApiBindingServiceImpl` 使用 `NewApiAccountFacade` 作为外部 New-API 边界。
- 默认 `UnavailableNewApiAccountFacade` fail-closed，不能伪造 binding / recheck 成功。
- create/recheck 路径已有 command、requestHash、integration call、success/unavailable 事实。
- `AccountQuotaServiceImpl` 的 quota request create 会写 `muse_account_quota_request` 与 `muse_account_integration_call`，状态为 `queued` / `pending_attribution`。

阻塞点：

- 没有真实 New-API runtime 或可验收替代 runtime 证明 binding / recheck / quota request 的成功闭环。
- quota request 目前只是 queued fact，不等于额度配置、订阅同步或余额同步完成。
- integration correlation 读侧依赖上述 integration call 事实质量；不能脱离 create/recheck/quota request 闭环单独 completed。

推荐解锁条件：

- 定义并实现真实 New-API Account facade，或写明可验收替代 runtime。
- 覆盖 success、unavailable、timeout、retry、idempotent replay、correlation 查询、owner/tenant 隔离。
- 对 admin/app integration detail 做敏感字段 allowlist 与 no-write HTTP+DB `_test`。

### 2. FileService / export / download

覆盖 3 个 operation：

```text
account:appCreateExportTask
account:appGetExportTask
account:appDownloadExport
```

已验证事实：

- `AccountExportServiceImpl` 通过 `AccountFileServiceFacade` 调用文件 owner。
- 默认 FileService 不可用时 create export 只返回 queued 或 fail-closed。
- download 路径要求 credential hash、一次性消费、task completed、fileRef 和真实 bytes。
- 高敏 `usage` / `security_events` export 因缺 step-up proof 会 fail-closed。

阻塞点：

- 没有真实 FileService / 对象存储 / 文件字节下载闭环。
- create task queued 不等于 export completed。
- appDownloadExport 不能用 mock bytes 或空 bytes 当 completed。
- step-up proof 仍未形成可信服务端合同。

推荐解锁条件：

- 接入真实 FileService facade 或可验收替代文件 runtime。
- HTTP+DB `_test` 覆盖 task create、completed detail、credential 可见性、credential 一次性消费、download bytes、audit、过期/撤销/并发消费失败。
- 明确高敏 export 的 step-up proof 来源；否则高敏类型继续保持 fail-closed 与 needs_verification。

### 3. usage / call attribution

覆盖 4 个 operation：

```text
account:adminListUsageRecords
account:getAppUsage
account:adminCreateCallAttributionJob
account:adminGetCallAttributionJob
```

已验证事实：

- `AccountUsageServiceImpl` 从 `MemberUsageRecordMapper` 和 `AccountIntegrationCallMapper` 聚合 usage / attribution 状态。
- `AccountAttributionServiceImpl.adminCreateCallAttributionJob` 当前只创建 queued job fact。
- 真实归因 source 由 `AccountAttributionSourceFacade` 代表，当前没有 completed-grade source owner 证据。

阻塞点：

- usage record 的上游来源、归因状态、token 计量与 attribution source 没有形成端到端事实链。
- create attribution job 只是排队，真实归因执行、terminal transition、补偿建议和 item result 还不能证明。
- adminGetCallAttributionJob 读侧依赖 job/item terminal fact 质量，不能只凭 detail mapper completed。

推荐解锁条件：

- 明确 usage source owner：AI/Content/Market/New-API 调用如何写入 `MemberUsageRecordDO`。
- 建立 attribution job worker 或明确同步归因替代路径。
- HTTP+DB `_test` 覆盖 queued、processing、completed、failed、partially_completed、revision conflict、call whitelist、owner/tenant 隔离和 no-write detail。

### 4. Market purchase / license / publish projection

覆盖 4 个 operation：

```text
account:adminListPurchaseRecords
account:appListPurchases
account:appListLicenses
account:appListPublishRecords
```

已验证事实：

- `AccountMarketRecordServiceImpl` 通过 `MarketAccountProjectionFacade.requireProjectionAvailable(recordType)` 检查 Market 投影是否可用。
- 读侧使用 `muse_account_record_projection`，并按 `record_type` 隔离 purchase / license / publish。
- 当前 Market 仍只有 4 个 completed，purchase / install / publish / projection 相关 Market operation 仍为 `needs_verification`。

阻塞点：

- Account projection 读模型依赖 Market owner 写入投影事实。
- Market purchase/license/publish 本身尚未 completed，不能在 Account 侧单独宣称 projection completed。
- 需要证明跨 owner 一致性：Market 源事实、Account projection、用户可见记录、状态枚举和排序分页一致。

推荐解锁条件：

- 先完成或至少审阅 Market purchase/install/publish/projection 的真实闭环。
- 建立 Market -> Account projection E2E `_test`：Market source fact 写入后 Account 读侧可见，跨 owner/tenant 不可见，projection stale/缺失 fail-closed。
- 在 Market 仍未 completed 前，Account 这 4 个 operation 继续保持 `needs_verification`。

### 5. security event acknowledge / session revoke

覆盖 1 个 operation：

```text
account:appAcknowledgeSecurityEvent
```

已验证事实：

- `appListSecurityEvents` 与 `appGetSecurityEvent` 已在 2026-06-13 推进 completed。
- `appAcknowledgeSecurityEvent` 仍为 `dedicated / needs_verification / requiresCommandId=true`。
- 既有审阅已确认：`session_revoked` OpenAPI 合同承诺真实 session revoke，但当前实现只返回“未接入 session 管理服务”的 fail-closed 文案。

阻塞点：

- ack 写入本身不够；`session_revoked` 必须有真实 session revoke owner 或合同降级。
- 不能把 fail-closed 文案当 completed。
- 如果修改 OpenAPI 降级合同，必须单独审批；不能作为掩盖实现缺口的 scanner/report 修改。

推荐解锁条件：

- 接入真实 session management / token revoke owner，或单独评审并批准 OpenAPI 合同变更。
- HTTP+DB `_test` 覆盖 commandId、ack row、replay、conflict、owner/tenant 隔离、session revoke success/fail-closed、audit/outbox/no-write rollback。

## 推荐路线

### 路线 A：Account unlock implementation 优先

先写 Account Remaining 21 执行版，把五类缺口拆成独立 implementation stage。每个 stage 先补真实闭环，再回到 completed approval。

优点：

- 直接推进 Account 33/33 的真实完成。
- 不把缺口留给 Market / Content 后续阶段。

代价：

- 会进入真实业务实现，不再只是 scanner/report/gate 的 completed approval。
- 需要用户确认外部 runtime 边界：New-API、FileService、Market projection、attribution source、session management。

### 路线 B：暂缓 Account，继续 Market / Content 独立切片

Account 剩余 21 保持 `needs_verification`，转向 Market 或 Content 中已有较强闭环证据的 operation-level completed approval。

优点：

- 可以继续增加 completed 总量。
- 避免在 Account 外部 owner 未明确时硬做实现。

代价：

- 总 P1R 仍会被 Account remaining 21 阻塞。
- Market projection 最终仍会反向影响 Account 4 个 Market projection operation。

### 推荐选择

推荐路线 A，但先只写 Account Remaining 21 执行版，不直接实现。执行版应先明确：

1. 哪些 runtime 由现有模块 owner 承担。
2. 哪些 facade 允许接入真实实现，哪些只能保持 fail-closed。
3. 哪些 OpenAPI 合同需要修订，哪些必须坚持实现兑现。
4. 每个 stage 的 HTTP+DB `_test`、focused test、P1R gate、XML 防空跑、protected diff。
5. 哪些 operation 可以在 stage 完成后进入 operation-level completed approval。

## Fresh 审阅结果

本审阅版已完成 fresh 双 review：

- Spec/scope review：PASS，无 P0/P1/P2 阻塞。
- Feasibility/testing review：PASS，无 P0/P1 阻塞。

审阅结论确认本审阅版可以进入执行版编写，但不代表 Account remaining 21 已完成，也不授权实现、提交或推进 coverage。

执行版必须吸收以下 reviewer 约束：

1. New-API 与 attribution 的真实 facade wiring 不能停留在“接入真实 facade”一句话；必须明确 `Unavailable*Facade` 默认实现与真实实现的 bean 选择策略，例如 `@Primary`、`@ConditionalOnMissingBean`、profile 排除或自动配置拆分，避免多 bean 冲突或继续选中 fail-closed 默认实现。
2. `adminCreateQuotaRequest`、`appCreateQuotaRequest`、`adminCreateCallAttributionJob` 等写命令必须明确 command、audit、job/outbox 的边界；若某 stage 不需要 outbox，也必须写明“不需要”的原因和验证方式。
3. export/download stage 必须把 `muse.account.download-credential-secret` 作为 completed 前置校验；FileService completed 证据必须包含 `fileRef`、过期时间、credential secret 与非空 bytes。
4. 新增 HTTP+DB `_test` 必须以 V1-V21 clean migrate 为基线；历史 V20 Account outbox 证据只能作为既有迁移回归，不能替代新 stage 主证据。
5. Market projection stage 必须独立覆盖 source fact、Account projection、stale/missing projection fail-closed、read-only no-write snapshot 与 owner/tenant 隔离。
6. rollback 不能只写 scanner/report 回滚；真实 unlock stage 必须包含 runtime switch、facade fallback 或配置级回退策略。

## 验收标准

本审阅版自身的验收标准：

- 文件写入 `docs/agent-specs/2026-06-14-P1RAccountRemaining21解锁审阅版.md`。
- 不产生 scanner/report/OpenAPI/业务实现 diff。
- 明确 Account remaining 21 的分组、阻塞、解锁条件和推荐路线。
- 不宣称任何新增 operation completed。

后续执行版的最低验收标准：

- fresh spec/scope review PASS。
- fresh quality/feasibility/testing review PASS。
- 用户明确批准 execution scope 后才允许实现。
- 每个 implementation stage 都必须有真实 HTTP+DB `_test`、focused tests、P1R mixed gates、XML 防空跑、protected diff 和 rollback 策略。

## 待确认

1. 是否确认下一阶段命名为 `P1R Account Remaining 21 Unlock`。
2. 是否确认路线 A：先写 Account Remaining 21 执行版，进入真实闭环解锁，而不是继续做纯 approval。
3. 是否确认外部 owner 边界优先级：New-API、FileService、Market projection、attribution source、session management。