4. 现场数据采集与误检漏检记录规范
误检漏检治理的起点不是调参，而是数据。如果现场只留下“今天误检有点多”这样的口头描述，后续无论怎么改阈值、换光源、重训模型，都无法判断改动是否真的有效。本节要解决的核心问题是：把 XG-X 控制器每一次判定结果，连同判定依据、图像证据、时间信息和批次身份，稳定地落成结构化记录，形成可回溯、可统计、可对比的数据底座。
一、检测结果日志：先定义“一行记录”代表什么
日志的最小单位应当是“一次检测事件”，而不是“一个工件”。XG-X 在一次触发中可能执行多个检测单元（如定位、有无、尺寸、字符），每个单元都有独立的判定结果。因此建议采用两级结构：主记录描述一次触发，明细记录描述各检测单元。主记录至少包含以下字段：
event_id：全局唯一事件号，建议由“日期+控制器编号+自增序号”组成，例如20250612-C01-000873；trigger_time：触发时刻，精确到毫秒；camera_id / program_no：相机通道与当前调用的检测程序号，程序切换必须留痕；overall_result：整件判定，取值 OK / NG；cycle_time_ms：本次检测耗时，用于识别节拍异常；batch_id / workpiece_index：批次号与批内序号，用于追溯。
明细记录则包含 event_id、unit_name（如“外径”“字符OCR”）、measured_value、lower_limit / upper_limit、unit_result、score（相关性或相似度得分）。把实测值和上下限一起记录，是后续做参数分布分析的前提——只有结果没有数值，就无法判断误检是“临界抖动”还是“整体偏移”。
二、NG/OK 图像留存：留什么、留多少、怎么命名
图像是判定证据，但全量留存会迅速吃满硬盘。推荐采用“NG 全留 + OK 抽样留 + 边界必留”的策略：
- NG 全留：所有 NG 事件的原始图与叠加判定框的标注图各存一张，这是复盘误检漏检的主要素材；
- OK 抽样留：按固定间隔（如每 200 件留 1 件）或按时间（每 10 分钟留 1 件）抽样，用于建立“正常样本基线”；
- 边界必留：实测值落在限值 ±5% 区间内的 OK 件强制留存，这类样本最接近误检漏检的临界状态，价值最高。
命名必须与日志可关联，建议格式为 {event_id}_{unit_name}_{result}.jpg，例如 20250612-C01-000873_外径_NG.jpg。图像与日志分目录存放时，目录结构按“日期/批次/结果”三级组织，避免单目录文件数过多导致检索缓慢。存储上建议设置滚动清理策略，例如 NG 图保留 90 天、OK 抽样图保留 30 天，清理前先归档统计结果。
三、时间戳对齐：让图像、日志、PLC 说同一时刻
现场最常见的数据不可用问题，是图像时间、日志时间与产线 PLC 时间各走各的。XG-X 控制器、工控机、PLC 若未统一时钟，事后无法判断“这次 NG 到底对应哪一件”。做法是：以产线 PLC 或上位机 NTP 服务器为基准，控制器与采集程序定期校时，偏差控制在 ±50 ms 以内；日志中的 trigger_time 统一记录触发沿时刻，而不是图像保存完成时刻，两者可能相差数十毫秒。若存在编码器位置信息，还应同时记录 encoder_pos，用位置而非纯时间做二次对齐，可有效消除节拍波动带来的错位。
四、批次追溯字段：让每一次判定都能定位到“哪一批、哪一件、哪一工位”
仅有时间戳不足以支撑追溯。当出现批量性误检时，需要快速回答：是某一批来料的问题，还是某个工位、某个班次、某次程序切换之后才出现的。因此主记录中应固定写入 batch_id、material_lot（来料批号）、fixture_no（工位/夹具编号）、operator_shift（班次）和 program_no。这些字段通常由上位机在换批或换程序时写入一个“批次上下文”，采集程序在每次触发时自动附加，避免依赖人工逐条填写。
下面是一份可直接参考的日志字段定义示例，主记录与明细记录通过 event_id 关联：
主记录 result_log.csv
event_id,trigger_time,batch_id,material_lot,fixture_no,program_no,operator_shift,overall_result,cycle_time_ms
20250612-C01-000873,2025-06-12 09:14:22.318,B250612A,LOT-4471,FX-03,P12,早班,NG,86
明细记录 unit_log.csv
event_id,unit_name,measured_value,lower_limit,upper_limit,unit_result,score,image_path
20250612-C01-000873,外径,12.047,12.000,12.050,OK,0.982,img/20250612/B250612A/20250612-C01-000873_外径_OK.jpg
20250612-C01-000873,字符OCR,-,-,-,NG,0.613,img/20250612/B250612A/20250612-C01-000873_字符OCR_NG.jpg
从这份记录可以直接读出：该件外径实测 12.047，接近上限 12.050，属于边界 OK；而字符 OCR 得分仅 0.613，是导致整件 NG 的主因。这类“数值正常但得分偏低”的记录，正是后续判断误检的重点样本。
五、从记录到可分析：最小统计口径
数据底座建好后，应能直接支撑三类基础统计：按 batch_id 统计 NG 率与各检测单元的 NG 占比；按 unit_name 统计实测值分布与边界命中次数；按 program_no 与 operator_shift 对比不同程序版本、不同班次下的判定差异。若某单元在程序切换后 NG 率明显上升，或边界命中次数骤增，就应优先复核该单元的阈值与图像质量，而不是全流程盲目调参。
cycle_time_ms 在开启存图后明显增大，应改为先缓存图像再后台落盘，或降低 OK 抽样频率。把日志、图像、时间戳和批次字段四者绑定成一条完整记录，误检漏检才从“现象描述”变成“可查询、可对比、可验证”的工程问题。后续所有阈值调整、模型优化和效果验证，都应基于这套数据底座展开，并以同一口径的前后对比作为判断依据。