需求6:鸡爪自动计数/称重设备接入 MOM。第一阶段只做「采集 → 展示 → 统计」,不自动回写生产报工或包装。
现场设备接线与网关由现场同事负责,系统侧提供 HTTP JSON 上报接口 + 管理端页面。
/mes/dc/device)/mes/dc/dashboard)/mes/dc/record)/mes/dc/statistics)DC001)、名称、设备类型;X-Device-Token: <令牌>(也支持 URL 参数 token,请求头优先)。| 方法 | 路径 | 说明 |
|---|---|---|
| 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" } }
bizId 重复上报返回首次记录的 recordId 与 duplicate=true,网关可安全重试;totalCount 且与上次累计值相同(设备重试未带 bizId)时按重复上报处理,不新增记录;recordTime 不传即记录接收时间。| 方法 | 路径 | 权限 | 说明 |
|---|---|---|---|
| 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)。
| 字段 | 展示位置 | 说明 |
|---|---|---|
| 设备编号/名称/类型/型号/安装位置 | 设备列表、记录列表、看板 | 类型走字典 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,避免网络重试造成重复计数。