工位客户端设备状态上报接口说明

服务根地址：http://127.0.0.1:8980
上下文路径：/js
管理路径：/a
接口无需登录（Shiro 已配置 anon）
上报数据用于 设备综合效率管理大屏（mesDeviceOeeScreen）的开动率、状态总览、最后上报时间等展示

一、背景说明

1.1 大屏数据来源

设备综合效率大屏通过接口 POST /js/a/mes/mesDevice/oeeScreenData 聚合展示，核心数据来自：

数据表	用途
`mes_device`	设备主数据（名称、编号、产线、当前工作状态）
`mes_device_state`	设备状态变更历史（开始时间、结束时间、持续时长）

大屏当前展示的是 时间开动率（基于状态记录计算），不是完整 OEE（缺少计划产量、良品数、理想节拍）。

1.2 客户端上报原则

时机	建议 state	说明
工位登录成功	`1`	标记设备开始运行，开动率从此刻累计
工位退出 / 收班	非 `1`/`2`	停止开动率累计，刷新「最后上报」
运行中心跳（可选）	`1`	建议每 5～15 分钟一次，避免「最后上报」长期不更新
故障 / 报警 / 维修	`3`/`4`/`5`/`6`	状态变化时立即上报
故障恢复	`1`	恢复运行

注意：若工位登录后上报 state=1，但退出时不上报，设备会一直保持「运行」状态，大屏开动率可能虚高（即使「最后上报」已过期）。

二、设备状态码

字典类型：mes_device_state

state	含义	大屏归类	是否计入开动率
`1`	正常	运行	是
`2`	手动	运行	是
`3`	故障	故障	否
`4`	维修	维修	否
`5`	质量报警	报警	否
`6`	物流堵料	报警	否

当前字典 没有「停机 / 待机」 专用状态。工位退出时可暂用 4（维修/收班），或与现场统一约定后再调整；后续可在字典中扩展 0「停机」等状态。

三、推荐接口：上报设备状态（JSON）

工位客户端 优先使用本接口，参数少、支持 JSON，与项目 api.http 示例一致。

3.1 基本信息

项	说明
请求 URL	`POST {baseUrl}/js/a/mes/mesProductRecord/device`
示例	`http://192.168.1.100:8980/js/a/mes/mesProductRecord/device`
Content-Type	`application/json` 或 `application/x-www-form-urlencoded`
鉴权	无需登录，无需 `__sid` / token

3.2 请求参数

参数	类型	必填	说明
oprno	string	是	设备编号，对应 `mes_device.sn`（大屏「设备编号」，如 `115OP030`）
lineSn	string	建议	产线编号，与设备档案一致（如 `115XT`）
state	string	是	设备状态码，见二、设备状态码
content	string	否	状态描述，大屏设备卡片会展示（如「工位登录，开始运行」）
codes	string	否	故障码，一般场景可不传

3.3 响应格式

JeeSite 标准 JSON 字符串：

{
  "result": "true",
  "message": "操作成功！"
}

失败示例：

{
  "result": "false",
  "message": "错误信息"
}

3.4 请求示例

工位登录 — 上报运行

POST /js/a/mes/mesProductRecord/device
Content-Type: application/json

{
  "oprno": "115OP030",
  "lineSn": "115XT",
  "state": "1",
  "content": "工位登录，开始运行"
}

工位退出 — 停止运行

POST /js/a/mes/mesProductRecord/device
Content-Type: application/json

{
  "oprno": "115OP030",
  "lineSn": "115XT",
  "state": "4",
  "content": "工位退出，停止运行"
}

运行心跳（可选）

POST /js/a/mes/mesProductRecord/device
Content-Type: application/json

{
  "oprno": "115OP030",
  "lineSn": "115XT",
  "state": "1",
  "content": "运行心跳"
}

设备故障

POST /js/a/mes/mesProductRecord/device
Content-Type: application/json

{
  "oprno": "115OP030",
  "lineSn": "115XT",
  "state": "3",
  "content": "设备故障：伺服报警"
}

form 表单方式（等价）

POST /js/a/mes/mesProductRecord/device
Content-Type: application/x-www-form-urlencoded

__ajax=json&oprno=115OP030&lineSn=115XT&state=1&content=工位登录，开始运行

四、备选接口：上报设备状态（Form）

适用于不便发送 JSON 的客户端（如部分 PLC 网关、老旧 WinForm 组件）。

4.1 基本信息

项	说明
请求 URL	`POST {baseUrl}/js/a/mes/mesProductRecord/deviceState`
Content-Type	`application/x-www-form-urlencoded`
鉴权	无需登录

4.2 请求参数

参数	类型	必填	说明
oprno	string	是	设备编号
state	string	是	设备状态码
productCate	string	是	产线编号（等同 `lineSn`）
deviceContent	string	否	状态描述
paramsNums	int	是	无故障码时固定传 `0`
errorCode	string	否	故障码；`paramsNums=0` 时可传空字符串

4.3 响应格式

CommonResp 结构：

字段	类型	说明
result	string	`"true"` 成功 / `"false"` 失败
message	string	提示信息
data	string	成功时为 `{state}OK`，如 `"1OK"`

{
  "result": "true",
  "message": "成功",
  "data": "1OK"
}

4.4 请求示例

POST /js/a/mes/mesProductRecord/deviceState
Content-Type: application/x-www-form-urlencoded

oprno=115OP030&state=1&productCate=115XT&deviceContent=工位登录&paramsNums=0&errorCode=

五、TCP 报文方式（MSBW，可选）

若工位客户端通过 Netty TCP 网关 与 MES 通信，可使用设备状态报文 MSBW（与 HTTP 接口写入同一张表）。

项	说明
报文类型	`MSBW`
处理入口	`MesProductRecordController.deviceState(msg)`
说明	一般由设备网关 / 产线控制器上报，工位 WinForm 客户端通常直接用 HTTP 即可

报文示例（注释格式，实际为定长协议）：

aaaabbbbbABWMSBWGWOP040 LX01ID151245P00000106200123062900001      DA2023-08-18ZT14:32:33

GWOP040：工位号（oprno）
LX01：状态码（01 → state=1）
产线等信息按 ProtocolParam 解析

工位客户端集成 建议优先 HTTP /device 接口，无需拼装 TCP 定长报文。

六、客户端集成流程

┌─────────────┐     登录成功      ┌──────────────────────────────┐
│  工位客户端  │ ───────────────► │ POST /device  state=1        │
└─────────────┘                   └──────────────────────────────┘
       │                                        │
       │  运行中（可选，每 5~15 分钟）            ▼
       ├──────────────────────────────► mes_device_state 新增记录
       │                                        │
       │  退出 / 收班                           ▼
       └──────────────────────────────► POST /device  state=4（或非 1/2）
                                                │
                                                ▼
                                    上一条记录闭合 end_date / interval
                                                │
                                                ▼
                                    大屏 oeeScreenData 刷新展示

6.1 集成检查清单

oprno 与 mes_device.sn 一致（可在 MES 设备管理模块核对）
lineSn 与设备档案产线一致
登录成功后调用 /device，state=1
退出 / 关闭客户端前调用 /device，state 为非运行状态
（可选）运行中定时心跳，state=1
故障、报警发生时即时上报对应 state

6.2 C# 调用示例

using System.Net.Http;
using System.Text;
using System.Text.Json;

public static async Task<bool> ReportDeviceStateAsync(
    string baseUrl, string oprno, string lineSn, string state, string content)
{
    using var client = new HttpClient();
    var payload = new { oprno, lineSn, state, content };
    var json = JsonSerializer.Serialize(payload);
    var resp = await client.PostAsync(
        $"{baseUrl.TrimEnd('/')}/js/a/mes/mesProductRecord/device",
        new StringContent(json, Encoding.UTF8, "application/json"));
    var body = await resp.Content.ReadAsStringAsync();
    return body.Contains("\"result\":\"true\"");
}

// 工位登录
await ReportDeviceStateAsync("http://192.168.1.100:8980", "115OP030", "115XT", "1", "工位登录，开始运行");

// 工位退出
await ReportDeviceStateAsync("http://192.168.1.100:8980", "115OP030", "115XT", "4", "工位退出，停止运行");

6.3 JavaScript 调用示例

async function reportDeviceState(baseUrl, oprno, lineSn, state, content) {
  const resp = await fetch(`${baseUrl}/js/a/mes/mesProductRecord/device`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ oprno, lineSn, state, content })
  });
  return resp.json();
}

// 工位登录
await reportDeviceState('http://192.168.1.100:8980', '115OP030', '115XT', '1', '工位登录，开始运行');

七、服务端处理逻辑（供联调参考）

上报成功后，服务端执行：

mes_device_state：闭合上一条记录的 end_date、interval，插入新状态记录（start_date 为当前时间）
mes_device：更新 work_status、work_time

大屏 oeeScreenData 读取逻辑摘要：

当前状态：取 mes_device_state 最新一条；无记录则用 mes_device.work_status
开动率：统计当日 state 为 1 或 2 的累计时长 ÷ 当日已过时长
最后上报：最新状态记录的 start_date；无记录则用 mes_device.work_time

八、常见问题

Q1：`oprno` 填工位号还是设备编号？

填 mes_device.sn（设备档案中的「唯一编号 / 设备编号」）。大屏卡片「设备编号」列即此字段。若工位与设备一一对应，需先在 MES 设备管理中确认映射关系。

Q2：退出时 state 传什么？

当前无「停机」状态，建议退出传 4，content 注明「工位退出」。若业务需要独立「待机」状态，需先在字典 mes_device_state 中扩展并在 OEE 计算逻辑中适配。

Q3：同一状态重复上报会怎样？

/device 接口每次调用都会 新增一条记录 并闭合上一条，开动率统计仍正确；可用于心跳刷新「最后上报」时间。

Q4：接口需要登录吗？

不需要。application.yml 中已配置：

${adminPath}/mes/mesProductRecord/device = anon
${adminPath}/mes/mesProductRecord/deviceState = anon

Q5：上报失败如何排查？

确认 oprno 在 mes_device 表中存在
确认 state 为 1～6 的有效值
查看 MES 接口日志（mes_log 表，apisave2 会记录请求内容）

九、相关代码位置

模块	路径
HTTP 接口（推荐）	`MesProductRecordController.device()`
HTTP 接口（Form）	`MesProductRecordController.deviceStateApi()`
TCP MSBW	`MesProductRecordController.deviceState()`
状态持久化	`MesDeviceStateService.updateState()`
OEE 大屏数据	`MesDeviceController.oeeScreenData()`
大屏页面	`src/main/resources/views/modules/mes/mesDeviceOeeScreen.html`
请求体 DTO	`com.jeesite.modules.mes.req.MesDeviceStateReq`

十、修订记录

日期	说明
2026-06-30	初版：工位客户端设备状态上报接口说明

工位客户端设备状态上报接口说明.md 12 KB Historik Rå