# P1R3 账户真实 API 规格计划 日期：2026-05-28 ## 背景 本次进入 P1R-3 Account Real API spec + plan 阶段，只完成 Account 域真实 API 的事实盘点、规格和执行计划，不进入代码实现。 P1R-3 的核心不是继续增强 `MuseContractPersistenceService`，也不是把 `generic_persistence` 包装成业务结果，而是把 Account 域从“通用持久化可响应”推进到“真实账户业务 API 可验收”的规格和计划阶段。 ## 执行位置 ```text /Users/qingse/.config/superpowers/worktrees/oh-my-muse/dev-1.0.0 ``` 分支： ```text dev/1.0.0 ``` 本阶段开始和收口时，工作树只包含本阶段新增文档改动，没有实现代码改动。 ## 已验证事实 P1R 覆盖矩阵中 Account 域当前状态： ```text 33 generic_persistence / incomplete ``` 同时保持： - completed operations = 0 - Content 51 个 operation 为 `dedicated / needs_verification` - Meta 16 个 operation 为 `dedicated / needs_verification` 当前代码事实： - 仓库没有 `muse-cloud/muse-module-account/**`。 - Account 当前真实 owner 应落在 `muse-module-member` 的 Account 子域。 - 当前 Account 合同入口仍是 `AdminMuseAccountContractController` 和 `AppMuseAccountContractController`。 - 两个 Controller 仍通过 `MuseContractPersistenceService` 通用持久化处理 Account 路由，不是 P1R 完成证据。 当前 DDL 事实： - V2 已有 `muse_member_entitlement`、`muse_member_entitlement_audit_log`、`muse_member_quota`、`muse_member_usage_record`、`muse_member_security_event`、`muse_member_new_api_binding`。 - P1R-3 计划新增 `muse_account_profile`、`muse_account_audit`、`muse_account_command`、`muse_account_balance_snapshot`、`muse_account_quota_request`、`muse_account_integration_call`、`muse_account_call_attribution_job`、`muse_account_call_attribution_item`、`muse_account_export_task`、`muse_account_download_credential`、`muse_account_security_event_ack`、`muse_account_record_projection`。 - purchase / license / publish records 统一使用 `muse_account_record_projection(record_type=...)` 作为 Account 视角读模型，不在 P1R-3 实现 Market 主流程。 ## 本阶段产物 - 规格：`docs/superpowers/specs/2026-05-28-P1R-3-account-real-api-design.md` - 计划：`docs/superpowers/plans/2026-05-28-P1R-3-account-real-api.md` ## 关键设计结论 - P1R-3 目标状态只能是 `dedicated / needs_verification`，不能写成 `completed`。 - Account owner 采用 `muse-module-member/account` 子域，不新增孤立 `muse-module-account`。 - `muse_account_profile` 承载 profile 扩展事实和 `expectedVersion` 乐观锁，不污染 `member_user`。 - `muse_account_audit` 与 `muse_account_command` 是 commandId 幂等、requestHash 冲突和审计的必需基础设施。 - New-API binding / recheck 必须写内部 integration call，并通过 `bindingId` / `jobId` 关联 `correlationId`；现有 OpenAPI 响应不新增 `correlationId`。 - New-API、call attribution、FileService unavailable 只能通过合同内业务错误、内部 job 状态或 OpenAPI 已声明状态表达，不能返回未声明的 `pending` 等状态，也不能 fake success。 - `appDownloadExport` 成功响应按 OpenAPI 返回 `application/octet-stream`，错误响应仍走统一 `code/data/msg`。 - AI runtime / task / SSE、Knowledge / RAGFlow、Market 主流程、统一 Events SSE 均不属于 P1R-3。 ## Review 结果 本阶段使用 fresh subagent 做了两轮文档 review，并按 review 结果修正后复审通过。 Spec compliance review 最终结果： ```text SPEC REVIEW PASS ``` Quality review 最终结果： ```text QUALITY REVIEW PASS ``` 过程中修正的关键问题： - 补齐 New-API binding create / recheck inline requestBody 的 typed VO。 - 明确 unavailable / failed / pending 等内部状态不得进入 OpenAPI 未声明 response status。 - 将 app quota request DTO 改为 `AppQuotaRequestCreateReqVO`，避免复用 admin DTO。 - 增加 `UnavailableNewApiAccountFacade`、`UnavailableMarketAccountProjectionFacade`、`UnavailableAccountFileServiceFacade` 的默认边界和测试要求。 - 移除会诱导创建独立 AI / Knowledge facade 的过宽表述，AI / Knowledge 只通过 attribution source unavailable 边界表达。 - 移除 `-Dsurefire.failIfNoSpecifiedTests=false`，并要求关键指定测试命令用 `test -f` 防止缺失测试被掩盖。 ## 当前阶段边界 本阶段只完成规格、计划、review 和 memory 留痕，没有实现代码。 未修改： - `docs/api-contracts/account/openapi.yaml` - `docs/superpowers/reports/p1r-api-coverage.*` - `muse-cloud/scripts/**` - `muse-cloud/muse-module-member/**` 实现代码 - `muse-cloud/sql/muse/**` 当前不应把任何 Account operation 标为 `completed`。 ## 残余风险 - 规格计划阶段未运行真实 PostgreSQL / Flyway 验证；实现阶段已在同一 PostgreSQL 实例的 `muse_local_test` 数据库补跑，结果见下文。 - 未接真实 New-API runtime，binding / recheck / quota request 仍需保持 `needs_verification`。 - 未接真实 FileService runtime，export task / download credential 仍需保持 `needs_verification`。 - 外部 Market / Content / AI / Knowledge owner 未闭合时，purchase / license / publish / attribution 只能走 Account 读模型和 unavailable 边界，不能标为 completed。 ## 下一步（规格计划阶段记录） 进入 P1R-3 实现前，应从 `docs/superpowers/plans/2026-05-28-P1R-3-account-real-api.md` Task 1 开始，按 fresh subagent + spec compliance review + quality review 执行。 实现阶段完成口径： - Account 33 个 operation 退出 `generic_persistence`。 - Account 33 个 operation 全部为 `dedicated / needs_verification`。 - Content 51 个 operation 保持 `dedicated / needs_verification`。 - Meta 16 个 operation 保持 `dedicated / needs_verification`。 - 不修改脚本掩盖缺口。 - 不把 Account 标为 `completed`。 ## 2026-05-29 实现阶段收口更新 ### 实现任务范围 本轮实现阶段在以下真实 worktree 执行： ```text /Users/qingse/.config/superpowers/worktrees/oh-my-muse/dev-1.0.0 ``` `4d9a242..HEAD` 已覆盖 P1R-3 Task 1-12： 1. Preflight 与覆盖基线冻结。 2. Account 基础设施与 V11 追加 DDL。 3. DTO / DAL / Mapper 骨架。 4. App `me` / `profile` 与 Admin 用户摘要。 5. 权益、配额、余额、用量。 6. New-API binding、recheck、quota request、integration call。 7. call attribution job。 8. purchase / license / publish records Account 投影。 9. security events。 10. export task / download credential。 11. Account 合同兜底退役。 12. P1R-3 覆盖门禁与报告对账。 Task 10 最新事实： - 已新增 Account export/download Controller、Service、FileService facade、unavailable facade、凭证与导出任务相关 DAL 和测试。 - 下载凭证边界覆盖 credential hash、owner、expiresAt、revoked、consumed、source blocked。 - 高敏导出在缺少可信 step-up 证明时 fail closed。 - `appDownloadExport` 成功响应按 OpenAPI 返回 `application/octet-stream`；错误仍走统一 `code/data/msg`。 - unavailable FileService 不返回伪造文件流。 Task 11 最新事实： - 已删除旧 Account 合同兜底 Controller。 - 已新增 `P1rAccountRouteOwnershipTest`，证明 33 个 P1R-3 Account 路由进入 dedicated Controller，不再回落到 `MuseContractPersistenceService`。 Task 12 最新事实： - 已新增 `P1rAccountRealApiGateTest`。 - 已更新 `docs/superpowers/reports/p1r-api-coverage.json` 和 `docs/superpowers/reports/p1r-api-coverage.md`。 - Account 33 个 operation 统一收口到 `dedicated / needs_verification`，仍保留真实运行态验收缺口。 ### Coverage 前后状态 实现起点 `4d9a242`： ```text Account 33 generic_persistence / incomplete Content 51 dedicated / needs_verification Meta 16 dedicated / needs_verification ``` 当前 `HEAD`： ```text Account 33 dedicated / needs_verification Content 51 dedicated / needs_verification Meta 16 dedicated / needs_verification ``` 该状态只证明仓库内 dedicated 入口、覆盖报告和门禁已收口。PostgreSQL / Flyway 迁移链路已在同实例 test 库验证；New-API、FileService 或端到端运行态仍未验收。 ### Review 结果 本轮实现按计划要求在每个实现 Task 后执行： 1. spec compliance review。 2. code quality review。 已记录的收口事实： - Task 10 在修正高敏导出 fail-closed、导出凭证消费边界、HMAC 凭证派生和 FileService 异常处理后，spec compliance review 与 code quality review 均通过。 - Task 11 的 spec compliance review 与 code quality review 均通过。 - Task 12 的 spec compliance review 与 code quality review 均通过。 这些 review 结果只证明 P1R-3 代码、报告和门禁符合当前 spec / plan，不代表外部 runtime owner 已闭合。 ### 测试命令和结果 本阶段已记录的验证命令与结果： ```bash python3 muse-cloud/scripts/p1r-audit-api-coverage.py --check ``` 结果：通过；覆盖报告保持 Account 33、Content 51、Meta 16 均为 `dedicated / needs_verification`。 ```bash cd muse-cloud test -f muse-server/src/test/java/cn/iocoder/muse/server/framework/api/P1rAccountRealApiGateTest.java test -f muse-server/src/test/java/cn/iocoder/muse/server/framework/api/P1rAccountRouteOwnershipTest.java test -f muse-server/src/test/java/cn/iocoder/muse/server/framework/api/P1rApiCoverageReportTest.java test -f muse-server/src/test/java/cn/iocoder/muse/server/framework/api/P1rContentRealApiGateTest.java test -f muse-server/src/test/java/cn/iocoder/muse/server/framework/api/P1rMetaRealApiGateTest.java JAVA_HOME=$(/usr/libexec/java_home -v 21) PATH="$JAVA_HOME/bin:$PATH" \ mvn -o test -pl muse-server -am \ -Dtest=P1rApiCoverageReportTest,P1rContentRealApiGateTest,P1rMetaRealApiGateTest,P1rAccountRealApiGateTest,P1rAccountRouteOwnershipTest \ -Dsurefire.failIfNoSpecifiedTests=false ``` 结果：通过，22 tests，0 failures。 说明：原计划中的 `-pl muse-server -am -Dtest=...` 命令在上游 reactor 模块没有同名测试时会触发 `failIfNoSpecifiedTests` 问题。本轮通过 `test -f` 先校验目标测试存在，再局部追加 `-Dsurefire.failIfNoSpecifiedTests=false` 避免上游模块误失败；这不是全局放宽测试缺失门禁。 ```bash cd muse-cloud JAVA_HOME=$(/usr/libexec/java_home -v 21) PATH="$JAVA_HOME/bin:$PATH" \ mvn -o test -pl muse-module-member/muse-module-member-server -am ``` 结果：通过，member-server 272 tests，0 failures。 ```bash git diff --check ``` 结果：通过，无空白错误输出。 2026-05-30 追加真实 PostgreSQL / Flyway 验证： ```bash # 使用 ~/.config/muse-repo/infra.env 中同一个 PostgreSQL 实例 # 基于 MUSE_POSTGRES_DATABASE=muse_local 创建固定 test 后缀数据库 createdb muse_local_test # 使用 Flyway API 和 application.yaml 同口径的 filesystem:sql/muse 迁移目录 Flyway.configure() .dataSource("jdbc:postgresql:///muse_local_test", username, password) .locations("filesystem:sql/muse") .baselineOnMigrate(true) .baselineVersion("0") .load() .migrate() ``` 结果： ```text PostgreSQL 17.10 flyway_success=true migrations_executed=11 target_schema_version=11 flyway_latest=11:extend account real api schema flyway_versions=1,2,3,4,5,6,7,8,9,10,11 v11_tables=12 account_index_count=47 ``` 结论：P1R-3 的 V11 迁移已在真实 PostgreSQL 实例的 `muse_local_test` 数据库通过 Flyway 迁移链验证。该验证覆盖 DDL/Flyway 可执行性，不等同于 New-API、FileService 或跨域端到端 runtime 验收。 ### 未验证 runtime 风险 - PostgreSQL / Flyway 已在同实例 `muse_local_test` 数据库验证 V1-V11 迁移链；后续阶段若新增 DDL，应继续先在同实例 `_test` 数据库跑真实 Flyway，再允许阶段收口。 - 未接真实 New-API runtime，binding / recheck / quota request / integration call 仍保持 `needs_verification`。 - 未接真实 FileService，export task / download credential 只能证明边界和状态机，不能证明真实文件交付。 - Market / AI / Knowledge owner 未闭合，purchase / license / publish / attribution 只能走 Account 投影或 unavailable 边界。 - 端到端 auth、错误响应、SSE 与跨域 runtime 行为仍需后续阶段验收。 ### 变更面记录 - OpenAPI：未修改 `docs/api-contracts/account/openapi.yaml`。 - Scanner：未修改 `muse-cloud/scripts/**`。 - SQL：新增 `muse-cloud/sql/muse/V11__extend_account_real_api_schema.sql`。 - Java：新增 Account Controller / Service / DTO / VO / DAL / Mapper / Facade / Guard / AutoConfiguration 及 P1R gate tests；删除旧 Account 合同兜底 Controller。 - Coverage：更新 `docs/superpowers/reports/p1r-api-coverage.json` 和 `docs/superpowers/reports/p1r-api-coverage.md`。