实现订阅计费、发票、催收与按比例计费时用：自动化周期性收款与…

适用于构建 SaaS 订阅、周期性扣款、自动发票、失败付款催收和按比例计费的自动化计费系统。

适用场景

解决思路

1. 导入计费模块：`from billing import BillingEngine, Subscription`。
2. 初始化计费引擎：`billing = BillingEngine()`。
3. 创建订阅：调用 `billing.create_subscription(customer_id="cus_123", plan_id="plan_pro_monthly", billing_cycle_anchor=datetime.now(), trial_days=14)`，传入客户 ID、套餐 ID、计费周期锚点和试用天数。
4. 处理计费周期：调用 `billing.process_billing_cycle(subscription.id)` 执行该订阅的账单生成、扣款或续费流程。
5. 实现 SaaS 订阅计费：为每个客户维护 plan、订阅状态和计费周期，并周期性触发扣款。
6. 自动生成并交付发票：根据计费周期和订阅状态生成 invoice，并将发票发送给客户。
7. 实现失败付款催收（dunning）：对失败付款配置重试计划、客户通知、宽限期和账户限制。
8. 实现按比例计费（proration）：在周期中升级/降级、增减席位或更改计费频率时调整费用。
9. 处理税费：在账单中计算 sales tax、VAT、GST。
10. 处理按用量计费：根据 usage 计算费用并计入账单。
11. 管理计费周期与续费：跟踪 renewal 和 billing cycle anchor，到期时续订并触发下一周期。
12. 选择并配置计费周期：支持 monthly、annual、quarterly、weekly 或 custom（如 usage-based、per-seat）。
13. 实现订阅状态机：按 `trial → active → past_due → canceled`，并支持 `paused → resumed` 等状态流转。
14. 需要详细模式和工作示例时，阅读 `references/details.md`。

适用边界 · 注意事项

• 不适用于一次性付款、无周期扣款或无订阅生命周期的简单收款场景。
• 不需要发票、催收、按比例计费、税费或用量计费的支付场景，不必引入完整计费自动化。
• 已有托管计费平台且无需自研计费引擎时，避免重复建设。