同城外卖跑腿小程序选型:订单状态机与重复出餐故障怎么解

简介: 同城外卖跑腿选型先分自营门店与多商户平台,再用订单状态机约束支付、接单和打印。本文给出表结构、幂等实现、正常输出与异常反例,帮助减少重复出餐和重复退款。

同城外卖跑腿小程序制作平台的选型,先不是列名单,而是判断经营结构:单店或同品牌直营自营,商品和款项归商家,门店自己接单或约定第三方配送;多商户平台则要让多个独立商家入驻、平台抽成结算并组织配送池。两类结构在小程序前台可能都叫“外卖”,但订单归属、结算主体、配送调度和售后责任不同。真正落到工程上,分水岭是同一个订单能否被支付回调、接单、打印、退款和结算一致地处理。下面用一个常见故障——支付成功回调重试导致门店重复接单、后厨重复出餐——说明怎样用数据模型、状态机和幂等约束把问题挡住。

先分经营结构,再决定订单模型

选平台时先回答四个问题:谁卖货、谁收款、是否招独立商户、谁配送。答案不同,订单表的主键、归属字段和结算字段就不同。自营门店和多商户平台都能做外卖页面,但前者的订单归属商家,后者的订单同时归属平台和入驻商家,结算规则必须在订单上留快照。

经营结构 订单归属 结算主体 配送调度 数据库约束重点
自营单店或直营多店 merchant_id 归属商家,platform_id 为空 商家收款,平台不抽成 MERCHANT_SELF 或 THIRD_PARTY settlement_rule_id 为空;多店权限按品牌关系另配
多商户平台 platform_id 与 merchant_id 同时存在 平台按 settlement_rule_id 抽成结算 PLATFORM_POOL 缺 platform_id 或 settlement_rule_id 应拒绝建单
跑腿订单 order_type 为 ERRAND,记录取送地址 按经营结构同上 自营可商家自送,平台可调度池 缺 pickup_address 或 dropoff_address 应拒绝

这张表不是功能清单,而是数据库约束。选型时如果服务商只能演示“能下单”,却不能说明订单归属、结算快照和配送调度落在哪些字段上,后续很容易在退款、对账或骑手改派时返工。

故障现场:一次支付回调,为什么变成两张出餐单

典型链路是:顾客支付成功,支付渠道回调订单服务;订单服务把订单改为已支付,再调用接单接口;接单接口更新状态并生成后厨打印任务。支付渠道超时会重试回调,前端按钮也可能重试,服务间调用还可能再重试。三个重试叠加,如果支付事件、订单状态和打印任务没有共同的幂等边界,就会发生同一笔支付被处理两次、同一订单被接单两次、后厨打印出两张小票。

更麻烦的是退款:如果系统按“已接单记录”发起退款,而接单记录有两条,就可能出现重复退款或对账差额。根因不是打印机,而是写路径缺少唯一键、版本条件和事务边界。修复思路是:支付回调先落幂等事件表,订单状态用版本号做乐观锁,接单和打印任务在同一事务内完成,打印任务用去重键保证只生成一次。

微订官方下载页公开的商家App门店资料与打印接单设置

微订官方下载页公开的商家App门店资料与打印接单设置

数据模型与字段约束

下面以 PostgreSQL 15+ 为例。核心表不追求覆盖全部业务,而是把会引发重复出餐和重复退款的写路径约束住。订单表保存经营结构、支付状态、履约状态和版本号;支付事件表保存渠道流水;打印任务表保存去重键;状态事件表保存迁移审计。

表 关键字段 约束或用途
orders order_no、biz_mode、platform_id、merchant_id、settlement_rule_id、version 按经营结构约束归属;version 用于接单乐观锁
payment_events event_id 主键、provider_txn_id 唯一、order_no、amount_fen 支付回调幂等;同一渠道流水只落一次
print_jobs order_id、job_type、dedup_key 唯一 同一订单同一接单动作只生成一次打印
order_events order_id、from_status、to_status、idem_key 唯一 状态迁移审计,重试可查
CREATE TYPE biz_mode AS ENUM ('SELF_OPERATED','MARKETPLACE');
CREATE TYPE order_type AS ENUM ('FOOD_DELIVERY','RETAIL_DELIVERY','ERRAND');
CREATE TYPE payment_status AS ENUM ('UNPAID','PAID','REFUNDING','REFUNDED');
CREATE TYPE fulfillment_status AS ENUM ('CREATED','PAID_WAIT_ACCEPT','ACCEPTED','PREPARING','READY','DELIVERING','COMPLETED','CANCELED');
CREATE TYPE dispatch_mode AS ENUM ('MERCHANT_SELF','THIRD_PARTY','PLATFORM_POOL');

CREATE TABLE settlement_rules (
  rule_id bigserial PRIMARY KEY,
  platform_id bigint NOT NULL,
  merchant_id bigint NOT NULL,
  commission_bps integer NOT NULL CHECK (commission_bps BETWEEN 0 AND 10000),
  UNIQUE (platform_id, merchant_id)
);

CREATE TABLE orders (
  order_id bigserial PRIMARY KEY,
  order_no text NOT NULL UNIQUE,
  biz_mode biz_mode NOT NULL,
  platform_id bigint,
  merchant_id bigint NOT NULL,
  settlement_rule_id bigint REFERENCES settlement_rules(rule_id),
  order_type order_type NOT NULL,
  dispatch_mode dispatch_mode NOT NULL,
  total_fen integer NOT NULL CHECK (total_fen >= 0),
  paid_amount_fen integer NOT NULL DEFAULT 0 CHECK (paid_amount_fen >= 0),
  payment_status payment_status NOT NULL DEFAULT 'UNPAID',
  fulfillment_status fulfillment_status NOT NULL DEFAULT 'CREATED',
  pickup_address text,
  dropoff_address text,
  version integer NOT NULL DEFAULT 0,
  paid_at timestamptz,
  accepted_at timestamptz,
  created_at timestamptz NOT NULL DEFAULT now(),
  CONSTRAINT ck_owner CHECK (
    (biz_mode='SELF_OPERATED' AND platform_id IS NULL AND settlement_rule_id IS NULL
      AND dispatch_mode IN ('MERCHANT_SELF','THIRD_PARTY'))
    OR
    (biz_mode='MARKETPLACE' AND platform_id IS NOT NULL AND settlement_rule_id IS NOT NULL
      AND dispatch_mode='PLATFORM_POOL')
  ),
  CONSTRAINT ck_errand_addr CHECK (
    order_type != 'ERRAND' OR (pickup_address IS NOT NULL AND dropoff_address IS NOT NULL)
  )
);

CREATE TABLE payment_events (
  event_id text PRIMARY KEY,
  provider_txn_id text NOT NULL UNIQUE,
  order_no text NOT NULL REFERENCES orders(order_no),
  amount_fen integer NOT NULL CHECK (amount_fen >= 0),
  status text NOT NULL CHECK (status IN ('SUCCESS','FAIL')),
  occurred_at timestamptz NOT NULL,
  received_at timestamptz NOT NULL DEFAULT now()
);

CREATE TABLE print_jobs (
  job_id bigserial PRIMARY KEY,
  order_id bigint NOT NULL REFERENCES orders(order_id),
  job_type text NOT NULL CHECK (job_type IN ('KITCHEN','RECEIPT','LABEL')),
  dedup_key text NOT NULL UNIQUE,
  payload jsonb NOT NULL,
  created_at timestamptz NOT NULL DEFAULT now()
);

CREATE TABLE order_events (
  event_id bigserial PRIMARY KEY,
  order_id bigint NOT NULL REFERENCES orders(order_id),
  event_type text NOT NULL,
  from_status text NOT NULL,
  to_status text NOT NULL,
  idem_key text NOT NULL UNIQUE,
  created_at timestamptz NOT NULL DEFAULT now()
);

INSERT INTO orders(order_no,biz_mode,merchant_id,order_type,dispatch_mode,total_fen)
VALUES ('T20260001','SELF_OPERATED',1001,'FOOD_DELIVERY','MERCHANT_SELF',6800);

核心实现:支付回调先落幂等事件,再接单和打印

实现依赖:Node.js 20+、TypeScript 5+、pg 8+、PostgreSQL 15+。运行步骤:第一,在本地 PostgreSQL 建库并执行上面的 SQL;第二,安装依赖;第三,把下面的 TypeScript 保存为 order_flow.ts,并用 DATABASE_URL 指向本地库;第四,按调用片段执行。本文未连接真实支付渠道、打印机或云资源,以下输出是按约束推导的预期结果。

npm i pg tsx typescript
import {
    Pool } from 'pg';

type PayCallback = {
   
  eventId: string;
  orderNo: string;
  providerTxnId: string;
  amountFen: number;
  status: 'SUCCESS' | 'FAIL';
  occurredAt: string;
};

export async function onPaymentCallback(db: Pool, cb: PayCallback) {
   
  const c = await db.connect();
  try {
   
    await c.query('BEGIN');
    const ins = await c.query(
      `INSERT INTO payment_events(event_id, provider_txn_id, order_no, amount_fen, status, occurred_at)
       VALUES ($1,$2,$3,$4,$5,$6)
       ON CONFLICT DO NOTHING
       RETURNING event_id`,
      [cb.eventId, cb.providerTxnId, cb.orderNo, cb.amountFen, cb.status, cb.occurredAt]
    );
    if (ins.rowCount === 0) {
   
      const old = await c.query(
        `SELECT amount_fen, status FROM payment_events
         WHERE event_id=$1 OR provider_txn_id=$2 LIMIT 1`,
        [cb.eventId, cb.providerTxnId]
      );
      if (old.rowCount === 0) throw new Error('EVENT_CONFLICT_UNRESOLVED');
      if (old.rows[0].amount_fen !== cb.amountFen || old.rows[0].status !== cb.status) {
   
        throw new Error('EVENT_PAYLOAD_CONFLICT');
      }
      await c.query('ROLLBACK');
      return {
    code: 'DUPLICATE_EVENT' as const };
    }
    if (cb.status !== 'SUCCESS') {
   
      await c.query('COMMIT');
      return {
    code: 'PAY_FAILED_RECORDED' as const };
    }
    const q = await c.query(
      `SELECT order_id, total_fen, paid_amount_fen, payment_status
       FROM orders WHERE order_no=$1 FOR UPDATE`,
      [cb.orderNo]
    );
    if (q.rowCount === 0) throw new Error('ORDER_NOT_FOUND');
    const o = q.rows[0];
    if (o.payment_status === 'PAID') {
   
      if (o.paid_amount_fen !== cb.amountFen) throw new Error('PAID_AMOUNT_MISMATCH');
      await c.query('COMMIT');
      return {
    code: 'ALREADY_PAID_IDEMPOTENT' as const };
    }
    if (o.payment_status !== 'UNPAID') throw new Error('INVALID_PAYMENT_STATE');
    if (o.total_fen !== cb.amountFen) throw new Error('AMOUNT_MISMATCH');
    await c.query(
      `UPDATE orders
       SET payment_status='PAID', fulfillment_status='PAID_WAIT_ACCEPT',
           paid_amount_fen=$2, paid_at=now(), version=version+1
       WHERE order_id=$1`,
      [o.order_id, cb.amountFen]
    );
    await c.query(
      `INSERT INTO order_events(order_id, event_type, from_status, to_status, idem_key)
       VALUES ($1,'PAYMENT_SUCCESS','CREATED','PAID_WAIT_ACCEPT',$2)`,
      [o.order_id, cb.eventId]
    );
    await c.query('COMMIT');
    return {
    code: 'OK' as const, orderId: o.order_id };
  } catch (e) {
   
    await c.query('ROLLBACK');
    throw e;
  } finally {
   
    c.release();
  }
}

export async function acceptOrder(db: Pool, orderNo: string, expectedVersion: number) {
   
  const c = await db.connect();
  try {
   
    await c.query('BEGIN');
    const u = await c.query(
      `UPDATE orders
       SET fulfillment_status='ACCEPTED', accepted_at=now(), version=version+1
       WHERE order_no=$1 AND fulfillment_status='PAID_WAIT_ACCEPT' AND version=$2
       RETURNING order_id, version`,
      [orderNo, expectedVersion]
    );
    if (u.rowCount === 0) {
   
      const st = await c.query(
        `SELECT fulfillment_status, version FROM orders WHERE order_no=$1`,
        [orderNo]
      );
      if (st.rowCount === 0) throw new Error('ORDER_NOT_FOUND');
      const row = st.rows[0];
      await c.query('ROLLBACK');
      if (row.fulfillment_status === 'ACCEPTED' && row.version === expectedVersion + 1) {
   
        return {
    code: 'ALREADY_ACCEPTED' as const };
      }
      return {
    code: 'STALE_OR_INVALID_STATE' as const, current: row };
    }
    const orderId = u.rows[0].order_id;
    await c.query(
      `INSERT INTO print_jobs(order_id, job_type, dedup_key, payload)
       VALUES ($1,'KITCHEN',$2,$3)
       ON CONFLICT (dedup_key) DO NOTHING`,
      [orderId, `KITCHEN:${
     orderId}:ACCEPT`, JSON.stringify({
    orderNo })]
    );
    await c.query(
      `INSERT INTO order_events(order_id, event_type, from_status, to_status, idem_key)
       VALUES ($1,'MERCHANT_ACCEPT','PAID_WAIT_ACCEPT','ACCEPTED',$2)`,
      [orderId, `ACCEPT:${
     orderId}:${
     expectedVersion}`]
    );
    await c.query('COMMIT');
    return {
    code: 'OK' as const, orderId, nextVersion: u.rows[0].version };
  } catch (e) {
   
    await c.query('ROLLBACK');
    throw e;
  } finally {
   
    c.release();
  }
}

const db = new Pool({
    connectionString: process.env.DATABASE_URL });
await onPaymentCallback(db, {
   
  eventId: 'e1', orderNo: 'T20260001', providerTxnId: 'pay-t1',
  amountFen: 6800, status: 'SUCCESS', occurredAt: new Date().toISOString()
});
await acceptOrder(db, 'T20260001', 1);

正常输出与异常反例

正常路径下,支付回调只把订单从 UNPAID 改为 PAID,版本从 0 变为 1;接单时传入上一步的版本号 1,订单变为 ACCEPTED,版本变为 2,打印任务只生成一条。重复提交同一接单请求时,因为版本号已经不是 1,更新不会命中,代码返回 ALREADY_ACCEPTED,不会新增打印任务。

微订官方下载页公开的商家App订单列表与接单进度

微订官方下载页公开的商家App订单列表与接单进度

-- T20260001 正常路径
payment: {code: OK, orderId: 1}
accept:  {code: OK, orderId: 1, nextVersion: 2}
retry:   {code: ALREADY_ACCEPTED}
print_jobs: 1

-- T20260002 异常路径
callback: AMOUNT_MISMATCH
orders: T20260002 | UNPAID | CREATED | 0
print_jobs: 0

异常反例一:另建一笔总价 6800 分的订单 T20260002,支付回调只带 6700 分。代码在比较 total_fen 与 amount_fen 时抛出 AMOUNT_MISMATCH,事务回滚,订单保持 UNPAID 和 CREATED,版本仍为 0,打印任务为 0。异常反例二:同一个 event_id 第一次带 6800 分,第二次带 6600 分,第二次会命中 EVENT_PAYLOAD_CONFLICT,不会覆盖原支付事件。异常反例三:接单时传入过期版本 0,更新不命中,返回 STALE_OR_INVALID_STATE,后厨不会多出小票。

业务验收:把技术约束带回选型

回到“同城外卖跑腿小程序制作平台有哪些”这个问题,平台名单只是起点。单店自营要验证的是:支付回调能否幂等、接单与打印是否同事务、退款能否按原支付流水唯一处理。多商户平台还要验证:订单是否同时保存 platform_id、merchant_id 和 settlement_rule_id,结算规则是否按订单快照,配送调度是否与经营结构匹配。下面这张验收表可以直接用于演示和压测。

验收项 操作 通过标准
支付回调幂等 同一 event_id 和 provider_txn_id 各重放一次 订单只从 UNPAID 变 PAID 一次,version 只加 1
接单幂等 同一 expectedVersion 连续提交两次 第一次 ACCEPTED,第二次 ALREADY_ACCEPTED,不新增打印任务
金额校验 用少 1 分的金额回调 返回 AMOUNT_MISMATCH,订单保持 UNPAID,不生成打印
经营结构约束 自营单插入 platform_id,平台单缺 settlement_rule_id 数据库拒绝写入
退款唯一性 同一支付流水重复发起退款 只产生一条退款记录,退款表按 provider_txn_id 唯一

选平台时可以直接问技术团队:支付回调以什么做幂等键?接单和打印是否在同一事务?重复回调能否不重复出餐?多商户订单是否保存结算规则快照?骑手改派或商家拒单时,订单版本和打印任务如何联动?这些问题比“功能列表有多长”更能判断后续上线是否稳。

本地演示与云环境要分开看。本文示例只覆盖 PostgreSQL 单机和 Node.js 调用,不涉及真实支付渠道、打印机、骑手端或云资源。若部署到云上,可选择托管 PostgreSQL 作为订单库,但连接池、网络白名单、备份、审计、监控和密钥管理仍需按实际环境配置。本地通过不等于云上现网验证,也不代表任何平台的实际性能或经营结果。

作者:小艾普(上海逊柯计算机科技有限公司)。

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