MES报工与追溯反查接口怎么设计？分页、幂等与耗时验收

产线上报工（工序完工、流转到下道工序）不只是记一个数量，还牵到工单完成、在制品位置变更、追溯链更新。很多工厂的 MES 报工接口一开始只做了能存就行，等要按单板反查、按设备反查、按时间窗反查时，才发现分页没做好、重试会重复报工、大时间窗查询直接把库拖慢。把报工和追溯反查作为一组接口来设计，分页、幂等、耗时三项在接口层面就能验收，后面再加分析也不需要返工。

一、报工与追溯反查的职责划分

报工接口负责一件事：把一次报工动作落库，并同步更新工单进度与追溯关系。它不返回追溯明细，也不做统计。

追溯反查接口负责另一件事：给定一个维度（单板码、料盘码、设备号、时间窗等），返回相关报工行与上下游关系。它不改数据，只做只读聚合。

把两者拆开后，报工的幂等好做，反查的索引好建，耗时也好单独压测。合在一起往往会变成一个大事务加一个大查询，两项都顾不好。

二、报工接口设计

接口路径：POST /mes/reporting。

入参至少包含：report_no（客户端或网关生成的报工流水号，用作幂等键）、work_order_no（工单号）、operation_seq（工序序号）、serial_no 或 batch_no（单板码或批次号二选一）、product_code、equipment_no、report_qty、report_status（PASS / NG / REWORK 之一）、operator、report_time。

可选：ng_reason_code、ng_desc、ref_scan_nos（本次报工关联的扫码流水号列表）。

出参：report_no、id、status（ACCEPTED / DUPLICATE / REJECTED）、result_code、report_time_server（服务器认定的报工时间）、work_order_remaining_qty。

幂等机制：幂等键为 report_no，建唯一索引。重复提交返回 DUPLICATE 以及首次报工的 id 与 report_time_server，不新增。客户端用 report_no 做去重，网关也可在报工入口接一层五分钟窗口内的短幂等，减少落库冲突。report_status 一旦 ACCEPTED 不允许通过报工接口改为 NG，变更走单独的结果修正接口，带审批。

校验：工单与工序是否存在、是否已关闭。该工序剩余应报数量是否足够（防超报），可配阈值，严格模式超零即拒，宽松模式允许正负容差并在 result_code 里返回 OVER_REPORT。设备与产品或程序的匹配：equipment_no 当前程序是否允许报该产品。report_time 与服务器时间偏差过大时，以服务器时间为准并记录 WARN_TIME_DRIFT。

三、追溯反查接口设计

通用查询：GET /mes/reporting/trace，参数 dimension 等于 SERIAL / BATCH / REEL / EQUIPMENT / OPERATOR / WORK_ORDER 之一，value 为对应取值，page、size、sort_by 等于 report_time、sort_dir 等于 ASC。

返回结构：total 为该维度下匹配总行数，page、size、pages，行列表每行含 report_no、work_order_no、operation_seq、serial_no 或 batch_no、product_code、equipment_no、report_qty、report_status、operator、report_time、ng_reason_code。

上下游反查：GET /mes/reporting/trace/upstream 与 GET /mes/reporting/trace/downstream，参数 serial_no 加分页。upstream 返回该单板在此工序之前的报工行，按 operation_seq 倒序到 1。downstream 返回后续工序行。两者共享同一种分页壳，前端可复用组件。

时间窗聚合：GET /mes/reporting/trace/by-window，参数 equipment_no、from_time、to_time、group_by 等于 operation_seq 和分页。返回按 operation_seq 分组后的数量合计、PASS 与 NG 拆分，以及原始明细的分页入口。size 上限建议 200，总拉取量由客户端按页累积。

四、分页规范

统一用 page 加 size，不混用游标与偏移。

必须返回 total。total 为零时 pages 为零，不返回 pages 等于一的空数组。

排序必须确定：sort_by 加 sort_dir 为必填，默认 sort_by 等于 report_time、sort_dir 等于 ASC。

深翻页用基于排序键的键集分页：查询改写为报工时间大于上一页最后时间且工序序号大于等于上一页最后序号，避免偏移随深度线性变慢。

size 默认 50，上限 200。超出返回 PARAM_SIZE_EXCEED 并返回上限值，不静默截断。

五、幂等验收（报工）

同一 report_no 同内容：返回 DUPLICATE，返回首次报工的 report_time_server 与 id，work_order_remaining_qty 不变。

同一 report_no 不同 report_qty：仍返回首次报工结果，不覆盖，日志记 PARAM_CHANGED_IGNORED。

同一 report_no 不同 report_status（通过变不良）：拒绝，返回 status_mutation_not_allowed，走修正接口。

网关层重试：网关或设备客户端在超时后重试，后端返回 DUPLICATE 而非再加一。验收时用并发发同一 report_no 压五十次，落库行数等于一，DUPLICATE 计数等于四十九。

report_no 长度与格式：字母数字与短横线，长度 20 到 64，全小写。客户端大写或含空格在入参校验阶段拒绝，避免大小写不一致导致假重复。

幂等窗口与对账：短窗口（五分钟）用于防设备抖动；对账用 report_no 维度的幂等表做次日差异核对，不依赖窗口。

六、耗时验收

报工（写）：p95 小于 200 毫秒（单次报工，含幂等查重与工单剩余量回写）。p99 小于 500 毫秒。失败场景（REJECTED）不因为校验链长而拖慢：校验不通过应在 50 毫秒内返回，不走到落库事务。验收方法：单客户端串行一千次，加十个客户端并发各五百次，report_no 全部不同，统计响应时间分布。

追溯反查（读）：单板反查（SERIAL）p95 小于 300 毫秒，任意页。设备时间窗反查（八小时窗、中等产线）p95 小于 800 毫秒，首页返回完整 total。24 小时窗或更大要求客户端缩小窗口或用 by-window 的预聚合，接口不承诺 p95，返回提示 WINDOW_TOO_LARGE。total 的计算不能与数据拉取串行做两遍：用覆盖索引或物化计数，避免首页返回前把明细扫一遍。排序列（report_time、operation_seq）必须有索引，且 dimension 枚举对应的列有覆盖索引，反查索引按维度各建，不共用一个万能索引。

七、常见坑

用 operation_seq 当唯一标识：同一工单换版本后序号会重排，反查必须带 work_order_no 加 operation_seq 组合。

分页只传 size 不传排序：数据库不保证顺序，翻页之间出现重复或遗漏行，客户端以为 MES 数据错了。

report_time 用客户端时间落库：设备时钟差几分钟，时间窗反查对不上班次。必须以服务器时间落库，客户端时间只记在 client_report_time 供排查。

幂等只在应用层做内存缓存：服务重启后窗口失效，同一 report_no 被重复计数。幂等键必须落库唯一索引。

反查返回整张工单上下文：追溯接口返回的是报工行，不是工单快照。把物料清单、工艺路线也塞进行列表会把响应体撑大，耗时指标直接失效。

八、FAQ

报工接口要不要返回工单完成状态？只返回 work_order_remaining_qty。是否完工由工单查询接口判定，报工接口职责是报工。

total 不准怎么办？允许最终一致，但同一请求内 total 与行列表必须自洽。跨请求 total 可能因并发报工微调，文档里写明即可。

追溯反查要不要支持导出 Excel？接口层不提供。导出走独立文件任务，返回下载链接，不把表格字节流塞进 JSON 分页壳。

设备离线后补报工怎么算耗时？补报工是正常报工，报工时间可落在过去，但接口耗时仍然按服务器收到到返回计时，与报工时间无关。

report_no 由谁生成？优先客户端（设备、扫码枪或站端）带时间戳、设备号与序列生成；网关层只做格式校验，不改内容，确保幂等键在调用方可控。

九、结语

报工接口把事情写对，追溯反查把事情查快。分页确定排序和 total 的口径，幂等靠 report_no 落库唯一索引而不是内存窗口，耗时用 p95 与 p99 把写和读分开验收。三项在联调阶段就定死，上线后质量异常反查才不会出现数据是对的、但谁都查不到的尴尬。

（本文属技术分享，由 AI 辅助撰写，如有疏漏欢迎在评论区指正。）