findscripter 何时使用
适用场景：
- 搭建 SaaS 订阅计费（月/季/年/周/自定义周期）。
- 自动生成并投递发票，处理续费与取消。
- 处理失败支付的恢复（催收 dunning）：重试计划、客户通知、宽限期、账号限制。
- 计算计划升降级、席位增减、计费频率变更时的按比例分摊（proration）。
- 计算销售税、VAT、GST，并满足各地区合规。
- 处理按用量计费（usage-based）。
不该用（负边界）：
- 只需一次性开票或手动收款。
- 任务与计费/订阅无关。
- 你无权改动定价、套餐或计费流程。
步骤
- 定义套餐、定价、计费间隔与分摊规则。
- 梳理订阅生命周期状态与续费/取消行为：
trial → active → past_due → canceled，以及paused → resumed。 - 实现开票、收款、重试与催收工作流。
- 按地区建模税费与合规要求。
- 用沙箱支付验证，并对账（reconcile）账本输出。
- 需详细模板时，参考源仓库的
resources/implementation-playbook.md。
指令
- 计费周期处理：到期才出账；
process_billing_cycle中datetime.now() < current_period_end则跳过；出账后生成发票、charge_customer，成功则mark_paid+advance_billing_period+ 发送发票，失败则mark_past_due并启动催收。 - 收款金额转分：
amount=int(amount * 100)（Stripe 以最小货币单位计），捕获stripe.error.CardError返回失败结果。 - 催收重试计划（示例三档）：
self.retry_schedule = [
{'days': 3, 'email_template': 'payment_failed_first'},
{'days': 7, 'email_template': 'payment_failed_reminder'},
{'days': 14, 'email_template': 'payment_failed_final'},
]
重试成功 → 发票 mark_paid、订阅恢复 ACTIVE、发 payment_recovered；耗尽重试 → subscription.cancel(at_period_end=False) 并通知。
- 分摊计算（按当前周期天数线性）：
total_days = (period_end - period_start).days
days_remaining = (period_end - change_date).days
unused_amount = (old_plan.amount / total_days) * days_remaining
new_plan_amount = (new_plan.amount / total_days) * days_remaining
net_proration = new_plan_amount - unused_amount
席位减少不退款：prorated_charge = max(0, prorated_amount)。
- 税务按地区税率表查表（如
US_CA=0.0725、GB=0.20、DE=0.19、AU=0.10）；按客户国家/州确定管辖区，US 用US_{state}、欧盟用国家码、AU 为 GST；EU VAT 号用 VIES API 校验。
示例
from billing import BillingEngine, Subscription
billing = BillingEngine()
subscription = billing.create_subscription(
customer_id="cus_123",
plan_id="plan_pro_monthly",
billing_cycle_anchor=datetime.now(),
trial_days=14,
)
billing.process_billing_cycle(subscription.id)
发票流转：draft → open（finalize 后 total = subtotal + tax）→ paid；可经 to_pdf()（reportlab）或 to_html() 输出。用量计费支持 tiered/per_unit/volume 三种定价模型。
注意事项
- 安全红线：测试环境绝不向真实客户收费；上线前核验税务处理与合规义务。
- 最佳实践：尽量全自动化、清晰通知客户、重试逻辑兼顾恢复率与体验、分摊计算公平、按管辖区算对税、为所有计费事件留审计日志、优雅处理边界情况。
- 常见坑：分摊未计入部分周期；发票漏加税；催收过于激进、过快取消；失败不通知客户；硬编码计费周期、不支持自定义计费日。
- 把输出当作起点而非环境特定验证的替代；缺少必要输入、权限、安全边界或成功标准时，停下来澄清。
互见
- 源仓库参考：
references/billing-cycles.md、dunning-management.md、proration.md、tax-calculation.md、invoice-lifecycle.md；资产assets/billing-state-machine.yaml、invoice-template.html、dunning-policy.yaml。
采编自 sickn33/antigravity-awesome-skills（MIT），适配重写而非逐字翻译。