Autumn Checkout 是 Autumn 计费系统中围绕既有 V2 attach 动作构建的一层轻量确认层,而非独立的计费引擎。当 attach 的上下文解析出 checkoutMode 为「autumn_checkout」时,Autumn 不会立即执行计费,而是先存储一个包含原始 attach 参数的轻量 checkout 对象;公开的 checkout 路由稍后会用这些存储的参数重新运行 attach,从而构建新的预览或在确认时执行计费。这意味着 checkout 并不持久化一份冻结的计费方案,而是持久化请求,再根据当前状态重新计算。
主要能力与流程:
attach 到 Autumn Checkout:attach() 先走正常的 V2 流水线(setupAttachBillingContext、computeAttachPlan、evaluateStripeBillingPlan、handleAttachV2Errors),然后判断若 billingContext.checkoutMode === "autumn_checkout" 且未设置 skipAutumnCheckout,则调用 createAutumnCheckout;否则执行 executeBillingPlan。因此,Autumn checkout 是在计费方案生成之后才决定的,且在创建 checkout 之前校验已经运行。skipAutumnCheckout: true 是确认流程使用的逃生开关,使第二次 attach 调用直接执行计费而不再次创建 checkout。
存储内容:billingPlanToAutumnCheckout() 构建的 Checkout 记录包含 id、org_id、env、internal_customer_id、customer_id、action("attach")、params、params_version、status("pending")、created_at、expires_at。缓存通过 setCheckoutCache() 作为主存储,Postgres 通过 checkoutRepo.insert() 作为审计/备份写入;缓存 TTL 为 24 小时,数据库记录也会设置 expires_at。返回的计费响应使用 checkoutToUrl() 生成 /c/:checkout_id 作为 payment_url。
公开 Checkout 流程:路由在 server/src/internal/checkouts/checkoutRouter.ts 中暴露 GET /:checkout_id、POST /:checkout_id/preview、POST /:checkout_id/confirm 三个端点。checkoutMiddleware 负责共享设置:按 checkout ID 限流、优先从缓存加载 checkout、仅在判断 checkout 存在但不可用时才回退到数据库、拒绝已完成或已过期的 checkout、将过期的数据库记录标记为 expired、用 checkout 的 org、env 和 features 重建公开请求上下文。关键行为是:如果缓存缺失,中间件不会从数据库重建 checkout,而是在检查数据库审计状态后抛出 unavailable。
各处理器行为:handleGetCheckout 仅支持 CheckoutAction.Attach,将 checkout.params 转换为 AttachParamsV1,调用 billingActions.attach({ preview: true }),从存储参数重新计算当前计费方案并转换为 attach 预览响应,因此页面展示的是当前计算的价格而非创建时的快照。handlePreviewCheckout 与 GET 思路相同,但会在重新运行预览 attach 前,将更新后的 feature_quantities 合并进存储参数,适用于调试 checkout UI 中的数量编辑。handleConfirmCheckout 校验 action === "attach" 且 status === "pending",重新运行 attach({ preview: false, skipAutumnCheckout: true }) 执行真实计费方案,成功后删除缓存条目(checkout 一次性使用)并将数据库行标记为 completed,返回包含 invoice_id 的成功元数据。重要错误行为:仅在执行成功后才删除缓存;失败时 checkout 保持 pending 和缓存状态以便重试;非 RecaseError 的失败被包装为内部 checkout 失败。
Checkout 模式决策树:决策位于 setupAttachCheckoutMode.ts,可能输出 null、"stripe_checkout" 或 "autumn_checkout"。redirect_mode: "never" 时始终返回 null。第一轮判断是否需要 Stripe Checkout:当客户无支付方式且产品为一次性,或客户无支付方式、产品为付费订阅且客户尚无 Stripe 订阅时选择 Stripe checkout;例外是首个付费订阅产品带试用且 cardRequired === false 时返回 null。两个抑制条件:已存在支付方式,或启用了 invoiceMode,则本轮返回 null。第二轮为强制重定向(redirect_mode: "always"):一次性产品走向 "stripe_checkout",无现有 Stripe 订阅的付费订阅走向 "stripe_checkout",其他情况走向 "autumn_checkout"。
Autumn Checkout 的适用情形:当 redirect_mode: "always" 且不需要 Stripe checkout 时作为回退。实践包括:客户已有支付方式但仍希望应用 attach 前有确认页;客户正在变更现有订阅且希望重定向/确认体验;attach 的目标既非一次性也非首个付费订阅且无需 Stripe checkout;启用 invoice mode 且 redirect_mode 为 "always" 但仍希望用户落到 Autumn 确认页;免费产品 attach 配合 redirect_mode: "always" 也会落到此处。核心心智模型:stripe_checkout 表示 Stripe 仍需收集支付信息或拥有 checkout 体验;autumn_checkout 表示 Autumn 已有足够上下文计费,但 API 调用方要求一个确认步骤。
限制与不做的事:当前不支持任意计费动作,处理器只接受 CheckoutAction.Attach;不存储冻结的 billingPlan;不绕过正常 attach 校验;成功时不删除数据库行而是标记 completed 并移除缓存;不会通过从数据库恢复到缓存来恢复缺失的缓存条目。数据模型允许 CheckoutAction.UpdateSubscription,但公开处理器目前仅支持 attach;若扩展超出 attach,需要同步更新 checkout 创建、公开处理器、预览/响应构造、中间件假设以及仍描述 attach-only 行为的技能文档。
调试清单:若 checkout 链接意外出现,检查 params.redirect_mode、setupAttachCheckoutMode() 是否看到支付方式、产品是一次性/免费/付费订阅、客户是否已有 Stripe 订阅、发票模式或无卡试用是否抑制了 Stripe checkout。若预览与原始 attach 响应不同,remember GET /checkouts/:id 会从存储参数重算 attach,比较创建时与获取时的客户状态,检查 feature 数量是否通过 preview 修改。若确认时创建了第二个 checkout 而非扣费,确认代码路径使用了 skipAutumnCheckout: true。若有效链接显示 unavailable,检查缓存是否过期或删除、数据库状态是否为 completed 或 expired,记住数据库是审计/备份而非公开使用的恢复来源。