编写履约插件

用自己的插件交付已付订单所买的内容、拒绝无法履约的结账,并观察失败的交付被自动重试。

计费在结算订单之后,会通知每个已启用的 billing.fulfilment 插件。本文在一个本地插件里添加你自己的履约方(fulfiller)。它对每个已付订单运行一次,对每笔退款运行一次,还可以在扣款之前拒绝结账。内置的 plan-credits 履约方(src/server/billing/plan-credits-fulfiller.ts)是参考实现。

准备工作

  • 能在本机运行、数据库已迁移的项目,以及一个可以购买的上架套餐,见管理定价套餐。
  • 想看到真实订单结算的话,需要一个处于测试模式的支付服务商,见接入支付服务商。
  • 定时任务在运行,因为重试由它执行。
  • 明确订单要交付什么,以及用什么键保证重复交付无害,例如以订单 id 为键的一行记录。

添加履约方

编写履约方

新建 src/server/billing/seat-fulfiller.ts。履约方是一个带 id 的对象,可以实现三个钩子中的任意几个。类型定义在 src/server/billing/fulfilment-types.ts。

import type { BillingFulfiller } from "./fulfilment-types";

export const seatFulfiller: BillingFulfiller = Object.freeze({
  id: "seats",
  async canCheckout({ userId, planKey }) {
    if (planKey !== "team") return { ok: true };
    const allowed = await userMayBuySeats(userId);
    return allowed
      ? { ok: true }
      : { ok: false, code: "seats_unavailable", reason: "This account cannot buy seats." };
  },
  async onOrderPaid(order) {
    if (order.planKey !== "team") return;
    await grantSeatsOnce({ orderId: order.id, userId: order.userId });
  },
  async onOrderRefunded(order, refund) {
    if (refund.fullRefund) await revokeSeats(order.id);
  },
});

userMayBuySeats、grantSeatsOnce 和 revokeSeats 由你实现,放在 src/server/db/repositories/ 下的仓储里。三个钩子要遵守的规则:

钩子收到规则
canCheckoutuserId、planKey、productKey、checkoutMode在订单创建之前运行。返回 ok: false 会以 HTTP 409 和你的 code 终止结账
onOrderPaid订单:id、userId、provider、planKey、productKey、checkoutMode、amountCents、currency必须幂等。重试可能发生在一次只成功了一半的调用之后
onOrderRefunded订单以及 refundId、amountCents、fullRefund重试规则相同;每笔在服务商侧成功的退款调用一次

交付失败时直接抛出异常。计费会记录失败并重试,付款不会被撤销。

给插件写清单

属于你自己项目的插件类型是 local。它可以在 /admin/plugins 停用。新建 src/plugins/seats/manifest.ts:

import { defineManifest } from "../kernel/types";

export const seatsManifest = defineManifest({
  id: "seats",
  version: "0.1.0",
  kind: "local",
});

创建两半

每个插件都有一个可在浏览器加载的部分,履约方放在服务端那一半。新建 src/plugins/seats/plugin.ts:

import { definePlugin } from "../kernel/types";
import { seatsManifest } from "./manifest";

export const seatsPlugin = definePlugin({ manifest: seatsManifest });

以及 src/plugins/seats/plugin.server.ts:

import { seatFulfiller } from "../../server/billing/seat-fulfiller";
import { defineServerPlugin } from "../kernel/types";
import { seatsManifest } from "./manifest";

export const seatsServerPlugin = defineServerPlugin({
  manifest: seatsManifest,
  contributes: { "billing.fulfilment": [seatFulfiller] },
});

服务端这一半请使用相对路径导入。Agent 服务也会加载同一份列表,所以从这里能到达的代码都不能导入 React、图标或 @/ 别名。

注册两半

把 seatsPlugin 加到 src/plugins/installed.ts 的 installedPlugins,把 seatsServerPlugin 加到 src/plugins/installed.server.ts 的 installedServerPlugins。两处都要写在 // @module: 标记区域之外,那些区域属于随仓库提供的模块。

为拒绝代码补上文案

如果 canCheckout 可能拒绝,买家会带着你的 code 落到支付失败页。在 src/i18n/locales/en/messages.ts 和 src/i18n/locales/zh/messages.ts 的 checkoutFailure.reasons 与 checkoutFailure.nextActions 下各加一句说明。

观察失败后的重试

  1. 让 onOrderPaid 抛出异常,例如 throw new Error("seat service down"),然后用服务商的测试卡购买这个套餐。

  2. /admin/orders 中订单仍然是 paid。打开 /admin/audit,会看到一条 billing.fulfilment.failed 记录,目标是订单 id,元数据里有你的履约方、事件 paid、第几次尝试和错误信息。

  3. 去掉 throw,等一分钟,然后手动执行一轮:

    pnpm jobs:run

    报告中 billing-fulfilments 任务显示 "attempted": 1, "succeeded": 1。如果报告是 "skipped",说明进程内循环已经执行了这一轮,直接查看那一行记录。

每次失败之后按固定间隔重试:

第几次尝试运行时间
1订单结算时
2第 1 次失败后 1 分钟
3再过 5 分钟
4再过 30 分钟
5再过 2 小时
6再过 12 小时;这次仍失败会写入 billing.fulfilment.abandoned 并停止

如果订单在此期间已退款或取消,paid 交付会被放弃。如果你停用了插件,它失败的记录会保留,每小时重新检查一次,不消耗尝试次数。

验证结果

  • pnpm validate:plugins 通过:注册表接受新插件,两半都已安装。
  • pnpm validate:billing-fulfilment 通过:计费仍然只通知履约方一次,记录失败并重试。
  • 测试购买之后,billing_fulfilments 中该订单的每个履约方各有一行,事件为 paid,状态为 succeeded。可以用 pnpm db:studio 打开这张表。
  • 在 /admin/orders 给订单退款,会多出一行事件为 refunded:<refundId> 的记录。

下一步