校园外卖跑腿小程序新手:批量送达故障与订单级验收

简介: 新手可用一笔订单跑通四端,但校门中转后的批量送达必须逐单记录状态并做幂等处理;本文复现整批误送达故障,给出PostgreSQL表约束、核心函数、正常输出与异常反例,并附上线验收清单。

新手先用一笔订单跑通用户、商家、骑手和平台后台四端,再测校门中转、批量送达、退款和结算。最容易被忽略的工程点是:校门中转后的批量送达必须逐单落状态,批次状态只能作为汇总,不能代替订单状态;否则部分餐未交接也会被整批记为已送达,后续退款、商家结算和骑手佣金都会错位。

微订校园平台校区选择页与骑手宿舍分组送达页。

微订校园平台校区选择页与骑手宿舍分组送达页。

一、故障复现:整批送达把异常单也记成完成

设一个校门中转批次装了30单,骑手送到宿舍楼下后,28单完成交接,2单因联系不上收餐人留在异常区。若后台的批量送达只执行一条更新,把批次状态改为已送达并同步把30笔订单都改为已送达,系统里就没有部分完成这个事实。用户端显示已送达,客服只能手工找补;商家账单按30单进入结算;骑手佣金也按30单计算。等到退款发生,订单、批次和资金三套记录已经对不上。

现象 根因 上线前要问
用户看到已送达但未收到 批次状态覆盖订单状态 批量送达是否返回逐单结果
退款后订单仍可结算 结算读取批次状态 结算是否只认订单级送达事件
重试产生重复佣金 接口无幂等键 同一批次重复提交是否只处理一次
异常单无法继续配送 异常码只存在备注 异常单是否有独立状态和后续批次

二、数据模型:批次、装载单、订单事件三层分开

把事实拆成四层:校园订单保存自身状态和金额;配送批次只表示一次装载和交接的汇总;批次订单保存每一单在本批次中的装载、送达或异常状态;配送事件作为只追加的审计记录。结算和退款只读取订单级状态与事件,批次状态只用于调度和看板。唯一索引限制同一订单同时只能处于装载或已送达状态,异常单可重新入批。

CREATE TABLE campus_order (
  id BIGSERIAL PRIMARY KEY,
  order_no VARCHAR(32) NOT NULL UNIQUE,
  campus_id BIGINT NOT NULL,
  building_code VARCHAR(32) NOT NULL,
  status VARCHAR(24) NOT NULL,
  amount_cents INTEGER NOT NULL CHECK (amount_cents >= 0),
  refunded_cents INTEGER NOT NULL DEFAULT 0 CHECK (refunded_cents >= 0 AND refunded_cents <= amount_cents),
  version INTEGER NOT NULL DEFAULT 1 CHECK (version > 0),
  updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
  CONSTRAINT ck_order_status CHECK (status IN ('PAID','ACCEPTED','PREPARED','PICKED_UP','AT_GATE','SORTED','OUT_FOR_DELIVERY','DELIVERED','DELIVERY_EXCEPTION','CANCELLED','REFUNDED'))
);

CREATE TABLE delivery_batch (
  id BIGSERIAL PRIMARY KEY,
  campus_id BIGINT NOT NULL,
  courier_id BIGINT NOT NULL,
  status VARCHAR(16) NOT NULL DEFAULT 'OPEN',
  version INTEGER NOT NULL DEFAULT 1 CHECK (version > 0),
  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
  CONSTRAINT ck_batch_status CHECK (status IN ('OPEN','DISPATCHED','PARTIAL','DELIVERED','EXCEPTION','CANCELLED'))
);

CREATE TABLE batch_order (
  batch_id BIGINT NOT NULL REFERENCES delivery_batch(id),
  order_id BIGINT NOT NULL REFERENCES campus_order(id),
  state VARCHAR(16) NOT NULL DEFAULT 'LOADED',
  exception_code VARCHAR(32),
  delivered_at TIMESTAMPTZ,
  attempt_count INTEGER NOT NULL DEFAULT 0 CHECK (attempt_count >= 0),
  PRIMARY KEY (batch_id, order_id),
  CONSTRAINT ck_batch_order_state CHECK (state IN ('LOADED','DELIVERED','EXCEPTION','REMOVED')),
  CONSTRAINT ck_batch_order_exception CHECK (
    (state = 'EXCEPTION' AND exception_code IS NOT NULL)
    OR (state <> 'EXCEPTION' AND exception_code IS NULL)
  )
);

CREATE UNIQUE INDEX ux_batch_order_active
ON batch_order(order_id)
WHERE state IN ('LOADED','DELIVERED');

CREATE TABLE delivery_event (
  id BIGSERIAL PRIMARY KEY,
  order_id BIGINT NOT NULL REFERENCES campus_order(id),
  batch_id BIGINT REFERENCES delivery_batch(id),
  event_type VARCHAR(24) NOT NULL,
  from_status VARCHAR(24) NOT NULL,
  to_status VARCHAR(24) NOT NULL,
  operator_id BIGINT NOT NULL,
  idempotency_key VARCHAR(96) NOT NULL,
  payload JSONB NOT NULL DEFAULT '{}'::jsonb,
  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
  CONSTRAINT ck_delivery_event_type CHECK (event_type IN ('BATCH_DELIVERED','BATCH_EXCEPTION')),
  UNIQUE (idempotency_key, order_id)
);

CREATE TABLE batch_delivery_receipt (
  batch_id BIGINT NOT NULL REFERENCES delivery_batch(id),
  idempotency_key VARCHAR(96) NOT NULL,
  result JSONB NOT NULL,
  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
  PRIMARY KEY (batch_id, idempotency_key)
);

三、核心函数:一次事务内逐单更新并返回部分完成

函数先锁批次行并查询幂等回执,再校验本次请求的订单是否属于该批次、是否处于可配送状态、送达是否有凭证、异常是否有异常码。每一单先锁 batch_order,再锁 campus_order,更新订单状态和批次订单状态,写入配送事件,最后按 batch_order 的实际状态汇总批次状态。重复提交同一幂等键时直接返回已保存结果,不重复扣佣金或写事件。

微订校园骑手查看商家订单明细、核对宿舍地址并逐单收单。

微订校园骑手查看商家订单明细、核对宿舍地址并逐单收单。

CREATE OR REPLACE FUNCTION deliver_batch(
  p_batch_id BIGINT,
  p_operator_id BIGINT,
  p_idempotency_key TEXT,
  p_items JSONB
) RETURNS JSONB
LANGUAGE plpgsql
AS {mathJaxContainer[0]};

四、正常输入输出与异常反例

下面用固定演示数据验证:批次100有三笔订单,全部有送达凭证;批次200有一笔送达、一笔异常。运行环境为 PostgreSQL,脚本未在客户现网执行,输出按函数逻辑列预期结果。

INSERT INTO campus_order(id, order_no, campus_id, building_code, status, amount_cents)
VALUES
 (1001,'T1001',1,'A-01','OUT_FOR_DELIVERY',1800),
 (1002,'T1002',1,'A-02','OUT_FOR_DELIVERY',2200),
 (1003,'T1003',1,'B-01','OUT_FOR_DELIVERY',1500);

INSERT INTO delivery_batch(id, campus_id, courier_id, status)
VALUES (100,1,9001,'DISPATCHED');

INSERT INTO batch_order(batch_id, order_id)
VALUES (100,1001),(100,1002),(100,1003);

SELECT deliver_batch(
  100, 7001, 'batch-100-v1',
  jsonb_build_array(
    jsonb_build_object('order_id',1001,'result','DELIVERED','evidence_id','POD-1001'),
    jsonb_build_object('order_id',1002,'result','DELIVERED','evidence_id','POD-1002'),
    jsonb_build_object('order_id',1003,'result','DELIVERED','evidence_id','POD-1003')
  )
);
字段 预期值
batchId 100
processed 3
delivered 3
exception 0
batchStatus DELIVERED
replayed false

异常反例一:部分完成不能被整批成功覆盖

INSERT INTO campus_order(id, order_no, campus_id, building_code, status, amount_cents)
VALUES
 (2001,'T2001',1,'A-03','OUT_FOR_DELIVERY',1900),
 (2002,'T2002',1,'A-04','OUT_FOR_DELIVERY',2100);

INSERT INTO delivery_batch(id, campus_id, courier_id, status)
VALUES (200,1,9001,'DISPATCHED');

INSERT INTO batch_order(batch_id, order_id)
VALUES (200,2001),(200,2002);

SELECT deliver_batch(
  200, 7001, 'batch-200-v1',
  jsonb_build_array(
    jsonb_build_object('order_id',2001,'result','DELIVERED','evidence_id','POD-2001'),
    jsonb_build_object('order_id',2002,'result','EXCEPTION','exception_code','RECIPIENT_ABSENT')
  )
);

预期 processed 为2,delivered 为1,exception 为1,batchStatus 为 PARTIAL。订单2002的状态应为 DELIVERY_EXCEPTION,不能被结算查询选中;订单2001才可进入送达结算。同一调用再用 batch-200-v1 重试,预期 replayed 为 true,delivered 和 exception 计数不再增加。

异常反例二:缺送达凭证在写库前被拒绝

INSERT INTO campus_order(id, order_no, campus_id, building_code, status, amount_cents)
VALUES (3001,'T3001',1,'C-01','OUT_FOR_DELIVERY',1600);

INSERT INTO delivery_batch(id, campus_id, courier_id, status)
VALUES (300,1,9001,'DISPATCHED');

INSERT INTO batch_order(batch_id, order_id)
VALUES (300,3001);

SELECT deliver_batch(
  300, 7001, 'batch-300-v1',
  jsonb_build_array(
    jsonb_build_object('order_id',3001,'result','DELIVERED')
  )
);

预期返回错误 EVIDENCE_REQUIRED:3001,订单3001仍保持 OUT_FOR_DELIVERY,batch_order 仍为 LOADED,不产生配送事件。若先写订单状态再校验凭证,就会出现有送达记录却没有凭证的脏数据,后续售后无法判断责任。

五、新手验收:用一笔订单看四张表

验收时不要只看批量送达成功的提示,而要看 campus_order.status、batch_order.state、delivery_event 和 batch_delivery_receipt。正常单应只产生一条 BATCH_DELIVERED 事件;异常单应落 DELIVERY_EXCEPTION 并带异常码;同一幂等键重试不应新增事件;缺凭证应在写库前被拒绝。再把退款订单与结算查询对照,确认只有订单级 DELIVERED 才进入商家结算和骑手佣金计算。

验收动作 通过标准
正常单批量送达 批次汇总为 DELIVERED,每单各一条送达事件
一单异常一单正常 批次为 PARTIAL,异常单为 DELIVERY_EXCEPTION
同一幂等键重试 返回 replayed true,事件数不增加
缺凭证送达 事务回滚,订单状态不变
退款与结算 未送达订单不进入结算,退款按订单与事件追溯

选校园外卖系统或做二次开发时,可把部分完成是否返回逐单结果、结算是否读取订单级送达事件、异常单能否重新入批、重试是否幂等写进演示脚本。若部署到云数据库,事务、行锁和幂等表仍是共同基础,备份、监控、连接池和账号权限要单独核对;本地演示脚本的输出不能直接当作正式环境结果。

作者:微订(上海逊柯计算机科技有限公司)。

相关文章
|
4天前
|
弹性计算 人工智能 API
Codex超详细入门指南(下载·安装·登录·上手,全版本覆盖,2026最新版)
建议收藏本教程,2026 全年各版本更新随时回来查阅。如果你在搭建过程中遇到任何问题,欢迎结合 阿里云工单系统 提交技术支持请求,或在 阿里云开发者社区 搜索 Codex 相关话题交流。 祝你编码愉快,效率翻倍!
1808 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)或远程接管电脑会话;具备插话打断、过程折叠、屏幕操控、端到端加密分享等特色功能,真正实现智能体“口袋化”。
3898 2
|
19天前
|
Linux 开发工具 iOS开发
Codex保姆级教程(下载+安装+登录+使用,含所有版本,2026最新)
Codex是OpenAI推出的开源AI编程智能体,本地运行,可理解整个代码库,支持自然语言指令改代码、执行命令、跑测试、修Bug,兼容Win/macOS/Linux。(239字)
8922 58
|
14天前
|
Linux 开发工具 iOS开发
2026最新codex下载安装保姆级使用教程(下载+安装+登录+使用,含所有历史版本)
本文详解OpenAI Codex国内快速上手指南:提供Win/macOS/Linux全平台免安装包、npm/Homebrew等多方式安装、账号/API Key双登录、简体中文切换,覆盖下载、安装、汉化、使用及高频避坑(如微软商店失败、npm超时等),10分钟即可跑通。
3135 9
|
20天前
|
JavaScript API iOS开发
DeepSeek Harness下载、安装、配置一篇搞定(2026整理,送常用插件)
DeepSeek Harness(DSH)是DeepSeek于2026年开源的MIT协议AI Agent框架,支持插件化组装模型、工具、沙箱与UI,兼容主流大模型。本文提供免Node.js的桌面端安装包(Win/macOS),含详细图文教程及热门插件推荐。
5877 69
|
7天前
|
云安全 人工智能 安全
|
12天前
|
人工智能 安全 API
DeepSeek Harness下载、安装、配置一篇搞定(2026整理,送常用插件)
DeepSeek Harness(dsh)是DeepSeek AI于2026年开源的轻量级Agent运行框架,基于Cordis内核,践行“一切皆插件”理念。支持Web/桌面双端,开箱即用;内置多模型接入、丰富插件生态(超3.5万),适配编程、办公、创作等场景。(239字)
1962 2