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

微订校园平台校区选择页与骑手宿舍分组送达页。
一、故障复现:整批送达把异常单也记成完成
设一个校门中转批次装了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,事件数不增加 |
| 缺凭证送达 | 事务回滚,订单状态不变 |
| 退款与结算 | 未送达订单不进入结算,退款按订单与事件追溯 |
选校园外卖系统或做二次开发时,可把部分完成是否返回逐单结果、结算是否读取订单级送达事件、异常单能否重新入批、重试是否幂等写进演示脚本。若部署到云数据库,事务、行锁和幂等表仍是共同基础,备份、监控、连接池和账号权限要单独核对;本地演示脚本的输出不能直接当作正式环境结果。
作者:微订(上海逊柯计算机科技有限公司)。