数据接入
文档状态：当前技术指南。接线的目的不是积累更多点位，而是让一次真实运行能够支持工程判断。
本文定义设备与业务数据进入 Ingot 的接入契约，包括 SiteId、EdgeId、ExecutionId 等身份语义，以及来源、映射、时间、质量结果关联和分析准入要求。任何真实接入均须完成数据归属、来源可追溯性和质量结果关联检查。
接线完成的定义
一条合格的数据链必须回答：
- 这是哪台设备、哪个产品和哪次运行？
- 工程师计划设置什么，设备实际采用什么？
- 过程在各阶段实际怎样变化？
- 使用了什么材料、工装、批次和维护状态？
- 最终质量与安全结果是什么？
- 每项数据来自哪里、使用什么单位和配置版本？
上述事实的稳定关联是数据进入工艺追因与配方优化流程的准入条件。
数据来源
Ingot 不把 PLC 当成唯一入口。一条运行记录可以组合：
- 控制系统的工艺规范、状态、阶段和过程信号；
- 仪器、传感器、视觉或边缘网关测量；
- 实验室、在线检测或人工质检结果；
- MES、QMS、工单、条码和批次追溯；
- 工装、材料、校准与维护台账。
适配器把原始值映射为稳定业务编码、标准单位、质量状态、时间和来源。研发项目只引用这些稳定语义，不绑定厂商地址或协议。
标识与关联
一次运行使用职责不同且不可互相替代的稳定标识：
SiteId：数据所属的生产单元，是站点隔离、容量和故障域边界；EdgeId：安装后稳定不变的现场节点身份，与SiteId和独立凭据绑定；ExecutionId：由 Edge 生成，是 Platform 中真实过程执行及其现场事件的统一身份；ExecutionKey：研发实验计划和真实执行的关联键。
Platform 必须显式记录 ExecutionKey 与 ExecutionId 的关系。生产事件和类型化过程采样同时保存 SiteId 与 EdgeId，对象汇总以站点为边界，不能把不同工厂中同名设备合并。MES 工单、条码、仪器样本号或设备寄存器可以携带 ExecutionKey 作为外部参考，但不能替代 Edge 生成的 ExecutionId。检验记录通过同一关系关联到执行。
如果控制器只能保存数值，可维护短数字与 ExecutionKey 的确定性关系。禁止仅根据时间邻近在事后猜测执行和检验的对应关系。
配置生命周期
采集配置按以下状态推进：
草稿 → 目标 Edge 探查 → 真实值验证 → 发布 → Edge 本地验证 → 安全应用 → 状态确认
发布前检查：
- 地址、端口、认证和网络可达；
- 点位真实可读；
- 数据类型、字节序、倍率和偏移正确；
- 原始值和换算值符合工程常识；
- 必需点位、运行边界和上下文来源齐全；
- 标准单位与工艺模型一致。
Edge 保存最后一次成功配置。新配置只有在形成一份必需项完整、可解码的有效快照后才通过启动健康期；仅建立连接或建立 OPC UA 订阅不算成功。新配置失败时保留旧版本并上报失败，不能静默切换到未版本化本地配置。
运行状态分别报告读取尝试、设备读取成功、有效快照、事件产出、非运行空快照、重复抑制、源身份停滞和最后错误。running 表示最近存在有效快照，不再用单一“采样成功”同时代表连接、数据与事件健康。上行状态同时报告待传事件数、最老待传时间、队列容量占用、存储空间、近期发送速率和预计排空时间；容量达到告警线时进入降级状态。Platform 按接收心跳的时间保存七天健康快照，用于判断停采或积压何时开始和恢复，不采用可能漂移的设备时间作为节点在线时间。
HTTP 与 MQTT 文档报文采用有界解析：解压后或响应体超过 16 MiB、JSON 深度超过 64 层时拒绝处理，防止异常设备报文耗尽 Edge 内存。HTTP 支持 GET/POST、内容类型、请求体、固定请求头和密钥引用请求头。Authorization、Cookie 和常见 API 密钥头只能使用密钥引用；固定请求体和普通请求头会随配置及 CSV 原样保存，不得在其中填写凭据。HTTP 数据路径只能相对于已配置的设备基础地址，设备请求不跟随重定向，防止密钥请求头被发送到其他主机。连接与单次读取超时最小为 1000ms；操作超时会进入降级并按重连间隔重试，不会让工作器静默退出。
驱动能力
不同协议支持的配置不同。平台能力矩阵同时驱动界面和发布校验，避免接受一个最终会被驱动忽略的字段。
| 能力 | HTTP 轮询 | MQTT | OPC UA | Modbus TCP | 三菱 1E |
|---|---|---|---|---|---|
| 采样时间取自设备 | ✅ | ✅ | 使用服务器 SourceTimestamp | ✅ | ✅ |
| 序号字段 | ✅ | ✅ | ❌ | ❌ | ❌ |
| 连接与单次操作超时 | ✅ | ✅ | ✅ | ✅ | ✅ |
| 重连间隔 | ✅ | ✅ | ✅ | ✅ | ✅ |
| 控制参数集合路径 | ✅ | ✅ | ❌ | ❌ | ❌ |
| 按主题绑定点位 | ❌ | ✅ | ❌ | ❌ | ❌ |
| 字节序 / 字序 | ❌ | ❌ | ❌ | ✅ | ❌ |
| 位寻址 | ❌ | ❌ | ❌ | ✅ | ✅ |
| 探查枚举点位 | ✅ | ✅ | ✅ | 只回读已配置寄存器 | 只回读已配置软元件 |
Modbus 和 MELSEC 不执行地址盲扫，防止意外访问不应读取的区域。
点位选择器
Modbus TCP
<寄存器区>:<地址>:<类型>[:<字节序>:<字序>]
<寄存器区>:<地址>.<位>:boolean
寄存器区为 holding-register、input-register、coil 或 discrete-input。线圈与离散输入只能读取 boolean。保持或输入寄存器的单个位需要显式位偏移。
字符串第 4 段表示字节长度。连接配置决定地址基准；使用从 1 开始的手册地址时，Edge 在请求前转换为协议地址。
三菱 MC A-compatible 1E
<软元件>:<编号>:<类型>[:<字节长度>]
<字软元件>:<编号>.<位>:boolean
- X / Y 编号使用八进制；
- B / W 使用十六进制；
- 其他常用软元件使用十进制；
- M / X / Y / B / S / L 作为
boolean时使用位单位读取； - 位软元件作为
int16等数值读取时表示从该点开始的连续位打包字。
相邻点位可以按连接配置合并为连续读取，减少网络往返；Modbus 与 MELSEC 都限制最大合并间隙，不跨越较大的未声明地址区。诊断单点问题时可把合并间隔设为 0。
寄存器设备时间必须显式声明 unix-s、unix-ms 或 iso-8601 编码。发布校验会检查点位数据宽度，32 位 Unix 秒不会再被当作 Unix 毫秒解释。
MQTT 多主题
设备网关可能把一台设备的数据拆到多个主题：
- 每个订阅配置稳定通道代码、实际主题、可选报文根路径和主题变量；
- 点位可以绑定来源主题；
- 多主题值合并为一份等价采样快照；
- 所有必需点位都出现后才产生采样；
- 仅包含上下文的主题更新快照但不单独触发采样；
- 配置引用未订阅主题时拒绝保存。
- 会命中同一报文的重叠订阅过滤器会被拒绝，避免报文根、通道和主题变量产生歧义；
- 主题变量的层级索引必须位于过滤器范围内。
必须为跨主题值设置合理的最大陈旧时间。主题停止后，过期值视为缺失；否则系统可能把旧值持续当作当前状态。
报文可以声明 UTF-8、GBK、GB 18030 或 Big5 编码，以及无压缩、gzip、deflate 或 Brotli 压缩。解码、解压和 JSON 解析在探查与正式采集使用同一条受限路径。
设备模板与实例
同类设备批量接入使用四个职责不同的对象：
| 对象 | 保存什么 | 何时变化 |
|---|---|---|
| 任务模板 | 协议语义、工艺数据模型、点位映射、运行边界和采集策略 | 型号语义或映射变化时发布新版本 |
| 数据源实例 | 目标 Edge、设备身份、实际网络地址和密钥引用 | 每台设备独立维护 |
| 任务绑定 | 选择哪个模板版本与哪个数据源版本 | 组合关系变化时创建新版本 |
| 设备接入任务 | 由绑定生成、可探查并最终发布的部署单元 | 每台设备逐一验证和发布 |
因此“数据源”和“任务绑定”不是同一份配置：前者回答“连接哪台设备”，后者回答“这台设备采用哪套采集模板”。模板不允许任意继承或覆盖点位定义；变更点位必须发布新的模板版本。
首台设备按完整表单配置并通过目标 Edge 真实探查后，可以从已发布任务提取一个已发布模板、首台数据源和绑定。提取属于一次配置迁移：系统创建带版本来源的新任务版本并退役原运行版本，不会给已发布版本补写字段。MQTT 模板使用稳定通道代码，实例化时解析为各设备的实际主题。
CSV 的四个动作是两个对象各自的导入与导出，不是重复功能：
- 导出数据源 CSV，获得连接实例的表头和已有设备行；
- 增加或修改同类设备的 Edge、身份、地址与密钥引用，再导入数据源 CSV；
- 导出任务绑定 CSV，获得模板—数据源组合的表头和已有绑定；
- 为新增数据源选择模板版本，再导入任务绑定 CSV。
两类 CSV 都使用带表头的 UTF-8 格式，单批最多 500 项，并在一个事务内校验和写入；任一行无效时整批不写入。先导入数据源，再导入引用它们的绑定。凭据字段只保存密钥引用；固定请求体和普通请求头会随数据源 CSV 导出，不能在其中填写凭据。导出还会中和电子表格公式前缀，避免名称等文本在表格软件中被当作公式执行。批量实例化只生成草稿，每台设备必须单独完成真实探查才能发布。
模板、数据源、绑定和最终任务都记录版本来源。已发布版本不可覆盖；修改通过新版本完成。这样可以回答某条现场数据使用了哪一版映射和哪一版连接实例，而不是把配置复制后失去来源关系。
值转换与质量策略
每个映射可以配置源类型、源单位、倍率、偏移、质量字段与允许质量值、有效上下限、越界行为、缺失行为和默认值。发布校验确保：
- 目标数据项必须存在于所引用的工艺数据模型；
- 所有非空数据项必须映射，且不能选择省略缺失值或省略越界值；
- 单位必须与工艺模型一致，倍率和偏移不能替代未声明的单位换算；
- 默认值能转换为目标数据类型；整数目标不接受产生小数的换算结果；
- 布尔值只接受明确的真假词或 0/1，不把任意非零数静默当作真；
- OPC UA 的非 Good 状态默认拒绝，只有显式列出的状态可以通过；
- 发布探查必须至少观察到配置引用的每个值、质量、上下文、设备时间、设备序号和工艺规范路径；运行时可选点位也不例外。设备不提供源序号时应留空，而不是保留一个无法验证的默认路径。间歇字段应在设备能产生该字段时完成探查。
- 设备时间戳默认不得领先 Edge 接收时间超过 300000ms，阈值可配置，超过后拒绝样本；这与源身份停滞检测共同防止错误时钟或错误编码污染事件时间线。
OPC UA 订阅还校验服务器对每个 MonitoredItem 的接受状态。正式采集检查必需点位的最大值龄与同一快照时间偏差；活动运行期间长时间没有通知会进入降级状态。当前 OPC UA 驱动采集变量节点，不采集事件和报警；这是明确的驱动边界。
业务映射
控制变量
control-parameter:<控制参数编码>
signal:<信号编码>:<特征编码>
signal:<信号编码>:<特征编码>:<阶段编码>
例如：
control-parameter:holding-temperature
signal:temperature:mean:holding
目标与结果约束
inspection:<检验特性编码>
inspection-outcome:<检测定义编码>
例如：
inspection:form-error
inspection:crack-rate
inspection-outcome:final-inspection
inspection-outcome 使用无量纲单位 1，将正式检验记录的 PASS 映射为 1、FAIL 映射为 0；INCONCLUSIVE 不会被猜测，会排除该运行。显式映射后，实际值缺失也会排除该运行。系统不能用计划值补齐训练数据。
执行边界与阶段
运行边界和阶段承担不同职责：
- 开始和完成事件决定一次运行是否完整；
- 阶段号用于对齐过程轨迹和计算阶段特征；
- 阶段可以变时长、重复或跳转，不能单独决定运行完整性。
过程特征可以包括均值、极值、标准差、斜率、积分、峰值、过冲、到达时间、停留时间和覆盖率。特征定义必须版本化；改变定义会产生新版本和内容哈希。
生产上下文
上下文字段从现场信号、业务系统或时间有效台账解析。运行开始时固化快照，并记录捕获状态：
- 来源提供并成功解析；
- 根据版本化生产上下文解析；
- 配置缺失或无法解析。
场景标记为分析必需的字段无法解析时，该运行不得进入相应分析。其他字段继续用于追溯和覆盖评估。
数据质量与分析准入
观察进入分析前至少检查：
- 运行已完成；
- 实际设置存在；
- 过程数据和需要的特征可用；
- 目标与结果约束检验完整；
- 必需上下文已解析；
- 单位、时间和配置版本一致；
- 数值有限；
- 运行与检验关联唯一。
被排除的运行保留原始记录、来源哈希和原因。数据质量页面应能回答“缺什么、为什么缺、影响哪些分析、怎样修复”。
新场景接入顺序
- 定义工程问题、运行边界和稳定设备身份；
- 选择或实现协议驱动；
- 建立设备模板和点位映射；
- 定义实际工艺规范、过程信号、阶段和单位；
- 配置生产上下文和检验特性；
- 在目标 Edge 上验证真实值并发布；
- 完成一条运行—轨迹—检验闭环；
- 检查数据质量和分析准入；
- 经工程师确认后才进入比较、追因和优化。