中小城市外卖跑腿小程序:订单状态机与退款派单互斥实现

简介: 中小城市外卖跑腿小程序可按用户、商家、骑手、后台四端做最小闭环。本文用订单状态机与退款派单互斥给出可核对实现:表结构与约束、条件更新、幂等结算、并发反例,并附部署迁移与合规字段的验收清单。

中小城市搭同城生活平台,外卖跑腿小程序先按用户、商家、骑手、平台后台四端做最小闭环:商家上架接单、用户下单支付、骑手接单回传、平台退款对账。首期最容易出问题的不是端数,而是订单状态与退款、派单的写入顺序:退款还在审核,骑手已经接单,结算任务又把同一笔钱记了两次。本文从这一故障切入,给出表结构与约束、条件更新实现、正常输出与并发反例,并附部署迁移和合规字段的验收清单。

一、先把故障说清:三种写入撞在同一行订单上

一笔订单至少有三种写入会撞在一起:用户侧发起退款、骑手侧接单、定时任务结算。如果三者都按“先查状态、再写状态”的两步走,中间没有任何互斥,那么两个事务可以同时读到 PAID,各自认为合法,先后提交后状态就变成最后写入者。更隐蔽的是结算:它往往不读订单行锁,而是扫订单列表,看到 PAID 就记一笔收入,等退款落库后再记一笔退款支出,账面上收入与退款都有,实际资金流已经错位。

把状态机写成可执行约束是第一步。下表是首期够用的九个状态和允许的转移,任何不在表内的转移都应在数据库层失败,而不是靠业务代码自觉。

当前状态 允许迁移到 触发角色 说明
CREATED PAID、CLOSED 用户、系统 超时未支付关闭
PAID ACCEPTED、REFUNDING、CLOSED 骑手、用户 退款与接单在此竞争
ACCEPTED PICKED、REFUNDING 骑手、用户 退款需同时通知改派
PICKED DELIVERED、REFUNDING 骑手、用户 退款按售后处理
DELIVERED SETTLED、REFUNDING 系统、用户 已送达订单走售后单
REFUNDING REFUNDED、PAID、ACCEPTED 财务 驳回时按事件表回滚到原状态
REFUNDED、SETTLED、CLOSED 无 — 终态,只允许追加事件

二、数据模型:用约束把状态机钉在库里

表设计的目标不是把字段堆全,而是让错误写入在数据库层就失败。四个核心表分别是订单主表、订单事件表、退款表和结算流水表;商家资质单独一张表,承接后面的合规字段。以下脚本以 PostgreSQL 15 为设计目标,未在真实业务库执行。

CREATE TABLE orders (
  id           BIGSERIAL PRIMARY KEY,
  order_no     VARCHAR(32)   NOT NULL UNIQUE,
  city_code    CHAR(6)       NOT NULL,
  merchant_id  BIGINT        NOT NULL,
  rider_id     BIGINT,
  status       VARCHAR(16)   NOT NULL DEFAULT 'CREATED',
  total_amount NUMERIC(12,2) NOT NULL,
  version      INTEGER       NOT NULL DEFAULT 0,
  created_at   TIMESTAMPTZ   NOT NULL DEFAULT now(),
  updated_at   TIMESTAMPTZ   NOT NULL DEFAULT now(),
  CONSTRAINT ck_orders_status CHECK (status IN
    ('CREATED','PAID','ACCEPTED','PICKED','DELIVERED','SETTLED','REFUNDING','REFUNDED','CLOSED')),
  CONSTRAINT ck_orders_amount CHECK (total_amount BETWEEN 0.01 AND 999999.99),
  CONSTRAINT ck_orders_rider CHECK
    (status NOT IN ('ACCEPTED','PICKED','DELIVERED') OR rider_id IS NOT NULL)
);
CREATE INDEX ix_orders_city_status ON orders(city_code, status);

CREATE TABLE order_events (
  id          BIGSERIAL PRIMARY KEY,
  order_id    BIGINT      NOT NULL REFERENCES orders(id),
  event_type  VARCHAR(32) NOT NULL,
  from_status VARCHAR(16),
  to_status   VARCHAR(16),
  payload     JSONB       NOT NULL DEFAULT '{}'::jsonb,
  created_at  TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE INDEX ix_order_events_order ON order_events(order_id, id);

CREATE TABLE refunds (
  id         BIGSERIAL PRIMARY KEY,
  order_id   BIGINT        NOT NULL REFERENCES orders(id),
  refund_no  VARCHAR(32)   NOT NULL UNIQUE,
  amount     NUMERIC(12,2) NOT NULL,
  status     VARCHAR(16)   NOT NULL DEFAULT 'APPLIED',
  created_at TIMESTAMPTZ   NOT NULL DEFAULT now(),
  CONSTRAINT ck_refunds_status CHECK (status IN ('APPLIED','APPROVED','REJECTED','DONE')),
  CONSTRAINT ck_refunds_amount CHECK (amount BETWEEN 0.01 AND 999999.99)
);
CREATE UNIQUE INDEX ux_refunds_order_open
  ON refunds(order_id) WHERE status IN ('APPLIED','APPROVED');

CREATE TABLE settlement_ledger (
  id         BIGSERIAL PRIMARY KEY,
  order_id   BIGINT        NOT NULL REFERENCES orders(id),
  entry_type VARCHAR(16)   NOT NULL,
  amount     NUMERIC(12,2) NOT NULL,
  created_at TIMESTAMPTZ   NOT NULL DEFAULT now(),
  CONSTRAINT ck_ledger_type CHECK (entry_type IN ('ORDER_INCOME','REFUND_OUT')),
  CONSTRAINT ux_ledger UNIQUE (order_id, entry_type)
);
约束 位置 拦住什么问题
ck_orders_status orders.status 脚本或旧版本写入非法状态值
ck_orders_rider orders 状态已进入配送中但 rider_id 为空
ux_refunds_order_open refunds 部分唯一索引 同一订单出现两笔在途退款
ux_ledger settlement_ledger 同一订单重复入账
ix_order_events_order order_events 事件无法按订单按序回溯

三、核心实现:条件更新、行锁与幂等结算

退款入口做两件事:用一条带版本号的条件更新抢占状态,影响行数为 1 才继续写事件表;影响行数为 0 直接返回冲突,让调用方重新读状态。这里不先 SELECT 再 UPDATE,避免把判断和写入拆成两个时点。下面的函数依赖 Node 20、TypeScript 5 与 pg 8,属于设计示例。

import {
    Pool } from 'pg';

type RefundResult =
  | {
    ok: true; status: string }
  | {
    ok: false; code: 'STATE_CONFLICT' };

export async function tryRefund(
  db: Pool,
  orderId: number,
  expectVersion: number
): Promise<RefundResult> {
   
  const client = await db.connect();
  try {
   
    await client.query('BEGIN');
    const upd = await client.query(
      `WITH old AS (
         SELECT id, status, version FROM orders
          WHERE id = $1 AND status IN ('PAID','ACCEPTED') AND version = $2
          FOR UPDATE
       )
       UPDATE orders o
          SET status = 'REFUNDING', version = o.version + 1, updated_at = now()
         FROM old
        WHERE o.id = old.id
       RETURNING old.status AS from_status, o.status AS to_status, o.version`,
      [orderId, expectVersion]
    );
    if (upd.rowCount === 0) {
   
      await client.query('ROLLBACK');
      return {
    ok: false, code: 'STATE_CONFLICT' };
    }
    await client.query(
      `INSERT INTO order_events(order_id, event_type, from_status, to_status, payload)
       VALUES ($1, 'REFUND_APPLIED', $2, $3, $4)`,
      [orderId, upd.rows[0].from_status, upd.rows[0].to_status,
       JSON.stringify({
    expectVersion })]
    );
    await client.query('COMMIT');
    return {
    ok: true, status: 'REFUNDING' };
  } catch (err) {
   
    await client.query('ROLLBACK');
    throw err;
  } finally {
   
    client.release();
  }
}

结算同理:只有 DELIVERED 能进 SETTLED,流水表唯一约束兜底。重复调用命中 SQLSTATE 23505 时按幂等返回,而不是抛错重试。

四、反例与验证:三种必须跑出来的失败

下面三段 SQL 用同一张订单验证三类失败。执行环境为 PostgreSQL 15、READ COMMITTED 隔离级别;以下为按该隔离级别推导的预期结果,未在真实业务库执行。

-- 反例一:退款与接单并发,只有一个能成功
-- 会话 A:发起退款
BEGIN;
WITH old AS (
  SELECT id, status FROM orders
   WHERE id = 1001 AND status IN ('PAID','ACCEPTED') AND version = 3
   FOR UPDATE
)
UPDATE orders o SET status = 'REFUNDING', version = o.version + 1
  FROM old WHERE o.id = old.id
RETURNING old.status AS from_status, o.status AS to_status, o.version;
-- 会话 B:几乎同时接单
BEGIN;
UPDATE orders SET status = 'ACCEPTED', version = version + 1
 WHERE id = 1001 AND status = 'PAID' AND version = 3;
-- 预期:A 返回 1 行,from_status=PAID,to_status=REFUNDING,version=4;
--       B 阻塞至 A 提交后重判 WHERE,version 已为 4,返回 UPDATE 0。
COMMIT;

-- 反例二:已送达订单再走订单状态退款
UPDATE orders SET status = 'REFUNDING'
 WHERE id = 1001 AND status IN ('PAID','ACCEPTED') AND version = 4;
-- 预期:UPDATE 0,状态仍为 DELIVERED,应转入售后单而不是改订单状态

-- 反例三:重复结算与超额退款
INSERT INTO settlement_ledger(order_id, entry_type, amount)
VALUES (1001, 'ORDER_INCOME', 38.50);
-- 预期:SQLSTATE 23505,违反 ux_ledger,应用层按 ALREADY_SETTLED 幂等返回

INSERT INTO refunds(order_id, refund_no, amount)
VALUES (1001, 'RF-1001-01', 0.00);
-- 预期:违反 ck_refunds_amount,0.00 不在 0.01 到 999999.99 之间
场景 输入 预期输出 处理方式
正常退款 订单 1001,PAID,version=3 1 行,状态 REFUNDING,事件表新增 1 条 进入财务审核
并发接单 同一版本 3 执行接单 UPDATE 0 返回 STATE_CONFLICT,前端提示重试
已送达退款 订单 1001,DELIVERED UPDATE 0 创建售后单,不打订单状态
重复结算 二次写入 ORDER_INCOME SQLSTATE 23505 幂等返回,不再记账

退款金额上限要单独说明:refunds 表只约束单笔金额为正且不超上限,无法跨表引用订单金额,因此“退款金额不超过订单实付”需在应用层插入前算一次,并在对账任务中复核。这是本设计留下的明确边界,验收时要专门构造一笔超额退款。

五、部署与迁移:本地演示与托管环境的差异

首期单城试点,部署形态通常先在 SaaS 与私有化之间二选一。判断维度不是日单量,而是四件事:谁持续承担更新、监控、备份与故障响应;有多少需求必须改代码而不是改配置;同一使用周期内软件、服务器、备份、维护、第三方服务与迁移各由谁付费;停止服务后数据能否按约定取回。

迁移演练按一套固定动作走:先约定导出清单,包括订单主键、商户关联、金额口径、退款记录与时间状态,用授权脱敏数据导入接收端,接收方核字段、条数、金额、状态与关联,记录差异。演练时先冻结旧端相关写入,再补齐截止点之后的增量,校验通过后切换新端。新端一旦产生订单或退款,回退就不能直接拿旧备份覆盖,必须先对账。没有可通用于所有项目的日单阈值,峰值集中度、查询复杂度和维护安排都会改变结论。

本地单机数据库与托管数据库的差异要提前写进验收:连接数上限、备份与恢复方式、主从切换时的连接中断、跨可用区时延,都会影响重试与幂等策略。本地演示能验证状态机与约束,不能替代托管环境的故障切换演练。

六、合规字段:把规章要求落成表结构

如果平台涉及网络餐饮,字段设计要承接现行规章的要求。现行规章要求平台对入网商家实名登记,登记信息包括名称、统一社会信用代码、实际经营地址、法定代表人或负责人、联系方式、经营资质,并至少每六个月核验更新一次;平台应要求网店名称与实体经营门面招牌名称一致,并在主页面显著位置持续展示经营资质、实体经营门面、实际经营地址;不提供堂食服务的入网商家,应在主页面显著位置设置“无堂食”标识。

订单侧另有三条保存义务:订单信息保存时间自交易完成之日起不少于三年,包括食品名称、下单时间、配送人员、送达时间、收货地址;配送人员培训记录保存期限不得少于二年。这些要求适用于被认定为平台提供者或入网餐饮服务提供者的主体,具体角色以当地监管确认为准。

要求 落到字段或任务 核对方式
实名登记与定期核验 merchants 表:uscc、legal_person、contact_phone、actual_address、license_no、license_verified_at 核验记录与 updated_at 是否覆盖六个月周期
主页信息展示 storefront_photo、actual_address 对外可读视图 前台页面抽样截图核对
网店名称一致 shop_sign_name 与 name 比对任务 抽 20 家比对差异
无堂食标识 dine_in_flag 前台标识与开关状态一致
订单信息保存 订单归档表或分区表,字段含食品名称、下单时间、配送人员、送达时间、收货地址 按 order_id 回查一年前订单
配送培训记录 配送人员培训表,记录培训时间与人员 记录数与在职骑手数比对

七、业务验收:一笔订单跑完再上线

上线前用一笔真实测试订单跑完整链路,每一步留证据:

  1. 下单:生成 order_no,status=CREATED,version=0。
  1. 支付回调:CREATED 转 PAID,事件表新增 PAY_SUCCESS。
  1. 骑手接单:PAID 转 ACCEPTED,rider_id 非空;用旧版本号重复提交应返回冲突。
  1. 发起退款:PAID 或 ACCEPTED 转 REFUNDING;同时用另一连接接单,只允许一个成功。
  1. 退款完成:REFUNDING 转 REFUNDED,写退款流水;此时再调结算应返回 NOT_DELIVERED。
  1. 正常送达与结算:DELIVERED 转 SETTLED,流水表只允许一条 ORDER_INCOME。
  1. 导出与对账:导出订单、退款、流水三张表,按 order_id 关联核对金额与状态。
  1. 回退:模拟切换失败,确认旧端可读、增量可补齐、新端未产生业务时才允许直接回退。

常见追问

校园团购模块要不要和外卖订单共用一张订单表?团购套餐的上架、图文视频生成与多平台发布属于营销域,核销、退款、结算属于交易域,两地合表会让状态机迅速膨胀。建议用适配层对接,外部只暴露套餐 ID、核销码、订单号三类键;接入前核对账号主体、商品与套餐字段、订单与核销状态、数据归属与接口频率。

先 SaaS 还是私有化?看维护责任与退出条件。团队没有专职运维时,重点核对方是否承担更新、监控、备份与故障响应;有隔离部署或接口要求时,再评估私有部署的源码许可、依赖升级与持续费用。

状态机放在应用层还是数据库?两层都要。数据库约束拦住非法值,条件更新拦住并发覆盖,应用层负责给出可读的冲突码和重试建议;只做应用层校验,脚本和定时任务很容易绕过。

对账要核到什么程度?至少核字段、条数、金额、状态与关联五项,并保留差异清单和责任人。总额相等不代表没有问题,一条重复加一条遗漏可以互相抵消。

把上面七节落到一张验收表:四端闭环跑通、状态机约束生效、退款与接单互斥、结算幂等、迁移可回退、合规字段可查、导出可对账。先在一个城区、少量品类上跑完这七项,再考虑扩城和接入营销模块,比一开始就把功能铺满更稳。

作者:校园外卖平台(外卖平台软件开发公司)。

相关文章
|
18天前
|
Linux 开发工具 iOS开发
Codex保姆级教程(下载+安装+登录+使用,含所有版本,2026最新)
Codex是OpenAI推出的开源AI编程智能体,本地运行,可理解整个代码库,支持自然语言指令改代码、执行命令、跑测试、修Bug,兼容Win/macOS/Linux。(239字)
8131 58
|
3天前
|
弹性计算 人工智能 API
Codex超详细入门指南(下载·安装·登录·上手,全版本覆盖,2026最新版)
建议收藏本教程,2026 全年各版本更新随时回来查阅。如果你在搭建过程中遇到任何问题,欢迎结合 阿里云工单系统 提交技术支持请求,或在 阿里云开发者社区 搜索 Codex 相关话题交流。 祝你编码愉快,效率翻倍!
1552 1
|
6天前
|
JSON 前端开发 API
阿里云最新Qwen4-Max大模型介绍:模型定位、特征、能力、适用场景解析
2026 年 11 月 11 日,阿里发布第四代旗舰模型Qwen4-Max预览版,首发千问 AI 平台 Token Plan,并同步接入千问办公、Qoder 等入口。该版本聚焦知识理解、世界感知、编程与 Agentic 四项升级,主打复杂编程、专业办公、前端设计与专业软件操作。预览期至 11 月 25 日 24:00,到期后模型标识下线;限时 2 折、新用户再享 5 折,最低 1 折可体验。
|
19天前
|
JavaScript API iOS开发
DeepSeek Harness下载、安装、配置一篇搞定(2026整理,送常用插件)
DeepSeek Harness(DSH)是DeepSeek于2026年开源的MIT协议AI Agent框架,支持插件化组装模型、工具、沙箱与UI,兼容主流大模型。本文提供免Node.js的桌面端安装包(Win/macOS),含详细图文教程及热门插件推荐。
5736 69
|
6天前
|
云安全 人工智能 安全
|
13天前
|
Linux 开发工具 iOS开发
2026最新codex下载安装保姆级使用教程(下载+安装+登录+使用,含所有历史版本)
本文详解OpenAI Codex国内快速上手指南:提供Win/macOS/Linux全平台免安装包、npm/Homebrew等多方式安装、账号/API Key双登录、简体中文切换,覆盖下载、安装、汉化、使用及高频避坑(如微软商店失败、npm超时等),10分钟即可跑通。
2962 9
|
6天前
|
人工智能 前端开发 API
阿里云Qwen4-Max 大模型详解:定位、特征、能力、适用场景与相对Qwen3-Max差异解析
2026年11月11日,阿里发布第四代旗舰模型Qwen4-Max预览版,首发千问AI平台Token Plan并接入千问办公、Qoder等入口。该版本聚焦知识理解、世界感知、编程与Agentic四项升级,主打复杂编程、专业办公、前端设计与专业软件操作等真实任务。预览期为11月11日10:00至11月25日24:00,仅支持Token Plan调用,到期后模型标识下线;限时2折、新用户再享5折,最低1折可体验。
|
3天前
|
Linux Go 开发工具
手机上跑 DeepSeek 智能体:开源安卓客户端 DSH Go 安装与使用指南
DSH Go 是一款开源安卓客户端,将 DeepSeek Harness 智能体引擎装进手机:免 Root、免 Termux,一键安装即用;支持本机运行(内置 Ubuntu+Node.js)或远程接管电脑会话;具备插话打断、过程折叠、屏幕操控、端到端加密分享等特色功能,真正实现智能体“口袋化”。
2430 0
|
11天前
|
人工智能 安全 API
DeepSeek Harness下载、安装、配置一篇搞定(2026整理,送常用插件)
DeepSeek Harness(dsh)是DeepSeek AI于2026年开源的轻量级Agent运行框架,基于Cordis内核,践行“一切皆插件”理念。支持Web/桌面双端,开箱即用;内置多模型接入、丰富插件生态(超3.5万),适配编程、办公、创作等场景。(239字)
1893 1