编写履约插件
用自己的插件交付已付订单所买的内容、拒绝无法履约的结账,并观察失败的交付被自动重试。
计费在结算订单之后,会通知每个已启用的 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/ 下的仓储里。三个钩子要遵守的规则:
| 钩子 | 收到 | 规则 |
|---|---|---|
canCheckout | userId、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 下各加一句说明。
观察失败后的重试
-
让
onOrderPaid抛出异常,例如throw new Error("seat service down"),然后用服务商的测试卡购买这个套餐。 -
/admin/orders中订单仍然是paid。打开/admin/audit,会看到一条billing.fulfilment.failed记录,目标是订单 id,元数据里有你的履约方、事件paid、第几次尝试和错误信息。 -
去掉
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>的记录。