基于 Stripe/Metering 的用量计费：从 SLO 指标到账单流水
基于 Stripe/Metering 的用量计费：从 SLO 指标到账单流水 🎯
📚 目录
- 基于 Stripe/Metering 的用量计费：从 SLO 指标到账单流水 🎯
-
- 0) 摘要（TL;DR）🚀
- 1) 名词与口径统一（SLO ↔ 计量 ↔ 计费）📏
- 2) 目标架构 🧭
- 3) 端到端时序 🧵
- 4) 数据模型与表设计（PostgreSQL）🗄️
- 5) Webhook 幂等与无序处理 🧩
- 6) 账期/窗口/宽限期时间线 🗓️
- 7) 多租户与权限边界（ABP）🏷️
- 8) Stripe 集成要点 🧩
-
- 8.1 创建 Meter、Price 并绑定（Price↔Meter）
- 8.2 记录用量（v1 与 v2）📨
- 8.3 修正与迁移 🧯
- 9) 幂等结算与对账 🧮
- 10) 欠费保护与停复机 🛡️
- 11) 发票“最终化”与宽限 ⌛
- 12) API v2 流式上报 🌊
- 13) 可观测性与 SLO 🔭
- 14) 运行与运维 🧰
- 15) 代码骨架（ABP 模块 & 后台作业）🧱
- 16) 常见坑（踩雷清单）⚠️
0) 摘要（TL;DR）🚀
在 ABP vNext 中落地从 SLO 指标 → 计量 (Meter) → 账单流水 的闭环：业务埋点 → Usage Ledger 幂等入账 → Stripe Meter Events 上报（带 timestamp 与业务幂等 identifier）→ Stripe 账期聚合生成发票 → Webhook 对账与欠费保护。
要点：
- Meters 取代 legacy usage-records（新项目一律使用 Meters）。
- 事件时间戳需在过去 35 天或未来 5 分钟内；用量值为整数。
- Price↔Meter 通过
price.recurring.meter绑定；订阅项引用该 Price。 - 发票默认 1 小时“最终化”宽限，可配置（例如用量型 72h）。
- 高吞吐使用 API v2 Meter Event Streams（先建会话 token，15 分钟有效）。
1) 名词与口径统一（SLO ↔ 计量 ↔ 计费）📏
- SLI/SLO/SLA → Billable Metrics：仅将“可结算使用量”纳入口径；定义单位（次、条、千 tokens…）、聚合函数（
sum/count/last）、窗口与时区。 - 时间戳与整数值：上报事件
timestamp必须在过去 35 天或未来 5 分钟；payload[value]仅整数（建议内部用“毫单位”整型）。 - 账期与窗口：预聚合 day/hour 的边界按 UTC 对齐；同一窗口内后到事件覆盖先到（pre-aggregated 语义）。
- 按千/打包计费：价格层可用
transform_quantity做归一化（例如“每 1000 次计费”）。⚠️ 与复杂阶梯价组合时的效果需事先走通样例，确保口径一致。
2) 目标架构 🧭
- Meters 附着在 Price 上：在 Price 的
recurring.meter字段绑定 Meter（订阅项引用该 Price，从而“带出”Meter）。 - API v2 流式：先创建 meter event session（token 15 分钟），再向流式端点推送 NDJSON；10k EPS（可申请更高）。
- ABP 多租户：
ICurrentTenant贯穿上下文；实体实现IMultiTenant自动按租户过滤。