钱包与商业系统

“共享一个钱包”不等于把所有价值压成一个余额数字。OceanWay 需要统一付款主体、计量与账本，同时清楚区分可消费积分、订阅授权、定向权益、资源包和企业合同。

计费边界

每个个人空间或企业 Organization 只有一个 Billing Account：

Billing Account
├── 积分钱包
│   ├── 充值积分
│   ├── 套餐积分
│   ├── 活动赠送积分
│   └── 企业授信（后续）
├── 定向权益
│   ├── 图片张数
│   ├── 视频次数 / 秒数
│   └── 音频次数
├── 产品订阅与席位
├── 资源包
└── 预算与限额
    ├── Workspace
    ├── Project
    ├── Member
    ├── Product
    ├── Agent
    ├── Service Account
    └── API Key

预算和限额只是消费约束，不是多个子钱包。所有产品最终进入同一个追加式账本，避免余额转移、重复入账和跨产品对账困难。

当前实现基线

现有统一计费 V2 候选已经提供可复用底座：

• 网页创作与公开 API 共用费率快照、积分账户和账本；
• 网页通过 Session/内部 Worker 身份执行，公开 API 通过 Developer Key 鉴权；
• PostgreSQL 使用 NUMERIC(38,18) 与十进制字符串保存精确金额；
• 支持 Token、分层 Token、按张、按秒、按次和混合计量；
• 支持预占、结算、释放、退款、待对账和幂等；
• 套餐、活动、开户和充值积分按批次保存；
• 图片张数、视频次数/秒数、音频次数等定向权益独立于积分；
• 一个请求只有在定向权益完整覆盖时才使用权益，否则完整使用积分，不做隐式混扣。

目标架构复用这套精确账本，把当前“按用户所有”升级为“按 Billing Account 所有”，再增加 Organization、Workspace、Project、成员、Service Account 与产品订阅维度。

Text/Media Gateway 只返回 Provider Usage、供应成本和任务事实，不拥有 OceanWay 用户费率、Rate Card、Reservation、Ledger、Refund、钱包、订阅或用户 Quota。网关内部容量和成本保护不能映射或覆盖用户余额。Media Gateway 也不保留面向客户的价格簿。完整调用边界见调度、执行与模型网关池。

价值类型

钱包首页应同时展示“可用积分、即将到期权益、订阅、预算与待结算”，不能把它们相加成一个没有业务含义的总数。

统一消费链路

失败边界：

• 未通过权限、费率或余额检查时不调用上游；
• 明确未发往上游或上游明确失败时释放预占；
• 产物生成但媒体落盘失败时按原 Reservation 执行补偿或退款；
• 实际费用超过预占时进入待对账，不允许静默负余额；
• 重复幂等请求不重复调用、扣款、发放或退款。

产品只提交 Quote 请求和不可变 Meter Event，不能直接修改余额。

Media Gateway Task/Provider Attempt Observation 只证明 Provider 侧事实，未来可选的 Callback Receipt 也不例外。只有 OceanWay Execution/Metering 在关联同一 Attempt、已验证的输出或资产状态与 Price Snapshot 后，才能提交一次性结算事实；重复轮询、乱序状态或迟到回调不得重复结算。

Meter Event

每条用量事实至少记录：

meterEventId
idempotencyKey
organizationId
workspaceId
projectId?
billingAccountId
principalId
serviceAccountId?
product
runId
runStepId
executionAttemptId
agentRevisionId?
modelOfferingId
modelDeploymentId
usage
priceSnapshotId
occurredAt
traceId
correlationId
operationId

模型供应商成本、OceanWay 用户售价和最终财务结算是三个可独立对账的事实，不能只保存一个“扣了多少积分”。

其中 OceanWay Rate Card、Reservation 与追加式 Ledger 是用户账务事实源；Text/Media Gateway 的 Provider Usage/Cost 和供应商账单只构成供应成本证据。缺少任一侧证据时进入对账，不得由网关余额或内部价格推算用户扣款。

付款方与预算

Run 创建时固定 billingAccountId，执行中不得更改：

• 个人空间任务使用个人 Billing Account；
• 企业 Project 使用企业 Billing Account；
• Workspace 与 Project 可以获得预算；
• 成员、Agent、Service Account 与 API Key 可以获得更细的硬/软限制；
• 组织余额不足时禁止自动改扣成员个人钱包；
• Agent 调用子 Agent 时沿用同一个预算树，不能重新获得完整额度。

预算至少支持：

• 单次上限；
• 每日、每月或合同周期上限；
• 软预警与硬阻断；
• 允许产品、模型、Agent 和环境；
• 审批阈值；
• 已用、预占、待对账和可用额度；
• 预算责任人与通知对象。

高成本任务在执行前展示付款主体、预计区间和预算影响。API 请求无法交互确认时，使用预先配置的硬限制和明确错误响应。

执行、资产与账务对账

普通失败任务、财务差异和正式对账案件不是同一个概念。当 Provider、Run、Asset、Usage 与 Billing 事实无法自然闭合时，管理员平台创建 Reconciliation Case：

reconciliationCaseId
caseType / status / severity
correlationId / operationId
runId / executionAttemptId
gatewayTaskId? / providerAttemptId?
assetVersionId?
reservationId / meterEventId? / ledgerEntryIds[]
economicExposure
evidenceLinks[]
resolutionProposal
approvalRecords[]
resolutionCommandId?
openedAt / resolvedAt?

典型案件包括：

• Provider 是否创建任务未知，Reservation 长期未终态；
• Provider 成功但结果未取回或 Asset 未登记；
• Asset 已登记但 Run 或 Settlement 未完成；
• Usage 缺失、实际费用超过预占或供应账单不一致；
• 重复 Provider Attempt、重复 Meter Event 或疑似重复结算；
• 用户已退款但 Provider 成本已经发生；
• Poll 与未来 Callback 的终态或 Usage 冲突。

对账人员只能提出和执行受控领域命令：查询原任务、重新取回原结果、释放 Reservation、按可信 Usage 结算、追加退款或记录平台承担成本。禁止直接编辑 Reservation、余额或 Ledger 行；账务修复只追加可追溯分录。涉及金额或客户影响的动作按策略进行职责分离、审批和审计。

Reconciliation Case 由管理员平台与运维控制面管理流程与证据，Billing Service 仍是 Reservation、Settlement、Refund 和 Ledger 的唯一事实源。

商业商品模型

商品由不可变 Benefit Snapshot 描述，避免付款后因运营编辑而改变已购权益：

订阅生命周期需要明确生效、续费、升级、降级、取消、过期和补差价规则。订阅授权与可消费积分分开，取消工作台订阅不应自动抹掉合法剩余的充值积分。

购买入口

购买与介绍分为三层：

1. 公共 /pricing：解释产品组合、适合对象、计量方式、企业方案和常见问题。
2. console.oceanway.tech 统一客户控制台：完成充值、订阅、资源包、席位、付款方式、账单、发票、预算和合同查看。
3. 产品内升级入口：显示当前任务相关的升级建议，跳转到统一购买流程并带回目标商品，不在每个产品复制一套商城。

购买完成后，Entitlement 由统一服务发放，所有平台读取同一事实源。

Console 是购买和账户管理界面，不是账务事实源。完整页面边界、产品回跳和企业权限见统一客户控制台。

产品订阅与共享积分

推荐原则是“产品授权可独立，积分可跨平台”：

• Canvas、漫剧、电商可以有独立订阅和席位；
• 订阅决定能否进入某项专业功能、并发和企业能力；
• 同一 Billing Account 的通用积分可支付所有已允许产品的模型用量；
• 定向权益只用于匹配的能力；
• 企业管理员可以限制某产品或某 Project 的消费。

这样既能清楚销售不同产品，又不会让用户在五个平台之间充值和搬运余额。

第三方费用

MCP 可能触发广告费、运费、采购款或 SaaS 自身用量。它们与 OceanWay 模型积分不是同一类费用：

• OceanWay 账本记录自身模型、运行和平台服务费用；
• 第三方费用记录 Provider、外部账户、预估/实际金额和责任主体；
• 涉及真实资金或不可逆费用时需要额外审批；
• 界面不得把第三方费用伪装成 OceanWay 积分扣款；
• 对账和发票责任按合同明确。

FDE 商业边界

FDE 项目通常包含售前、合同、里程碑、变更单、发票、回款和验收，不适合直接用普通积分钱包结算：

• FDE 专业服务费走合同、订单与发票；
• 项目期间需要的平台模型用量可以绑定合同额度或企业 Billing Account；
• 里程碑付款不会伪装成钱包充值；
• 交付完成后的持续 API/工作台使用进入组织订阅与账本；
• 公共案例发布与客户付款状态完全分离。

FDE 的私有里程碑、交付物、验收和合同权益摘要通过 Console 的 Delivery Workspace 展示；oceanway.tech/fde 与 /cases 只承担公开说明和获得授权的案例发布。私有交付数据不得因付款、验收或项目结束自动进入公开页面。

账务和合规不变量

• 每个 Billing Account 只有一套追加式账本，禁止直接改余额。
• 用量事实、价格快照、Reservation 和结算分录不可变且可追溯。
• 展示精度与存储精度分离；页面两位摘要不能写回精确账本。
• 网页和 API 共享计费账户，不表示它们使用同一种认证凭据。
• Key Quota、项目预算和成员额度不是子钱包。
• 付款方在执行前固定，任何失败都不能静默换钱包。
• 退款必须关联原订单、权益发放与消费事实，并保持幂等。
• 管理员不能直接改余额、Reservation 或 Ledger；所有对账处置通过幂等 Billing Command 并产生 Audit。
• Incident 恢复后必须扫描受影响的 Reservation、Meter Event、Settlement、Refund 与 Provider Cost Fact。
• 企业合同、第三方费用和 OceanWay 积分使用不同会计事实。