ChatGPT Team Helper代码实现原理:订单状态机与自动发货全链路拆解

原创2026-10-15 06:32:051,617 阅读

ChatGPT Team Helper代码实现原理:订单状态机与自动发货全链路拆解

ChatGPT Team Helper 是一个一站式 Team 账号管理与兑换平台,核心能力是"多渠道订单接入 + 自动发货 + 权限管理"。本文将拆解它的订单状态机设计,以及从下单、支付回调到自动兑换发货的全链路实现原理,帮助你理解一个自动发货系统背后真正的工程细节。

ChatGPT Team Helper 订单状态机与自动发货系统应用图标

一、全链路总览:一笔订单经历了什么?

在 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 中:

  1. 限流与配额检查:按 IP 做下单限流,并检查同一邮箱/IP 的待支付订单数量上限,防止恶意刷单;
  2. 加锁后原子操作:整个"清理过期订单 → 检查配额 → 预留兑换码 → 写订单"过程包在 withLocks(['purchase']) 分布式锁内执行(锁实现见 backend/src/utils/locks.js);
  3. 多渠道路由预留:一个商品可以配置多个上游渠道(如 xianyu、xhs),系统按顺序尝试 reserveAvailableCode,第一个有可售库存的渠道即被锁定,订单记录中同时写入 code_channel 与预留的 code_id;
  4. 落库即 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 件事:

  1. 加锁:锁住 purchase:{订单号},下游订单还会额外锁住每个预留兑换码,防止并发重复处理;
  2. 幂等标记 paid:先检查 refunded 终态;仅当 status !== 'paid' 时执行 created → paid 的状态跃迁,并记录 paid_at、zpay_trade_no——这就是重复回调不重复发货的幂等保障;
  3. 积分发放 / 下游结算:零售订单发邀请积分与购买积分;下游(downstream)场景则走 finalizeDownstreamPaidOrder 结算多个兑换码;
  4. 自动兑换(真正的"发货"):调用 redeemCodeInternal,将订单绑定的兑换码兑换到订单邮箱名下,并把 redeemed_at、邀请状态写回订单。这里还有一个精妙的容错:如果报"兑换码已被使用",但兑换人正是订单邮箱,就视为"已经发过货了",静默补写 redeemed_at 而不是让用户报错;
  5. 邮件通知:未发过邮件则发送订单邮件(email_sent_at 保证只发一次);
  6. 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 拉取订单入库,任务自带"运行中"防重入锁,兑换侧同样支持"邮箱 + 小红书订单号"自动匹配。

支付网关与渠道配置参考

八、总结:这套设计值得借鉴的 3 个点

  1. 状态机 + 幂等:created → paid → redeemed 单向流转,重复回调/重复通知被幂等检查吞掉,"只发一次货"靠时间戳字段兜底而非运气;
  2. 锁粒度下沉到兑换码:订单锁 + 兑换码锁的组合(backend/src/utils/locks.js),让高并发下的预留、兑换、释放互不踩踏,杜绝超卖;
  3. 双通道对账 + 兜底清扫:回调可能丢、用户可能不付款——主动轮询保证"钱到了必发货",过期清扫器保证"没付款必放库存",两个方向的闭环让订单状态永远不会"悬空"。

这套"订单状态机 + 自动发货"的链路,是 ChatGPT Team Helper 作为一站式 Team 账号管理平台的可靠性基础,也是任何卡券/账号类自动发货系统可以对照学习的完整范式。

登录后查看全文
chatgpt-team-helper