leida_simi/设备状态查询接口文档.md

# 设备状态查询接口文档

## 基本信息

| 项目 | 说明 |
|------|------|
| 协议 | HTTP/1.1 |
| 方法 | GET |
| Content-Type | application/json; charset=UTF-8 |

---

## 1. 设备状态查询

### 接口地址

```
GET /api/v1/device/status
```

查询所有传感器的实时状态数据。

---


#### 示例

```
GET /api/v1/device/status HTTP/1.1
```

---

### 响应参数

#### 公共字段

| 字段 | 类型 | 说明 |
|------|------|------|
| code | int | 状态码，200=成功，400=失败 |
| message | String | 状态描述，成功时返回 `success`，失败时返回错误信息 |
| data | Array | 传感器数组，每个元素为一个传感器对象；失败时为 `null` |

#### data 传感器对象

| 字段 | 类型 | 说明 |
|------|------|------|
| name | String | 传感器名称 |
| code | String | 传感器编码 |
| data | Array | 该传感器的测量数据数组 |

#### data 测量数据对象

| 字段 | 类型 | 说明 |
|------|------|------|
| name | String | 测量项名称，如"温度"、"湿度" |
| value | float | 测量值 |
| unit | String | 单位，如"℃"、"%"、"°" |

---

---

### 响应示例

#### 成功响应（200）

```json
{
  "code": 200,
  "message": "success",
  "data": [
    {
      "name": "东侧温湿度传感器",
      "code": "ws_01",
      "data": [
        {
          "unit": "℃",
          "value": 25.6,
          "name": "温度"
        },
        {
          "unit": "%",
          "value": 68,
          "name": "湿度"
        }
      ]
    },
    {
      "name": "南侧倾斜传感器",
      "code": "qx_01",
      "data": [
        {
          "unit": "°",
          "value": 3.0,
          "name": "X轴倾斜"
        },
        {
          "unit": "%",
          "value": -0.8,
          "name": "Y轴倾斜"
        }
      ]
    },
    {
      "name": "北侧水浸传感器",
      "code": "sj_01",
      "data": [
        {
          "unit": "",
          "value": 0,
          "name": "漏水状态"
        }
      ]
    },
    {
      "name": "北侧烟感传感器",
      "code": "yw_01",
      "data": [
        {
          "unit": "",
          "value": 0,
          "name": "烟雾浓度"
        }
      ]
    }
  ]
}
```

#### 失败响应（400）

```json
{
  "code": 400,
  "message": "Error",
  "data": null
}
```

---

## 2. 设备报警查询

### 接口地址

```
GET /api/v1/device/alarm
```

查询当前所有设备的报警信息。

#### 示例

```
GET /api/v1/device/alarm HTTP/1.1
```

---

### 响应参数

#### 公共字段

| 字段 | 类型 | 说明 |
|------|------|------|
| code | int | 状态码，200=成功，400=失败 |
| message | String | 状态描述 |
| data | Array | 报警信息数组；无报警时为空数组 `[]`；失败时为 `null` |

#### data 报警对象

| 字段 | 类型 | 说明 |
|------|------|------|
| alarm_id | String | 报警唯一标识 |
| sensor_code | String | 触发报警的传感器编码 |
| sensor_name | String | 触发报警的传感器名称 |
| alarm_level | String | 报警等级：1=警告，2=报警，3=严重报警 |
| alarm_level_name | String | 报警等级：1=警告，2=报警，3=严重报警 |
| alarm_value | float | 触发报警时的传感器数值 |
| alarm_threshold | float | 报警阈值 |
| alarm_time | String | 报警触发时间，yyyy-MM-dd HH:mm:ss 格式 |
| description | String | 报警描述 |
| stream | String | 视频流 |
| pic | String | 报警图片 |

---

---

### 响应示例

#### 有报警（200）

```json
{
  "code": 200,
  "message": "success",
  "data": [
    {
      "alarm_id": "ALM_20260708_001",
      "sensor_code": "sj_01",
      "sensor_name": "北侧水浸传感器",
      "alarm_level": 3,
      "alarm_value": 1,
      "alarm_threshold": 0,
      "alarm_time": "2026-07-08 14:30:00",
      "description": "北侧区域检测到漏水，请立即处理",
      "stream": "rtsp://121.43.244.209:554/live/sj_01"
    },
    {
      "alarm_id": "ALM_20260708_002",
      "sensor_code": "ws_01",
      "sensor_name": "东侧温湿度传感器",
      "alarm_level": 2,
      "alarm_value": 42.5,
      "alarm_threshold": 40,
      "alarm_time": "2026-07-08 15:00:00",
      "description": "东侧温度超过阈值，当前温度 42.5℃",
      "stream": "rtsp://121.43.244.209:554/live/ws_01"
    }
  ]
}
```

#### 无报警（200）

```json
{
  "code": 200,
  "message": "success",
  "data": []
}
```

#### 失败响应（400）

```json
{
  "code": 400,
  "message": "Error",
  "data": null
}
```

---

## 注意事项

1. 设备状态接口中 `data` 数组的传感器数量不固定，取决于设备实际接入的传感器类型
2. 报警接口中 `data` 为空数组 `[]` 表示当前无报警
3. 报警等级 `1=警告`、`2=报警`、`3=严重报警`
4. 报警时间格式统一为 `yyyy-MM-dd HH:mm:ss`
5. `stream` 字段为关联的视频流 RTSP 地址，用于调取报警时刻的监控画面

---

## 3. 设备状态判定查询

### 接口地址

```
GET /api/v1/device/judge
```

查询所有传感器实时数据及报警判定信息（含阈值比较结果）。

#### 示例

```
GET /api/v1/device/judge HTTP/1.1
```

---

### 响应参数

#### 公共字段

| 字段 | 类型 | 说明 |
|------|------|------|
| code | int | 状态码，200=成功，400=失败 |
| message | String | 状态描述，成功时返回 `success`，失败时返回错误信息 |
| data | Array | 传感器数组，每个元素为一个传感器对象；失败时为 `null` |

#### data 传感器对象

| 字段 | 类型 | 说明 |
|------|------|------|
| name | String | 传感器名称 |
| code | String | 传感器编码 |
| data | Array | 该传感器的测量判定数据数组 |

#### data 测量判定数据对象

| 字段 | 类型 | 说明 |
|------|------|------|
| type | String | 测量类型编码，可选值见下表 |
| value | float | 测量值 |
| determineType | String | 判定运算符，如 `">"`、`"<"`、`">="`、`"<="`、`"=="` |
| level | String | 报警等级，`1`=警告，`2`=报警，`3`=严重报警 |

#### type 枚举值

| key | name | type | unit | 适用传感器 |
|-----|------|------|------|-----------|
| `temperature` | 温度 | float | ℃ | 温湿度传感器 |
| `humidity` | 湿度 | float | % | 温湿度传感器 |
| `leak` | 水浸状态 | int | — | 水浸传感器 |
| `angle_x` | X轴倾角 | float | ° | 倾斜传感器 |
| `angle_y` | Y轴倾角 | float | ° | 倾斜传感器 |
| `angle_z` | Z轴倾角 | float | ° | 倾斜传感器 |
| `smoke_level` | 烟雾浓度 | float | ppm | 烟感传感器 |
| `status` | 当前状态 | int | — | 通用 |
| `intrusion` | 人员入侵 | string | — | AI分析 |
| `gather` | 人员聚集 | string | — | AI分析 |

---

### 响应示例

#### 成功响应（200）

```json
{
  "code": 200,
  "message": "success",
  "data": [
    {
      "name": "东侧温湿度传感器",
      "code": "ws_01",
      "data": [
        {
          "type": "temperature",
          "value": 25.6,
          "determineType": ">",
          "level": "1"
        },
        {
          "type": "humidity",
          "value": 68,
          "determineType": ">",
          "level": "1"
        }
      ]
    },
    {
      "name": "南侧倾斜传感器",
      "code": "qx_01",
      "data": [
        {
          "type": "angle_x",
          "value": 25.6,
          "determineType": ">",
          "level": "1"
        },
        {
          "type": "angle_y",
          "value": -0.8,
          "determineType": ">",
          "level": "1"
        }
      ]
    }
  ]
}
```

#### 失败响应（400）

```json
{
  "code": 400,
  "message": "Error",
  "data": null
}
```

---

> 版本: v2.0 | 更新: 2026-07-08