首页
学习
活动
专区
圈层
工具
发布
社区首页 >专栏 >酒水溯源的首尾码区间入库:编码模型、并发控制与幂等设计

酒水溯源的首尾码区间入库:编码模型、并发控制与幂等设计

原创
作者头像
用户4575637
发布于 2026-11-17 15:57:39
发布于 2026-11-17 15:57:39
210
举报

酒水溯源的首尾码区间入库:编码模型、并发控制与幂等设计

整箱酒入库时,仓库人员通常不会逐瓶扫码。操作方式是扫箱外首码与尾码,系统按区间推断中间所有瓶码。这个交互看起来只是一次范围输入,落到存储层却牵出三个问题:区间如何表示、并发入库如何避免重叠、重复提交如何保证幂等。

本文以酒水流通场景为例,拆解首尾码区间入库的数据模型与工程实现。

一、业务约束

先列出约束,后面的数据模型、索引与接口都围绕它们设计。

  • 一批货可能分多次到库,同一区间的不同片段要能分别登记。
  • 名酒按单瓶管理,非名酒按区间管理,两种模式共存于同一套码表。
  • 入库、调拨、销售、退货都会产生状态变更,每次变更要能定位到具体一瓶。
  • 离线仓库端可能断网,恢复后需要补传,不能重复计入库存。

第二条决定了不能用单一模型硬套。名酒单瓶登记的粒度是瓶,非名酒区间的粒度是段,二者在查询层统一,在存储层分开。

二、码空间与区间表示

把码值抽象成可比较的整数,而不是字符串。字符串比较在跨前缀、变长编码时会出现"10"排在"9"前面的问题,区间判断会直接失效。

代码语言:sql
复制
CREATE TABLE trace_code_range (
  id           BIGINT      NOT NULL AUTO_INCREMENT,
  tenant_id    BIGINT      NOT NULL,
  batch_id     VARCHAR(40) NOT NULL,
  sku_id       BIGINT      NOT NULL,
  code_start   BIGINT      NOT NULL,
  code_end     BIGINT      NOT NULL,
  qty          INT         NOT NULL,
  warehouse_id BIGINT      NOT NULL,
  status       TINYINT     NOT NULL,   -- 1 待入库 2 已入库 3 已出库 4 已冻结
  created_at   TIMESTAMP(3) NOT NULL,
  PRIMARY KEY (id),
  KEY idx_sku_range (tenant_id, sku_id, code_start, code_end),
  KEY idx_batch (tenant_id, batch_id)
);

qty 不靠 code_end - code_start + 1 实时计算,而是在写入时落库。原因有两个:部分码段存在跳号,算术结果不可信;盘点时需要对数量做快照,实时计算会让历史单据随数据变化而漂移。

区间重叠检测是写入前的必经步骤。用一条范围查询判断是否已存在交集:

代码语言:sql
复制
SELECT id, code_start, code_end
FROM trace_code_range
WHERE tenant_id = ?
  AND sku_id = ?
  AND code_start <= ?
  AND code_end >= ?
LIMIT 1;

参数依次是租户、商品、新区间尾码、新区间首码。命中即说明有交集,直接拒绝并返回冲突区间,让仓库端确认是否为重复扫码。

三、并发控制

两个仓库同时入库同一批货是常态,仅靠先查后插会产生竞态。这里用三层防护。

第一层是数据库唯一约束。对 (tenant_id, batch_id, code_start) 建唯一索引,重复提交在写入时直接失败,不依赖应用层判断。

第二层是行级锁。冲突检测与插入放在同一事务内,对命中的区间行加 FOR UPDATE,把并发写串行化到同一商品维度。

代码语言:sql
复制
START TRANSACTION;
SELECT id FROM trace_code_range
 WHERE tenant_id = ? AND sku_id = ?
   AND code_start <= ? AND code_end >= ?
 FOR UPDATE;
-- 无交集则插入
INSERT INTO trace_code_range (...) VALUES (...);
COMMIT;

第三层是应用层令牌。仓库端每次提交携带客户端生成的 request_id,服务端以 request_id 做短期去重,网络重试不会产生第二条记录。

三层防护的职责不同:唯一约束兜底,行锁处理正常并发,令牌处理重试。缺任何一层都会在特定场景下漏掉。

四、幂等与分段提交

一次入库可能涉及上千个区间。整批放在一个事务里,锁持有时间长,失败后全部回滚,仓库端要重新扫一遍。更稳妥的做法是按商品分段提交,每段独立事务。

代码语言:python
复制
def import_ranges(batch_id, ranges, chunk_size=100):
    results = []
    for chunk in chunks(ranges, chunk_size):
        with transaction() as tx:
            if seen_request(tx, batch_id, chunk.key):
                results.append(("skipped", chunk.key))
                continue
            if has_overlap(tx, chunk):
                results.append(("conflict", chunk.key))
                continue
            insert_ranges(tx, chunk)
            mark_request(tx, batch_id, chunk.key)
            results.append(("ok", chunk.key))
    return results

分段带来一个新的问题:部分成功。接口必须返回逐段结果,而不是笼统的成功或失败。仓库端据此只重扫失败段,已成功的段不再重复提交。skipped 与 ok 要分开返回,否则前端无法判断是重复提交还是首次写入。

五、单瓶映射与按需展开

区间存储节省空间,但消费者扫码查询的是单瓶。两种做法:写入时展开全部瓶码,或查询时按区间反解。

展开的优点是查询简单,缺点是存储放大。一个百万瓶的批次会生成百万行,索引维护成本高。反解的做法是保留区间,查询时用码值定位区间,再判断该瓶是否已单独登记状态。

代码语言:sql
复制
SELECT r.id, r.batch_id, r.status,
       b.production_date, b.ocr_confidence
FROM trace_code_range r
JOIN trace_batch b ON b.batch_id = r.batch_id
WHERE r.tenant_id = ?
  AND r.sku_id = ?
  AND r.code_start <= ?
  AND r.code_end >= ?;

单瓶级的状态变更(例如名酒的销售登记)单独写入 trace_code_item 表,区间表只保存整体状态。查询时先查单瓶表,未命中再回落到区间状态。这样常见路径(未拆零的非名酒)不产生额外写入,名酒的精确追溯也不受影响。

六、OCR 与批次信息

生产日期与批次号通常印在箱体上,靠人工输入错误率高。拍照识别作为辅助手段,识别结果带置信度入库。

代码语言:json
复制
{
  "batch_no": "20260912-A3",
  "production_date": "2026-09-12",
  "ocr_confidence": 0.94,
  "need_review": false
}

置信度低于阈值的记录进入复核队列,而不是直接拒绝。仓库现场光线差、箱体磨损都会拉低识别率,直接拒绝会让操作员反复重拍,整体效率反而下降。复核队列的设计要点是把"机器不确定"与"人输入错误"分开统计,前者优化模型,后者优化表单。

七、离线补传

仓库端在断网时把扫码记录写入本地队列,恢复后按顺序补传。补传接口必须与在线接口共用同一套幂等逻辑,否则离线重放会产生重复库存。

队列记录要带客户端时间与服务端接收时间两个字段。客户端时间用于业务排序,服务端时间用于审计、限流与日志排序。只保留一个时间,后续排查"为什么这批货显示晚到"时会缺少依据。

八、取舍

这套方案的核心取舍是"区间为主、单瓶为辅"。

区间模型让非名酒的入库吞吐大幅提高,代价是单瓶查询需要多一次反解;单瓶表让名酒的追溯足够精确,代价是写入路径分叉。两条路径在查询层合并,业务方不需要感知差异。

另一处取舍是分段提交。它牺牲了整批事务的原子性,换来失败可恢复与锁持有时间可控。对于仓库这种以"扫完即走"为目标的场景,部分成功并明确告知,比整批回滚更符合实际操作习惯。

在酒水连锁与名酒经销商的落地中,这套区间与单瓶并存的模型被用于微步溯源防伪系统的入库模块,主要收益来自重复扫码拦截与离线补传的可靠性,而不是单纯的功能数量。

九、小结

首尾码区间入库不是一个前端交互问题,而是码空间建模、并发控制、幂等设计与查询策略的组合。把区间当一等公民、把单瓶当补充,再把分段提交与逐段结果做扎实,系统才能在多仓库、弱网络、高并发的现场稳定运行。

原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。

如有侵权,请联系 cloudcommunity@tencent.com 删除。

目录
  • 酒水溯源的首尾码区间入库:编码模型、并发控制与幂等设计
    • 一、业务约束
    • 二、码空间与区间表示
    • 三、并发控制
    • 四、幂等与分段提交
    • 五、单瓶映射与按需展开
    • 六、OCR 与批次信息
    • 七、离线补传
    • 八、取舍
    • 九、小结
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档