条码扫描事件表的字段设计与去重幂等

在条码质量追溯与电子MES场景中，扫码枪、PDA和固定读码器每秒钟都会往系统投递扫描事件。事件流一旦进入平台，字段怎么定、重复怎么判、幂等怎么做，直接决定追溯链条能不能闭环。本文将条码扫描事件表拆成"业务字段、设备上下文、幂等控制"三层，并给出在接口层实现去重幂等的落地做法，方便做MES与追溯平台对接时直接复用。

一、条码扫描事件要承载什么

一次有效的条码扫描，业务侧最少要回答四个问题：谁扫的、扫了什么、在哪里扫、结果如何。设备侧还需要记录枪或读码器型号、会话和采集时间，以便后续做数据质量分析与现场排查。把这两类诉求拆开，事件表就不会因为不断加字段而变成一张宽而乱的流水表。

二、业务字段层

业务字段回答追溯问题，按"对象、动作、结果"三组来组织。

对象组描述被扫的载体与内容。scan_barcode 记录条码原始字符串，包含前导零与分隔符；barcode_type 记录码制类型，常见值为一维码、二维码、DataMatrix、QR、ITF-14 等。bind_sn 记录该条码在系统中解析后绑定的序列号或物料编码，bind_lot 记录绑定的批次号，bind_station 记录绑定的工位或工序编号。对象组里不建议把业务含义写死在列名中；例如不要把"产品码"和"箱码"拆成两列，而是统一进 scan_barcode，由 bind_sn 和 bind_lot 表达归属。

动作组描述发生了什么。scan_action 记录动作类型，典型值有入料、领料、过站、完工、返工、报废、复检、拆箱、合箱。action_source 记录动作来源，用于区分人工扫码、设备自动采集、系统回写与手工补录。

结果组描述系统判定。scan_result 是扫描校验结果，典型值为合格、不合格、待判定、条码不存在、条码已绑定其他工单、重复扫描。result_code 与 result_message 记录校验子码与一句话原因，例如 result_code=ALREADY_BOUND 时 result_message 写明冲突的工单号与 SN，方便前端直接展示而不需要二次查询。

三、设备上下文层

设备上下文不参与业务校验，但决定排障效率。device_id 记录采集设备标识，如 PDA 序列号或固定读码器 IP 加端口。device_type 记录设备形态，如手持 PDA、固定读码器、工业相机。scan_session_id 记录一次连续采集的会话标识，同一个会话内的连续多次扫描在展示时可以按会话折叠。operator_id 与 operator_name 记录当前操作员账号与姓名。site_id、workshop_id、line_id、station_id 四级站点标识把扫描位置钉到工厂、车间、产线、工位。capture_time 记录设备端或接入代理捕获的原始时间，event_time 记录平台落库时间，两列分开便于做时钟漂移分析。

四、幂等控制层

现场网络抖动、扫码枪重发、MQ 重试都会让同一次扫描在接口侧出现多次。幂等控制的核心是：用业务可解释的键做判重，不依赖消息中间件自身的去重。

idempotency_key 是幂等键。它的值由调用方生成并在重传时保持不变，生成策略有两种。策略一是设备侧生成 UUID，写入 PDA 本地日志，重传时带上同一值；策略二是服务端根据业务键推导，例如 device_id 加 capture_time（秒级）加 scan_barcode 加 scan_action 做哈希，适合老设备无法生成唯一值的场景。两种策略可以并存：接口优先使用客户端传入的 idempotency_key，缺失时再按服务端策略派生。

dedup_status 记录去重判定结果，值包括 accepted（首次接收）、duplicate（重复已忽略）、conflict（与已有记录冲突，需人工介入）。processing_status 记录事件在流水中的处理阶段，值包括 received、validating、bound、completed、failed，与业务结果解耦，方便做流水线排障。

created_by、updated_by 记录数据变更归属，created_at、updated_at 使用数据库时间。

五、索引与查询习惯

事件表的增长速度远高于普通业务表，索引策略直接影响追溯查询的响应时间。主键使用自增或雪花 ID；按追溯场景加三组查询索引。按 SN 反查用 bind_sn 与 event_time 联合索引；按批次与工位统计用 bind_lot 与 station_id 与 event_time；按设备与时间段做采集质量分析用 device_id 与 capture_time。idempotency_key 需要唯一索引支撑幂等判定。分区或分表按 event_time 月分区，单月数据量预估后决定是否切到周分区。

避免在 scan_barcode 和 result_message 这类长文本字段上建索引或做前缀模糊查询，这类查询应通过 bind_sn、bind_lot、scan_result、result_code 完成。

六、接口层去重幂等的落地做法

接口层通常有两种形态：HTTP REST 接收网关和消息队列消费端。两种形态的幂等做法可以统一成"先判后写"。

REST 接口做法。在请求头约定一个幂等键头，例如 X-Idempotency-Key。网关收到请求后，先以 idempotency_key 为键在幂等记录缓存中做查询；命中则直接返回上次保存的响应体与状态码，不进入业务逻辑。未命中则生成一个占位标记，状态为 received，把请求交给下游处理；下游处理完成后，把响应体写回幂等记录缓存并设置过期时间。过期时间需要大于现场最大的重传间隔，通常设 24 小时到 7 天，视业务容忍度而定。占位标记要支持 CAS 写入：并发重传在同一毫秒到达时，只有一个写入成功，另一个读到占位后走"重复"分支返回。

消息队列消费端做法。MQ 本身的重投机制不能保证严格一次，消费端需要在本地维护幂等键集合。小窗口场景可以用 Redis 的 SETNX 或 Lua 脚本做原子判重，键为 idempotency_key，值为事件摘要与响应状态。大窗口或需要持久化的场景，把幂等记录落到数据库的幂等表：主键为 idempotency_key，字段包含响应体快照、状态码、落库时间、过期时间；定时任务清理过期记录。消费端处理完一条消息后，先写幂等记录，再确认消息；如果写幂等记录失败，不确认，让 MQ 重投后由幂等键拦截。

两种形态的公共约束：返回给调用方的响应必须稳定。同一 idempotency_key 的多次请求，返回的事件 ID、scan_result、result_code 必须相同，否则调用方无法判断是否该重传。建议把事件侧的主键 ID 在首次写入时就回填到幂等记录中，后续重复请求直接返回该 ID。

七、典型现场问题与对策

时钟不一致是幂等最常见问题之一。PDA、读码器、网关和数据库时钟可能差几十秒到几分钟。对策是把 capture_time 和 event_time 两列同时保留，幂等键中的时间使用 capture_time 并对秒做截断或对齐到设备上报的时钟精度，而不是依赖服务端 event_time。

条码值大小写与前后空格会导致"同一扫描被判为不同"。对策是在接口入口处统一做规范：去掉前后空白、统一大小写、去掉一维码校验位后再拼入业务键。但 scan_barcode 原始列必须保留未清洗的原始值，用于事后核对。

高并发工位同时扫同一物料，例如合箱工序多把枪同时扫同一个箱码。这时 device_id 加 capture_time 加 scan_barcode 加 scan_action 组成的幂等键仍然能区分不同枪的不同扫描，不会被错误合并。如果业务语义要求"同一箱在同一秒只记录一次"，需要由业务规则层额外做窗口聚合，而不是交给幂等键。

MQ 消费端出现"丢一批又重投一批"的半重复。对策是在消费端对同一 idempotency_key 的重复次数做计数与告警；重复次数超过阈值（例如 5 次每小时）时，把 dedup_status 切为 conflict 并推人工工单，而不是无限忽略。

八、小结

条码扫描事件表的设计，本质是在"追溯要查什么"和"现场会重发什么"之间做取舍。业务字段按对象、动作、结果三组收敛，设备上下文单独一层，幂等用可解释的键在接口层先判后写，这套结构在条码质量追溯、SMT 过站与 MES 对接中都能复用。接口侧把响应写稳、时钟拿齐、原始值留好，重复扫描就不会变成追溯断点。

如果需要更细的对接约定，下一步可以把 idempotency_key 的生成规则、接口入参校验清单与幂等缓存的容量预算整理成一份对接 CheckList，和调用方一起评审。