自建校园代取快递系统，先按预算、技术人手、长期运维和数据自主决定交付方式，再把准备工作落成六类可验收资源：主体与账号、域名备案与服务器、源码与技术交付、履约数据模型、资金结算、驿站校方与骑手运营。这里把自建理解为源码安装或私有化部署；单校低预算可先用标准SaaS跑通正常单、退款和高峰批量，再评估私有化。代取快递最容易在交接环节暴露工程问题：同一订单重复提交、跨站扫码或错误取件码都可能造成重复取件和错分账。下面以“取件核验幂等与状态机”为例，给出模型、核心实现和异常验证。
一、准备清单先落成可验收资源
准备清单不宜只写“买服务器、买源码”。每一类资源都要有可核对的产出和验收证据，后续演示、合同和上线记录才能对得上。下表给出单校或两三校区项目的通用准备框架，具体备案要求、账号规则和支付条件以主管部门、平台及服务商最新页面为准。
| 准备项 | 最小产出 | 验收证据 | 重点核对 |
|---|---|---|---|
| 主体与账号 | 营业执照、小程序主体账号、支付商户号、隐私政策、用户协议、骑手协议、丢件理赔规则 | 账号主体与合同主体一致；协议可在下单前访问 | 配送类目、支付权限、个人信息处理边界 |
| 域名与基础设施 | 域名、HTTPS证书、服务器、数据库、备份、监控、地图与短信配置 | 备案主体一致；证书有效；备份可恢复 | 备案与审核要求按最新页面复核 |
| 源码与技术交付 | 授权类型、部署文档、运行环境、数据库、升级维护、数据导出、账号交接、故障处理 | 合同清单逐项签字；演示环境可复现 | 可修改范围、升级责任、SLA与数据归属 |
| 履约数据模型 | 学校、校区、站点、楼栋、订单号、取件码哈希、件数、状态机、交接日志 | 正常单、异常单、并发单可追溯 | 越站交接、重复取件、状态回退 |
| 资金结算 | 支付通道、分账或结算规则、退款冲回、提现审批、对账报表 | 订单金额与账务分录一致 | 退款后账单调整、提现权限 |
| 运营资源 | 驿站协议、校方许可、分拣点位、骑手实名与保险、排班、客服 | 真实楼栋走通交接链 | 丢件责任、异常转单、取件码核验 |
二、把故障定义清楚：重复取件与越站交接
代取快递的核心不是“有没有下单页”，而是一笔订单在驿站取件、校门交接、楼栋分拣、校内送达之间能否保持唯一状态。典型故障是：骑手或站点人员重复点击“完成”、支付回调重试、两个站点同时扫码，导致同一订单写两次收入，或A站订单在B站被核销。解决思路是状态机约束、幂等键、乐观锁和独立交接日志四件事一起上。
| 当前状态 | 允许动作 | 下一状态 | 约束 |
|---|---|---|---|
| CREATED | 支付成功 | PAID | 支付单号唯一 |
| PAID | 骑手接单 | ACCEPTED | 接单人与站点归属匹配 |
| ACCEPTED | 驿站取件 | PICKED_UP | 件数与取件凭据已记录 |
| PICKED_UP | 到站分拣 | SORTING | 站点与楼栋分组一致 |
| SORTING | 校内派送 | DELIVERING | 骑手与批次绑定 |
| DELIVERING | 取件码核验完成 | COMPLETED | 仅本站、仅当前版本可完成 |
| 任意履约中状态 | 异常登记 | EXCEPTION | 记录原因、责任人与下一步 |
微订骑手任务列表与校园宿舍配送组合。
数据模型与字段约束
示例使用MySQL 8.0。关键是订单号唯一、取件码只存哈希、件数有范围约束、状态用枚举收口、幂等键独立建表，账务分录与订单分离但可通过订单号核对。
CREATE TABLE parcel_order (
id BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT,
order_no VARCHAR(32) NOT NULL,
school_id BIGINT UNSIGNED NOT NULL,
station_id BIGINT UNSIGNED NOT NULL,
building_id BIGINT UNSIGNED NOT NULL,
pickup_code_hash CHAR(64) NOT NULL,
parcel_count TINYINT UNSIGNED NOT NULL,
delivery_fee_cents INT UNSIGNED NOT NULL,
status ENUM('CREATED','PAID','ACCEPTED','PICKED_UP','SORTING','DELIVERING','COMPLETED','EXCEPTION','CANCELED') NOT NULL DEFAULT 'CREATED',
version INT UNSIGNED NOT NULL DEFAULT 0,
created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
completed_at DATETIME NULL,
UNIQUE KEY uk_order_no (order_no),
KEY idx_station_status (station_id, status),
CONSTRAINT chk_parcel_count CHECK (parcel_count BETWEEN 1 AND 20),
CONSTRAINT chk_delivery_fee CHECK (delivery_fee_cents > 0)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
CREATE TABLE idempotency_record (
idem_key VARCHAR(64) PRIMARY KEY,
order_no VARCHAR(32) NOT NULL,
operator_id BIGINT UNSIGNED NOT NULL,
created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
KEY idx_idem_order (order_no)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
CREATE TABLE handover_log (
id BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT,
order_no VARCHAR(32) NOT NULL,
event_type ENUM('STATION_IN','SORTED','DELIVERED','EXCEPTION') NOT NULL,
operator_id BIGINT UNSIGNED NOT NULL,
station_id BIGINT UNSIGNED NOT NULL,
proof_object_key VARCHAR(255) NULL,
created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
KEY idx_handover_order (order_no, event_type)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
CREATE TABLE ledger_entry (
id BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT,
order_no VARCHAR(32) NOT NULL,
account_type ENUM('RIDER','PLATFORM') NOT NULL,
entry_type ENUM('DELIVERY_INCOME','REFUND_REVERSAL') NOT NULL,
amount_cents INT NOT NULL,
created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
UNIQUE KEY uk_order_account_type (order_no, account_type, entry_type),
KEY idx_ledger_order (order_no)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
核心实现：幂等、站点校验、乐观锁、账务分录
依赖环境：JDK 17、Spring Boot 3.x、spring-jdbc、mysql-connector-j、MySQL 8.0。运行步骤：1）建库并执行上述DDL；2）配置数据源和app.pickup.salt；3）启动应用；4）用下方输入调用完成交接接口；5）按输出和核对SQL检查状态、交接日志、账务分录。以下示例按本地可复现步骤编写，输出为按示例参数推导的预期结果；云上部署需另行联调。
import org.springframework.beans.factory.annotation.Value;
import org.springframework.jdbc.core.JdbcTemplate;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.util.HexFormat;
@Service
public class HandoverService {
private final JdbcTemplate jdbc;
private final String salt;
public HandoverService(JdbcTemplate jdbc, @Value("${app.pickup.salt}") String salt) {
this.jdbc = jdbc;
this.salt = salt;
}
@Transactional
public CompleteResult complete(CompleteCmd cmd) {
int inserted = jdbc.update("""
INSERT INTO idempotency_record(idem_key, order_no, operator_id, created_at)
VALUES (?, ?, ?, NOW())
ON DUPLICATE KEY UPDATE idem_key = idem_key
""", cmd.idempotencyKey(), cmd.orderNo(), cmd.operatorId());
if (inserted == 0) {
IdemRow old = jdbc.queryForObject(
"SELECT order_no, operator_id FROM idempotency_record WHERE idem_key = ?",
(rs, i) -> new IdemRow(rs.getString("order_no"), rs.getLong("operator_id")),
cmd.idempotencyKey());
if (!old.orderNo().equals(cmd.orderNo()) || old.operatorId() != cmd.operatorId()) {
throw new BusinessException("IDEMPOTENCY_KEY_REUSED");
}
return new CompleteResult("DUPLICATE", cmd.orderNo(), 0, 0);
}
OrderRow order = jdbc.query(
"SELECT order_no, station_id, pickup_code_hash, delivery_fee_cents, status, version FROM parcel_order WHERE order_no = ?",
(rs, i) -> new OrderRow(
rs.getString("order_no"),
rs.getLong("station_id"),
rs.getString("pickup_code_hash"),
rs.getInt("delivery_fee_cents"),
rs.getString("status"),
rs.getInt("version")
),
cmd.orderNo()
).stream().findFirst().orElseThrow(() -> new BusinessException("ORDER_NOT_FOUND"));
if (order.stationId() != cmd.stationId()) {
throw new BusinessException("STATION_MISMATCH");
}
if (!codeHash(cmd.pickupCode()).equals(order.pickupCodeHash())) {
throw new BusinessException("PICKUP_CODE_MISMATCH");
}
int updated = jdbc.update("""
UPDATE parcel_order
SET status = 'COMPLETED', version = version + 1, completed_at = NOW()
WHERE order_no = ? AND status = 'DELIVERING' AND version = ? AND station_id = ?
""", cmd.orderNo(), order.version(), cmd.stationId());
if (updated == 0) {
throw new BusinessException("ORDER_STATE_CONFLICT");
}
int riderCents = Math.toIntExact((long) order.deliveryFeeCents() * 80 / 100);
int platformCents = order.deliveryFeeCents() - riderCents;
jdbc.update("INSERT INTO ledger_entry(order_no, account_type, entry_type, amount_cents) VALUES (?, 'RIDER', 'DELIVERY_INCOME', ?)", cmd.orderNo(), riderCents);
jdbc.update("INSERT INTO ledger_entry(order_no, account_type, entry_type, amount_cents) VALUES (?, 'PLATFORM', 'DELIVERY_INCOME', ?)", cmd.orderNo(), platformCents);
jdbc.update("INSERT INTO handover_log(order_no, event_type, operator_id, station_id, proof_object_key) VALUES (?, 'DELIVERED', ?, ?, ?)",
cmd.orderNo(), cmd.operatorId(), cmd.stationId(), cmd.proofObjectKey());
return new CompleteResult("COMPLETED", cmd.orderNo(), riderCents, platformCents);
}
private String codeHash(String code) {
try {
MessageDigest md = MessageDigest.getInstance("SHA-256");
byte[] digest = md.digest((salt + ":" + code).getBytes(StandardCharsets.UTF_8));
return HexFormat.of().formatHex(digest);
} catch (NoSuchAlgorithmException e) {
throw new IllegalStateException(e);
}
}
}
record CompleteCmd(String orderNo, long stationId, String pickupCode, long operatorId, String idempotencyKey, String proofObjectKey) {
}
record OrderRow(String orderNo, long stationId, String pickupCodeHash, int deliveryFeeCents, String status, int version) {
}
record IdemRow(String orderNo, long operatorId) {
}
record CompleteResult(String status, String orderNo, int riderCents, int platformCents) {
}
class BusinessException extends RuntimeException {
BusinessException(String code) {
super(code); }
}
示例中的80/20仅用于演示整数拆分，真实比例、平台抽成、驿站费用和退款冲回应来自项目经营规则与支付通道约定。账务分录与订单分离，便于正常完成、退款和人工调整分别留痕。
三、正常输入输出与异常反例
示例条件：订单CD202503150001处于DELIVERING，delivery_fee_cents=500，站点ID为12，取件码为A1B2C3。正常请求如下。
{
"orderNo": "CD202503150001",
"stationId": 12,
"pickupCode": "A1B2C3",
"operatorId": 9001,
"idempotencyKey": "handover-CD202503150001-9001-01",
"proofObjectKey": "handover/2025/03/CD202503150001.jpg"
}
预期输出：订单变为COMPLETED，交接日志新增1条DELIVERED，账务分录新增2条，骑手400分、平台100分，合计500分。
{
"status": "COMPLETED",
"orderNo": "CD202503150001",
"riderCents": 400,
"platformCents": 100
}
| 场景 | 输入差异 | 预期结果 | 数据变化 |
|---|---|---|---|
| 重复提交 | 相同幂等键再次请求 | 返回DUPLICATE | 不新增账务分录和交接日志 |
| 取件码错误 | pickupCode改为X9Y8Z7 | PICKUP_CODE_MISMATCH | 事务回滚，订单仍为DELIVERING |
| 越站交接 | stationId改为13 | STATION_MISMATCH | 事务回滚，原站状态不变 |
| 并发不同幂等键 | 两个请求同时完成同一订单 | 一个COMPLETED，一个ORDER_STATE_CONFLICT | 仅一组账务分录落库 |
| 状态不符 | 订单仍为PAID | ORDER_STATE_CONFLICT | 无法越过取件、分拣环节直接完成 |
异常返回可由接口层统一映射，例如错误取件码返回：
{
"status": "REJECTED",
"code": "PICKUP_CODE_MISMATCH",
"orderNo": "CD202503150001"
}
这里的关键是：幂等键在事务内先占位，后续校验失败会随事务回滚；重复成功请求再次进入时直接返回DUPLICATE。订单完成使用版本号做条件更新，两个不同请求同时到达时只有一个能更新成功，另一个拿到ORDER_STATE_CONFLICT，从而避免重复账务。
四、业务验收、对账与部署差异
上线前按“正常单、重复单、错误码、越站、并发、退款”六类用例验收，每类记录请求参数、订单状态、交接日志、账务分录和操作人。下面两条SQL可作为账务核对的最小检查。
SELECT o.order_no, o.delivery_fee_cents, SUM(l.amount_cents) AS ledger_sum
FROM parcel_order o
JOIN ledger_entry l ON l.order_no = o.order_no
WHERE o.order_no = 'CD202503150001'
GROUP BY o.order_no, o.delivery_fee_cents;
SELECT COUNT(*) AS delivered_logs
FROM handover_log
WHERE order_no = 'CD202503150001' AND event_type = 'DELIVERED';
预期结果：ledger_sum=500，delivered_logs=1；重复提交后这两个值保持不变。若业务发生退款，应新增REFUND_REVERSAL分录并核对冲回金额，而不是修改原始完成分录。
| 部署关注点 | 本地演示 | 云上可选做法 | 核对事项 |
|---|---|---|---|
| 应用 | 本地启动jar | ECS部署，按需要配负载均衡 | 健康检查、滚动发布、日志采集 |
| 数据库 | 本地MySQL单实例 | RDS备份、参数组、连接池 | 备份恢复演练、慢查询、连接数 |
| 回调与重试 | 应用内重试或数据库轮询 | 消息队列解耦支付回调与交接通知 | 重复消费、顺序、死信处理 |
| 交接凭证 | 本地文件目录 | 对象存储保存照片或面单 | 访问控制、生命周期、脱敏 |
这些是可选的部署职责划分，不代表任何现网配置。本地演示与云环境的主要差异在网络、备份、监控、消息重试和对象存储权限；上线前应把差异项写入验收清单。准备自建系统时，先用一张订单把状态机、取件码核验、站点归属、幂等键和账务分录跑通，再扩展到多校区、驿站交接和高峰批量。下一步可带上真实楼栋、驿站交接规则、支付与结算资料，安排一次正常单、异常单和并发单演练，按输出记录核对状态、日志和账务。
微订校园小程序按地区列出学校，支持搜索并进入服务校区。
作者：微订（上海逊柯计算机科技有限公司）。
