设备数采 · API 调试记录

说明：本文档基于后端代码（yudao-module-mes 的 controller/admin/dv/telemetry）静态整理，供联调、回归、排查使用。示例报文字段对齐当前数据库真实样本（截至 2026-09-09）。

一、模块与数据流概述

所属模块：**MES 设备管理 → 设备数采**（前端 views/mes/dv/telemetry/）。
业务数据全部来自**外部数采服务**（近 5 分钟窗口），由后端拉取后落库到本地 mes_dv_telemetry，页面只读查询。
数采接口均无新增/修改/删除/导出操作，仅有 1 个拉取 + 5 个查询 接口，统一权限 mes:dv-telemetry:query。
落库表 mes_dv_telemetry 现状：**296 条 / 4 台设备**。

设备名称	tbDeviceId	记录数	遥测时间范围
单轴高低压-3	773544054188146757	64	2026-08-28 10:59:10
单轴高低压-4	773543983287631941	128	2026-08-28 10:59:09 ~ 2026-09-09 10:59:20
单轴高低压-5-改造	773543911229489221	64	2026-08-28 11:00:02
真空浇筑机	773543828480065605	40	2026-08-28 10:59:53 ~ 2026-09-09 10:59:38

注：单轴高低压-3、-5-改造数据停留在 08-28，说明近几天数采服务仅对部分设备持续产出数据，属外部数据侧现状。

数据流

[外部数采服务] --GET 近5分钟--> MesDvTelemetryPullJob(定时/手动) --convert+insertBatch--> mes_dv_telemetry
                                                                        |
                        页面 latest / page / check / check-summary <----┘ (只读)

二、调试前置条件

项	值	说明
接口前缀	`http://<服务器IP>:<端口>/admin-api`	后端服务地址
鉴权	`Authorization: Bearer <token>`	先登录获取 token
登录接口	`POST /admin-api/system/auth/login`	Body `{ "username": "…", "password": "…" }`，响应 `data.accessToken`
权限	`mes:dv-telemetry:query`	当前用户需拥有该权限，否则返回 403
数据表	`mes_dv_telemetry`（库 `mom-xgdl`）	无写库场景，仅拉取写入

通用请求头示例

GET /admin-api/mes/dv/telemetry/latest HTTP/1.1
Host: <服务器IP>:<端口>
Authorization: Bearer <token>

通用响应壳（所有接口）：

{ "code": 0, "msg": "", "data": … }

code = 0 成功；非 0 为业务/系统错误，见 msg。

数采服务地址配置（拉取 /pull 依赖）

配置项 yudao.mes.telemetry（MesTelemetryProperties）：

项	当前值(application-local.yaml)	说明
`base-url`	`http://106.227.91.252:3100`	数采服务基础地址，未配置时 /pull 报错
`path`	`/api/jxjs/mesTb/getDeviceDetails`	返回近 5 分钟设备数据

若切换其它运行 profile，请同步对应 yaml（local / test 等多 profile 保持一致）。

三、外部数采接口约定（/pull 后端代调）

后端 /pull 会以 HTTP GET 调用：

GET {base-url}{path}   (无参，返回近 5 分钟设备数据)

期望响应结构：

{
  "code": "200",
  "data": [
    {
      "tbDeviceId": "773543983287631941",
      "deviceName": "单轴高低压-4",
      "paramName": "Slave1@油变_总匝数设定",
      "paramKeyName": "Slave1@油变_总匝数设定",
      "standardValue": null,
      "timelyValue": "500",
      "avgValue": "500.00",
      "maxValue": "500",
      "minValue": "500",
      "whetherAnomaly": false,
      "telemetryDataTime": "2026-09-09 10:59:20",
      "billNo": null,
      "shiftName": "早班"
    }
  ]
}

字段 → 表列映射：

外部字段	表列	类型(库)	说明
tbDeviceId	tb_device_id	varchar(100)	数采设备ID，与设备台账 `tb_device_id` 对应
deviceName	device_name	varchar(100)	设备名称
paramName	param_name	varchar(100)	信号名称（展示名）
paramKeyName	param_key_name	varchar(100)	设备 KEY 名称（去重键）
standardValue	standard_value	varchar(64)	标准值
timelyValue	timely_value	varchar(64)	信号值（实时）
avgValue	avg_value	varchar(64)	均值
maxValue	max_value	varchar(64)	最大值
minValue	min_value	varchar(64)	最小值
whetherAnomaly	whether_anomaly	bit(1)	是否异常；接受 `1/0/true/false/Y/N` 字符串
telemetryDataTime	telemetry_data_time	datetime	遥测时间，后端按通用日期格式解析
billNo	bill_no	varchar(64)	单据号
shiftName	shift_name	varchar(64)	班次

容错规则（/pull 侧）：
- 外部 code != "200" → 报错「数采数据拉取失败：数采接口返回异常」。
- 外部返回 data 为空数组 → 正常返回 recordCount=0, deviceCount=0（不报错）。
- data 内某行不是 JSON 对象 → 该行跳过。

四、接口明细

统一路径前缀 /admin-api/mes/dv/telemetry，下同；以下均需 Authorization: Bearer，权限均 mes:dv-telemetry:query。

1. 拉取数采数据 `GET /pull`

无请求参数。后端调用外部数采接口并批量入库，返回本次统计。

请求：

curl "http://<服务器IP>:<端口>/admin-api/mes/dv/telemetry/pull" -H "Authorization: Bearer <token>"

正常响应（有数据）：

{
  "code": 0,
  "data": {
    "recordCount": 40,
    "deviceCount": 2,
    "pullTime": "2026-09-09 11:02:29"
  }
}

正常响应（近 5 分钟无数据）：

{ "code": 0, "data": { "recordCount": 0, "deviceCount": 0, "pullTime": "2026-09-09 11:02:29" } }

data 字段	类型	说明
recordCount	Integer	本次入库条数
deviceCount	Integer	本次涉及设备数（按 tbDeviceId 去重）
pullTime	LocalDateTime	拉取时间（入库批量共用）

异常场景：

code	触发条件
1_040_308_001（数采数据拉取失败：xxx）	未配置 base-url / 外部调用异常 / 返回为空 / code≠200

排查：外部服务地址是否可达（当前 base-url 为公网/内网地址，网络不通时即报错）；外部 code 是否字符串 "200"。

2. 历史记录分页 `GET /page`

参数	类型	必填	说明
pageNo	Integer	是	页码，从 1 开始
pageSize	Integer	是	每页条数
tbDeviceId	String	否	数采设备ID（精确）
deviceName	String	否	设备名称（模糊 like）
paramName	String	否	信号名称（模糊 like）
whetherAnomaly	Boolean	否	true=异常 / false=正常
shiftName	String	否	班次（精确）
telemetryDataTime	String[]	否	遥测时间区间 `[起,止]`，格式 `yyyy-MM-dd HH:mm:ss`

请求：

curl "http://<服务器IP>:<端口>/admin-api/mes/dv/telemetry/page?pageNo=1&pageSize=10&shiftName=%E6%97%A9%E7%8F%AD&whetherAnomaly=false" -H "Authorization: Bearer <token>"

正常响应：

{
  "code": 0,
  "data": {
    "total": 128,
    "list": [
      {
        "id": 410,
        "tbDeviceId": "773543983287631941",
        "deviceName": "单轴高低压-4",
        "paramName": "Slave1@六段出头一设定",
        "paramKeyName": "Slave1@六段出头一设定",
        "standardValue": null,
        "timelyValue": "0",
        "avgValue": "0",
        "maxValue": "0",
        "minValue": "0",
        "whetherAnomaly": false,
        "telemetryDataTime": "2026-09-09 10:59:20",
        "billNo": null,
        "shiftName": "早班",
        "pullTime": "2026-09-09 11:02:29",
        "createTime": "2026-09-09 11:02:29"
      }
    ]
  }
}

分页返回结构： 顶层 data.total（Long）+ data.list（数组）——注意是 list，不是 records，前端按 { total, list } 解析。

排序：telemetry_data_time 倒序，再按 id 倒序。历史表为“每次拉取全量追加”，同信号会重复多行，联调注意用时间区间过滤。

3. 各设备最新遥测（实时监控）`GET /latest`

参数	类型	必填	说明
tbDeviceId	String	否	精确过滤单台设备（设备台账「数采数据」Tab 用）
deviceName	String	否	设备名称模糊过滤

实现要点： 取 mes_dv_telemetry 最近 5000 条（按遥测时间倒序），内存按 tbDeviceId + paramKeyName 去重保留最新，返回**裸数组**。

请求：

curl "http://<服务器IP>:<端口>/admin-api/mes/dv/telemetry/latest" -H "Authorization: Bearer <token>"
curl "http://<服务器IP>:<端口>/admin-api/mes/dv/telemetry/latest?tbDeviceId=773543828480065605" -H "Authorization: Bearer <token>"

正常响应（裸数组）：

{
  "code": 0,
  "data": [
    {
      "id": 380,
      "tbDeviceId": "773543828480065605",
      "deviceName": "真空浇筑机",
      "paramName": "信号名称示例",
      "paramKeyName": "key@示例",
      "standardValue": null,
      "timelyValue": "0",
      "avgValue": "0",
      "maxValue": "0",
      "minValue": "0",
      "whetherAnomaly": false,
      "telemetryDataTime": "2026-09-09 10:59:38",
      "billNo": null,
      "shiftName": "早班",
      "pullTime": "2026-09-09 11:02:29",
      "createTime": "2026-09-09 11:02:29"
    }
  ]
}

边界提醒：
- 返回是数组，不是分页对象，前端需关闭分页组件解析，否则空展示。
- 无数据时返回 []（code 仍为 0）。
- 去重上限 5000 条，若历史数据量巨大导致一批内某设备早于 5000 条之外，该设备可能缺项。

4. 数采设备下拉 `GET /device-list`

无参数。从遥测表按 tb_device_id + device_name 分组去重返回。

curl "http://<服务器IP>:<端口>/admin-api/mes/dv/telemetry/device-list" -H "Authorization: Bearer <token>"

正常响应：

{
  "code": 0,
  "data": [
    { "tbDeviceId": "773543911229489221", "deviceName": "单轴高低压-5-改造" },
    { "tbDeviceId": "773543828480065605", "deviceName": "真空浇筑机" },
    { "tbDeviceId": "773544054188146757", "deviceName": "单轴高低压-3" },
    { "tbDeviceId": "773543983287631941", "deviceName": "单轴高低压-4" }
  ]
}

该下拉仅列出**已出现在遥测表**的设备；若某台账设备从未被拉取过，不会出现在此。

5. 供电参数比对校验明细 `GET /check`

当前实现与 /latest 完全一致（同一 service 方法），仅前端展示口径不同（明细逐行对比 timelyValue 与 standardValue）。

参数	类型	必填	说明
tbDeviceId	String	否	设备过滤
deviceName	String	否	设备名称模糊过滤

请求/响应结构与 /latest 相同（返回裸数组）。

响应字段比对含义：

字段	在比对页的用途
timelyValue	实时采集值
standardValue	供电标准值
whetherAnomaly	true=偏离标准（异常）

注意：当前后端仅**透传**外部数据的 standardValue / whetherAnomaly，未在内部做阈值计算。若外部未上报标准值（现库中 standard_value 为空），比对结论主要依赖 whetherAnomaly。

6. 供电参数比对校验统计 `GET /check-summary`

基于 /latest（同上去重后的每设备最新参数行）按设备聚合统计。

参数	类型	必填	说明
tbDeviceId	String	否	指定设备；不传则汇总全部设备
deviceName	String	否	设备名称模糊过滤

curl "http://<服务器IP>:<端口>/admin-api/mes/dv/telemetry/check-summary?tbDeviceId=773543983287631941" -H "Authorization: Bearer <token>"

正常响应：

{
  "code": 0,
  "data": [
    {
      "tbDeviceId": "773543983287631941",
      "deviceName": "单轴高低压-4",
      "totalCount": 64,
      "normalCount": 64,
      "anomalyCount": 0,
      "anomalyRate": 0.0
    }
  ]
}

data 字段	类型	说明
tbDeviceId / deviceName	String	设备
totalCount	Integer	该设备最新参数行数
normalCount	Integer	正常（whetherAnomaly=false）数
anomalyCount	Integer	异常（whetherAnomaly=true）数
anomalyRate	BigDecimal	异常率%，保留 1 位小数（四舍五入）；无参数时为 0

统计口径： totalCount = 设备在“最近 5000 条去重后”的信号数；anomalyRate = anomalyCount * 100.0 / totalCount（异常率百分比）。当前库中 4 台设备异常率均为 0（无异常行）。

五、遥测记录公共字段（page / latest / check 通用）

字段	类型	说明
id	Long	编号
tbDeviceId	String	数采设备ID
deviceName	String	设备名称
paramName	String	信号名称
paramKeyName	String	设备KEY名称（去重键）
standardValue	String	标准值（可能为空）
timelyValue	String	信号值（实时）
avgValue / maxValue / minValue	String	均值/最大/最小
whetherAnomaly	Boolean	true=异常，false=正常
telemetryDataTime	LocalDateTime	遥测数据时间
billNo	String	单据号（可能为空）
shiftName	String	班次（字典类文本直存）
pullTime	LocalDateTime	本次拉取入库时间
createTime	LocalDateTime	创建时间

六、调试注意事项与排查清单

鉴权/权限：401 检查 token 是否过期；403 检查是否缺 mes:dv-telemetry:query。
/pull 依赖外网/内网数采服务：当前 base-url http://106.227.91.252:3100 非本机，网络不可达时直接报「数采数据拉取失败」。可在服务器侧 curl http://106.227.91.252:3100/api/jxjs/mesTb/getDeviceDetails 前置验证。
5 分钟窗口：外部接口仅保留近 5 分钟数据，超过即丢。系统默认由定时任务（MesDvTelemetryPullJob，建议每 5 分钟）兜底；页面手动 /pull 仅用于实时补拉。
分页字段：/page 返回 { total, list }，不是 records；/latest、/check、/check-summary、/device-list 返回裸数组，前端不可开启分页组件解析。
whetherAnomaly 布尔：库列为 bit(1)，响应为 Boolean；布尔过滤传 true/false。
去重上限：/latest 系列仅取最近 5000 条做去重，数据量增长后注意设备是否缺项。
standardValue 缺失：现库中标准值全为空，/check 比对主要看 whetherAnomaly，联调时注意界面空值展示。
时间过滤：telemetryDataTime 传 yyyy-MM-dd HH:mm:ss 数组；历史表持续增长，查询建议必带时间区间。

七、数据自查 SQL（调试辅助）

-- 拉取落库是否成功：最近一次拉取
SELECT pull_time, COUNT(*) FROM `mom-xgdl`.`mes_dv_telemetry` GROUP BY pull_time ORDER BY pull_time DESC LIMIT 5;

-- 各设备记录与异常概况
SELECT device_name, COUNT(*) total,
       SUM(whether_anomaly = 1) anomaly
FROM `mom-xgdl`.`mes_dv_telemetry` GROUP BY device_name;

-- 单设备最近信号
SELECT param_name, timely_value, whether_anomaly, telemetry_data_time
FROM `mom-xgdl`.`mes_dv_telemetry`
WHERE tb_device_id = '773543983287631941' ORDER BY id DESC LIMIT 20;

设备数采 · API 调试记录

一、模块与数据流概述

数据流

二、调试前置条件

数采服务地址配置（拉取 /pull 依赖）

三、外部数采接口约定（/pull 后端代调）

四、接口明细

1. 拉取数采数据 GET /pull

2. 历史记录分页 GET /page

3. 各设备最新遥测（实时监控）GET /latest

4. 数采设备下拉 GET /device-list

5. 供电参数比对校验明细 GET /check

6. 供电参数比对校验统计 GET /check-summary

五、遥测记录公共字段（page / latest / check 通用）

六、调试注意事项与排查清单

七、数据自查 SQL（调试辅助）

1. 拉取数采数据 `GET /pull`

2. 历史记录分页 `GET /page`

3. 各设备最新遥测（实时监控）`GET /latest`

4. 数采设备下拉 `GET /device-list`

5. 供电参数比对校验明细 `GET /check`

6. 供电参数比对校验统计 `GET /check-summary`