# 物联环境监测前端接口文档

## 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';
```
