批次+序列号父子码的数据模型与组装绑定接口

批次与序列号并行存在时，产线会同时产出两类标识：一批原料共用一个批号，关键件/整机又各自打 SN。到组装段，系统要回答"这台成品里，哪几个 SN 绑了进来，它们各自来自哪个批"。父子码数据模型与组装绑定接口，就是围绕这条追溯链设计的。 一、结论先行 - 批次与序列号不是"二选一"，数据模型必须允许同一物料实例同时拥有 lot/batch 与 serial_no，并通过一个统一的物料实例表做关联，而不是在 BOM 或工单表里各记一套。 - 组装绑定接口的幂等应落在"父 SN + 子位号 + 子 SN"三元组上，避免同一工位重复扫码导致 BOM 实例重复挂子件。 - 绑定接口返回要携带子件追溯链（子 SN → 子批号 → 子物料编码），组装段才能把纸质批次报告与系统追溯对齐。 二、业务场景与追溯要求 离散制造中，批次用于"同炉/同罐/同车"的群体追溯，序列号用于单件精准定位。组装段常见做法是：关键件打 SN、辅材/包材只用批号、整机打最终 SN。追溯链要求覆盖三层： - 成品 SN → 直配子件 SN 或批号（装配层级）。 - 子件 SN → 子件自身所属批号与来料检验批。 - 子件批号 → 供应商来料批、检验结果与放行状态。 接口与模型设计的约束由此而来：必须能在一条查询里从成品 SN 拉到供应商来料批，同时不能因为某层只用批号就把追溯链截断。 三、核心实体与字段 围绕追溯链，建议的最小模型是"物料实例 + 父子关系 + 组装绑定"三张表，用"字段 xx：说明"列出关键字段，不用表格。 1）物料实例表 material_instance - 字段 instance_id：主键，雪花/UUID。 - 字段 item_code：物料编码，指向物料主数据。 - 字段 lot_no：批次号，同一批内多个实例共享。 - 字段 serial_no：序列号，唯一索引；未打码的物料可为空。 - 字段 instance_type：枚举 SINGLE（单件带 SN）/ BATCH（仅批号的一批）/ SPLIT（从一批拆分出的子实例），决定后续是按 SN 还是按批操作。 - 字段 quantity：数量，SINGLE 为 1，BATCH/SPLIT 为实际数量。 - 字段 parent_lot_no：父批号，记录拆分来源（SPLIT 时有值）。 - 字段 parent_instance_id：父实例外键，拆分/子包装溯源。 - 字段 supplier_lot_no：供应商来料批号。 - 字段 receive_batch_no：厂内收料批号。 - 字段 qc_status：检验状态，枚举 OK / NG / HOLD / EXEMPT。 - 字段 released_at：放行时间，放行前的实例不可进入合格绑定。 - 字段 created_at / updated_at：审计时间。 2）父子码关系表 parent_child_link - 字段 id：主键。 - 字段 parent_item_code：父物料编码。 - 字段 parent_serial_no：父序列号，成品或父级组件的 SN。 - 字段 parent_lot_no：父批号，父级仅用批时的标识。 - 字段 child_item_code：子物料编码。 - 字段 child_serial_no：子序列号。 - 字段 child_lot_no：子批号。 - 字段 child_instance_id：子物料实例外键，关联 material_instance 获取批次/检验/来源。 - 字段 link_type：枚举 ASSEMBLY（装配绑定）/ SPLIT（拆分）/ REPACK（重包装）/ REWORK（返工替换）。 - 字段 source_doc_no：来源单据号（工单、组装报告、返工单）。 - 字段 source_doc_type：单据类型。 - 字段 created_at：建链时间。 3）组装绑定记录表 assembly_bind_record - 字段 id：主键。 - 字段 parent_serial_no：父件 SN（整机 SN）。 - 字段 station_code：绑定发生工位。 - 字段 position_code：BOM 位号，标识"装在哪"。 - 字段 child_instance_id：子物料实例外键。 - 字段 child_serial_no：子 SN，冗余方便查询。 - 字段 child_lot_no：子批号，冗余。 - 字段 child_item_code：子物料编码。 - 字段 bind_type：枚举 STANDARD（标准装配）/ SUBSTITUTION（替代料）/ REWORK_REPLACE（返工替换）。 - 字段 operator：操作员。 - 字段 bind_time：绑定时间。 - 字段 idempotency_key：客户端幂等键。 - 字段 unique_key：父 SN + position_code + 子 SN 的拼接/哈希，唯一索引。 - 字段 status：绑定状态，ACTIVE / VOID（取消/退料作废）。 - 字段 version：乐观锁版本号。 四、组装绑定接口设计 组装扫码枪在工位上报"父 SN + 位号 + 子件扫码结果"，接口将扫码结果解析为子物料实例，落 parent_child_link 与 assembly_bind_record，并更新父件的已装计数。 1）请求契约 - 方法 POST，路径 /api/assembly/bind。 - 幂等键由终端生成，服务端按 unique_key 排重。 入参字段： - 字段 parent_serial_no：父件序列号（整机 SN）。 - 字段 station_code：工位编码。 - 字段 position_code：BOM 位号，决定装哪个位置。 - 字段 scanned_value：扫码枪原始值，可能是 SN、批号或托盘码。 - 字段 scan_type：扫码值类型，枚举 SERIAL / LOT / TRAY，服务端据此路由查 material_instance。 - 字段 bind_type：绑定类型 STANDARD / SUBSTITUTION / REWORK_REPLACE。 - 字段 operator：操作员编号。 - 字段 scanner_id：终端编号。 - 字段 idempotency_key：客户端幂等键。 - 字段 source_doc_no：组装报告/工单号。 2）服务端处理流程 - 校验父 SN 存在且对应工单/装配任务处于可绑定状态（如 ASSEMBLING，已关闭的成品不可再加子件）。 - 按 scanned_value + scan_type 定位子物料实例：SERIAL 查 serial_no 唯一索引；LOT 查 lot_no 并校验数量与 qc_status（未放行/NG 拒绝绑定）；TRAY 展开托盘-子件映射。 - 若 scan_type=LOT 且该批在 material_instance 中有多个可用实例，取 FIFO/最近放行的一行，并在返回中显式告知被绑的是哪个 instance_id 与剩余数量，让现场知道批内余量。 - 按 unique_key = parent_serial_no + position_code + 子 serial_no（若子无 SN，则用子 instance_id 替代）排重：命中则返回 idempotent=true 及该条绑定现状；未命中则写入 assembly_bind_record 与 parent_child_link。 - 位号容量校验：同一父 SN 的同一 position_code 若 BOM 定义只装 1 个子件，且已有 ACTIVE 绑定，拒绝第二条 STANDARD 绑定；REWORK_REPLACE 类型允许先 void 旧绑定再写新绑定。 3）返回结构 - 成功非幂等：返回新绑定的 bind_record_id、parent_serial_no、position_code、child_serial_no、child_lot_no、child_item_code、child_instance_id、child 追溯链（supplier_lot_no / receive_batch_no / qc_status）。 - 幂等命中：idempotent=true，返回被命中的 bind_record_id 与当前 status；不重复挂子件。 - 异常：4xx 标明原因（父 SN 不存在/不可绑定、子件未放行、位号已满、scan_type 与扫码值类型不匹配），客户端不应重试。 4）取消/退料接口 - POST /api/assembly/bind/void，入参 parent_serial_no + position_code + child_instance_id（或 child_serial_no）+ operator + void_reason。 - 将对应 assembly_bind_record 标记 status=VOID，不物理删除；parent_child_link 侧新增 link_type 为 UNBIND 的记录保留审计。已 void 的位号可被后续绑定重新占用。 五、批次拆合与父子码衍生关系 一批原料上线后被拆给多条工单，或几个小批合并成一托供线，都会改变"批 ↔ 实例"的对应关系。数据模型上通过 material_instance 的 parent_instance_id / parent_lot_no 与 link_type=SPLIT/REPACK 承载，组装绑定接口不直接处理拆合，只消费拆分后的实例。 拆分/合并时的接口建议（与组装绑定解耦）： - POST /api/material/split-lot，入参 parent_lot_no + split_out[]（子 lot_no + quantity + destination，destination 可关联到具体工单/托盘）+ operator。 - 产出若干 instance_type=SPLIT 的新 material_instance 行，parent_lot_no 指向原批；原 batch 实例的 quantity 相应扣减。 - 组装绑定接口只接收拆分后子实例对应的 SN/LOT，不会把整批一次性绑到一个位号上，从而避免"位号挂了整批、实际只用了其中几颗"的追溯失真。 六、查询与追溯接口 追溯是组装绑定的对向使用场景。建议提供一条"从成品 SN 展开追溯树"的查询接口，而不是让前端拼多表。 GET /api/trace/tree?parent_serial_no={}&depth={}&expand_lot=true - 返回以成品 SN 为根的树，每一层列出 child_item_code、child_serial_no（有则展示）、child_lot_no、position_code、bind_type、qc_status、supplier_lot_no。 - depth 控制展开层数，防止 BOM 很深时返回爆炸。 - expand_lot=true 时，遇到仅批号的节点展开其 material_instance 的 supplier_lot_no 与 receive_batch_no，保持追溯链不断。 七、常见坑 - 把批号和 SN 当成互斥字段：关键件既有批号（来料）又有 SN（赋码），字段设计成二选一会导致其中一层追溯丢失。material_instance 里 lot_no 和 serial_no 都保留，实例类型区分用法。 - 绑定幂等只用请求时间戳：同一位号被两把枪几乎同时扫入不同子件（替代料场景），时间戳相同但子件不同，按时间戳去重会吞掉替代料绑定。unique_key 必须包含 position_code 与子件标识。 - 位号重复绑定不拦截：BOM 定义一个位置只装 1 颗，接口不校验就会挂出 2 颗，追溯树出现"一个位号两个子件"的歧义。装配容量校验要在绑定前做。 - 批绑定不指定实例：scan_type=LOT 时直接拿 lot_no 绑，批内实际装了几颗、剩余多少全不清楚。绑定接口必须落到一个具体 material_instance，返回中携带该实例的余量。 - void 绑定直接删记录：质量审计需要看到"装过、退过、再装过"的完整序列。void 走状态翻牌+反向审计行，不删。 - 拆分只改数量不改关联：批拆分后仍用原 lot_no 查询，会把已拆给 A 工单的那部分也绑到 B 工单。拆分必须产出独立实例，绑定消费子实例。 八、小结 批次与序列号并行不是数据冗余，而是两把尺子：批号量群体，SN 量单件。父子码模型用 material_instance + parent_child_link 把两把尺子缝在一起，组装绑定接口在"父 SN + 位号 + 子实例"的三元组上幂等，返回完整的子件追溯链。拆合走独立的实例拆分接口，绑定只消费拆分后的子实例，追溯树从成品 SN 一路拉到供应商来料批不断链。