ChatGPT Team Helper代码实现原理:订单状态机与自动发货全链路拆解
ChatGPT Team Helper代码实现原理:订单状态机与自动发货全链路拆解
ChatGPT Team Helper 是一个一站式 Team 账号管理与兑换平台,核心能力是"多渠道订单接入 + 自动发货 + 权限管理"。本文将拆解它的订单状态机设计,以及从下单、支付回调到自动兑换发货的全链路实现原理,帮助你理解一个自动发货系统背后真正的工程细节。
一、全链路总览:一笔订单经历了什么?
在 ChatGPT Team Helper 中,一笔购买订单会经过这样一条主链路:
用户下单 → 预留兑换码 → 跳转 Zpay 支付
→ 支付回调 / 主动轮询(双通道对账)
→ 标记 paid → 自动兑换(自动发货)
→ 邮件 + Telegram 通知 → 完成
任何阶段超时 → expired,释放预留库存
整条链路横跨以下几个核心模块:
| 模块 | 文件 | 职责 |
|---|---|---|
| 下单与支付路由 | backend/src/routes/purchase.js | 创建订单、接收支付回调、触发自动兑换 |
| 订单过期清理 | backend/src/services/order-expiration-sweeper.js | 定时将超时未付订单置为 expired 并释放库存 |
| 闲鱼 WebSocket 发货 | backend/src/services/xianyu-ws-delivery.js | 实时监听闲鱼订单事件并自动 IM 发货 |
| 小红书订单同步 | backend/src/services/xhs-sync-runner.js | 定时轮询同步小红书订单 |
| 并发锁 | backend/src/utils/locks.js | 订单级/兑换码级互斥,防止并发超发 |
二、订单状态机:7 个状态如何流转?
订单状态存储在 purchase_orders 表中,状态流转可以用下图概括:
┌────────────┐
创建订单 │ created │
(预留兑换码) ──▶ 待支付中 │
└─────┬──────┘
支付成功 │ 超时未付(15分钟,可配置)
┌─────▼──────┐
┌────────────▶ │ paid │
│ 退款 └─────┬──────┘
┌──▼────────┐ │ 自动兑换成功
│ refunded │ ┌──────▼──────────────┐
│ (已退款) │ │ paid + redeemed_at ≠ NULL │
└───────────┘ │ (即"已发货/已兑换") │
┌───────────┐ └─────────────────────┘
│ expired │ ◀── 定时任务清理
│ (已过期) │
└───────────┘
┌───────────┐
│ failed │ 支付通道异常/金额不匹配等
└───────────┘
关键状态说明(见 backend/src/routes/purchase.js):
- created / pending_payment:下单成功、兑换码已预留,等待支付;
- paid:支付确认,是触发"自动发货"的起点;
- redeemed:不是一个独立字段,而是
redeemed_at有值即代表已发货兑换完成; - expired:定时任务标记,同时释放预留的兑换码,库存自动回归可售;
- refunded / failed:终态,
shouldSyncOrderWithZpay会直接跳过这些状态的订单,不再向支付网关查询。
💡 设计要点:状态机是"单向"的——一旦进入
paid,即使重复收到回调也不会重复发货。这靠的是幂等判断(见下一节)。
三、下单即锁库存:created 状态如何预留兑换码?
自动发货系统最怕的问题就是超卖。ChatGPT Team Helper 的做法是"下单先锁码",核心逻辑在 backend/src/routes/purchase.js 的 POST /orders 中:
- 限流与配额检查:按 IP 做下单限流,并检查同一邮箱/IP 的待支付订单数量上限,防止恶意刷单;
- 加锁后原子操作:整个"清理过期订单 → 检查配额 → 预留兑换码 → 写订单"过程包在
withLocks(['purchase'])分布式锁内执行(锁实现见 backend/src/utils/locks.js); - 多渠道路由预留:一个商品可以配置多个上游渠道(如
xianyu、xhs),系统按顺序尝试reserveAvailableCode,第一个有可售库存的渠道即被锁定,订单记录中同时写入code_channel与预留的code_id; - 落库即 created:订单以
status = 'created'写入,并生成 Zpay 支付参数,notify_url指向/notify回调入口。
这样一来:只要订单处于待支付状态,对应兑换码就处于"预留中",其他订单看不到它——库存账目在任何时刻都是自洽的。
四、支付确认:回调 + 轮询双通道对账
支付结果不确定的场景下,只做回调是不够的。该系统同时实现了两条确认通道:
1)被动回调通道:/notify 入口
回调处理在 backend/src/routes/purchase.js,做了四层防御:
- 配置校验:
pid必须与后台配置一致; - 签名校验:用
buildZpaySign重算 MD5 签名并比对,不一致直接fail; - 状态校验:只有
trade_status === 'TRADE_SUCCESS'才继续; - 先应答后处理:先回复
success(Zpay 要求纯文本),真正的订单处理放进queueMicrotask异步执行,避免回调超时重推。
2)主动轮询通道:syncOrderStatusFromZpay
用户打开订单查询页(GET /orders/:orderNo)时,系统会主动调 Zpay 查询接口对账(backend/src/routes/purchase.js)。两个细节值得注意:
- 查询有最小间隔控制(默认 8 秒,
PURCHASE_ORDER_QUERY_MIN_INTERVAL_MS可配),防止高频查接口; - 查询结果与订单金额做金额一致性校验,不一致时标记
money_mismatch而不是直接发货。
两条通道殊途同归,最终都汇入同一个核心函数。
五、核心:handlePaidOrder 自动发货引擎
整个自动发货的心脏是 backend/src/routes/purchase.js 中的 handlePaidOrder,它在一个锁范围内顺序完成 6 件事:
- 加锁:锁住
purchase:{订单号},下游订单还会额外锁住每个预留兑换码,防止并发重复处理; - 幂等标记 paid:先检查
refunded终态;仅当status !== 'paid'时执行created → paid的状态跃迁,并记录paid_at、zpay_trade_no——这就是重复回调不重复发货的幂等保障; - 积分发放 / 下游结算:零售订单发邀请积分与购买积分;下游(downstream)场景则走
finalizeDownstreamPaidOrder结算多个兑换码; - 自动兑换(真正的"发货"):调用
redeemCodeInternal,将订单绑定的兑换码兑换到订单邮箱名下,并把redeemed_at、邀请状态写回订单。这里还有一个精妙的容错:如果报"兑换码已被使用",但兑换人正是订单邮箱,就视为"已经发过货了",静默补写 redeemed_at 而不是让用户报错; - 邮件通知:未发过邮件则发送订单邮件(
email_sent_at保证只发一次); - Telegram 通知:拼装"✅ 订单支付成功"消息推送,
telegram_sent_at同样保证幂等。
每一步都用独立的 *_sent_at 时间戳做"只执行一次"标记——这是自动发货系统保证不重复发货、不丢通知的关键模式。
六、超时兜底:订单过期清扫器
用户下了单不付款怎么办?backend/src/services/order-expiration-sweeper.js 提供了一个定时任务(默认 60 秒一轮,过期时间默认 15 分钟):
- 扫描所有
paid_at IS NULL AND status IN ('created', 'pending_payment')且超过阈值的订单,批量置为expired; - 同步清空
redemption_codes中对应预留记录的reserved_for_order_no,释放库存回可售池; - Credit 订单走同样的清理逻辑,并调用
releaseOpenAccountsOrderCode归还开放账号额度。
配合下单流程中的"进入先清理"(每次 POST /orders 都会先执行一次 cleanupExpiredOrders),形成"实时 + 定时"双保险,保证库存不会长期被死单占用。
七、多渠道自动发货:闲鱼 / 小红书 / Telegram
ChatGPT Team Helper 的"自动发货"不止 Zpay 一条路,它还覆盖了二手交易平台场景:
闲鱼:WebSocket 实时监听 + IM 自动发货
backend/src/services/xianyu-ws-delivery.js 通过闲鱼的 WebSocket 通道实时监听订单事件:
- 收到"已付款待发货"(
orderStatus = 2)事件后,自动通过 IM 向买家发送发货提示(含/redeem/xianyu兑换页链接); - 15 秒心跳保活、断线最多重连 5 次,配合 60 秒轮询兜底;
- 买家到兑换页输入邮箱 + 闲鱼订单号,系统自动匹配订单并兑换(见 docs/features/闲鱼.md)。
小红书:定时轮询同步
小红书没有实时通道,backend/src/services/xhs-sync-runner.js 采用定时任务方式调 API 拉取订单入库,任务自带"运行中"防重入锁,兑换侧同样支持"邮箱 + 小红书订单号"自动匹配。
支付网关与渠道配置参考
- Zpay 支付网关接入:docs/features/支付(ZPAY).md
- 上下游渠道(代码渠道/商品渠道)配置:docs/上下游渠道配置指南.md
- Telegram 机器人兑换/发货指令:docs/Telegram机器人指令.md
八、总结:这套设计值得借鉴的 3 个点
- 状态机 + 幂等:
created → paid → redeemed单向流转,重复回调/重复通知被幂等检查吞掉,"只发一次货"靠时间戳字段兜底而非运气; - 锁粒度下沉到兑换码:订单锁 + 兑换码锁的组合(backend/src/utils/locks.js),让高并发下的预留、兑换、释放互不踩踏,杜绝超卖;
- 双通道对账 + 兜底清扫:回调可能丢、用户可能不付款——主动轮询保证"钱到了必发货",过期清扫器保证"没付款必放库存",两个方向的闭环让订单状态永远不会"悬空"。
这套"订单状态机 + 自动发货"的链路,是 ChatGPT Team Helper 作为一站式 Team 账号管理平台的可靠性基础,也是任何卡券/账号类自动发货系统可以对照学习的完整范式。