billing

package
v0.28.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 13, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package billing is the billing domain: plans, orders, subscriptions, and the channel-agnostic payment-event pipeline (event idempotency, amount reconciliation, order state machine, entitlement hooks) shared by every payment channel adapter under billing/adapters.

适配器契约五律

新增渠道的验收清单,源自 waffo 首个非 Stripe 渠道接入复盘, docs/plan-billing-channel-framework-2026-10-23.md §BC-4:

  1. 钱事件唯一:续费类生命周期每个计费周期只产生一个 EventSubscriptionRenewed, 取"钱到账"事件(waffo=payment_succeeded、stripe=invoice.paid、 paypal=PAYMENT.SALE.COMPLETED);周期滚动通知(如 waffo subscription.renewed) 必须映射为 ignored。
  2. 首期去重:首笔付款同时触发激活+付款双事件时,只映射激活事件为 EventCheckoutCompleted(waffo 以 periodNumber=1 判定)。
  3. 稳定订阅引用:SubscriptionRef = 渠道侧跨周期不变的标识(stripe=subscription id、waffo=orderId);结账会话 metadata 必须带 order_id 并确认渠道会回传 (waffo orderMetadata 全事件透传)。
  4. ChannelEventID 全局唯一:库表幂等键是 (channel, channel_event_id) 复合列、 无事件类型维度;渠道侧幂等键为 (type, id) 二元组时(waffo),必须拼进 ChannelEventID 这一个字段("type:id")。
  5. 环境标记:事件带 mode: test|prod 时记入 Payload 并审计;渠道配置了 mode 时 跨环境事件直接拒收(test 回调永不落生产权益)。

五律契约修订(2026-10-24 billing 内核修复 #3,续期路径两条):

  1. 续期事件锚 PI:续期事件(EventSubscriptionRenewed)携带 OrderID 与 PaymentIntentRef 时,内核把 PI 落库进订单 metadata(SetOrderPaymentIntentRef)。 此前全仓只在 checkout.completed 落 PI,续期发票漏锚导致后续仅携 PI 的 退款/失败事件反查不到订单。渠道适配器因此必须在续期事件里尽量带上 PI。
  2. 续期金额对账:续期事件携带 OrderID 且金额 > 0 时,内核按订单 planCode+interval 查「当前」plan 价格对账(目录价即收款价,改价必须同步——这条防线原本只在 handlePaid 生效,续期路径是漏洞)。不等(EqualFold 比币种)则拒发续期: log.Error + 审计 billing.amount_mismatch + 事件收敛 processed;plan 缺失或 无价则跳过对账。OrderID 为空的续期(waffo/stripe)不受影响。

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func SeedPlans

func SeedPlans(ctx context.Context, pool *pgxpool.Pool, log *slog.Logger, seeds []PlanSeed) error

SeedPlans upserts seeds into the plan catalog, idempotently: calling it on every boot converges to the same state, and fields a seed does not declare keep whatever the database (007 baseline, a previous seed, or a platform admin edit) already holds. Each seed is applied independently; a failure names the plan code and stops the batch — the next boot re-applies the earlier seeds for free (they are idempotent), so no transaction spans the batch.

Call it once at boot, after migrations have run. log may be nil (slog.Default is used). An empty seeds slice is a no-op that never touches the pool.

Types

type PlanSeed

type PlanSeed struct {
	Code     string
	Name     string
	Currency string
	Limits   map[string]int
	SortNo   int
}

PlanSeed is a product's declarative override (or addition) to the framework plan catalog. The framework migration 007_plan_seed seeds `free`/`pro` with Chinese names and the plan.currency column default is CNY, so every non-Chinese product would otherwise have to hand-write UPDATE statements to fix its own price table. SeedPlans is that statement, typed and idempotent.

Semantics (all fields except Code are optional):

  • Name: "" leaves the stored name untouched.
  • Currency: "" leaves the stored currency untouched; a non-empty value is trimmed, upper-cased and validated (ISO-4217 shape + framework minor-unit support). New plan codes MUST declare one — otherwise the row would silently inherit the column default (CNY), the exact bug this API exists to remove.
  • Limits: nil/empty leaves the stored limits untouched. Non-empty MERGES into the stored JSONB (right-hand keys win), so seeding only {"price_monthly_cents": 9900} keeps tasks_monthly/workspaces and any admin-added keys. Key shape is policed with the same regex as the admin plan editor, so a typo fails at boot instead of poisoning the column.
  • SortNo: 0 leaves the stored sort untouched (0 is therefore not expressible as an explicit value; the seed baseline uses 1/2).

Field semantics are per-field, not whole-row: a product that only declares {Code: "free", Name: "Free"} gets an English name while the 007 limits and the admin-edited currency stay as they are.

Directories

Path Synopsis
adapters
paypal
Package paypal 实现 ploykit billing 的 PayPal 支付渠道 (billing/app.PaymentChannel),走 PayPal Subscriptions + Catalog Products REST API(目录型渠道家族,与 waffo 同类;BC-8 = 框架成色的试金石, 零内核改动接入):
Package paypal 实现 ploykit billing 的 PayPal 支付渠道 (billing/app.PaymentChannel),走 PayPal Subscriptions + Catalog Products REST API(目录型渠道家族,与 waffo 同类;BC-8 = 框架成色的试金石, 零内核改动接入):
sim
Package sim 提供三个「模拟支付渠道」方言(simwaffo / simpaypal / simstripe), 用于在真库上对 billing 全管线做端到端验收。
Package sim 提供三个「模拟支付渠道」方言(simwaffo / simpaypal / simstripe), 用于在真库上对 billing 全管线做端到端验收。
sim/simhttp
Package simhttp 是 sim 模拟渠道的 DEV 测试 HTTP 面(「模拟三个支付渠道的 测试接口」),供人工 curl / 外部脚本驱动全管线:
Package simhttp 是 sim 模拟渠道的 DEV 测试 HTTP 面(「模拟三个支付渠道的 测试接口」),供人工 curl / 外部脚本驱动全管线:
waffo
Package waffo 实现 ploykit billing 的 Waffo Pancake(MoR)支付渠道 (billing/app.PaymentChannel),走 waffo REST API(https://api.waffo.ai):
Package waffo 实现 ploykit billing 的 Waffo Pancake(MoR)支付渠道 (billing/app.PaymentChannel),走 waffo REST API(https://api.waffo.ai):
Package money provides the shared cents <-> display-string conversions used by every payment-channel adapter (waffo, stripe, paypal).
Package money provides the shared cents <-> display-string conversions used by every payment-channel adapter (waffo, stripe, paypal).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL