feat(ems/report): 新增电力图接口
添加物联环境监测按日分表的前端接口封装，包括： 1. 实现5个核心API接口 2. 定义完整的类型声明 3. 编写详细使用文档 4. 提供最佳实践建议main
parent
db0b2a9b6d
commit
8fbc702e86
@ -0,0 +1,352 @@
|
||||
# 物联环境监测前端接口文档
|
||||
|
||||
## 1. 目录说明
|
||||
|
||||
当前目录提供的是物联环境监测按日分表接口的前端封装：
|
||||
|
||||
- `types.ts`
|
||||
统一维护查询参数类型、返回项类型、振动字段枚举。
|
||||
- `index.ts`
|
||||
统一维护接口调用方法。
|
||||
|
||||
后端接口基路径：
|
||||
|
||||
```text
|
||||
/ems/record/iotEnvMonitorData
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 最推荐接口：`/latestAll`
|
||||
|
||||
### 2.1 使用场景
|
||||
|
||||
`/latestAll` 是前端首页、总览页、看板页最推荐优先调用的接口。
|
||||
|
||||
原因：
|
||||
|
||||
1. 前端不需要传任何参数。
|
||||
2. 前端不需要自己拼 `monitorIds`。
|
||||
3. 后端会自动从设备主数据中收集全部设备编码。
|
||||
4. 后端会自动回退到最近存在的日分表中，为每个设备取最新一条数据。
|
||||
5. 返回值已经按 `monitor_type` 做字段裁剪，前端不用再手动删无关字段。
|
||||
|
||||
### 2.2 请求定义
|
||||
|
||||
```http
|
||||
GET /ems/record/iotEnvMonitorData/latestAll
|
||||
```
|
||||
|
||||
请求参数：无
|
||||
|
||||
### 2.3 前端调用示例
|
||||
|
||||
```ts
|
||||
import { getIotEnvMonitorLatestAll } from '@/api/ems/report/recordIotenvInstant';
|
||||
|
||||
async function loadLatestAll() {
|
||||
const res = await getIotEnvMonitorLatestAll();
|
||||
const list = res.data ?? [];
|
||||
return list;
|
||||
}
|
||||
```
|
||||
|
||||
### 2.4 返回结构重点
|
||||
|
||||
接口返回外层仍然是项目统一的 `R` 结构：
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"msg": "操作成功",
|
||||
"data": []
|
||||
}
|
||||
```
|
||||
|
||||
重点注意：
|
||||
|
||||
1. 真正的数据列表在 `res.data`，不是 `res.rows`。
|
||||
2. `res.data` 中每一项都是 `Map` 风格对象，但前端已经在 `types.ts` 里补了联合类型。
|
||||
3. 每条记录都会保留公共字段：
|
||||
`objid`、`monitorId`、`monitorCode`、`monitorName`、`monitorType`、`energyName`、`collectTime`、`recodeTime`
|
||||
4. 每条记录只会返回当前设备类型有意义的测量字段。
|
||||
5. 无关字段不会返回。
|
||||
|
||||
### 2.5 返回示例
|
||||
|
||||
温度设备：
|
||||
|
||||
```json
|
||||
{
|
||||
"objid": 2042107207071436800,
|
||||
"monitorId": "E0001_2200",
|
||||
"monitorCode": "E0001_2200",
|
||||
"monitorName": "7.47.01",
|
||||
"monitorType": 5,
|
||||
"energyName": "温度",
|
||||
"temperature": 44.87,
|
||||
"collectTime": "2026-04-09 13:08:20",
|
||||
"recodeTime": "2026-04-09 13:07:53"
|
||||
}
|
||||
```
|
||||
|
||||
温湿度设备：
|
||||
|
||||
```json
|
||||
{
|
||||
"objid": 2036837406254174208,
|
||||
"monitorId": "E0012_4300",
|
||||
"monitorCode": "E0012_4300",
|
||||
"monitorName": "0033+CCC01",
|
||||
"monitorType": 6,
|
||||
"energyName": "温湿度",
|
||||
"temperature": 17.03,
|
||||
"humidity": 48.8,
|
||||
"collectTime": "2026-03-26 00:07:26",
|
||||
"recodeTime": "2026-03-26 00:07:35"
|
||||
}
|
||||
```
|
||||
|
||||
振动设备：
|
||||
|
||||
```json
|
||||
{
|
||||
"objid": 2036835875442266112,
|
||||
"monitorId": "E0014_3700",
|
||||
"monitorCode": "E0014_3700",
|
||||
"monitorName": "7.35.03",
|
||||
"monitorType": 10,
|
||||
"energyName": "振动",
|
||||
"vibrationSpeed": 0,
|
||||
"vibrationDisplacement": 0,
|
||||
"vibrationAcceleration": 0,
|
||||
"vibrationTemp": 27.6,
|
||||
"collectTime": "2026-03-26 00:01:01",
|
||||
"recodeTime": "2026-03-26 00:01:30"
|
||||
}
|
||||
```
|
||||
|
||||
### 2.6 `latestAll` 的边界行为
|
||||
|
||||
这个接口有两个很重要的前端认知点：
|
||||
|
||||
1. 即使某个设备当前没有实时数据，也可能仍然返回设备骨架。
|
||||
2. 这时会有设备公共字段，但测量值和时间字段可能是 `null`。
|
||||
|
||||
因此前端展示时建议：
|
||||
|
||||
1. 对测量值做 `?? '--'` 兜底。
|
||||
2. 对时间字段做空值判断。
|
||||
3. 根据 `monitorType` 决定展示哪个字段，不要假设每条记录都有相同字段。
|
||||
|
||||
示例：
|
||||
|
||||
```ts
|
||||
function resolvePrimaryValue(item: any) {
|
||||
switch (item.monitorType) {
|
||||
case 5:
|
||||
return item.temperature ?? '--';
|
||||
case 6:
|
||||
return `${item.temperature ?? '--'} / ${item.humidity ?? '--'}`;
|
||||
case 7:
|
||||
return item.noise ?? '--';
|
||||
case 8:
|
||||
return item.illuminance ?? '--';
|
||||
case 9:
|
||||
return item.concentration ?? '--';
|
||||
case 10:
|
||||
return item.vibrationTemp ?? '--';
|
||||
default:
|
||||
return '--';
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 其他接口一览
|
||||
|
||||
### 3.1 查询单设备某天最新值
|
||||
|
||||
```http
|
||||
GET /ems/record/iotEnvMonitorData/latest
|
||||
```
|
||||
|
||||
前端调用：
|
||||
|
||||
```ts
|
||||
getIotEnvMonitorLatest({
|
||||
date: '2026-04-09',
|
||||
monitorId: 'E0001_2200'
|
||||
});
|
||||
```
|
||||
|
||||
### 3.2 查询某天数据列表
|
||||
|
||||
```http
|
||||
GET /ems/record/iotEnvMonitorData/list
|
||||
```
|
||||
|
||||
前端调用：
|
||||
|
||||
```ts
|
||||
listIotEnvMonitorDataByDate({
|
||||
date: '2026-04-09',
|
||||
monitorIds: ['E0001_2200', 'E0012_4300'],
|
||||
startTime: '2026-04-09 08:00:00',
|
||||
endTime: '2026-04-09 18:00:00'
|
||||
});
|
||||
```
|
||||
|
||||
### 3.3 批量查询多个设备某天最新值
|
||||
|
||||
```http
|
||||
POST /ems/record/iotEnvMonitorData/latestBatch
|
||||
```
|
||||
|
||||
前端调用：
|
||||
|
||||
```ts
|
||||
getIotEnvMonitorLatestBatch({
|
||||
date: '2026-04-09',
|
||||
monitorIds: ['E0001_2200', 'E0012_4300']
|
||||
});
|
||||
```
|
||||
|
||||
### 3.4 按设备类型查询某天数据
|
||||
|
||||
```http
|
||||
GET /ems/record/iotEnvMonitorData/byType
|
||||
```
|
||||
|
||||
前端调用：
|
||||
|
||||
```ts
|
||||
listIotEnvMonitorDataByType({
|
||||
date: '2026-04-09',
|
||||
monitorType: 10,
|
||||
vibrationParam: 'vibrationSpeed'
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 参数格式约束
|
||||
|
||||
下面这些约束前端一定要遵守，因为后端已经改成严格解析：
|
||||
|
||||
### 4.1 `date`
|
||||
|
||||
仅支持两种格式：
|
||||
|
||||
```text
|
||||
yyyy-MM-dd
|
||||
yyyyMMdd
|
||||
```
|
||||
|
||||
正确示例：
|
||||
|
||||
```text
|
||||
2026-04-09
|
||||
20260409
|
||||
```
|
||||
|
||||
错误示例：
|
||||
|
||||
```text
|
||||
2026/04/09
|
||||
2026-4-9
|
||||
2026-02-29
|
||||
```
|
||||
|
||||
### 4.2 `startTime` / `endTime`
|
||||
|
||||
仅支持：
|
||||
|
||||
```text
|
||||
yyyy-MM-dd HH:mm:ss
|
||||
```
|
||||
|
||||
正确示例：
|
||||
|
||||
```text
|
||||
2026-04-09 08:00:00
|
||||
```
|
||||
|
||||
错误示例：
|
||||
|
||||
```text
|
||||
2026-04-09 8:00
|
||||
2026/04/09 08:00:00
|
||||
2026-04-09T08:00:00
|
||||
```
|
||||
|
||||
### 4.3 `monitorIds` 优先级
|
||||
|
||||
当 `monitorId` 和 `monitorIds` 同时传入时，后端会以 `monitorIds` 为主，忽略 `monitorId`。
|
||||
|
||||
前端建议：
|
||||
|
||||
1. 单设备查详情时只传 `monitorId`
|
||||
2. 多设备查列表或批量最新值时只传 `monitorIds`
|
||||
|
||||
---
|
||||
|
||||
## 5. 推荐调用策略
|
||||
|
||||
### 5.1 首页总览、总看板
|
||||
|
||||
优先调用：
|
||||
|
||||
```ts
|
||||
getIotEnvMonitorLatestAll()
|
||||
```
|
||||
|
||||
### 5.2 单设备详情卡片
|
||||
|
||||
优先调用：
|
||||
|
||||
```ts
|
||||
getIotEnvMonitorLatest({ date, monitorId })
|
||||
```
|
||||
|
||||
### 5.3 历史曲线
|
||||
|
||||
优先调用：
|
||||
|
||||
```ts
|
||||
listIotEnvMonitorDataByDate({ date, monitorId, startTime, endTime })
|
||||
```
|
||||
|
||||
### 5.4 某类设备总览
|
||||
|
||||
优先调用：
|
||||
|
||||
```ts
|
||||
listIotEnvMonitorDataByType({ date, monitorType })
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 导入方式
|
||||
|
||||
```ts
|
||||
import {
|
||||
getIotEnvMonitorLatestAll,
|
||||
getIotEnvMonitorLatest,
|
||||
listIotEnvMonitorDataByDate,
|
||||
getIotEnvMonitorLatestBatch,
|
||||
listIotEnvMonitorDataByType
|
||||
} from '@/api/ems/report/recordIotenvInstant';
|
||||
```
|
||||
|
||||
如果只需要类型：
|
||||
|
||||
```ts
|
||||
import type {
|
||||
IotEnvMonitorDataVO,
|
||||
IotEnvMonitorLatestQuery,
|
||||
IotEnvMonitorLatestBatchQuery,
|
||||
IotEnvMonitorByTypeQuery
|
||||
} from '@/api/ems/report/recordIotenvInstant/types';
|
||||
```
|
||||
Loading…
Reference in New Issue