编辑 | blame | 历史 | 原始文档

MES 数据采集(鸡爪计数设备)前端联调方案

需求6:鸡爪自动计数/称重设备接入 MOM。第一阶段只做「采集 → 展示 → 统计」,不自动回写生产报工或包装。
现场设备接线与网关由现场同事负责,系统侧提供 HTTP JSON 上报接口 + 管理端页面。

涉及页面

  • 生产管控 → 数据采集 → 设备管理(/mes/dc/device)
  • 生产管控 → 数据采集 → 实时看板(/mes/dc/dashboard)
  • 生产管控 → 数据采集 → 采集记录(/mes/dc/record)
  • 生产管控 → 数据采集 → 统计分析(/mes/dc/statistics)

设备端接入(现场网关/同事对接用)

1. 接入准备

  1. 在「设备管理」新增采集设备,填写设备编号(如 DC001)、名称、设备类型;
  2. 创建成功后弹窗一次性显示 40 位采集令牌,配置到设备端;
  3. 令牌仅在创建/重置时返回,遗失只能重置(旧令牌立即失效);
  4. 设备端每次请求携带请求头 X-Device-Token: <令牌>(也支持 URL 参数 token,请求头优先)。

2. 上报接口

方法 路径 说明
POST /admin-api/mes/data-collection/open/ingest 上报一次采集数据
POST /admin-api/mes/data-collection/open/heartbeat 上报心跳(建议每 1 分钟一次)

上报请求参数:

参数 类型 必填 说明
deviceCode String 是 设备编号,须与设备台账一致
bizId String 建议 设备侧唯一键,重复上报按幂等处理(返回 duplicate=true,不新增记录)
recordNo String 否 设备侧记录序号,仅展示
recordTime String 否 设备采集时间,格式 yyyy-MM-dd HH:mm:ss,不传取服务器时间
count Integer 二选一 本次计数;与 totalCount 都传时以 count 为准
totalCount Integer 二选一 设备累计计数;只传累计值时,系统用「本次累计 - 上次累计」计算本次数量
weight BigDecimal 否 本次重量(g)
totalWeight BigDecimal 否 设备累计重量(g),仅留存
online Boolean 否 是否在线实时上报,离线补报传 false,默认 true
firmwareVersion String 否 固件版本,上报后更新到设备台账

上报响应示例:

{
  "code": 0,
  "msg": "",
  "data": {
    "recordId": 1024,
    "duplicate": false,
    "quantity": 12,
    "todayQuantity": 120,
    "todayWeight": 3600.50,
    "serverTime": "2026-11-10 14:23:05"
  }
}

心跳请求参数:

参数 类型 必填 说明
deviceCode String 是 设备编号
firmwareVersion String 否 固件版本
ip String 否 设备 IP

心跳响应: { "code": 0, "data": { "serverTime": "...", "deviceName": "...", "enabled": true, "workOrderId": 2048, "workOrderCode": "WO202611100001" } }

3. 设备端注意事项

  • 设备编号与令牌必须同时正确,否则返回业务错误码(未携带令牌 / 令牌无效 / 设备不存在);
  • 设备状态为「禁用」时拒绝上报,需先在设备管理启用;
  • 计数与累计值不能为负,重量不能为负;
  • 同一 bizId 重复上报返回首次记录的 recordId 与 duplicate=true,网关可安全重试;
  • 只报 totalCount 且与上次累计值相同(设备重试未带 bizId)时按重复上报处理,不新增记录;
  • 设备计数器清零(本次累计小于上次累计)时,系统直接把本次累计值当作本次数量;
  • 时间统一按服务器本地时区,recordTime 不传即记录接收时间。

管理端 API

方法 路径 权限 说明
POST /mes/data-collection/device/create mes:dc-device:create 新增设备,返回 id + 一次性 token
PUT /mes/data-collection/device/update mes:dc-device:update 修改设备(不会修改令牌)
DELETE /mes/data-collection/device/delete?id= mes:dc-device:delete 删除设备
GET /mes/data-collection/device/get?id= mes:dc-device:query 设备详情
GET /mes/data-collection/device/page mes:dc-device:query 设备分页(code/name/deviceType/status/workOrderCode)
GET /mes/data-collection/device/simple-list mes:dc-device:query 设备精简列表(下拉用)
PUT /mes/data-collection/device/reset-token?id= mes:dc-device:reset-token 重置令牌,返回新令牌
PUT /mes/data-collection/device/bind-work-order mes:dc-device:bind 绑定生产工单,body:{ id, workOrderId }
PUT /mes/data-collection/device/unbind-work-order?id= mes:dc-device:bind 解绑生产工单
GET /mes/data-collection/record/page mes:dc-record:query 记录分页(deviceId/deviceCode/workOrderCode/productId/batchCode/status/recordTime 范围)
GET /mes/data-collection/record/get?id= mes:dc-record:query 记录详情
PUT /mes/data-collection/record/correct mes:dc-record:correct 更正记录,body:{ id, quantity, reason }
PUT /mes/data-collection/record/cancel mes:dc-record:cancel 作废记录,body:{ id, reason }
GET /mes/data-collection/record/export-excel mes:dc-record:export 导出 Excel(按当前筛选条件,不分页)
GET /mes/data-collection/statistics/summary mes:dc-statistics:query 统计汇总
GET /mes/data-collection/statistics/trend mes:dc-statistics:query 采集趋势
GET /mes/data-collection/statistics/device-overview mes:dc-statistics:query 设备实时概览(看板)

统计查询参数: beginTime、endTime(yyyy-MM-dd HH:mm:ss)、deviceId、workOrderId、granularity(day 按天 / hour 按小时,默认 day)。

统计响应:

{
  "code": 0,
  "data": {
    "totalQuantity": 1234,
    "totalWeight": 370200.50,
    "recordCount": 56,
    "deviceCount": 2,
    "devices": [
      { "deviceId": 1, "deviceCode": "DC001", "deviceName": "一号线鸡爪计数", "totalQuantity": 800, "totalWeight": 240000.00, "recordCount": 36 }
    ]
  }
}

趋势项:{ "period": "2026-11-10", "totalQuantity": 120, "totalWeight": 36000.00 }(按小时时 period 形如 2026-11-10 14:00)。

业务流程与数据带入

  1. 设备管理新增设备 → 一次性令牌 → 设备端配置;
  2. 设备端心跳 → 设备列表「在线状态」按最后心跳时间判定(超过 5 分钟无心跳视为离线);
  3. 设备端上报 → 生成采集记录(正常状态 0);上报时若设备已绑定工单,记录自动带入:
  • 生产工单 ID / 工单编号;
  • 产品 ID / 产品编码 / 产品名称;
  • 生产批次号。
  1. 绑定生产工单后,只影响**后续新上报**的记录;历史记录不回溯改绑;
  2. 解绑后,后续新记录不再带工单信息,历史记录保留绑定时的工单信息;
  3. 采集记录可更正(数量改为实际值,状态 1 已更正,保留更正前原始数量与原因)或作废(状态 2,仍保留在列表可追溯);
  4. 实时看板展示设备在线状态与今日产量;统计分析按时间范围/设备给出数量、重量、记录数、设备数与日/小时趋势;
  5. 统计与看板**排除已作废记录**;已更正记录按更正后数量参与统计。

字段展示规则

字段 展示位置 说明
设备编号/名称/类型/型号/安装位置 设备列表、记录列表、看板 类型走字典 mes_dc_device_type
设备状态 设备列表 字典 mes_dc_device_status:0 启用 / 1 禁用
在线状态 设备列表、看板 最后心跳时间在 5 分钟内为在线
当前绑定工单 设备列表 显示工单编号;操作按是否已绑定显示「绑定工单/解绑工单」
最后心跳/最后上报时间 设备列表 精确到秒
固件版本 设备列表 心跳或上报时更新
采集数量/设备累计数量/重量 采集记录 重量保留 2 位小数
记录状态 采集记录 字典 mes_dc_record_status:0 正常 / 1 已更正 / 2 已作废
上报方式 采集记录 在线 / 离线补报
生产工单编号/产品/批次 采集记录 上报时由绑定工单带入,可能为空
统计汇总/趋势/按设备汇总 统计分析 排除作废记录

业务规则说明

场景 规则
令牌创建/重置 仅本次接口返回,列表与详情不返回令牌
幂等 同一设备 + 相同 bizId 只落一条记录,重复请求返回首次记录并标记 duplicate=true
只报累计值 按「本次累计 - 上次累计」计算;首次或计数器清零按本次累计
停用设备 拒绝上报与心跳以外的采集操作;需先启用
更正 仅「正常」状态可更正;更正后不可再次更正;记录保留原始数量
作废 已作废不可重复作废;作废记录不参与统计与看板
统计范围 默认全部时间;可按设备/工单/时间范围筛选
第一阶段边界 采集数量只做展示与统计,**不自动回写生产报工、包装或库存**;回写逻辑待后续需求确认

注意事项

  • 设备端上报地址为网关可访问的后端地址(开发环境经前端代理 /admin-api,生产环境直接用后端域名 + /admin-api);
  • 令牌是设备身份凭证,只配置在网关,不写入日志/截图/文档;
  • 一个设备同一时间只绑定一张生产工单;换单需先解绑再绑定;
  • 绑定时只允许选择未完工、未取消的生产工单;
  • 设备已有采集记录时禁止删除(提示先处理记录),避免历史数据失去设备主体;
  • 采集记录导出使用当前筛选条件,导出全部匹配行(不分页);
  • 现场设备若只输出累计值,建议同时上报 bizId,避免网络重试造成重复计数。