D15 sub2api / newapi 计费体系

精讲（主营业务核心，全员必须理解）。公司的盈利闭环全在这：把上游能力变成可计费的服务卖给客户。第 4 周项目 B（计费引擎）就是它的简化复刻。

教学目标（学完能做什么）

• 能说出 sub2api / newapi 在计费链路里的分工
• 理解 newapi 类网关的四个核心概念：渠道(channel) / 令牌(token) / 分组(group) / 定价
• 能说清一次调用如何完成 鉴权 → 转发 → token 统计 → 扣费 → 流水
• 理解余额、流水、结算口径，能读懂一份计费流水
• 了解 sub-box 订阅体系与 dashboard 的定位

前置要求

• D11（数据库/事务）、D13（usage）、D14（端点验证）

本模块在业务中的位置

• 中游 + 下游：newapi 类网关把上游变成统一 API，sub2api 面向客户算钱。这一环决定公司赚不赚钱、账对不对得上。公司文档见 services/sub2api/docs/、services/sub-box/docs/。

内容分段

1. 分层再看一遍计费链路

上游端点（D14 验证过）→ newapi 类网关（渠道配置）→ sub2api（订阅/余额/流水）→ 客户
                              │                                       │
                          统一 API（OpenAI 兼容）                   面向客户算钱

• 记忆：newapi 管"货怎么供"，sub2api 管"钱怎么算"。

2. newapi 四个核心概念（渠道/令牌/分组/定价）

• 关键操作链：渠道（货）→ 分组（档）→ 令牌（卖给谁）→ 定价（收多少）。

3. 一次调用的计费全流程（D1 第 5 节的深化）

1. 客户用令牌请求 /v1/chat/completions（OpenAI 兼容）。
2. 网关鉴权：令牌有效？属于哪个分组？
3. 按分组/权重挑渠道，转发到上游（Claude 端点）。
4. 上游返回 usage（input/output tokens，D13 学过）。
5. 网关按定价表算钱：成本 = input_tokens × 输入单价 + output_tokens × 输出单价。
6. 在事务里：UPDATE 余额 + INSERT 流水（D11 的 ACID 用上了）。
7. 响应返回客户；余额不足/超限 → 401/403/429。

• 强调第 5-6 步：usage 是唯一计费依据，扣费必须事务原子。

4. 余额、流水、结算

• 余额：客户的"钱包"，充值/扣费都动它，NUMERIC 精确（D11）。
• 流水（bills）：每一笔的明细——用户、令牌、渠道、模型、input/output tokens、金额、时间。流水是账本的原始凭证，对账/排查全靠它。
• 结算：定期按流水汇总（按供应商/按商品/按客户），生成报表（对应公司"采购统计"的实践）。
• 设计原则：只记原始流水，汇总实时算或定期算，别用累加计数存余额反推。

5. sub2api 与 sub-box 定位

• sub2api：公司自研计费系统（主营业务核心）。细节以 services/sub2api/docs/ 为准。
• sub-box：订阅系统（v2.1.0），含 proxy 模式 + 节点、dashboard（subbox.server.akria.net），文档在 services/sub-box/docs/dashboard-design.md 与 enrollment.md。
• 关系：sub2api 管计费，sub-box 管订阅/节点/客户端，两者构成"卖 token"的完整交付。

6. 计费系统的几个"必须正确"的点

1. 金额精度：全程 NUMERIC，禁止 float。
2. 原子扣费：扣余额 + 记流水同一事务。
3. 幂等：重试同一请求不能重复扣费（用请求 ID/去重）。
4. 负数防护：余额扣成负数要么拒绝（WHERE balance >= cost），要么允许后记负账——业务上必须明确。
5. 限流：RPM/并发超限 → 429（D14 测出的边界）。
6. 对账：流水与上游 usage 对得上；定期与供应商结算对得上。

讲解节奏建议（约 90 分钟）

常见误区汇总