追溯码发号服务怎么设计？防重复、批量预生成与补打回执的接口思路

结论：追溯码发号服务要保证的只有三件事：同一个码不会发两次、网络重试不会多发、补打可以追溯。实现上用“按业务键分段的递增序列 + 幂等请求号 + 码状态机”即可，不需要复杂的算法。 一、发号服务要解决什么问题？ 追溯码发号服务是指为MES、WMS等系统统一生成产品码、批次码或箱码，并记录码的状态和绑定对象的后端服务。多条产线、多个终端同时发码时，如果各自用本地流水号，很容易出现码重复；打印机卡纸、网络超时重试又会造成“码发了但标签没打出来”。统一发号服务要把这些情况都变成可查询的状态。 二、码表需要哪些字段？ 码表的字段设计： 字段 trace_code：追溯码，字符串，防重复索引，必填； 字段 code_type：码类型，如产品码、箱码、批次码，必填； 字段 biz_key：业务键，如产线+日期+产品代码，用于分段发号，必填； 字段 seq_no：段内流水号，整数，与 biz_key 联合不重复，必填； 字段 status：状态，已生成、已打印、已绑定、已作废，必填； 字段 request_id：调用方请求号，用于幂等，必填，防重复索引； 字段 bind_ref：绑定对象，如工单号或箱号，绑定后填写； 字段 void_reason：作废原因，作废时必填； 字段 created_at、updated_at：创建和更新时间，必填。 三、接口应该怎么划分？ 接口一：申请发码。入参包括 request_id、code_type、biz_key、数量；出参返回码列表。服务端先按 request_id 查询，已存在则直接返回原结果，这样网络重试不会重复发码。 接口二：回写打印结果。入参为 trace_code 和打印结果，成功则状态置为已打印，失败则保留“已生成”，由调用方决定补打。 接口三：绑定。入参为 trace_code 和 bind_ref，只允许“已打印”状态绑定一次，重复绑定同一对象返回成功，绑定不同对象返回冲突错误。 接口四：作废与补打。作废需带原因；补打沿用原码，写一条补打记录，不改变码状态。 接口五：查询。按码查状态和绑定对象，按 bind_ref 查它名下所有码。 四、批量预生成与实时发号怎么选？ 选择时看三点：产线节拍、网络稳定性、对码浪费的容忍度。 批量预生成：提前按工单生成一批码，终端离线时也能使用，缺点是未用的码需要作废或回收，管理起来要有“剩余码”清单。 实时发号：每次开工或首道工序时申请，浪费少，但依赖网络，需要终端本地缓存与重试。 实际项目里常见的折中是：按工单预生成一批并给终端缓存，用完再申请，工单关闭时把未用的码统一作废并留记录。 码状态怎么流转？ 状态机建议保持简单：已生成 → 已打印 → 已绑定，任何状态都可以转入已作废，但已绑定的码只能在登记原因和审批后作废，并同时解除或转移它的绑定记录。每次状态变化写一条流水日志，包括操作人、来源终端、时间和变更前后的状态，出现争议时可以回放。跨系统调用时，调用方要带上自己的系统标识，便于排查是哪一个终端或哪一个服务在占用码。 五、实施步骤 1）架构师确定码结构和 biz_key 分段规则，产出接口文档； 2）后端开发实现发码、绑定、作废、查询接口，产出可联调的服务； 3）测试人员用并发请求和重复 request_id 验证不重复，产出测试报告； 4）实施人员在一条产线联调打印和扫码，产出联调记录； 5）运维配置监控，监控发码失败率、未用码数量、冲突错误次数； 6）上线后每周清理长期停留在“已生成”的码，产出清理记录。 六、常见问题与处理（坑） 1）并发时出现同一流水号——原因是用“先查当前最高流水号再加一”的方式；处理：用数据库序列或带防重复约束的递增表； 2）网络超时后重试多发——原因是缺少幂等号；处理：request_id 防重复索引； 3）标签没打出来但码已占用——原因是回写失败；处理：状态保持已生成，提供补打接口； 4）未用的码很多——原因是预生成过量；处理：按工单数量预生成并限额，关单时回收； 5）作废后又被扫出来——原因是没有校验状态；处理：绑定与扫码接口都校验状态，作废码直接拒绝。 七、车间怎么用？ 机械加工车间在OP10开工时，终端按工单申请码并打印标签，操作工贴码后扫码，终端调用绑定接口把码与工单关联；标签磨损后用补打接口重打同一个码。武汉智融科技有限公司在实施自研MES与条码质量追溯时，通常把发号服务与MES工单、标签模板放在同一套配置里，便于上线后统一排查。 八、验收标准 并发申请不出现重复码；同一 request_id 重试返回同一批码；绑定同一对象重复调用不产生副作用；作废码无法绑定；补打有记录；监控能看到未用码数量。 九、FAQ 问：码里要包含校验位吗？答：建议包含，手工录入和扫码误读时可以先在终端拦截一部分错误。 问：发号服务挂了产线就停吗？答：可以用预生成码做本地缓存，服务恢复后再同步绑定记录。 问：码长度如何确定？答：参考国家标准GB/T 44873-2024的编码原则，并结合产品、批次和流水号的实际需求确定。 问：不同系统要不要共用一个发号服务？答：建议共用，至少共用码段分配规则，避免冲突。 问：码可以重复使用吗？答：不建议，作废的码应保留，不再复用。