OceanWay Unified Billing V2

状态：LOCAL_DEPLOYMENT_CANDIDATE / CANDIDATE_EVIDENCE / NOT_FORMAL_TEST

术语边界

所有用户端和管理员端界面统一使用“积分”，不展示 api_credit。api_credit 仅保留为内部账本、数据库表与字段、API currency / unit 值和响应 Header 标识；本轮不修改这些机器契约。

产品规则

• OceanWay 是唯一面向用户的计费方；UUMI/new-api 只负责模型目录、价格目录、协议适配、渠道路由和结果返回。
• 网页创作与开发者 /v1 API 使用同一用户、同一 API Key、同一积分余额、同一费率快照和同一账本。
• 1.00 账户余额等于 1.00 积分。账户初始余额按原值直接入账，产品界面不展示来源迁移、旧余额或独立钱包。
• 内部金额使用十进制字符串与 PostgreSQL NUMERIC(38,18)；Token 级扣费最多保留 18 位小数。页面只把最终结果四舍五入显示为两位小数，不把显示值写回账本。
• 调用前必须存在有效费率并完成预占；没有费率、余额不足或按秒模型缺少时长时，请求不会发给上游。

钱包与权益

积分余额

内部表 api_credit_accounts 保存账户级精确调整，api_credit_lots 保存以下积分批次：

• subscription：套餐期限内的余额额度，优先消费并按最早到期时间排序；
• promotion：赠送余额额度，在套餐余额后优先消费；
• opening：账户初始余额；
• purchased：充值或余额商品发放。

api_credit_reservations 保存预占、实际结算、释放与待对账状态； api_credit_ledger_entries 是追加式审计分录。用户余额流水把一次请求展示为实际结算金额， 不会把预占和释放噪声重复展示成消费。

定向生成权益

套餐或活动可以发放图片张数、视频次数、视频秒数和音频次数。定向权益保存在独立的 generation_entitlement_* 批次、预占与流水表中，并可限制模型、质量或最长时长。 一个生成请求只有在可用权益能够完整覆盖时才使用权益；否则使用积分，不创建隐式 的“部分次数 + 部分余额”混合扣款。

消费顺序为：匹配的套餐定向权益 → 匹配的活动定向权益 → 套餐积分 → 活动积分 → 账户初始余额/充值余额。

费率模型

每个逻辑模型可使用以下一种计量方式：

• token：输入、输出、缓存读取、缓存写入、图片 Token、音频 Token；
• tiered：按上下文阈值选择本地解析后的分层 Token 费率；
• image：按实际张数；
• second：按请求中的实际秒数；
• request：按次；
• hybrid：Token 费用加按张、按秒或按次的固定费用。

管理员后台“模型计费”提供 从 UUMI 同步。POST /api/admin/pricing/sync 读取 https://uumi.lol/api/pricing，忽略 UUMI 的用户分组倍率，按 default=1 保存为 OceanWay 当前默认费率快照。model_ratio 在 new-api 中以 QuotaPerUnit=500000 表达，导入器乘 2 只是换算为“每百万 Token”展示与结算单位，不是额外加价；tiered_expr 中的明确单价直接 使用。原始表达式永不在 OceanWay 执行，只解析受支持的线性 tier(...) 结构。

同步会同时导入缓存读取和缓存创建倍率、固定 model_price、per_second 和价格版本。 管理员可以在本地快照上调整后保存；环境变量人工覆盖仍具有最高优先级。上游价格变化不会 在单个用户请求的热路径中自动改变已经保存的 OceanWay 费率。

预占、结算与失败

1. 服务端以用户、业务请求、逻辑模型、渠道、上游模型和调用类型生成幂等身份与请求指纹。
2. 图片/视频/音频先尝试完整覆盖的定向权益；否则按费率估算并预占积分。
3. 请求成功后按响应 usage、实际张数、实际秒数或请求次数结算，释放未使用预占。
4. 明确未发往上游或上游明确失败时释放；生成后处理失败按原 reservation 退款。
5. 实际费用高于预占时进入 reconciliation_required，不做隐式负余额或事后补扣。
6. 重复幂等请求不会再次发送上游、重复扣款、重复发放或重复退款。

余额分录的不变量是“预占借记 + 未使用部分释放 = 实际结算”；实际金额保存在 reservation， 不会再写第二笔结算借记造成重复扣费。

商品、支付与退款

商品保存不可变的 billingBenefits 快照，包括精确 apiCreditAmount 与定向生成权益。 支付成功按订单幂等键发放；套餐余额与生成权益按订单周期到期，一次性余额商品进入 purchased 批次。整单退款撤销未使用部分；已经消费的额度以精确账户调整冲回，避免退款 后保留已消费价值。支付回调、权益发放和退款均在同一 PostgreSQL 事务中执行。

账户数据承接

• 用户余额按十进制原值 1:1 写入统一积分账本（内部标识为 api_credit），最多保留 18 位小数；负余额进入账户调整。
• 有效 API Key 保持原值、状态、到期、IP、Quota、Used、RPM 和并发限制，并写入运行时 HMAC 与加密密文。
• 重复 Apply 使用稳定 ID、行指纹和幂等键，不新增余额、用户或 Key；源财务快照变化会安全拒绝。
• 用户端只显示当前 OceanWay 余额、权益、订单和用量，不出现“旧”“迁移”或第二套钱包标记。

对外接口

• GET /api/credits：精确总余额、按批次来源拆分、到期时间和定向生成权益；display_total 仅用于两位小数展示。
• GET /api/credits/ledger：实际消费、发放、退回与调整的精确分页流水。
• GET /v1/models：只返回已经发布、可路由且存在有效费率的模型，价格币种为 api_credit。
• /v1/chat/completions、/v1/responses、图片、视频和音频创建接口：返回 OceanWay request ID，非流式响应还可返回精确已扣金额。
• 用户 API Key 只在 OceanWay 鉴权，不转发给 UUMI/new-api；服务端使用独立内部渠道密钥。

部署配置与验证清单

1. 配置 PostgreSQL、加密密钥、API Key HMAC Pepper、Worker 令牌及 UUMI/new-api 系统渠道。
2. 管理后台同步 UUMI 1 倍费率，检查所有已启用逻辑模型均有正确计量方式后保存。
3. 创建包含积分、图片张数、视频次数/秒数的合成商品，验证支付、幂等发放和退款撤销。
4. 使用合成用户验证小于 0.01 的 Token 扣费、失败释放、权益优先级、余额两位显示和精确流水。
5. 在只读源快照上执行账户/Key dry-run、Apply、重复 Apply 和 Verify，核对用户级余额与 Key 原值认证。
6. 使用专用测试 Key 对 UUMI/new-api 分别执行文本、图片、视频和音频真实小额请求，核对上游 usage、OceanWay reservation、最终费用与媒体结果。
7. 完成数据库备份/恢复、Worker 重启、待对账记录处理和管理员审计验证后，才可切换生产流量。

本地候选证据（2026-08-31）

• 完整 pnpm run check:release 通过：依赖审计、ESLint、Prettier、Vitest（577 files / 2557 tests passed，12 skipped）、TypeScript、Next 生产构建（70/70）和 Standalone 产物检查均为绿色。
• 一次性 PostgreSQL 空库上，精确账本与账户数据承接测试 2/2 通过：覆盖 18 位小数、权益优先级、结算/退款、余额 1:1、重复 Apply 幂等和用户端无来源标签。
• Billing V2 Playwright 在 Chromium、390 px 和 430 px 三种视口通过 6/6：首次安装、管理员统一余额入账、余额流水两位展示、用户端无“旧/迁移/Sub2API 余额”标签、模型费率列表和保存交互均已验证。
• In-app Browser 对本地 Standalone 实例完成登录、首页余额、余额流水与“模型计费”页面检查；页面无 console error，模型费率保存成功。
• 重复执行 Standalone 资产准备已加入回归测试，避免 Sharp pnpm 链接导致二次启动自复制失败。

当前代码与自动化测试只构成本地候选证据，不代表真实支付、真实账户数据、真实模型费用或 正式 Testing/Operations 已经通过；部署和真实数据操作仍需独立授权。