# 设备数采（设备数据采集）· 前端联调方案

## 涉及页面

| 页面 | 路由 | 说明 |
|------|------|------|
| 设备数采 | 设备管理 → 设备数采 | 实时数据（各设备最新遥测）+ 历史记录两个 Tab + 拉取按钮 + 实时自动刷新 |
| 设备台账 | 设备管理 → 设备台账 | 表单新增「数采设备ID」字段；查看详情新增「数采数据」Tab 展示该设备实时信号 |

## 业务流程与数据带入

1. **拉取数据**：页面点击「拉取最新数据」→ 调 `/mes/dv/telemetry/pull` → 后端调外部数采接口 `GET /api/jxjs/mesTb/getDeviceDetails`（近 5 分钟设备数据）→ 逐条写入 `mes_dv_telemetry` → 返回本次新增条数/设备数/拉取时间。
2. **实时查看**：实时数据 Tab 调 `/mes/dv/telemetry/latest`，按「设备+信号」去重保留最新一条；可开启「实时自动刷新」每 30 秒轮询一次。
3. **历史查看**：历史记录 Tab 调 `/mes/dv/telemetry/page` 分页，支持设备名称/信号名称/是否异常/遥测时间区间过滤。
4. **定时拉取**：系统内置定时任务「设备数采数据拉取」每 5 分钟自动拉取一次，避免近 5 分钟窗口数据丢失（页面无需感知）。
5. **设备关联**：设备台账表单手工维护「数采设备ID」（`tb_device_id`，对应外部数采 `tbDeviceId`）；台账详情「数采数据」Tab 用该 ID 调 `/latest?tbDeviceId=xx` 展示该设备实时信号。未填数采设备ID时该 Tab 置灰。

## API

### 1. 拉取数据 `GET /mes/dv/telemetry/pull`

无请求参数。权限 `mes:dv-telemetry:query`。

**响应：**

```json
{
  "code": 0,
  "data": {
    "recordCount": 120,
    "deviceCount": 8,
    "pullTime": "2026-08-20 10:00:00"
  }
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| recordCount | Integer | 本次拉取新增数据条数 |
| deviceCount | Integer | 本次拉取涉及设备数 |
| pullTime | String | 拉取时间 |

> 外部接口未配置 `base-url` / 调用失败 / 返回异常时，返回错误码 `数采数据拉取失败：xxx`；接口正常但近 5 分钟无数据时 recordCount=0（不报错）。

### 2. 实时数据 `GET /mes/dv/telemetry/latest`

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| tbDeviceId | String | 否 | 数采设备ID |
| deviceName | String | 否 | 设备名称（模糊） |

**响应：** `data` 为数组，每项为一条「设备+信号」最新遥测记录（字段见下表）。

### 3. 历史记录 `GET /mes/dv/telemetry/page`

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| pageNo / pageSize | Integer | 是 | 分页 |
| tbDeviceId | String | 否 | 数采设备ID |
| deviceName | String | 否 | 设备名称（模糊） |
| paramName | String | 否 | 信号名称（模糊） |
| whetherAnomaly | Boolean | 否 | 是否异常（true/false） |
| shiftName | String | 否 | 班次 |
| telemetryDataTime | String[] | 否 | 遥测时间区间，`yyyy-MM-dd HH:mm:ss` |

**响应：** `data` 为 `PageResult`，`records` 字段同下表。

### 4. 设备下拉 `GET /mes/dv/telemetry/device-list`

无参数。返回遥测表中已出现的设备去重列表：`[{ tbDeviceId, deviceName }]`，供筛选下拉使用。

### 遥测记录字段（latest / page 通用）

| 字段 | 类型 | 说明 |
|------|------|------|
| id | Long | 编号 |
| tbDeviceId | String | 数采设备ID |
| deviceName | String | 设备名称 |
| paramName | String | 信号名称 |
| paramKeyName | String | 设备KEY名称 |
| standardValue | String | 标准值 |
| timelyValue | String | 信号值（实时） |
| avgValue | String | 均值 |
| maxValue | String | 最大值 |
| minValue | String | 最小值 |
| whetherAnomaly | Boolean | 是否异常（true=异常） |
| telemetryDataTime | String | 遥测数据时间 |
| billNo | String | 单据号 |
| shiftName | String | 班次 |
| pullTime | String | 拉取时间 |
| createTime | String | 创建时间 |

## 字段展示规则

| 字段 | 展示位置 | 说明 |
|------|----------|------|
| deviceName | 实时/历史列表、筛选 | 设备名称 |
| paramName | 实时/历史列表 | 信号名称 |
| timelyValue | 实时/历史列表 | 信号值（实时） |
| whetherAnomaly | 实时/历史列表、历史筛选 | 布尔渲染为 Tag：正常(绿)/异常(红)；筛选用布尔选项 正常/异常 |
| shiftName | 实时/历史列表 | 班次 |
| telemetryDataTime | 实时/历史列表、历史筛选 | 遥测时间，`YYYY-MM-DD HH:mm:ss` |
| standardValue / avgValue / maxValue / minValue | 实时列表 | 标准值 / 均值 / 最大值 / 最小值 |
| billNo | 历史列表 | 单据号 |
| pullTime | 历史列表 | 拉取时间 |
| 最近拉取时间 | 页面顶部 | 拉取成功后回显 pullTime |

## 业务规则说明

| 场景 | 规则 |
|------|------|
| 数据拉取 | 手动按钮 + 定时任务（每 5 分钟）均可触发，写入 `mes_dv_telemetry` |
| 实时数据 | 按「tbDeviceId + paramKeyName」去重保留最新，展示最近一次拉取结果 |
| 历史数据 | 每次拉取全量入库（含重复信号），按遥测时间倒序分页 |
| 设备关联 | 设备台账 `tb_device_id` 与外部数采 `tbDeviceId` 对应；未填则台账详情「数采数据」Tab 禁用 |
| 是否异常 | 后端 `bit` 字段映射 Boolean；前端直接按布尔渲染，不依赖字典 |
| 定时任务 | 默认每 5 分钟执行，可在「系统管理 → 定时任务」调整/停用 |

## 注意事项

- 数采服务地址在后端 `yudao.mes.telemetry.base-url` 配置（`application-local.yaml`），未配置时 `/pull` 报「数采数据拉取失败」。
- 外部接口仅保留近 5 分钟数据，超过不拉即丢；建议保持定时任务运行，页面手动拉取仅做实时刷新用。
- 历史记录数据量会持续增长，查询建议带遥测时间区间过滤。
- 数采遥测为外部数据，只读展示，无新增/修改/删除/导出操作，仅一个「查询」按钮权限 `mes:dv-telemetry:query`。