钱包与计费
唯一积分钱包、价格规则、两条扣费路径与使用记录
基本规则
- 只有一个钱包。 每个用户在平台上只有一个积分余额。API 调用、Studio、Drama、Commerce 的所有消费都从这个余额扣除，产品不存余额。
- 人民币充值，系统内用积分。 对客户只显示人民币和积分，不提供多币种钱包。供应成本的原始单位按事实保存，不对客户展示。
- Console 可以看到全部。 用户在 Console 里看到总余额、充值记录，以及所有产品的使用记录，可以按产品筛选。
2026-10-02 已确定的充值与订阅方向
- 普通充值初始基准为 40元人民币获得100积分，即1元=2.5积分、1积分=0.4元，可由后台调整；这是销售换算，不是供应成本换算。金额以人民币分保存，内部积分单位与舍入由开发按真实基线完成映射和验证，不要求用户先提供技术数值。
- 首期提供充值与按周/按月订阅，周/月套餐更优惠。价格、额度、周期、重置、到期及支付方式通过后台配置，复用new-api已具备的字段与管理能力；尚未配置完整的套餐保持未上架，不阻塞配置功能开发。原生能力未覆盖的权益须明确扩展范围，不能宣称已有。所有产品仍使用统一钱包与记账服务，订阅接入不能绕过这条资金路径。
- 模型计费方式、价格与倍率复用new-api的配置能力，用户指定初始倍率为1，后续可调整。开发负责核对原生模型/输出/缓存等字段的含义及积分显示换算，不把字段映射转成用户必须先回答的编码阻断；原生计价字段与供应成本分别保存。
- 异常消费暂沿用new-api原生计费规则，由开发审计超额和缺用量的实际计算并接入统一记账、持久恢复与隔离PG验收。重复扣款、Key失配和未知提交重新付费生成等已复现缺陷仍须修复；用户选择原生计费规则不改变原任务核对和幂等要求。
- 退款暂由管理员控制，首期不开发用户自助线上退款或自动支付渠道退款。管理员处理原订单/原消费关联、实退金额及必要积分调整，保留权限、幂等和审计。模型失败释放未消费预留与充值退款是不同业务动作，不能通过关闭线上退款遗失原操作账务恢复。
支付相关内容均应配置化：充值比例、档位与折扣、套餐、渠道开关、商户信息、回调地址及原生渠道支持的选项。沿用new-api现有配置源和管理入口，在迁入Admin时接入平台权限与审计，不建立平行配置库或另一套计费引擎。商户密钥只由后端保存，管理读取脱敏，不进入前端包、日志或证据。订单保存创建时的金额、币种、权益与配置依据；后续改价不改写历史订单或消费快照。渠道未配置完整时不允许下单；商户凭据是启用真实支付与联调的输入，不是本地夹具开发的前置条件。
统一记账与价格快照
以下是平台改造的验收要求，尚未实现；不能因为 new-api 已有预扣能力就视为通过。
- 模型与非模型消费共用平台的余额、冻结额度和记账服务。新增接口必须接入 new-api 的资金路径，不建立 Core 钱包与 quota 之间的同步机制。产品不得在平台扣费前后再执行自己的积分扣减。
- 可用余额扣减、冻结额度变化、操作状态和资金流水必须在数据库事务内一致提交，并有唯一约束保护重复操作。用户余额与 API Key 的额度限制是不同概念，令牌额度的失败补偿也要有持久记录。
- 金额和积分使用确定的整数最小单位或定点数，接口声明单位与精度；禁止浮点误差改变资金结果。普通充值初始比例40元=100积分，后台可配置；内部单位与舍入映射由开发验证后写入正式契约。
- 预留时保存不可变价格快照：客户方案及版本、模型或收费项、单价、单位、倍率、精度与舍入规则。结算和退款沿用原快照，改价只影响后续的新操作。
- 每笔操作有平台生成的
operation_id。余额、资金流水、使用记录能通过它核对；展示日志不是资金正确性的唯一依据。 - 资金结果不依赖进程内标记或异步 goroutine 是否执行成功。失败的结算、退款和记录写入有持久恢复状态，重启后继续原操作。
五类规则要分开管理
| 规则 | 回答的问题 | 状态 |
|---|---|---|
| 积分单位 | 一元人民币对应多少积分、精度多少 | 初始40元=100积分，销售比例可配置；内部映射由开发验证 |
| 充值套餐 | 付多少钱、得到多少积分、有无赠送 | 档位与折扣沿用原生配置；实际启用值由后台填写 |
| 模型价格表 | 每种模型每个计量单位消耗多少积分 | 原生计费配置，初始倍率1；后续调整保留历史快照 |
| 客户价格方案 | 某个账户适用哪套价格（零售标准、老零售、FDE、企业协议） | 待定 |
| 周期权益 | 是否有包月或周期额度 | 首期支持周/月优惠订阅；原生套餐字段后台配置，接入统一记账后验收 |
充值优惠影响“买到多少积分”，客户价格方案影响“每次用多少积分”。两者可以同时存在，但叠加规则必须明确，不能默默叠加。
三类客户的定价方式
零售客户。 设置零售标准方案和老零售客户方案。迁移时核对老客户在 sub2api 上的实际价格待遇，而不只是界面上的倍率。新增模型单独定价。旧价保护覆盖哪些模型、有效多久，待定。历史余额按原购买力换算，不自动扩大为永久享受旧充值优惠。
FDE 客户。 专属套餐拆成两部分报价：服务（实施、定制、培训等）和使用额度（积分或约定模型用量）。服务费不计入可消耗的模型余额。一个专属账户绑定一个价格方案，首期不做多人共享余额。
模型对接客户。 留在 uumi，不进入平台钱包。
客户价格的选择顺序：
- 有效期内的企业协议价，覆盖了该模型时优先。
- 未覆盖的模型，使用该账户指定的基础价格方案。
- 基础方案也没有价格时，拒绝调用并提示未配置，不静默使用意外的低价。
new-api 已有分组倍率和“用户组到使用组”的特殊倍率，简单的等级价可以直接用它实现。逐模型的企业协议价、价格版本与有效期需要扩展。
两条扣费路径
一、模型调用。 API 调用，以及产品代用户发起的模型调用，都经过平台的模型中转：
- 调用前按客户价格预扣积分。
- 完成后按上游返回的实际用量结算，多退少补。
- 写一条使用记录，标注来源产品。
二、非模型扣费。 不对应模型调用的收费（如 Commerce 批量导出、Studio 视频合成）使用平台新增的内部扣费接口：
| 动作 | 说明 |
|---|---|
| 预留 | 产品提交收费项、用途、任务身份和报价依据，平台校验产品权限与金额，冻结余额；余额不足直接拒绝 |
| 结算 | 业务完成后按原价格快照和确认的结果扣除，可以小于等于预留金额 |
| 释放 | 确认业务未执行或明确失败后退回冻结的积分；停止页面等待不等于可以释放 |
每次请求必须带产品后端生成的幂等键，作用域绑定“产品、用户、业务操作、动作”，并保存请求指纹。同键同请求返回原结果，同键不同金额、模型或输入返回 409；普通用户传入的 Header 不能直接成为账务身份。结算与释放还必须引用原 operation_id，平台从持久操作中取得用户与产品，不从新请求里重新指定。
模型调用的实际金额可能高于预扣额：平台必须在发出请求前评估允许的用量上限，必要时补充预留；已发生的超额消费不得因余额不足丢失流水。原生超额计费规则由开发核对并记录实际适用行为，不能静默记零。非模型业务要超过预留上限时，先申请补充预留，获得成功回执后才能继续扩大执行范围。
预留到期与异常恢复
预留有截止时间，但是否释放取决于业务状态：
| 状态 | 到期与恢复规则 |
|---|---|
| 仅预留，确认尚未发送执行请求 | 通过原子状态转换释放；执行方必须先取得开始执行的成功回执，已释放操作不能再启动 |
| 执行中 | 截止时间触发查询、续期或恢复处理，不直接释放；Worker 租约到期只触发接管 |
| 提交或结果未知、缺少用量 | 进入待核对，保留原任务及冻结记录；查询原任务，禁止重新创建或自动全额退款 |
| 明确成功 | 按确认的用量与价格快照结算；重复回执只生效一次 |
| 明确失败或确认未执行 | 按客户收费规则释放或退款；取消请求被接受不等于供应商已取消、不等于自动退款 |
| 已结算或已释放 | 终态不可被迟到请求覆盖；迟到成功作为异常核对记录处理，不能自动再次提交模型任务 |
结算与释放并发时只能有一个资金结果。退款关联原消费流水，不按当前价格重新计算。页面刷新、网络重试、Worker 重启均复用原操作；只有用户明确发起新的业务执行才建立新操作。
待核对必须有可查询状态、审计与处理入口，不能无限冻结而没有负责人。最大核对周期及部分成功收费政策在验证后定稿；人工处理同样使用幂等账务接口。
这个接口 new-api 没有，需要新增。旧 Core 已实现过类似的操作记录与幂等结算（代码在工作区 archive/repos/oceanway-core，见 service/billing_settlement.go 及其测试），可以作为设计参考。
使用记录
每一次扣费都要能回答“为什么扣了这些积分”：
- 账户、来源产品、调用者（Key 或产品）
- 模型与规格、实际用量及单位（Token、张、秒、次分开，不全叫 Token）
- 适用的价格方案和单价、预扣、实际扣除、释放或退款
- 关联的请求 ID 或产品任务 ID
new-api 的日志表需要增加“来源产品”字段，并支持非模型扣费的记录。
Console 与 Admin 的分工
| Console（客户看） | Admin（员工管） |
|---|---|
| 总余额、充值记录、赠送明细 | 充值套餐：实付金额、积分、赠送、适用客户、有效期 |
| 使用记录：按产品筛选，能看到每笔的价格依据 | 价格表：标准、客户等级、企业协议价及版本 |
| 公开价目表；登录后显示本人适用的价格 | 企业客户：专属账户与价格方案绑定 |
| 加减积分、有支付凭证的补单，全部留审计记录 |
待定事项
- 普通充值初始40元=100积分，充值/订阅/支付/计费配置化已定；具体套餐与商户输入仅影响对应能力上架，不阻断开发。内部单位、原生字段映射与统一记账兼容性由开发验证。
- 是否赠送积分、积分是否过期、赠送与购买积分的扣减顺序、退款时赠送如何处理。
- 零售老客户旧价保护的模型范围和期限。
- 首发实际启用的支付方式及商户配置，未启用渠道不得接受订单。
- 异常消费沿用new-api原生计费；部分成功及长期待核对的人工处理入口、负责人和验收须补齐。
- 首期管理员控制退款、无用户自助线上退款已确定；人工退款的原订单关联、权限和积分调整验收仍须完成。
验证场景及证据要求见平台集成验证。