📚 课程目录第4章视觉追溯的数据对象定义

4. 视觉追溯的数据对象定义

在 XG-X 视觉系统中，追溯并不是“把检测结果存下来”这么简单。追溯的本质是：当产品在后续工序、客户现场或售后环节出现问题时，能够凭借一条记录还原“这个产品当时被看到了什么、系统判断了什么、依据是什么、发生在什么时间”。因此，数据对象定义决定了追溯系统的上限——字段设计得不对，后面再好的数据库和 MES 对接都无法弥补。

本节把需要追溯的信息拆成三类：标识类（字符、条码、二维码、日期、批次）、判定类（检测结果、缺陷图像）、定位与时间类（坐标、时间戳）。三类信息共同构成一条完整的追溯记录。

一、标识类数据：回答“这是哪一个产品”

标识类数据是追溯的主键来源。XG-X 常见的读取对象包括：OCR/OCV 读取的字符（如喷码批号“A240715-03”）、一维条码（Code128、Code39）、二维码（QR、DataMatrix），以及直接印在产品上的日期码（生产日期、有效期）。

设计字段时，不能只存一个“读到的字符串”。因为同一个字符串可能来自不同码制、不同工位、不同相机，必须把来源和质量一起记录。建议字段如下：

code_type：码制类型，枚举值 OCR / CODE128 / QR / DM / DATE。
code_value：解码后的原始字符串，如 A240715-03。
read_grade：读取质量等级，XG-X 可输出 0～4 或 A～F，用于判断是否接近临界。
read_station：读取工位编号，如 ST01。
is_primary：是否作为主追溯键，布尔值，避免多码冲突时无法确定唯一标识。

这里有一个容易忽略的点：日期和批次应当拆开存储。很多现场把“20240715-A”整体当作一个字符串，结果无法按日期范围查询、无法按批次统计不良率。正确做法是解析出 prod_date（DATE 类型）和 lot_no（VARCHAR），原始字符串另存 raw_text 备查。

二、判定类数据：回答“系统认为它合格吗、为什么”

检测结果字段必须能表达三态：OK、NG、RETRY（重检）。只存 OK/NG 会丢失重检信息，导致同一产品出现多条记录却无法区分。建议字段：

judge_result：枚举 OK / NG / RETRY。
ng_code：不良代码，如 NG_CHAR_MISS、NG_QR_DAMAGE，与 XG-X 的判定分支对应。
defect_image_path：缺陷图像存储路径，建议按 日期/工位/批次 分目录，避免单目录文件过多。
image_keep_flag：是否保留原图。OK 件通常只留缩略图或特征值，NG 件保留全图，用于控制存储量。

缺陷图像不要直接存进数据库 BLOB 字段。XG-X 单张图像可达数 MB，长期运行会迅速撑爆数据库。推荐“数据库存路径 + 文件服务器存图”的方式，路径字段长度预留 255 字符。

三、定位与时间类数据：回答“在哪里、什么时候”

坐标字段用于还原缺陷在产品上的物理位置。XG-X 输出的坐标通常以图像左上角为原点，X 向右为正、Y 向下为正，单位是像素。如果后续要与机械手或贴标机联动，必须同时记录像素坐标和物理坐标，并保存标定系数，否则换型后坐标无法复用。

pos_x、pos_y：像素坐标，整数。
phys_x_mm、phys_y_mm：物理坐标，浮点，保留 3 位小数。
calib_id：标定参数版本号，保证坐标可换算。
timestamp：检测时刻，建议用带时区的 ISO 8601 格式，如 2024-07-15T14:32:08.215+08:00，精确到毫秒。

时间戳必须由同一时钟源产生。如果 XG-X 控制器时间与 MES 服务器时间不同步，追溯记录会出现“产品还没生产，记录已经上传”的荒谬情况。建议 XG-X 与 MES 通过 NTP 对时，偏差控制在 100 ms 以内。

四、字段设计示例与数据流

把上述字段整合成一张追溯主表，核心结构如下（示例，字段类型可按实际数据库调整）：

CREATE TABLE trace_record (
  trace_id        BIGINT PRIMARY KEY,
  code_type       VARCHAR(16),
  code_value      VARCHAR(128),
  read_grade      TINYINT,
  read_station    VARCHAR(16),
  prod_date       DATE,
  lot_no          VARCHAR(32),
  judge_result    VARCHAR(8),
  ng_code         VARCHAR(32),
  defect_img_path VARCHAR(255),
  pos_x           INT,
  pos_y           INT,
  phys_x_mm       DECIMAL(10,3),
  phys_y_mm       DECIMAL(10,3),
  calib_id        VARCHAR(16),
  timestamp       DATETIME(3)
);

下图展示了一条追溯记录从 XG-X 采集到入库的字段构成与数据流关系。左侧是 XG-X 侧产生的原始数据对象，中间经过字段映射与解析，右侧形成结构化追溯记录，并区分 OK 件与 NG 件的不同存储策略。

五、字段设计中的三个关键判断

第一，主键怎么定。如果产品只有一个二维码，code_value 可直接作主键；如果同时有 OCR 字符和二维码，应指定二维码为主追溯键，OCR 作为辅助校验字段。不要用 timestamp 作主键，毫秒级仍可能重复。

第二，图像存不存、存多久。OK 件全存图像会让存储成本失控。建议 OK 件只存缩略图和特征值，NG 件存全图，保留周期按客户要求设定，例如 NG 图像保留 90 天、OK 特征值保留 1 年。字段 image_keep_flag 就是为这个策略服务的。

第三，时间戳用本地时间还是 UTC。如果产线只有一条、MES 也在同一时区，用本地时间加时区偏移即可；如果有多工厂、多时区，建议统一存 UTC，展示时再转换。无论选哪种，全系统必须一致，并在字段注释中写明。

常见错误：把 judge_result 设计成布尔值。一旦出现重检、复判、人工放行，布尔值无法表达，只能加字段补救，导致表结构反复变更。从一开始就用枚举字符串，扩展成本最低。

完成字段定义后，建议用一条真实产品跑通全链路：XG-X 读取二维码 → 输出判定与坐标 → 按上述字段写入数据库 → 在 MES 中按 code_value 反查，确认字符、批次、缺陷图像、坐标、时间戳全部可还原。只有这条链路走通，追溯数据对象才算真正定义完成。