质量追溯四类档案的数据模型与反查接口：原料、生产、检验、流向怎么关联

做质量追溯，最终要落到四个可以互查的档案：原料档案、生产档案、检验档案、流向档案。很多系统把四者做成孤立的查询，出了问题只能逐个翻记录。本文从接口与数据模型的角度，给出一个能互相反查的建模方案，以及围绕“一码到底”的反查接口设计。

一、为什么四类档案要能互查

一次客诉或不合格，通常需要回答四个问题：这批货用了哪些原料（正向追溯）；哪些批次/工单用了这块原料（反向追溯）；相关批次做过哪些检验结论；这些批次流向了哪些客户/仓库。如果四类档案各自为政，接口调用次数和跨库JOIN会成为性能与一致性的风险。

做法是把四类档案挂在同一个“追溯上下文”上，上下文由产品唯一码（SN/批次码/PCB码等）驱动，四类表通过一个共同的追溯键关联。

二、追溯上下文与主键设计

追溯上下文的载体是一个“追溯上下文实例”，每个实例绑定一个或多个业务码，四类档案通过该实例互相定位。

字段 trace_context_id：追溯上下文唯一标识，BIGINT 自增或雪花ID，四表共用的关联键。

字段 biz_code：业务码（SN/批次号/PCB码/料盘码等），VARCHAR(64)，在上下文表内唯一，外部接口以该码入参。

字段 biz_code_type：业务码类型，TINYINT 字典（10 SN，20 批次，30 PCB码，40 料盘码，50 其他），用于同一 biz_code 在不同含义下不冲突。

字段 product_code：产品料号，VARCHAR(64)，用于按料号聚合查。

字段 lot_no：批次号，VARCHAR(64)。

字段 line_no：产线号，VARCHAR(64)。

字段 context_status：上下文状态，TINYINT（10 进行中，20 已完结，30 已封存），决定后续档案能否继续写入。

字段 created_at / updated_at：时间戳，毫秒。

字段 tenant_id / factory_code：租户与工厂，用于多厂隔离。

外部系统不直接操作上下文表，而是通过“创建/查询追溯上下文”的接口间接使用 trace_context_id。

三、四类档案的字段模型

3.1 原料档案（material_archive）

字段 id：主键。

字段 trace_context_id：关联追溯上下文。

字段 biz_code：冗余记录关联的业务码，便于单码直查。

字段 material_code：来料料号，VARCHAR(64)。

字段 supplier_code：供应商编码，VARCHAR(64)。

字段 supplier_lot：供应商批次，VARCHAR(64)。

字段 incoming_lot：入库批次，VARCHAR(64)。

字段 qty：使用数量，DECIMAL(18,4)。

字段 unit：单位，VARCHAR(16)。

字段 use_start_time / use_end_time：投料起止时间，DATETIME。

字段 operator：操作人，VARCHAR(64)。

字段 station_code：工位/产线，VARCHAR(64)。

字段 iqc_status：来料检验结论，TINYINT（10 待检，20 合格，30 不合格，40 特采）。

字段 remark：备注。

3.2 生产档案（production_archive）

字段 id：主键。

字段 trace_context_id：关联追溯上下文。

字段 biz_code：冗余业务码。

字段 work_order_no：工单号，VARCHAR(64)。

字段 operation_code：工序编码，VARCHAR(64)。

字段 process_step：工序步序，INT。

字段 equipment_code：设备编码，VARCHAR(64)。

字段 start_time / end_time：工序起止时间。

字段 qty_good / qty_ng：合格数/不合格数，DECIMAL(18,4)。

字段 program_version：工艺参数/程序版本，VARCHAR(128)。

字段 cycle_time_sec：周期秒，INT。

字段 result_code：工序结果，TINYINT（10 合格，20 返工，30 报废，40 待判定）。

字段 operator / station_code。

3.3 检验档案（inspection_archive）

字段 id：主键。

字段 trace_context_id：关联追溯上下文。

字段 biz_code：冗余业务码。

字段 inspection_type：检验类型，TINYINT（10 IQC，20 IPQC，30 OQC，40 FQC，50 客诉复检）。

字段 inspection_plan_code：检验方案编码，VARCHAR(64)。

字段 sample_qty / lot_qty：抽样数/批次总数，DECIMAL(18,4)。

字段 pass_qty / fail_qty：合格/不合格数。

字段 verdict：判定结论，TINYINT（10 合格，20 不合格，30 特采，40 让步，50 待定）。

字段 defect_codes：缺陷码集合，JSON 或 VARCHAR(512)。

字段 inspector / inspection_station：检验员/站点。

字段 start_time / end_time。

字段 report_no：检验报告编号，VARCHAR(128)。

3.4 流向档案（flow_archive）

字段 id：主键。

字段 trace_context_id：关联追溯上下文。

字段 biz_code：冗余业务码。

字段 out_type：出库类型，TINYINT（10 成品入库，20 发货，30 客户收货，40 退货，50 报废出库）。

字段 target_type：去向类型，TINYINT（10 仓库，20 客户，30 经销商，40 内部调拨）。

字段 target_code：去向编码，VARCHAR(64)（仓库号/客户编码等）。

字段 target_name：去向名称，VARCHAR(128)。

字段 out_qty / in_qty：出/入数量，DECIMAL(18,4)。

字段 container_code：容器/托盘/箱码，VARCHAR(64)。

字段 out_time：出库时间。

字段 ship_no / receipt_no：发运单号/收货单号，VARCHAR(128)。

字段 region_code：地区编码，VARCHAR(32)。

四、反查接口设计

四类档案建好后，关键是用一套反查接口把“正向追溯”和“反向追溯”跑通。所有反查接口共享入参风格，返回都包含四类摘要。

4.1 正向追溯：给定一个 biz_code，查四档

接口 POST /api/trace/forward

入参：

字段 biz_code：业务码，必填。

字段 biz_code_type：业务码类型，选填，不传时按默认 SN 解析。

字段 scope：返回范围，enum（all / material / production / inspection / flow），默认 all。

字段 time_from / time_to：时间窗口。

返回：

字段 code / message：通用响应。

字段 data.context：追溯上下文摘要（product_code、lot_no、line_no、context_status）。

字段 data.material_list：原料档案列表，含 material_code、supplier_lot、incoming_lot、qty、use_start_time、iqc_status。

字段 data.production_list：生产档案列表，含 work_order_no、operation_code、start_time、result_code。

字段 data.inspection_list：检验档案列表，含 inspection_type、verdict、defect_codes、report_no。

字段 data.flow_list：流向档案列表，含 out_type、target_type、target_code、target_name、out_time、ship_no。

字段 data.next_biz_codes：由本业务码衍生出的下游业务码列表，每个元素含 child_biz_code、child_type、relation_type（如 parent_child / rework / split）。

4.2 反向追溯：给定原料批次，查受影响范围

接口 POST /api/trace/backward

入参：

字段 source_type：源头类型，enum（supplier_lot / incoming_lot / material_code / defect_code / verdict）。

字段 source_value：源头值。

字段 material_code：当 source_type 为 supplier_lot/incoming_lot 时选填，用于限定料号。

字段 time_from / time_to。

返回：

字段 data.affected_context_ids：受影响的追溯上下文 ID 列表。

字段 data.affected_biz_codes：受影响业务码列表，每个元素含 biz_code、biz_code_type、product_code、current_stage。

字段 data.outbound_summary：已外发摘要，按 target_code 分组的出库数量与时间。

字段 data.recommend_actions：建议动作，enum 列表（hold_shipment / quarantine / inspect / recall），仅建议，由业务侧执行。

4.3 按维度聚合反查

接口 GET /api/trace/aggregation

入参：

字段 dim：维度，enum（material_code / supplier_code / operation_code / defect_code / target_code / verdict）。

字段 dim_value。

字段 time_from / time_to。

返回：

字段 data.total_contexts：关联上下文数。

字段 data.total_qty：涉及数量。

字段 data.verdict_distribution：按判定结论分布。

字段 data.top_defects：缺陷码 Top N。

字段 data.outbound_targets：去向 Top N。

4.4 分页与耗时验收

反查接口必须支持分页，返回里加字段 total、page、page_size、has_more；单次返回建议 ≤ 1000 条。接口 SLA 建议：正向单次上下文追溯 p95 ≤ 800ms（四表 JOIN 走 trace_context_id 索引），反向跨上下文追溯 p95 ≤ 3s，聚合接口 p95 ≤ 2s。超过阈值应降级为异步任务并返回 task_id，由查询进度接口拉取。

五、索引与查询建议

trace_context_id 在四表上都要建索引，并与 biz_code 组成复合索引 (biz_code, biz_code_type, trace_context_id)，确保单码直查不走全文扫描。反向追溯的常用入口（supplier_lot、incoming_lot、defect_codes、verdict、target_code）各自建索引；defect_codes 若用 JSON，用函数索引或生成列。

正向追溯查询走"biz_code → trace_context_id → 四表 UNION"；反向追溯走"入口索引 → trace_context_id 集合 → 四表"。

六、与上下游系统的对接点

ERP/WMS 原料入库与成品出库时写 material_archive 与 flow_archive，入参必须携带 incoming_lot / target_code / out_time。检验系统把 verdict、defect_codes、report_no 写回 inspection_archive，接口要求带 trace_context_id。设备/SCADA 工序结果落 production_archive，program_version 与 cycle_time_sec 用于工艺追溯。WMS/发运把 container_code、ship_no 进入 flow_archive，便于按箱/托盘召回。对接时统一使用"带 trace_context_id 的写入接口"，下游只查。

七、常见问题

Q：biz_code 在不同产线会重复怎么办？A：用 (biz_code, biz_code_type, tenant_id/factory_code) 做联合唯一，上下文实例隔离不同产线/租户的同码。

Q：返工/重工后产生新 SN，关系怎么记？A：在上下文表或单独的 relation 边表记 parent_biz_code → child_biz_code 的 relation_type（rework/split/merge），正向接口通过 next_biz_codes 返回。

Q：聚合接口要不要做缓存？A：只读聚合建议加缓存，key 包含 (dim, dim_value, time_from, time_to, 租户)，TTL 5–15 分钟；写入时删除涉及 dim 的缓存。

Q：历史数据怎么补？A：补录脚本按 biz_code 重建 trace_context_id，四类表逐条写入，补完后跑一次反向接口校验 affected_context_ids 数量是否符合预期。