zizi-al/oh-my-muse
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
oh-my-muse/docs/superpowers/specs/2026-05-28-P1R-3-account-real-api-design.md

32 KiB
Raw Blame History

P1R-3：Account Real API 规格

  • 版本：v1
  • 日期：2026-05-28
  • 状态：review 已通过；2026-05-29 实现阶段已收口到 dedicated / needs_verification
  • 上游规格：docs/superpowers/specs/2026-05-25-P1R-muse-cloud-real-api-design.md
  • 基线输入：docs/superpowers/reports/p1r-api-coverage.json
  • 范围：muse-cloud/muse-module-member/** 中 Account 专用实现、Account 相关追加迁移、P1R-3 覆盖门禁
  • 非范围：AI runtime / SSE、Knowledge / RAGFlow、Market 主流程、Events SSE、修改 muse-cloud/scripts/** 掩盖缺口、静默修改 OpenAPI、把 Account operation 标为 completed

1. 结论

P1R-3 的目标不是继续扩展 MuseContractPersistenceService，也不是把 Account 的通用持久化响应包装成 OpenAPI DTO。

本阶段要把 Account 域从“通用持久化可响应”推进到“真实账户业务 API 可验收”：

  1. Account 33 个 operation 当前全部是 generic_persistence / incomplete，必须退出通用持久化完成口径。
  2. 仓库没有 muse-module-account，当前 Account 合同实际挂在 muse-module-member；P1R-3 的 owner 应落在 muse-module-member 的 Account 子域，而不是新增孤立模块。
  3. Account owner 只拥有用户资料、权益、配额、用量、New-API 绑定、调用归因读模型、安全事件、个人中心导出的账户事实。
  4. 购买、授权、发布记录只能读取 Market/Content/Knowledge/AI 已产生的事实或投影，不能在 Account 阶段实现 Market 主流程。
  5. New-API binding / recheck / quota request / integration call / call attribution 必须有 commandId 幂等、外部调用记录和失败补偿边界；其中 quota request 与 call attribution 按 OpenAPI 暴露 correlationId，binding / recheck 只在服务端 integration call 中关联 bindingId / jobId，不向响应偷加 OpenAPI 未定义字段。未接真实 New-API runtime 前只能保持 needs_verification。
  6. P1R-3 通过后的覆盖状态目标统一为 dedicated / needs_verification，不能写成 completed。外部 owner 未闭合时返回合同内 CommonResult 业务错误或 pending job，不使用 coverage 的 blocked 完成状态。

2. 已验证事实

2.1 执行工作面

用户给定主路径 /Users/qingse/Sync/local-git/oh-my-muse 当前不是本阶段真实工作面。只读核验结果显示：

  • /Users/qingse/Sync/local-git/oh-my-muse 当前在 feature/p1-muse-cloud-backend-20260524，且有未跟踪文件。
  • dev/1.0.0 已被 worktree 占用：/Users/qingse/.config/superpowers/worktrees/oh-my-muse/dev-1.0.0。
  • 写入本规格和执行计划前，真实工作面 dev/1.0.0 的 git status --short --branch 输出为 ## dev/1.0.0...origin/dev/1.0.0，无未提交改动。

本规格和执行计划落在真实 worktree：

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

2.2 覆盖矩阵

来自 docs/superpowers/reports/p1r-api-coverage.json：

指标 数量
全量 operation 233
completed 0
needs_verification 67
incomplete 166
generic_persistence 164
sse_placeholder 2
missing 0
blocked 0
Content dedicated / needs_verification 51
Meta dedicated / needs_verification 16
Account operation 33
Account generic_persistence / incomplete 33
Account dedicated / needs_verification 0

Account 当前没有 catch_all、sse_placeholder、missing 或 dedicated。所有 Account operation 的 notes 均为：由 MuseContractPersistenceService 通用持久化处理，不是 P1R 完成证据。

2.3 当前代码事实

当前没有 muse-cloud/muse-module-account/**。Account 合同入口在 muse-cloud/muse-module-member/**：

  • muse-cloud/muse-module-member/muse-module-member-server/src/main/java/cn/iocoder/muse/module/member/controller/admin/AdminMuseAccountContractController.java
  • muse-cloud/muse-module-member/muse-module-member-server/src/main/java/cn/iocoder/muse/module/member/controller/app/AppMuseAccountContractController.java

这两个 Controller 使用宽泛路由接管：

  • Admin：/muse/account/**
  • App：/muse/me、/muse/profile、/muse/account/**

并统一委托：

  • MuseContractPersistenceService.handle(...)

当前缺失：

  • Account 专用 Controller。
  • Account Application Service。
  • Account OpenAPI 对应 DTO / VO。
  • Account DO / Mapper。
  • Account commandId + requestHash 幂等服务。
  • Account 领域审计与 security event 写入。
  • App user owner guard 的统一后端强制。
  • Admin RBAC 权限点。
  • New-API binding / recheck 的真实外部调用边界。
  • integration call / correlation / call attribution 的专用事实表或投影。
  • balance snapshot、export task、download credential 的专用持久化。
  • purchase / license / publish record 的 Account 视角投影。

已有 Yudao 会员能力可复用但不是 OpenAPI 完成路径：

  • AppMemberUserController 只覆盖 /member/user/**。
  • MemberUserController 只覆盖 /member/user/** 管理端会员用户。
  • MemberUserService / MemberUserMapper 可作为用户资料底层能力。

2.4 当前 DDL

muse-cloud/sql/muse/V2__init_account_schema.sql 已有 Account 基础表：

  • muse_member_entitlement
  • muse_member_entitlement_audit_log
  • muse_member_quota
  • muse_member_usage_record
  • muse_member_security_event
  • muse_member_new_api_binding

muse-cloud/sql/muse/V7__add_contract_operation_audit.sql 已有通用操作记录：

  • muse_domain_operation_record

muse-cloud/sql/muse/V8__add_contract_workflow_and_market_interaction.sql 已有通用工作流和市场购买：

  • muse_domain_workflow_task
  • muse_market_purchase

muse-cloud/sql/muse/V6__init_market_schema.sql 已有 Market 侧可读来源：

  • muse_market_asset
  • muse_market_asset_version
  • muse_market_installation
  • muse_market_publish_request
  • muse_market_appeal
  • muse_market_handoff

这些表不足以完成 P1R-3：

  • 没有 Account 专用 command 表；muse_domain_operation_record 只有 domain 级 replay，没有 request hash 冲突判断。
  • 没有 balance snapshot 表。
  • 没有 integration call 表。
  • 没有 call attribution job 专用表和 per-call 归因结果。
  • 没有 quota request 专用状态表；当前只落 muse_domain_workflow_task。
  • 没有 account export task 表和 download credential 表。
  • muse_member_security_event 只有确认字段，缺 acknowledge action / note / riskSummary / append-only audit。
  • muse_member_entitlement_audit_log 缺 OpenAPI 所需 before/after 快照完整填充和审计事件关系。
  • purchase/license/publish records 没有 Account 视角读模型或明确 projection owner。

3. 目标

  1. 为 33 个 Account operation 定义真实 API 落地边界。
  2. 用专用 Controller / Service / DTO / DAL / DDL 替代通用持久化完成口径。
  3. 建立当前用户、profile、权益、配额、余额、用量、安全事件、导出下载的账户事实模型。
  4. 建立 New-API binding / recheck / quota request / integration call / call attribution 的 correlation 边界。
  5. 建立 purchase / license / publish records 的 Account 视角投影，不接管 Market 主流程。
  6. 建立 commandId 幂等、requestHash 冲突校验、owner guard、admin RBAC、审计和错误响应。
  7. 建立 P1R-3 阶段门禁，防止 Account operation 继续被 generic_persistence 或 completed 混淆。

4. 非目标

  1. 不修改 OpenAPI 来适配当前代码。若发现合同纠偏需求，必须单独列出原因、影响范围和是否属于合同纠偏。
  2. 不实现 AI task 真实 New-API 调用、AI runtime、Agent、Prompt、Quality、Suggestion、Job。
  3. 不实现 AI task SSE stream 或统一 Events SSE。
  4. 不实现 Knowledge / RAGFlow / projection 主流程。
  5. 不实现 Market 购买、安装、handoff、审核、召回、申诉主流程。
  6. 不把 MuseContractPersistenceService、muse_domain_operation_record、muse_domain_workflow_task 原始行、空列表、status: accepted 作为完成证据。
  7. 不修改 muse-cloud/scripts/** 来掩盖真实缺口。若扫描器无法识别 dedicated 实现，先说明扫描规则合同纠偏原因和影响范围。
  8. 不把前端按钮隐藏或页面权限当作后端权限。

5. Operation 清单与当前状态

operationId Method Path 当前状态 真实 owner P1R-3 目标
adminListAccountUsers GET /admin-api/muse/account/users generic_persistence / incomplete Account User Query dedicated / needs_verification
adminGetUserEntitlements GET /admin-api/muse/account/users/{userId}/entitlements generic_persistence / incomplete Account Entitlement Query dedicated / needs_verification
adminCreateQuotaAdjustment POST /admin-api/muse/account/users/{userId}/quota-adjustments generic_persistence / incomplete Account Quota Command dedicated / needs_verification
adminListQuotaAdjustments GET /admin-api/muse/account/users/{userId}/quota-adjustments generic_persistence / incomplete Account Quota Query dedicated / needs_verification
adminListNewApiBindings GET /admin-api/muse/account/new-api-bindings generic_persistence / incomplete Account New-API Query dedicated / needs_verification
adminCreateNewApiBinding POST /admin-api/muse/account/users/{userId}/new-api-binding generic_persistence / incomplete Account New-API Command dedicated / needs_verification
adminCreateQuotaRequest POST /admin-api/muse/account/users/{userId}/quota-requests generic_persistence / incomplete Account New-API Quota Command dedicated / needs_verification
adminGetBalanceSnapshots GET /admin-api/muse/account/users/{userId}/balance-snapshots generic_persistence / incomplete Account Balance Query dedicated / needs_verification
adminCreateCallAttributionJob POST /admin-api/muse/account/call-attribution-jobs generic_persistence / incomplete Account Attribution Command dedicated / needs_verification
adminGetCallAttributionJob GET /admin-api/muse/account/call-attribution-jobs/{jobId} generic_persistence / incomplete Account Attribution Query dedicated / needs_verification
adminGetIntegrationCallByCorrelation GET /admin-api/muse/account/integration-calls/by-correlation/{correlationId} generic_persistence / incomplete Account Integration Query dedicated / needs_verification
adminListUsageRecords GET /admin-api/muse/account/usage-records generic_persistence / incomplete Account Usage Query dedicated / needs_verification
adminListPurchaseRecords GET /admin-api/muse/account/purchase-records generic_persistence / incomplete Account Purchase Projection Query dedicated / needs_verification
getCurrentUser GET /app-api/muse/me generic_persistence / incomplete Account Current User Query dedicated / needs_verification
getProfile GET /app-api/muse/profile generic_persistence / incomplete Account Profile Query dedicated / needs_verification
updateProfile PATCH /app-api/muse/profile generic_persistence / incomplete Account Profile Command dedicated / needs_verification
getAppEntitlements GET /app-api/muse/account/entitlements generic_persistence / incomplete Account Entitlement Query dedicated / needs_verification
getAppUsage GET /app-api/muse/account/usage generic_persistence / incomplete Account Usage Query dedicated / needs_verification
getAppNewApiBinding GET /app-api/muse/account/new-api-binding generic_persistence / incomplete Account New-API Query dedicated / needs_verification
appRecheckNewApiBinding POST /app-api/muse/account/new-api-binding/recheck generic_persistence / incomplete Account New-API Command dedicated / needs_verification
getAppBalanceSnapshots GET /app-api/muse/account/balance-snapshots generic_persistence / incomplete Account Balance Query dedicated / needs_verification
appCreateQuotaRequest POST /app-api/muse/account/quota-requests generic_persistence / incomplete Account Quota Request Command dedicated / needs_verification
appGetQuotaRequest GET /app-api/muse/account/quota-requests/{requestId} generic_persistence / incomplete Account Quota Request Query dedicated / needs_verification
appGetIntegrationCallByCorrelation GET /app-api/muse/account/integration-calls/by-correlation/{correlationId} generic_persistence / incomplete Account Integration Query dedicated / needs_verification
appListPurchases GET /app-api/muse/account/purchases generic_persistence / incomplete Account Purchase Projection Query dedicated / needs_verification
appListLicenses GET /app-api/muse/account/licenses generic_persistence / incomplete Account License Projection Query dedicated / needs_verification
appListPublishRecords GET /app-api/muse/account/publish-records generic_persistence / incomplete Account Publish Projection Query dedicated / needs_verification
appListSecurityEvents GET /app-api/muse/account/security-events generic_persistence / incomplete Account Security Query dedicated / needs_verification
appGetSecurityEvent GET /app-api/muse/account/security-events/{eventId} generic_persistence / incomplete Account Security Query dedicated / needs_verification
appAcknowledgeSecurityEvent POST /app-api/muse/account/security-events/{eventId}/acknowledge generic_persistence / incomplete Account Security Command dedicated / needs_verification
appCreateExportTask POST /app-api/muse/account/export-tasks generic_persistence / incomplete Account Export Command dedicated / needs_verification
appGetExportTask GET /app-api/muse/account/export-tasks/{taskId} generic_persistence / incomplete Account Export Query dedicated / needs_verification
appDownloadExport GET /app-api/muse/account/downloads/{credentialId} generic_persistence / incomplete Account Export Download dedicated / needs_verification

6. 目标架构

flowchart TD
    A[Admin Account Controllers] --> B[Account Application Services]
    C[App Account Controllers] --> B
    B --> D[Account Command Service]
    B --> E[Account Audit Service]
    B --> F[Account Owner Guards]
    B --> G[Account Query Assemblers]
    B --> H[Account Persistence]
    B --> I[External Facades]
    H --> J[(member_user)]
    H --> K[(muse_member_* tables)]
    H --> L[(muse_account_* extension tables)]
    I --> M[New-API Client Boundary]
    I --> N[Market Projection Boundary]
    I --> O[FileService Boundary]
    I --> P[Attribution Source Boundary]

6.1 Controller

推荐拆分：

Controller 职责
AdminAccountUserController 用户摘要、用户权益、配额调整、余额快照
AdminAccountNewApiController New-API binding 列表、创建/刷新、quota request
AdminAccountUsageController usage records、integration call、call attribution job
AdminAccountPurchaseController purchase records 管理端查询
AppAccountProfileController /app-api/muse/me、/app-api/muse/profile
AppAccountEntitlementController 权益、用量、余额、quota request
AppAccountNewApiController binding 查询、recheck、integration call 查询
AppAccountMarketRecordController purchases、licenses、publish records
AppAccountSecurityController security events、acknowledge
AppAccountExportController export task、download credential

Controller 只负责：

  • @PreAuthorize 或 app authenticated owner 入口。
  • X-API-Version: 1 校验。
  • path/query/body 参数校验。
  • DTO 进入 Application Service。
  • 默认用 CommonResult<T> 返回 code/data/msg。
  • appDownloadExport 是 OpenAPI 明确的例外：成功响应必须返回 application/octet-stream 文件流；失败响应仍沿用项目统一错误响应。

禁止：

  • Controller 访问 Mapper。
  • Controller 拼接业务 JSON。
  • Controller 调用 MuseContractPersistenceService 作为完成路径。
  • Controller 静态返回 OpenAPI 样例。

6.2 Service

推荐服务：

Service 职责
AccountProfileService 当前用户、资料查询、资料更新、乐观锁
AccountEntitlementService 权益、配额、余额快照查询与装配
AccountQuotaService 配额调整、quota request 状态机
AccountNewApiBindingService New-API binding、recheck、外部同步边界
AccountUsageService usage records、usage summary、integration call 查询
AccountAttributionService call attribution job 创建、状态、归因校验边界
AccountMarketRecordService purchase/license/publish records Account 投影查询
AccountSecurityService security event 查询、确认、append-only 审计
AccountExportService export task、download credential、FileService 边界
AccountCommandService commandId、requestHash、resultSnapshot 幂等
AccountAuditService Account 领域审计和安全事件写入

6.3 DTO / Assembler

每个 OpenAPI schema 必须对应专用 VO/DTO，不能返回 Map<String, Object> 或 DO。

最小 DTO 覆盖：

  • AdminAccountUserSummaryRespVO
  • AdminUserEntitlementDetailRespVO
  • QuotaAdjustmentReqVO
  • QuotaAdjustmentResultRespVO
  • QuotaAdjustmentLedgerEntryRespVO
  • NewApiBindingSummaryRespVO
  • NewApiBindingCreateReqVO
  • NewApiBindingResultRespVO
  • AdminQuotaRequestCreateReqVO
  • AdminQuotaRequestResultRespVO
  • AppQuotaRequestResultRespVO
  • QuotaRequestStatusRespVO
  • AdminBalanceSnapshotEntryRespVO
  • AppBalanceSnapshotEntryRespVO
  • CallAttributionJobCreateReqVO
  • CallAttributionJobResultRespVO
  • CallAttributionJobDetailRespVO
  • AdminIntegrationCallDetailRespVO
  • AppIntegrationCallDetailRespVO
  • AdminUsageRecordRespVO
  • AdminPurchaseRecordRespVO
  • AppCurrentUserSummaryRespVO
  • AppProfileRespVO
  • AppProfileUpdateReqVO
  • AppEntitlementRespVO
  • AppUsageSummaryRespVO
  • AppNewApiBindingSummaryRespVO
  • AppNewApiBindingRecheckReqVO
  • AppNewApiBindingRecheckRespVO
  • AppQuotaRequestCreateReqVO
  • AppPurchaseRecordRespVO
  • AppLicenseRecordRespVO
  • AppPublishRecordRespVO
  • SecurityEventSummaryRespVO
  • SecurityEventDetailRespVO
  • SecurityEventAcknowledgeReqVO
  • SecurityEventAcknowledgeResultRespVO
  • AccountExportTaskCreateReqVO
  • AccountExportTaskResultRespVO
  • AccountExportTaskDetailRespVO

Assembler 负责：

  • ID 转字符串。
  • 时间字段统一为 OpenAPI date-time。
  • 手机、邮箱、外部订单、IP、设备信息脱敏。
  • PageResult<T> 与 OpenAPI PaginatedResult.list 对齐。
  • 不暴露 New-API token、provider authority、模型路由、Prompt/Response 原文、后台权限表。

7. 持久化设计

7.1 复用现有表

表 P1R-3 用途 缺口
member_user 当前用户、用户摘要、账号基础状态 不直接承载 P1R-3 profile 乐观锁和公开笔名等扩展事实
muse_account_profile profile 扩展、expectedVersion、公开资料 P1R-3 新增轻量扩展表
muse_member_entitlement plan、权益、额度摘要 需要 DTO 装配和来源语义
muse_member_quota quota 明细、剩余和重置周期 需要资源类型映射和并发调整
muse_member_entitlement_audit_log quota adjustment ledger 需要 before/after 快照和 audit event 关联
muse_member_usage_record usage records、app usage summary 需要 correlation、归因状态、统计聚合
muse_member_security_event security event 查询 需要 acknowledge action/note/audit
muse_member_new_api_binding New-API binding 需要 recheck status、失败原因、外部同步时间
muse_domain_workflow_task 可作为过渡读取旧任务 不能作为 Account dedicated 完成证据
muse_market_purchase purchase projection 上游来源 Account 只通过 muse_account_record_projection 读取
muse_market_installation license projection 上游来源 Account 只通过 muse_account_record_projection 读取
muse_market_publish_request publish records 上游来源 Account 只通过 muse_account_record_projection 读取

7.2 追加迁移

P1R-3 实现阶段建议新增 V11__extend_account_real_api_schema.sql。最小新增：

  • muse_account_command
  • muse_account_audit
  • muse_account_profile
  • 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

关键约束：

  • muse_account_command 唯一键：(tenant_id, command_id)。
  • command 记录必须包含 operation_id、actor_user_id、owner_user_id、target_type、target_id、request_hash、result_snapshot。
  • 同一 commandId + 不同 requestHash 返回 409。
  • muse_account_audit 必须覆盖写操作、外部调用、导出下载和高敏安全动作，索引 account_user_id、operation_id、correlation_id。
  • muse_account_profile 必须以 account_user_id 唯一，包含 profile_version 支撑 expectedVersion。
  • muse_account_record_projection 必须包含 record_type，限定为 purchase、license、publish，并保存上游 source_table / source_id / source_revision。
  • app 可见表必须具备 account_user_id / owner_user_id 索引。
  • correlation_id 在 integration call 维度需要唯一或去重键。
  • download credential 必须具备 credential_hash、account_user_id、task_id、expires_at、consumed_at、revoked_at。

8. Owner Guard 与权限边界

8.1 App owner guard

App 入口所有读写必须以 getLoginUserId() 作为唯一账户 owner：

  • 不接受请求体中的 userId 作为 owner。
  • requestId、eventId、taskId、credentialId、correlationId 都必须反查 owner。
  • 查不到或 owner 不匹配返回 403 或 404，不能返回跨用户空数据掩盖越权。
  • appDownloadExport 必须同时校验 credential owner、过期、撤销、source blocked 和 task 完成状态。

8.2 Admin 权限边界

Admin 入口必须使用后端 RBAC：

操作组 建议权限点
用户摘要/权益/余额/用量/购买记录查询 muse:account:query
quota adjustment muse:account:quota-adjust
quota request / New-API binding muse:account:new-api:manage
call attribution job muse:account:attribution:manage
security event 管理端查询若后续加入 muse:account:security:query

Admin 也必须校验目标用户存在。Admin 只能管理账户域事实，不能绕过 Market、AI、Knowledge 的 owner 状态机。

9. commandId 与幂等

所有写操作必须通过 AccountCommandService：

operationId 幂等目标
adminCreateQuotaAdjustment quotaAdjustment:userId
adminCreateNewApiBinding newApiBinding:userId
adminCreateQuotaRequest quotaRequest:userId
adminCreateCallAttributionJob callAttribution:correlationId
updateProfile profile:actorUserId
appRecheckNewApiBinding newApiBindingRecheck:actorUserId
appCreateQuotaRequest quotaRequest:actorUserId
appAcknowledgeSecurityEvent securityEvent:eventId
appCreateExportTask exportTask:actorUserId

规则：

  1. commandId 必填的 operation 必须从请求体读取，不依赖 X-Command-Id。
  2. 稳定 JSON 计算 requestHash。
  3. 相同 commandId + 相同 requestHash 返回旧 resultSnapshot，并在 DTO 中按合同表达 idempotent_hit。
  4. 相同 commandId + 不同 requestHash 返回 409，错误码为 Account 幂等冲突。
  5. command 预占与业务写入必须在同一事务内。
  6. 异步任务只保证“任务创建幂等”，不保证外部 runtime 已完成。

10. Audit 与 Security Event

Account 审计分两层：

  1. muse_account_command：所有写命令的幂等和 result snapshot。
  2. muse_account_audit：业务可读审计，覆盖操作者、目标用户、operation、前后状态、correlationId、requestHash、风险摘要。

最小审计字段：

  • operationId
  • actorUserId
  • accountUserId
  • side
  • targetType
  • targetId
  • commandId
  • requestHash
  • correlationId
  • beforeSnapshot
  • afterSnapshot
  • status
  • errorCode
  • errorMessage
  • createdAt

Security event：

  • appAcknowledgeSecurityEvent 必须 append-only 记录 acknowledgement，不应覆盖历史处理动作。
  • action=session_revoked 不在 P1R-3 实现真实 session 失效；若 session owner 未接入，返回明确业务错误或 pending action，不伪造成功。
  • 账户导出高敏行为应生成 sensitive_export security event 或 audit event。

11. 错误响应

除 appDownloadExport 成功响应按 OpenAPI 返回 application/octet-stream 文件流外，其余接口使用项目现有 CommonResult<T> 成功封装。所有错误响应应保持 code/data/msg 的项目运行态一致性，不新增 OpenAPI 未定义字段。

Account 最小错误码：

场景 HTTP/业务语义 建议业务错误
X-API-Version 不支持 400 ACCOUNT_API_VERSION_UNSUPPORTED
用户不存在 404 ACCOUNT_USER_NOT_EXISTS
app owner 不匹配 403 ACCOUNT_RESOURCE_FORBIDDEN
commandId 缺失 400 ACCOUNT_COMMAND_ID_REQUIRED
commandId 冲突 409 ACCOUNT_COMMAND_ID_CONFLICT
expectedVersion 冲突 409 ACCOUNT_VERSION_CONFLICT
New-API binding 不存在 404 ACCOUNT_NEW_API_BINDING_NOT_EXISTS
New-API runtime 不可用 503 或业务错误 ACCOUNT_NEW_API_UNAVAILABLE
correlationId 不存在 404 ACCOUNT_INTEGRATION_CALL_NOT_EXISTS
余额/权益不足 409 ACCOUNT_QUOTA_EXHAUSTED
下载凭证过期/撤销 403 ACCOUNT_DOWNLOAD_CREDENTIAL_INVALID
导出来源 blocked 403 ACCOUNT_EXPORT_SOURCE_BLOCKED

12. New-API / Correlation 边界

P1R-3 只定义 Account 与 New-API 的账户侧边界：

  • adminCreateNewApiBinding / appRecheckNewApiBinding 只能创建 binding 或 recheck job。
  • binding / recheck 必须写入 muse_account_integration_call，并通过 bindingId / jobId 与内部 correlationId 关联；现有 OpenAPI 响应没有 correlationId 字段，P1R-3 不修改响应合同。
  • quota request 和 call attribution 已在 OpenAPI 中暴露 correlationId，必须用该值支持 adminGetIntegrationCallByCorrelation / appGetIntegrationCallByCorrelation。
  • 真实 New-API 用户创建、额度配置和余额查询若 runtime 未接入，必须以合同内业务错误或内部 pending/failed integration call 记录表达；不能为了“可追踪”向响应添加 OpenAPI 未定义字段，也不能返回 OpenAPI 未声明的状态值。
  • muse_account_integration_call 是外部调用去重、重试、错误和 attribution 的账户侧事实。
  • adminGetIntegrationCallByCorrelation 可看全局调用详情。
  • appGetIntegrationCallByCorrelation 只能查看当前用户 owner 的调用。

Call attribution：

  • adminCreateCallAttributionJob 只能基于已存在的 integration call / New-API callIds。
  • 请求体不能直接指定可信 user/work/agent/asset/license 归因事实。
  • 服务端必须从调用审计记录、业务任务、作品、资产、授权关系校验后写 attribution item。
  • AI runtime 真实调用不在 P1R-3 实现；Account 只消费调用记录。

13. 数据来源

数据域 P1R-3 数据来源
user/profile/me member_user + muse_account_profile + entitlement/security projection
entitlements muse_member_entitlement
quota muse_member_quota + muse_member_entitlement_audit_log
quota requests muse_account_quota_request + integration call
balance snapshots muse_account_balance_snapshot
usage records/app usage muse_member_usage_record + attribution fields
purchase records muse_account_record_projection(record_type=purchase)，上游来自 muse_market_purchase
license records muse_account_record_projection(record_type=license)，上游来自 muse_market_installation
publish records muse_account_record_projection(record_type=publish)，上游来自 muse_market_publish_request
New-API binding muse_member_new_api_binding + recheck job
integration calls muse_account_integration_call
call attribution jobs muse_account_call_attribution_job / item
security events muse_member_security_event + ack extension
export tasks/downloads muse_account_export_task + muse_account_download_credential + FileService boundary；下载成功响应为文件流

14. 外部阶段边界

边界 P1R-3 处理方式
AI task 真实 New-API 调用 P1R-4；P1R-3 不创建 AI task、不调模型
AI runtime / agent / prompt / quality / suggestions / jobs P1R-4；Account 只读已归因用量
AI task SSE stream P1R-4；P1R-3 export/call attribution job 不实现 SSE
Knowledge / RAGFlow / projection P1R-5；Account 只读授权或用量投影
Market P1R-6；Account 只读购买/授权/发布投影，不处理购买/安装/审核
Events SSE / 端到端验收 P1R-7；P1R-3 不标 completed
FileService P1R-3 定义导出下载边界；真实存储未接入时保持 needs_verification

15. 实现单元

P1R-3 实现阶段建议按以下单元推进：

  1. Preflight 与覆盖基线冻结。
  2. Account 基础设施与追加 DDL。
  3. DTO / DAL / Mapper 骨架。
  4. App me / profile。
  5. 权益、配额、余额、用量。
  6. New-API binding、recheck、quota request、integration call。
  7. call attribution job。
  8. purchase / license / publish records 投影。
  9. security events。
  10. export task / download credential。
  11. Account catch-all 路由退役。
  12. P1R-3 覆盖门禁与报告对账。

16. 验收标准

P1R-3 spec + plan review 通过后，进入实现阶段。实现阶段完成必须满足：

  1. Account 33 个 operation 有专用 Controller / Service / DTO。
  2. Account 33 个 operation 不再是 generic_persistence、catch_all、sse_placeholder 或 missing。
  3. Account operation 未经 P1R-7 真实端到端验收前，不允许标 completed。
  4. Account 全部保持 dedicated / needs_verification。
  5. Content 51 个 operation 保持 dedicated / needs_verification。
  6. Meta 16 个 operation 保持 dedicated / needs_verification。
  7. completedOperations=0。
  8. muse-cloud/scripts/** 未被用来掩盖缺口。
  9. Account 模块聚焦测试通过。
  10. P1rAccountMigrationSqlTest 通过，证明 V11 迁移包含 Account 审计、profile、projection、integration、export/download 等必要约束。
  11. P1R 门禁测试通过。
  12. 若未运行真实 PostgreSQL / Flyway / New-API runtime / FileService，必须在留痕中保留 needs_verification 风险。

17. 待确认项

  1. P1R-3 是否允许在 muse-module-member 内新增 account 包作为长期 owner。默认推荐此方案，因为仓库没有 muse-module-account，且用户资料属于 member 模块。
  2. New-API runtime 在 P1R-3 是否有可用测试环境。若没有，binding/recheck/quota request 只能做到合同内业务错误或内部 pending/failed 可追踪，保持 needs_verification。
  3. FileService 是否有可用测试环境。若没有，export task / download credential 只能验证凭证与状态机，不能验证真实文件流交付。