# 1. 采集网关接口说明

当前接口仅支持通过 HTTP 调用 Modbus TCP 设备，暂不支持 Modbus RTU 或其他设备类型

## 采集网关服务器请求地址

```text
http://127.0.0.1:8000
```

接口完整请求地址拼接规则：

```text
完整请求地址 = 服务器请求地址 + 接口路径
```

示例：

```text
http://127.0.0.1:8000/api/dc-gateway/modbus/read
```



## 通用约定

### 请求格式

所有 `POST` 接口都使用 JSON 请求体，并且请求头必须包含：

```http
Content-Type: application/json
```

### 返回格式

除健康检查外，业务接口统一返回以下 JSON 结构：

```json
{
  "code": 0,
  "msg": "success",
  "data": {}
}
```

字段说明：

| 字段 | 类型 | 必定返回 | 含义 |
|---|---|---:|---|
| `code` | integer | 是 | 业务状态码。`0` 表示成功，`1` 表示失败。调用方应优先用该字段判断业务是否成功。 |
| `msg` | string | 是 | 业务消息。成功时通常为 `success`，失败时为错误原因。 |
| `data` | object | 是 | 业务数据对象。不同接口的字段不同。 |

### HTTP 状态码说明

接口校验失败、设备连接失败、Modbus 通信失败时，通常仍返回 HTTP `200`，业务是否成功由响应体中的 `code` 判断。

AI 调用接口时应按以下规则判断结果：

1. HTTP 请求失败或超时：认为网关服务不可达。
2. HTTP 返回成功但 JSON 中 `code = 0`：认为业务调用成功。
3. HTTP 返回成功但 JSON 中 `code != 0`：认为业务调用失败，失败原因读取 `msg`。

## 接口列表

| 接口 | 方法 | 路径 | 用途 |
|---|---|---|---|
| 健康检查 | `GET` | `/api/dc-gateway/health` | 检查网关服务是否存活。 |
| 原始 Modbus 读取 | `POST` | `/api/dc-gateway/modbus/read` | 读取 Modbus 数据，但不解析为业务值，只返回 Tx/Rx 通信报文。 |
| 点位读取并转换 | `POST` | `/api/dc-gateway/modbus/read_points` | 按点位定义读取 Modbus 数据，并按数据类型转换为业务值。 |
| 点位读取并转换别名 | `POST` | `/api/dc-gateway/modbus/read-points` | 与 `/api/dc-gateway/modbus/read_points` 等价，建议优先使用下划线版本。 |

## 通用设备字段

以下字段用于描述要连接的 Modbus TCP 设备，出现在 `/modbus/read` 和 `/modbus/read_points` 请求体的顶层。

| 字段 | 类型 | 必填 | 默认值 | 允许值或范围 | 含义 |
|---|---|---:|---|---|---|
| `device_type` | string | 否 | `ModbusTCP` | 只能是 `ModbusTCP` | 设备协议类型。当前仅支持 Modbus TCP。 |
| `ip` | string | 是 | 无 | 合法 IPv4 或 IPv6 地址 | Modbus TCP 设备的 IP 地址，不是网关服务器地址。 |
| `port` | integer | 是 | 无 | `1..65535` | Modbus TCP 设备监听端口。常见端口为 `502`，示例使用 `505`。 |
| `word_byte_order` | string | 否 | `ABCD` | `ABCD`、`BADC`、`CDAB`、`DCBA` | 多寄存器数据的字节序和字序，用于 `int32`、`float32`、`int64`、`float64` 等寄存器值转换。 |
| `address_base` | integer | 否 | `0` | `>= 0` | 地址偏移量。网关实际发送给 Modbus 协议的地址为 `address + address_base`。通常传 `0`。 |
| `slave_id` | integer | 是 | 无 | `0..247` | Modbus 从站 ID，也称 Unit ID、Device ID 或 Slave Address。 |

### 地址规则

请求体中的 `address` 是调用方传入的逻辑地址。网关实际发送给 Modbus 协议的地址计算方式如下：

```text
protocol_address = address + address_base
```

如果设备文档给出的地址已经是从 `0` 开始的协议地址，则使用：

```json
"address_base": 0
```

如果设备文档用 `40001` 表示第一个保持寄存器，调用方需要先换算为协议地址 `0`，再请求接口。不要直接把 `40001` 当作 `address` 传入，除非明确需要这种偏移行为。

### word_byte_order 说明

`word_byte_order` 用于寄存器型多字节数据的转换。每个 Modbus 寄存器为 2 字节。

| 值 | 含义 |
|---|---|
| `ABCD` | 默认顺序。寄存器内字节不反转，寄存器顺序不反转。 |
| `BADC` | 每个寄存器内的两个字节反转，寄存器顺序不反转。 |
| `CDAB` | 寄存器顺序反转，寄存器内字节不反转。 |
| `DCBA` | 每个寄存器内字节反转，同时寄存器顺序反转。 |

## Modbus 功能码

| `function_code` | Modbus 名称 | 读取对象 | 返回原始类型 | 点位类型限制 |
|---:|---|---|---|---|
| `1` | Read Coils | 线圈 | bit/boolean | `/read_points` 中只能使用 `bool`。 |
| `2` | Read Discrete Inputs | 离散输入 | bit/boolean | `/read_points` 中只能使用 `bool`。 |
| `3` | Read Holding Registers | 保持寄存器 | 16 位 register | 可使用寄存器型数据类型，也可使用 `bool` 读取寄存器整体或指定位。 |
| `4` | Read Input Registers | 输入寄存器 | 16 位 register | 可使用寄存器型数据类型，也可使用 `bool` 读取寄存器整体或指定位。 |

## communication 字段格式

`communication` 只在 `/api/dc-gateway/modbus/read` 返回，用于记录本次 HTTP 请求期间网关与 Modbus 设备之间的原始通信报文。

示例：

```text
Tx:001-00 00 33 00 00 00 06 01 03 00 00 00 04
Rx:002-00 00 33 00 00 00 0B 01 03 08 00 01 42 A8 00 00 40 F8
```

格式说明：

| 片段 | 含义 |
|---|---|
| `Tx` | 网关发送给 Modbus 设备的 Modbus TCP ADU 报文。 |
| `Rx` | Modbus 设备返回给网关的 Modbus TCP ADU 报文。 |
| `001`、`002` | 当前 HTTP 请求内的报文序号，从 `001` 开始递增。 |
| `-` 后内容 | 大写十六进制字节，字节之间使用空格分隔。 |

补充说明：

| 规则 | 说明 |
|---|---|
| trace 隔离 | 每个 HTTP 请求都有独立的 trace，并发请求不会互相清空或串包。 |
| 重试报文 | 如果底层 Modbus 客户端发生重试，`communication` 中可能出现多组 `Tx` 或 `Rx`。 |
| 失败场景 | 如果设备无响应，可能只有 `Tx` 没有 `Rx`。 |

## 接口：健康检查

### 基本信息

| 项 | 值 |
|---|---|
| 方法 | `GET` |
| 路径 | `/api/dc-gateway/health` |
| 完整地址 | `http://127.0.0.1:8000/api/dc-gateway/health` |
| 请求体 | 无 |
| 用途 | 判断 Data Collector Gateway HTTP 服务是否启动。 |

### 成功返回

```json
{
  "status": "ok"
}
```

返回字段说明：

| 字段 | 类型 | 含义 |
|---|---|---|
| `status` | string | 服务状态。`ok` 表示 HTTP 服务存活。 |

### 调用示例

```bash
curl http://127.0.0.1:8000/api/dc-gateway/health
```

## 接口：原始 Modbus 读取

### 基本信息

| 项 | 值 |
|---|---|
| 方法 | `POST` |
| 路径 | `/api/dc-gateway/modbus/read` |
| 完整地址 | `http://127.0.0.1:8000/api/dc-gateway/modbus/read` |
| Content-Type | `application/json` |
| 用途 | 向 Modbus TCP 设备发起一次读取请求，只返回通信报文，不返回解析后的业务值。 |

### 请求体结构

```json
{
  "device_type": "ModbusTCP",
  "ip": "192.168.75.240",
  "port": 505,
  "word_byte_order": "ABCD",
  "address_base": 0,
  "slave_id": 1,
  "read": {
    "function_code": 3,
    "address": 0,
    "quantity": 4
  }
}
```

顶层字段说明见“通用设备字段”。

`read` 字段说明：

| 字段 | 类型 | 必填 | 默认值 | 允许值或范围 | 含义 |
|---|---|---:|---|---|---|
| `read` | object | 是 | 无 | 对象 | 本次读取的参数对象。 |
| `read.function_code` | integer | 是 | 无 | `1`、`2`、`3`、`4` | Modbus 功能码，决定读取线圈、离散输入、保持寄存器或输入寄存器。 |
| `read.address` | integer | 是 | 无 | `>= 0` | 起始地址。实际协议地址为 `read.address + address_base`。 |
| `read.quantity` | integer | 是 | 无 | `1..125` | 读取数量。功能码 `1`、`2` 表示读取 bit 数量；功能码 `3`、`4` 表示读取 register 数量。 |

### 成功返回示例

```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "device": {
      "device_type": "ModbusTCP",
      "ip": "192.168.75.240",
      "port": 505,
      "word_byte_order": "ABCD",
      "address_base": 0,
      "slave_id": 1
    },
    "communication": [
      "Tx:001-00 00 33 00 00 00 06 01 03 00 00 00 04",
      "Rx:002-00 00 33 00 00 00 0B 01 03 08 00 01 42 A8 00 00 40 F8"
    ]
  }
}
```

成功返回字段说明：

| 字段 | 类型 | 含义 |
|---|---|---|
| `code` | integer | `0` 表示读取成功。 |
| `msg` | string | 成功时为 `success`。 |
| `data.device` | object | 本次请求实际使用的设备连接参数。 |
| `data.device.device_type` | string | 设备类型，当前固定为 `ModbusTCP`。 |
| `data.device.ip` | string | 目标 Modbus 设备 IP。 |
| `data.device.port` | integer | 目标 Modbus 设备端口。 |
| `data.device.word_byte_order` | string | 本次请求使用的字节序设置。原始读取不解析值，但仍会回显该参数。 |
| `data.device.address_base` | integer | 本次请求使用的地址偏移。 |
| `data.device.slave_id` | integer | 本次请求使用的 Modbus 从站 ID。 |
| `data.communication` | string[] | 本次 Modbus TCP 原始 Tx/Rx 报文列表。 |

### 失败返回示例

设备无响应或通信失败：

```json
{
  "code": 1,
  "msg": "Modbus Error: [Input/Output] No response received after 3 retries, continue with next request",
  "data": {
    "device": {
      "device_type": "ModbusTCP",
      "ip": "192.168.75.240",
      "port": 505,
      "word_byte_order": "ABCD",
      "address_base": 0,
      "slave_id": 1
    },
    "communication": [
      "Tx:001-00 00 33 00 00 00 06 01 03 00 00 00 04"
    ]
  }
}
```

请求字段校验失败：

```json
{
  "code": 1,
  "msg": "read.quantity: Input should be less than or equal to 125",
  "data": {
    "communication": []
  }
}
```

失败返回字段说明：

| 字段 | 类型 | 含义 |
|---|---|---|
| `code` | integer | `1` 表示失败。 |
| `msg` | string | 失败原因，可能是连接失败、Modbus 错误或请求字段校验错误。 |
| `data.device` | object | 如果请求已经通过基础校验，通常会回显设备参数。 |
| `data.communication` | string[] | 失败前已经捕获到的通信报文。字段校验失败时通常为空数组。 |

### 调用示例

```bash
curl -X POST http://127.0.0.1:8000/api/dc-gateway/modbus/read \
  -H "Content-Type: application/json" \
  -d '{
    "device_type": "ModbusTCP",
    "ip": "192.168.75.240",
    "port": 505,
    "word_byte_order": "ABCD",
    "address_base": 0,
    "slave_id": 1,
    "read": {
      "function_code": 3,
      "address": 0,
      "quantity": 4
    }
  }'
```

## 接口：点位读取并转换

### 基本信息

| 项 | 值 |
|---|---|
| 方法 | `POST` |
| 推荐路径 | `/api/dc-gateway/modbus/read_points` |
| 兼容路径 | `/api/dc-gateway/modbus/read-points` |
| 完整地址 | `http://127.0.0.1:8000/api/dc-gateway/modbus/read_points` |
| Content-Type | `application/json` |
| 用途 | 按点位定义逐个读取 Modbus 数据，并把原始 bit/register 转换为 `bool`、`int16`、`float32` 等业务值。 |

### 请求体结构

```json
{
  "device_type": "ModbusTCP",
  "ip": "192.168.75.240",
  "port": 505,
  "word_byte_order": "ABCD",
  "address_base": 0,
  "slave_id": 1,
  "points": [
    {
      "function_code": 3,
      "address": 7,
      "type": "int16"
    },
    {
      "function_code": 3,
      "address": 1,
      "type": "float32"
    },
    {
      "function_code": 3,
      "address": 10,
      "type": "bool",
      "bit": 2
    },
    {
      "function_code": 1,
      "address": 0,
      "type": "bool"
    }
  ]
}
```

顶层字段说明见“通用设备字段”。

`points` 字段说明：

| 字段 | 类型 | 必填 | 默认值 | 允许值或范围 | 含义 |
|---|---|---:|---|---|---|
| `points` | object[] | 是 | 无 | 至少 1 个元素 | 点位读取定义列表。网关会按数组顺序逐个读取。 |
| `points[].function_code` | integer | 是 | 无 | `1`、`2`、`3`、`4` | 当前点位使用的 Modbus 功能码。 |
| `points[].address` | integer | 是 | 无 | `>= 0` | 当前点位起始地址。实际协议地址为 `points[].address + address_base`。 |
| `points[].type` | string | 是 | 无 | `bool`、`int16`、`uint16`、`int32`、`uint32`、`int64`、`uint64`、`float32`、`float64` | 当前点位的数据类型。接口会按该类型决定读取寄存器数量和转换方式。输入会被转换为小写。 |
| `points[].bit` | integer 或 null | 否 | `null` | `0..15` | 仅寄存器点位支持。用于从一个 16 位寄存器中取某一位并返回布尔值。功能码 `1`、`2` 不允许传 `bit`。 |

### 点位类型和读取长度

| `type` | 读取长度 | 可用功能码 | 返回 JSON 类型 | 含义 |
|---|---:|---|---|---|
| `bool` | 功能码 `1`、`2` 为 1 bit；功能码 `3`、`4` 为 1 register | `1`、`2`、`3`、`4` | boolean | 布尔值。寄存器点位未传 `bit` 时，寄存器值非 `0` 返回 `true`；传 `bit` 时读取指定位。 |
| `int16` | 1 register | `3`、`4` | integer | 有符号 16 位整数。 |
| `uint16` | 1 register | `3`、`4` | integer | 无符号 16 位整数。 |
| `int32` | 2 registers | `3`、`4` | integer | 有符号 32 位整数。 |
| `uint32` | 2 registers | `3`、`4` | integer | 无符号 32 位整数。 |
| `float32` | 2 registers | `3`、`4` | number | IEEE 754 单精度浮点数。 |
| `int64` | 4 registers | `3`、`4` | integer | 有符号 64 位整数。 |
| `uint64` | 4 registers | `3`、`4` | integer | 无符号 64 位整数。 |
| `float64` | 4 registers | `3`、`4` | number | IEEE 754 双精度浮点数。 |

### 点位校验规则

| 规则 | 说明 |
|---|---|
| `function_code` 必须合法 | 只能是 `1`、`2`、`3`、`4`。 |
| 线圈和离散输入只能读布尔值 | 当 `function_code` 为 `1` 或 `2` 时，`type` 必须是 `bool`。 |
| 线圈和离散输入不能使用 `bit` | 当 `function_code` 为 `1` 或 `2` 时，不能传 `bit`。 |
| 寄存器点位可以使用 `bit` | 当 `function_code` 为 `3` 或 `4` 且 `type` 为 `bool` 时，可用 `bit` 读取寄存器指定位。 |
| 不允许额外字段 | 请求对象中出现未定义字段会校验失败。 |

### 成功返回示例

```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "device": {
      "device_type": "ModbusTCP",
      "ip": "192.168.75.240",
      "port": 505,
      "word_byte_order": "ABCD",
      "address_base": 0,
      "slave_id": 1
    },
    "points": [
      {
        "function_code": 3,
        "address": 7,
        "type": "int16",
        "value": -321
      },
      {
        "function_code": 3,
        "address": 10,
        "type": "bool",
        "bit": 2,
        "value": true
      }
    ]
  }
}
```

成功返回字段说明：

| 字段 | 类型 | 含义 |
|---|---|---|
| `code` | integer | `0` 表示所有点位读取和转换成功。 |
| `msg` | string | 成功时为 `success`。 |
| `data.device` | object | 本次请求实际使用的设备连接参数。 |
| `data.points` | object[] | 点位读取结果数组，顺序与请求体 `points` 一致。 |
| `data.points[].function_code` | integer | 该点位使用的 Modbus 功能码。 |
| `data.points[].address` | integer | 该点位请求中的逻辑地址，不包含 `address_base` 偏移。 |
| `data.points[].type` | string | 该点位的数据类型，返回为小写。 |
| `data.points[].bit` | integer | 仅当请求点位传入 `bit` 时返回。 |
| `data.points[].value` | boolean、integer 或 number | 转换后的点位值。具体 JSON 类型由 `type` 决定。 |

### 失败返回示例

设备连接失败：

```json
{
  "code": 1,
  "msg": "failed to connect to 192.168.75.240:505",
  "data": {
    "device": {
      "device_type": "ModbusTCP",
      "ip": "192.168.75.240",
      "port": 505,
      "word_byte_order": "ABCD",
      "address_base": 0,
      "slave_id": 1
    },
    "points": []
  }
}
```

读取部分点位后失败：

```json
{
  "code": 1,
  "msg": "Modbus Error: [Input/Output] No response received after 3 retries, continue with next request",
  "data": {
    "device": {
      "device_type": "ModbusTCP",
      "ip": "192.168.75.240",
      "port": 505,
      "word_byte_order": "ABCD",
      "address_base": 0,
      "slave_id": 1
    },
    "points": [
      {
        "function_code": 3,
        "address": 7,
        "type": "int16",
        "value": -321
      }
    ]
  }
}
```

失败返回字段说明：

| 字段 | 类型 | 含义 |
|---|---|---|
| `code` | integer | `1` 表示失败。 |
| `msg` | string | 失败原因，可能是连接失败、Modbus 错误或请求字段校验错误。 |
| `data.device` | object | 如果请求已经通过基础校验，通常会回显设备参数。 |
| `data.points` | object[] | 失败前已成功读取的点位。字段校验失败或连接失败时通常为空数组。 |

### 调用示例

```bash
curl -X POST http://127.0.0.1:8000/api/dc-gateway/modbus/read_points \
  -H "Content-Type: application/json" \
  -d '{
    "device_type": "ModbusTCP",
    "ip": "192.168.75.240",
    "port": 505,
    "word_byte_order": "ABCD",
    "address_base": 0,
    "slave_id": 1,
    "points": [
      {
        "function_code": 3,
        "address": 7,
        "type": "int16"
      },
      {
        "function_code": 3,
        "address": 1,
        "type": "float32"
      },
      {
        "function_code": 1,
        "address": 0,
        "type": "bool"
      }
    ]
  }'
```

## AI 调用决策指南

AI 或自动化程序选择接口时遵循以下规则：

| 目标 | 应调用接口 | 原因 |
|---|---|---|
| 只想检查网关是否启动 | `GET /api/dc-gateway/health` | 不访问 Modbus 设备，只检查 HTTP 服务。 |
| 需要查看原始 Modbus Tx/Rx 报文 | `POST /api/dc-gateway/modbus/read` | 返回 `communication`，适合调试通信、对比 Modbus Poll 报文。 |
| 需要得到点位业务值 | `POST /api/dc-gateway/modbus/read_points` | 返回 `points[].value`，自动按类型转换。 |

AI 构造请求时必须区分两个地址：

| 地址 | 字段或配置 | 含义 |
|---|---|---|
| 网关服务器地址 | `http://127.0.0.1:8000` | HTTP API 服务地址，用于拼接请求 URL。 |
| Modbus 设备地址 | 请求体 `ip` 和 `port` | 实际被读取的 Modbus TCP 设备地址。 |

AI 构造 `/modbus/read_points` 点位时应按以下步骤：

1. 根据设备点表选择 `function_code`。
2. 将设备点表地址换算为从 `0` 开始的 Modbus 协议地址，填入 `address`。
3. 如果需要统一偏移，再设置 `address_base`，否则保持 `0`。
4. 根据点位数据类型设置 `type`。
5. 如果读取保持寄存器或输入寄存器中的某一位，设置 `type` 为 `bool` 并填写 `bit`。
6. 发送请求后检查响应体 `code`，不要只检查 HTTP 状态码。



# 2. 模方登录接口

- 登录接口请求地址

```
http://192.168.75.110:32080/api/ai/auth/password_login
```

- 请求入参

``````
{
    "username":"dataturing",
    "password":"123456"
}
``````

- 响应格式

```
{
    "errcode": 0,
    "msg": "成功",
    "token": "MTc4MTU3NjM4NDsxNzgxNTgzNTg0OzY7ZThLU2hySEFnbTtkZTY0OWI2YzNjMmYyOTNj",
    "token_expire_time": 1781583584,
    "user_id": 6,
    "name": "Dataturing",
    "username": "dataturing",
    "permissions": [
		...
    ]
}
```



# 3. 汇采接口



## 前置说明

### 服务器地址

```
http://192.168.75.110:32080
```

### 通用约定

- 请求方式：`POST`
- 请求体：`application/json`
- 成功响应通常使用 HTTP 200，并通过 JSON 中的 `state` 判断业务结果。
- 创建设备成功响应：`{"state":0,"state_info":"成功"}`；创建点位接口成功时返回 `{"state":0,"state_info":"成功"}`。
- 通用参数错误：`{"state":2,"state_info":"无效参数"}`。

### 注意

在调用汇采接口前请先调用模方登录接口获取token，获取token后放入请求头Header的Authorization字段

- 示例

```
	header = {
		"Authorization": "TOKEN"
	}
```

### 通用状态枚举

以下状态枚举适用于汇采内的所有设备类型，不限于 Modbus。创建设备和创建点位时接口会写入初始状态，调用方通常不需要传；查询设备列表、连接设备、查询点位列表等接口会返回这些状态字段。

设备 `status` 表示设备连接状态：

| 值 | 英文状态 | 含义 | 典型场景 |
|---:|---|---|---|
| `1` | `disconnected` | 未连接 | 设备未执行连接、已断开，或连接失败后回到未连接状态。 |
| `2` | `connected` | 已连接 | 设备连接成功。注意这不等同于正在采集。 |
| `3` | `error` | 连接异常 | 设备连接过程或连接状态异常。 |

设备 `running_status` 表示采集状态，不表示 TCP/串口等底层连接是否成功：

| 值 | 英文状态 | 含义 | 典型场景 |
|---:|---|---|---|
| `0` | `idle` | 未采集 | 设备尚未开始采集、已停止采集，或刚连接但没有采集任务运行。 |
| `1` | `running` | 采集中 | 设备正在执行采集任务。 |
| `2` | `error` | 采集异常 | 采集过程中发生异常，例如读取点位失败、通信异常或采集任务报错。 |

设备 `connect_status` 表示最近一次连接/通信检测状态：

| 值 | 英文状态 | 含义 | 典型场景 |
|---:|---|---|---|
| `0` | `idle` | 未检测或空闲 | 尚未进行连接检测，或设备当前处于空闲状态。 |
| `1` | `normal` | 连接正常 | 最近一次连接或通信状态正常。 |
| `2` | `abnormal` | 连接异常 | 最近一次连接或通信状态异常。 |

点位 `status` 表示点位采集状态：

| 值 | 英文状态 | 含义 | 典型场景 |
|---:|---|---|---|
| `0` | `idle` | 未采集 | 点位尚未采集或设备未运行采集任务。 |
| `1` | `working` | 采集正常 | 点位最近一次采集正常。 |
| `2` | `error` | 采集异常 | 点位最近一次采集失败或转换失败。 |

状态字段关系说明：

| 字段 | 表示对象 | 说明 |
|---|---|---|
| `status` | 设备连接状态 | 判断设备是否已连接。 |
| `running_status` | 设备采集状态 | 判断设备是否正在采集或采集是否异常。 |
| `connect_status` | 最近连接/通信检测状态 | 判断最近一次连接或通信是否正常。 |
| 点位 `status` | 单个点位采集状态 | 判断某个点位最近一次采集是否正常。 |

## Modbus 创建设备与创建点位接口文档

### 枚举汇总

- Modbus 设备连接类型 `device_type`

`device_type` 是通用创建设备接口中 Modbus 连接类型的 JSON 字段名。

| 值 | 含义 | 连接 URL 形态 | 必填关联字段 |
|---:|---|---|---|
| 1 | TCP | `tcp://{ip}:{port}` | `ip`、`port` |
| 2 | RTU | `rtu://{serial_port}` | `serial_port` |
| 3 | UDP | `udp://{ip}:{port}` | `ip`、`port` |
| 4 | RTU OVER TCP | `rtuovertcp://{ip}:{port}` | `ip`、`port` |
| 5 | RTU OVER UDP | `rtuoverudp://{ip}:{port}` | `ip`、`port` |

说明：当前创建 Modbus 设备应使用通用 `POST /api/collector/device`。其中 `type` 传协议字符串 `modbus`，`device_type` 传上表的连接类型。传 `device_type=0` 会导致创建设备失败。

- 串口校验位 `parity`

| 值 | 含义 | 代码常量 |
|---:|---|---|
| 1 | Even，偶校验 | `ModbusDeviceParityEven` |
| 2 | None，无校验 | `ModbusDeviceParityNone` |
| 3 | Odd，奇校验 | `ModbusDeviceParityOdd` |

说明：当前 `Parity()` 转换函数中，除 `2`、`3` 外都会按 Even 处理；即 `0` 也会被当作 Even 传给底层 Modbus 客户端。

- 字节序 `byte_order`

| 值 | 含义 | 代码常量 |
|---:|---|---|
| 1 | Big Endian，大端字节序 | `ModbusDeviceByteOrderBigEndian` |
| 2 | Small Endian，小端字节序 | `ModbusDeviceByteOrderSmallEndian` |

- 字序 `word_order`

| 值 | 含义 | 代码常量 |
|---:|---|---|
| 1 | Big Endian，大端字序 | `ModbusDeviceWordOrderBigEndian` |
| 2 | Small Endian，小端字序 | `ModbusDeviceWordOrderSmallEndian` |

- 数据位 `data_bit`

| 值 | 含义 |
|---:|---|
| 5 | 5 个数据位 |
| 6 | 6 个数据位 |
| 7 | 7 个数据位 |
| 8 | 8 个数据位，常用值 |

- 停止位 `stop_bit`

| 值 | 含义 |
|---:|---|
| 1 | 1 个停止位 |
| 2 | 2 个停止位 |

- Modbus 功能码 `func_code`

| 值 | 含义 | 读操作 | 数据区 |
|---:|---|---|---|
| 1 | Coil | Read Coils | 线圈 |
| 2 | Discrete Input | Read Discrete Inputs | 离散输入 |
| 3 | Holding Register | Read Holding Registers | 保持寄存器 |
| 4 | Input Register | Read Input Registers | 输入寄存器 |

- 点位数据类型 `type`

创建点位接口中的 `type` 是字符串，表示点位数据类型。

| 值 | 含义 | 占用寄存器数量 |
|---|---|---:|
| `bool` | 布尔值 | 1 |
| `int16` | 16 位有符号整数 | 1 |
| `uint16` | 16 位无符号整数 | 1 |
| `int32` | 32 位有符号整数 | 2 |
| `uint32` | 32 位无符号整数 | 2 |
| `float32` | 32 位浮点数 | 2 |
| `int64` | 64 位有符号整数 | 4 |
| `uint64` | 64 位无符号整数 | 4 |
| `float64` | 64 位浮点数 | 4 |

说明：`func_code` 为 `1` 或 `2` 时采集结果按布尔/0-1 处理；`func_code` 为 `3` 或 `4` 且 `type=bool` 时会从寄存器中按 `bit` 取某一位。

### 1. 创建设备

#### 基本信息

- URL：`/api/collector/device`
- 方法：`POST`

#### 请求字段

| 字段 | 类型 | 必填 | 默认/行为 | 含义 |
|---|---|---|---|---|
| `type` | string | 是 | 无默认值 | 设备协议类型。创建 Modbus 设备固定传 `"modbus"`。缺失会在转换设备对象时失败。 |
| `name` | string | 是 | 未显式 trim | 设备名称。 |
| `device_type` | int | 是 | 缺失时为 `0`，会导致创建失败 | Modbus 连接类型，见 `device_type` 枚举。 |
| `ip` | string | TCP/UDP 类连接必填 | 缺失时为空字符串 | 设备 IP。`device_type` 为 1、3、4、5 时用于组装连接 URL。 |
| `port` | int | TCP/UDP 类连接必填 | 缺失时为 `0` | 设备端口。`device_type` 为 1、3、4、5 时用于组装连接 URL。 |
| `slave_id` | int | 建议必填 | 缺失时为 `0` | Modbus 从站 ID/Unit ID。采集时会设置到底层客户端，通常取值 `0` 到 `255`。 |
| `serial_port` | string | RTU 必填 | 缺失时为空字符串 | 串口名。`device_type=2` 时用于组装 `rtu://{serial_port}`。 |
| `timeout` | int | 否 | 缺失时为 `3` | 超时时间，单位秒。 |
| `byte_order` | int | 建议必填 | 缺失时为 `0`，底层编码设置可能失败 | 字节序，见 `byte_order` 枚举；创建时会调用底层 `SetEncoding`。 |
| `word_order` | int | 建议必填 | 缺失时为 `0`，底层编码设置可能失败 | 字序，见 `word_order` 枚举；创建时会调用底层 `SetEncoding`。 |
| `is_persistent` | bool | 否 | 缺失时为 `false` | 是否持久化/持久设备标记，写入设备 `is_persistent`。 |
| `baud_rate` | int | RTU 建议必填 | 缺失时为 `0` | 串口波特率，例如 `9600`。 |
| `data_bit` | int | RTU 建议必填 | 缺失时为 `0` | 串口数据位，见 `data_bit` 枚举。 |
| `parity` | int | RTU 建议必填 | 传 `0` 会按 Even 转换 | 串口校验位，见 `parity` 枚举。 |
| `stop_bit` | int | RTU 建议必填 | 缺失时为 `0` | 串口停止位，见 `stop_bit` 枚举。 |
| `mode` | int | 否 | 缺失时为 `0` | 模式字段。当前创建、连接和采集逻辑只保存该字段，未参与连接 URL 生成和读写。 |
| `address_offset` | int | 否 | 缺失时为 `0` | 地址偏移。实际读点时使用 `点位 address - address_offset` 作为 Modbus 读取地址。 |
| `retry_times` | int | 否 | 缺失时为 `0` | 读取失败重试次数。小于 0 时部分流程会按 0 处理。 |
| `group_id` | int | 否 | 缺失时为 `0` | 父设备分组 ID。`0` 表示顶层设备。 |
| `sort_index` | int | 否 | 缺失时为 `0` | 设备排序序号。 |
| `alarm_interval` | int | 否 | 缺失时为 `0` | 告警间隔。 |
| `collect_interval` | int | 否 | 缺失时为 `0` | 采集周期。 |

#### 请求示例：Modbus TCP

```json
{
  "name": "modbus_tcp_1",
  "type": "modbus",
  "device_type": 1,
  "ip": "127.0.0.1",
  "port": 5502,
  "slave_id": 1,
  "timeout": 3,
  "byte_order": 1,
  "word_order": 1,
  "is_persistent": true,
  "group_id": 0,
  "alarm_interval": 0,
  "collect_interval": 0,
  "address_offset": 0,
  "retry_times": 0
}
```

#### 请求示例：Modbus RTU

```json
{
  "name": "modbus_rtu_1",
  "type": "modbus",
  "device_type": 2,
  "serial_port": "COM3",
  "slave_id": 1,
  "timeout": 3,
  "baud_rate": 9600,
  "data_bit": 8,
  "parity": 2,
  "stop_bit": 1,
  "byte_order": 1,
  "word_order": 1,
  "is_persistent": true,
  "group_id": 0,
  "alarm_interval": 0,
  "collect_interval": 0,
  "address_offset": 0,
  "retry_times": 0
}
```

#### 成功响应

```json
{
  "state": 0,
  "state_info": "成功"
}
```

#### 主要失败响应

| 场景 | 响应 |
|---|---|
| Query 绑定失败、JSON 绑定失败、`type` 缺失、连接类型无效、底层客户端初始化失败、数据库写入失败等 | `{"state":2,"state_info":"失败"}` |

### 2. 编辑设备

#### 基本信息

- URL：`/api/collector/modbus/device/edit`
- 方法：`POST`
- 处理函数：`EditModbusDevice`
- 请求结构：`ReqEditModbusDevice`
- 主要用途：编辑已存在的 Modbus 设备连接参数、采集周期、设备分组和持久化配置。

#### 重要说明

- 该接口是 Modbus 专用旧接口，和通用创建设备接口 `/api/collector/device` 的字段名不完全一致。
- 该接口是全量更新语义，未传字段会按 Go 零值写入，例如 `timeout` 变为 `0`、`is_persistent` 变为 `false`、`address_offset` 变为 `0`。编辑前建议先查询设备详情或设备列表，基于原配置修改后整包提交。
- 编辑前设备不能处于已连接状态。若设备 `status=2`，接口返回 `先停止设备采集，再编辑设备`。应先调用连接/断开设备接口将设备断开。
- 请求字段 `type` 在本接口中表示 Modbus 连接类型，取值与前文 Modbus 设备连接类型枚举一致；不是通用创建设备接口里的协议字符串 `type="modbus"`。
- 编辑成功后接口会移除内存中的旧设备并重新加载设备对象，设备状态会回到未连接状态。

#### 请求字段

| 字段 | 类型 | 必填 | 默认/行为 | 含义 |
|---|---|---|---|---|
| `ori_id` | int | 是 | 缺失或为 `0` 返回 `设备不存在` | 要编辑的原设备 ID。 |
| `type` | int | 是 | 缺失时为 `0`，后续连接可能因连接类型无效失败 | Modbus 连接类型。`1` TCP，`2` RTU，`3` UDP，`4` RTU OVER TCP，`5` RTU OVER UDP。 |
| `name` | string | 是 | 绑定时必填；保存前会 `strings.TrimSpace` | 设备名称。 |
| `ip` | string | TCP/UDP 类连接必填 | 会 `strings.TrimSpace` | 设备 IP。`type` 不为 `2` 时为空会返回 `选择Modbus TCP类型时，IP不能为空`。 |
| `port` | int | TCP/UDP 类连接必填 | 缺失时为 `0` | 设备端口。`type` 为 `1`、`3`、`4`、`5` 时用于组装连接 URL。 |
| `slave_id` | int | 是 | Go binding 的 `required` 对数字零值敏感，缺失或为 `0` 会绑定失败 | Modbus 从站 ID/Unit ID。 |
| `serial_port` | string | RTU 必填 | 会 `strings.TrimSpace` | 串口名。`type=2` 时为空会返回 `选择Modbus RTU类型时，串口不能为空`。 |
| `timeout` | int | 建议必填 | 缺失时会写入 `0`，编辑接口不自动补 `3` | 超时时间，单位秒。 |
| `byte_order` | int | 建议必填 | 缺失时会写入 `0` | 字节序，见 `byte_order` 枚举。 |
| `word_order` | int | 建议必填 | 缺失时会写入 `0` | 字序，见 `word_order` 枚举。 |
| `is_persistent` | bool | 否 | 缺失时会写入 `false` | 是否持久化设备。 |
| `baud_rate` | int | RTU 建议必填 | 缺失时会写入 `0` | 串口波特率，例如 `9600`。 |
| `data_bit` | int | RTU 建议必填 | 缺失时会写入 `0` | 串口数据位，见 `data_bit` 枚举。 |
| `parity` | int | RTU 建议必填 | 传 `0` 会按 Even 转换 | 串口校验位，见 `parity` 枚举。 |
| `stop_bit` | int | RTU 建议必填 | 缺失时会写入 `0` | 串口停止位，见 `stop_bit` 枚举。 |
| `mode` | int | 否 | 缺失时会写入 `0` | 模式字段，当前主要保存配置。 |
| `address_offset` | int | 否 | 缺失时会写入 `0` | 地址偏移。实际读点时使用 `点位 address - 设备 address_offset`。 |
| `retry_times` | int | 否 | 缺失时会写入 `0` | 读取失败重试次数。 |
| `device_group_id` | int | 否 | 缺失时会写入 `0` | 父设备分组 ID。`0` 表示顶层设备。 |
| `alarm_interval` | int | 否 | 缺失时会写入 `0` | 告警间隔。 |
| `collect_interval` | int | 否 | 缺失时会写入 `0` | 采集周期。 |

#### 请求示例：编辑 Modbus TCP 设备

```json
{
  "ori_id": 1,
  "type": 1,
  "name": "modbus_tcp_1_edited",
  "ip": "127.0.0.1",
  "port": 5502,
  "slave_id": 1,
  "timeout": 3,
  "byte_order": 1,
  "word_order": 1,
  "is_persistent": true,
  "device_group_id": 0,
  "alarm_interval": 0,
  "collect_interval": 5,
  "address_offset": 0,
  "retry_times": 0,
  "mode": 0
}
```

#### 请求示例：编辑 Modbus RTU 设备

```json
{
  "ori_id": 1,
  "type": 2,
  "name": "modbus_rtu_1_edited",
  "serial_port": "COM3",
  "slave_id": 1,
  "timeout": 3,
  "baud_rate": 9600,
  "data_bit": 8,
  "parity": 2,
  "stop_bit": 1,
  "byte_order": 1,
  "word_order": 1,
  "is_persistent": true,
  "device_group_id": 0,
  "alarm_interval": 0,
  "collect_interval": 5,
  "address_offset": 0,
  "retry_times": 0,
  "mode": 0
}
```

#### 成功响应

```json
{
  "state": 0,
  "state_info": "操作成功",
  "data": null
}
```

#### 主要失败响应

| 场景 | 响应 |
|---|---|
| JSON 绑定失败、`name` 缺失、`slave_id` 缺失或为零等 | `{"state":2,"state_info":"无效参数"}` |
| `ori_id` 缺失或为 `0` | `{"state":2,"state_info":"设备不存在"}` |
| RTU 设备未传 `serial_port` | `{"state":2,"state_info":"选择Modbus RTU类型时，串口不能为空"}` |
| TCP/UDP 类设备未传 `ip` | `{"state":2,"state_info":"选择Modbus TCP类型时，IP不能为空"}` |
| 查询原设备失败 | `{"state":2,"state_info":"检测设备状态失败"}` |
| 原设备不存在 | `{"state":2,"state_info":"设备ID不合法"}` |
| 设备仍处于已连接状态 | `{"state":2,"state_info":"先停止设备采集，再编辑设备"}` |
| 数据库更新失败 | `{"state":2,"state_info":"编辑失败"}` |

### 3. 创建采集点位

#### 基本信息

- URL：`/api/collector/modbus/point/add_collect_point`
- 方法：`POST`
- 处理函数：`modbusPointAdd`
- 请求结构：`ReqModbusPointAdd`

#### 请求字段

| 字段 | 类型 | 必填 | 默认/行为 | 含义 |
|---|---|---|---|---|
| `name` | string | 是 | 会 `strings.TrimSpace`；trim 后为空会返回 `名称不能为空` | 点位名称。 |
| `point_id` | string | 否 | 空字符串允许 | 外部点位标识。非空时，同一设备下不能重复。采集写入 `PointData.PointId` 使用该字段。 |
| `device_id` | int | 是 | 无默认值 | 所属 Modbus 设备 ID。接口会查询设备是否存在，找不到返回 `设备ID不合法`。 |
| `scale_ratio` | float64 | 是 | 无默认值 | 缩放系数。寄存器数值采集时先乘以该系数。Go binding 的 `required` 对数字零值敏感，建议传非 0，常用 `1`。 |
| `value_offset` | float64 | 否 | Go 零值 `0` | 值偏移。寄存器采集结果乘 `scale_ratio` 后再加该偏移。 |
| `describe` | string | 否 | 空字符串 | 点位描述，保存到 `description`。 |
| `invalid_values` | string | 否 | 空字符串解析为空数组 | 无效值列表，逗号分隔，例如 `"-9999,9999"`。接口会逐项解析为 float64，无法解析则返回无效参数。 |
| `valid_range_start` | number/null | 否 | `null` | 合法范围最小值。采集值小于该值时跳过写入。 |
| `valid_range_end` | number/null | 否 | `null` | 合法范围最大值。采集值大于该值时跳过写入。 |
| `type` | string | 否，但采集必须有效 | 无显式默认值 | 点位数据类型，见数据类型枚举。字段名与创建设备的 `type` 不同语义。 |
| `address` | int | 是 | Go 零值 `0` | Modbus 地址。实际读取地址为 `address - 设备 address_offset`。 |
| `func_code` | int | 是 | Go 零值 `0` 会导致后续采集功能码无效 | Modbus 功能码，见 `func_code` 枚举。 |
| `group_id` | int | 否 | Go 零值 `0` | 点位分组 ID；`0` 表示不归属具体分组或默认分组。 |
| `bit` | int | `type=bool` 且读寄存器时需要 | Go 零值 `0` | 位下标。`func_code=3/4` 且 `type=bool` 时，从寄存器值中取 `(value >> bit) & 1`。建议范围 `0` 到 `15`。 |

#### 请求示例：保持寄存器 uint16

```json
{
  "device_id": 1,
  "name": "holding_register_uint16",
  "point_id": "HR_UINT16",
  "describe": "保持寄存器 uint16 示例",
  "func_code": 3,
  "address": 10,
  "type": "uint16",
  "scale_ratio": 1,
  "value_offset": 0,
  "group_id": 0,
  "invalid_values": "",
  "valid_range_start": null,
  "valid_range_end": null,
  "bit": 0
}
```

#### 请求示例：寄存器位点 bool

```json
{
  "device_id": 1,
  "name": "alarm_bit_3",
  "point_id": "ALARM_BIT_3",
  "describe": "保持寄存器第 3 位报警",
  "func_code": 3,
  "address": 20,
  "type": "bool",
  "bit": 3,
  "scale_ratio": 1,
  "value_offset": 0,
  "group_id": 0,
  "invalid_values": "",
  "valid_range_start": null,
  "valid_range_end": null
}
```

#### 请求示例：线圈点位

```json
{
  "device_id": 1,
  "name": "coil_1",
  "point_id": "COIL_1",
  "describe": "线圈 1",
  "func_code": 1,
  "address": 1,
  "type": "bool",
  "scale_ratio": 1,
  "value_offset": 0,
  "group_id": 0,
  "invalid_values": "",
  "valid_range_start": null,
  "valid_range_end": null,
  "bit": 0
}
```

#### 成功响应

```json
{
  "state": 0,
  "state_info": "成功",
  "data": null
}
```

#### 主要失败响应

| 场景 | 响应 |
|---|---|
| JSON 绑定失败、`scale_ratio` 缺失或为零等 | `{"state":2,"state_info":"无效参数"}` |
| `invalid_values` 中存在非数字项 | `{"state":2,"state_info":"无效参数"}` |
| 查询设备失败 | `{"state":2,"state_info":"检测设备ID失败"}` |
| 设备不存在 | `{"state":2,"state_info":"设备ID不合法"}` |
| `name` trim 后为空 | `{"state":2,"state_info":"名称不能为空"}` |
| 同一设备下 `point_id` 重复 | `{"state":2,"state_info":"point_id 重复, point_id: {point_id}"}` |
| 数据库插入失败 | `{"state":2,"state_info":"新增失败"}` |

### 4. 编辑采集点位

#### 基本信息

- URL：`/api/collector/modbus/point/edit_collect_point`
- 方法：`POST`
- 处理函数：`modbusPointEdit`
- 请求结构：`ReqModbusPointEdit`
- 主要用途：编辑已存在的 Modbus 采集点位，包括点位名称、`point_id`、地址、功能码、数据类型、缩放和合法值范围。

#### 重要说明

- 该接口是全量更新语义，除 `ori_id` 外的点位配置应按完整点位对象提交。未传字段会按 Go 零值写入，例如 `group_id=0`、`value_offset=0`、`bit=0`、`invalid_values=""`。
- `ori_id` 是要编辑的采集点位内部 ID，对应查询设备点位列表返回的 `data.point[].id`。
- 编辑点位不会迁移点位所属设备。请求结构虽然继承了 `device_id` 字段，但处理逻辑会从原点位读取 `DeviceID`，并继续保存到原设备下。
- `point_id` 允许为空字符串；非空时会检查同一设备下是否重复，检查时会排除当前 `ori_id` 对应的原点位。
- 编辑成功后会更新数据库、设备内存点位缓存和通用点位缓存。点位状态会重置为未采集状态。

#### 请求字段

| 字段 | 类型 | 必填 | 默认/行为 | 含义 |
|---|---|---|---|---|
| `ori_id` | int | 是 | 无默认值 | 要编辑的原采集点位 ID。 |
| `name` | string | 是 | 绑定时必填；保存前会 `strings.TrimSpace` | 点位名称。 |
| `point_id` | string | 否 | 空字符串允许 | 外部点位标识。非空时，同一设备下不能重复。 |
| `device_id` | int | 否 | 编辑逻辑不使用该字段 | 请求结构继承字段。编辑时点位仍归属原设备，不会按该字段迁移。 |
| `scale_ratio` | float64 | 是 | Go binding 的 `required` 对数字零值敏感，建议传非 `0`，常用 `1` | 缩放系数。寄存器数值采集时先乘以该系数。 |
| `value_offset` | float64 | 否 | Go 零值 `0` | 值偏移。寄存器采集结果乘 `scale_ratio` 后再加该偏移。 |
| `describe` | string | 否 | 空字符串 | 点位描述，保存到 `description`。 |
| `invalid_values` | string | 否 | 空字符串解析为空数组 | 无效值列表，逗号分隔，例如 `"-9999,9999"`。接口会逐项解析为 float64，无法解析则返回无效参数。 |
| `valid_range_start` | number/null | 否 | `null` | 合法范围最小值。采集值小于该值时跳过写入。 |
| `valid_range_end` | number/null | 否 | `null` | 合法范围最大值。采集值大于该值时跳过写入。 |
| `type` | string | 否，但采集必须有效 | 无显式默认值 | 点位数据类型，见数据类型枚举。 |
| `address` | int | 是 | Go 零值 `0` | Modbus 地址。实际读取地址为 `address - 设备 address_offset`。 |
| `func_code` | int | 是 | Go 零值 `0` 会导致后续采集功能码无效 | Modbus 功能码，见 `func_code` 枚举。 |
| `group_id` | int | 否 | Go 零值 `0` | 点位分组 ID。 |
| `bit` | int | `type=bool` 且读寄存器时需要 | Go 零值 `0` | 位下标。`func_code=3/4` 且 `type=bool` 时，从寄存器值中取 `(value >> bit) & 1`。建议范围 `0` 到 `15`。 |

#### 请求示例：编辑保持寄存器 uint16 点位

```json
{
  "ori_id": 101,
  "name": "holding_register_uint16_edited",
  "point_id": "HR_UINT16_EDITED",
  "describe": "编辑后的保持寄存器 uint16 示例",
  "func_code": 3,
  "address": 10,
  "type": "uint16",
  "scale_ratio": 1,
  "value_offset": 0,
  "group_id": 0,
  "invalid_values": "",
  "valid_range_start": null,
  "valid_range_end": null,
  "bit": 0
}
```

#### 请求示例：编辑寄存器位点 bool

```json
{
  "ori_id": 102,
  "name": "alarm_bit_4",
  "point_id": "ALARM_BIT_4",
  "describe": "保持寄存器第 4 位报警",
  "func_code": 3,
  "address": 20,
  "type": "bool",
  "bit": 4,
  "scale_ratio": 1,
  "value_offset": 0,
  "group_id": 0,
  "invalid_values": "",
  "valid_range_start": null,
  "valid_range_end": null
}
```

#### 成功响应

```json
{
  "state": 0,
  "state_info": "成功",
  "data": null
}
```

#### 主要失败响应

| 场景 | 响应 |
|---|---|
| JSON 绑定失败、`ori_id` 缺失、`name` 缺失、`scale_ratio` 缺失或为零等 | `{"state":2,"state_info":"无效参数"}` |
| `invalid_values` 中存在非数字项 | `{"state":2,"state_info":"无效参数"}` |
| 原点位不存在或查询失败 | `{"state":2,"state_info":"校验失败"}` |
| 同一设备下 `point_id` 重复 | `{"state":2,"state_info":"point_id 重复, point_id: {point_id}"}` |
| 数据库更新失败 | `{"state":2,"state_info":"编辑失败"}` |

## 连接/断开设备接口

### 基本信息

- URL：`/api/collector/common/device/set_connect_status`
- 方法：`POST`
- 请求体：`application/json`
- 普通响应类型：JSON
- 主要用途：连接或断开指定采集设备。该接口是通用设备接口，Modbus 设备调用时 `type` 传 `modbus`。

### 请求字段

| 字段 | 类型 | 必填 | 默认/行为 | 含义 |
|---|---|---|---|---|
| `id` | int | 是 | Go 零值 `0` | 设备 ID。接口会从采集器内存中按 ID 查找设备。 |
| `status` | int | 是 | Go 零值 `0` 会进入非法状态逻辑 | 要设置的设备连接状态。`1` 表示断开，`2` 表示连接。 |
| `type` | string | 建议传 | 当前处理逻辑不直接使用该字段 | 设备协议类型。Modbus 设备传 `modbus`，其他可传 `s7`、`bacnet`、`ethernet-ip`、`opc-ua`、`opc-da`、`snmp`、`iec104`。 |

### status 取值

| 值 | 含义 | 接口行为 |
|---:|---|---|
| `1` | disconnected，断开连接 | 调用设备断开逻辑，成功后设备 `status` 通常为 `1`，`running_status` 通常为 `0`。 |
| `2` | connected，连接设备 | 调用设备连接逻辑，成功后设备 `status` 通常为 `2`，`running_status` 取决于设备采集状态。 |
| 其他 | 非法状态 | 返回失败响应，通常为 `{"state":2,"state_info":"操作设备失败"}`。 |

### 请求示例：连接 Modbus 设备

```json
{
  "id": 1,
  "type": "modbus",
  "status": 2
}
```

### 请求示例：断开 Modbus 设备

```json
{
  "id": 1,
  "type": "modbus",
  "status": 1
}
```

### 成功响应

```json
{
  "state": 0,
  "state_info": "",
  "data": {
    "status": 2,
    "running_status": 0,
    "msg": ""
  }
}
```

### 成功响应字段说明

| 字段 | 类型 | 含义 |
|---|---|---|
| `state` | int | 业务状态码。成功时为 `0`。 |
| `state_info` | string | 状态描述。该接口成功时通常为空字符串。 |
| `data.status` | int | 操作后的设备连接状态，见设备 `status` 枚举。 |
| `data.running_status` | int | 操作后的设备运行状态，见 `running_status` 枚举。 |
| `data.msg` | string | 连接失败时可能返回底层错误消息；成功时通常为空字符串。 |

### 失败响应示例

请求体无法绑定或字段类型错误：

```json
{
  "state": 2,
  "state_info": "无效参数",
  "data": null
}
```

设备不存在或不在当前采集器内存中：

```json
{
  "state": 2,
  "state_info": "查询详情失败",
  "data": null
}
```

连接设备时发现点位标识与其他运行设备重复：

```json
{
  "state": 2,
  "state_info": "point_id: AI_TEMP_01 在运行的设备中已存在",
  "data": null
}
```

设备连接或断开失败：

```json
{
  "state": 2,
  "state_info": "操作设备失败",
  "data": {
    "status": 1,
    "running_status": 0,
    "msg": ""
  }
}
```

## 查询设备点位列表接口

### 基本信息

- URL：`/api/collector/common/device/get_collect_point`
- 方法：`POST`
- 请求体：`application/json`
- 普通响应类型：JSON
- 主要用途：查询指定设备当前内存中的采集点位列表。该接口是通用设备点位接口，Modbus 设备调用时 `type` 传 `modbus`。

### 请求字段

| 字段 | 类型 | 必填 | 默认/行为 | 含义 |
|---|---|---|---|---|
| `id` | int | 是 | Go 零值 `0` | 设备 ID。 |
| `type` | string | 是 | 空字符串会返回无效参数 | 设备协议类型。查询 Modbus 点位固定传 `modbus`。 |
| `group_id` | int | 否 | `0` | 点位分组 ID。为 `0` 时返回该设备下全部点位；非 `0` 时只返回该分组下点位。 |

### type 取值

| 值 | 含义 |
|---|---|
| `modbus` | Modbus 设备点位。 |
| `s7` | S7 设备点位。 |
| `bacnet` | BACnet 设备点位。 |
| `ethernet-ip` | EtherNet/IP 设备点位。 |
| `opc-ua` | OPC UA 设备点位。 |
| `opc-da` | OPC DA 设备点位。 |
| `snmp` | SNMP 设备点位。 |
| `iec104` | IEC104 设备点位。 |

### 请求示例：查询 Modbus 设备全部点位

```json
{
  "id": 1,
  "type": "modbus",
  "group_id": 0
}
```

### 请求示例：查询指定点位分组

```json
{
  "id": 1,
  "type": "modbus",
  "group_id": 100
}
```

### Modbus 成功响应示例

```json
{
  "state": 0,
  "state_info": "",
  "data": {
    "point": [
      {
        "id": 101,
        "point_id": "HR_UINT16",
        "name": "holding_register_uint16",
        "address": 10,
        "type": "uint16",
        "device_id": 1,
        "status": 1,
        "describe": "保持寄存器 uint16 示例",
        "function_code": 3,
        "present_value": 123,
        "scale_ratio": 1,
        "value_offset": 0,
        "group_id": 0,
        "bit": 0,
        "update_time": "2026-06-16T10:03:00+08:00",
        "invalid_values": "",
        "valid_range_start": null,
        "valid_range_end": null
      }
    ],
    "total": 1
  }
}
```

### Modbus 成功响应字段说明

| 字段 | 类型 | 含义 |
|---|---|---|
| `state` | int | 业务状态码。成功时为 `0`。 |
| `state_info` | string | 状态描述。该接口成功时通常为空字符串。 |
| `data.point` | object[] | 点位列表。 |
| `data.total` | int | 本次返回的点位数量。传 `group_id` 过滤时为过滤后的数量。 |
| `data.point[].id` | int | 采集点位内部 ID。 |
| `data.point[].point_id` | string | 外部点位标识。创建点位时未传则可能为空字符串。 |
| `data.point[].name` | string | 点位名称。 |
| `data.point[].address` | int | Modbus 点位地址，采集时实际读取地址为 `address - 设备 address_offset`。 |
| `data.point[].type` | string | Modbus 点位数据类型，例如 `bool`、`uint16`、`float32`。 |
| `data.point[].device_id` | int | 所属设备 ID。 |
| `data.point[].status` | int | 点位采集状态，见点位 `status` 枚举。 |
| `data.point[].describe` | string | 点位描述。 |
| `data.point[].function_code` | int | Modbus 功能码，见 `func_code` 枚举。 |
| `data.point[].present_value` | number | 当前内存中的点位最新值。设备未采集或未刷新时可能为 `0`。 |
| `data.point[].scale_ratio` | number | 缩放系数。 |
| `data.point[].value_offset` | number | 值偏移。 |
| `data.point[].group_id` | int | 点位分组 ID。 |
| `data.point[].bit` | int | 位下标。寄存器布尔点位使用；非位点通常为 `0`。 |
| `data.point[].update_time` | string | 点位更新时间，Go JSON time/RFC3339 格式。 |
| `data.point[].invalid_values` | string | 无效值列表字符串，多个值用逗号分隔；没有配置时为空字符串。 |
| `data.point[].valid_range_start` | number/null | 合法范围最小值。 |
| `data.point[].valid_range_end` | number/null | 合法范围最大值。 |

### 失败响应示例

请求体无法绑定或 `type` 不支持：

```json
{
  "state": 2,
  "state_info": "无效参数",
  "data": null
}
```

设备不存在或不在当前采集器内存中：

```json
{
  "state": 2,
  "state_info": "设备ID不合法",
  "data": null
}
```

### 注意事项

- 该接口返回的是设备内存对象中的点位，不是每次直接查询数据库。
- Modbus 点位响应字段中的 `function_code` 对应创建点位接口请求字段 `func_code`。
- Modbus 点位响应字段中的 `type` 对应创建点位接口请求字段 `type`，底层内部字段名为 `data_type`。
- `present_value` 是当前内存最新值；如果设备未连接、未采集或点位未刷新，不能仅凭该字段判断设备实时可用性。

## 查询设备列表接口

### 基本信息

- URL：`/api/collector/device`
- 方法：`GET`
- 请求参数位置：Query String
- 普通响应类型：JSON
- 主要用途：查询当前采集器内存中的设备列表，并按设备分组、点位分组组织成树形结构。

### 请求参数

| 参数 | 类型 | 必填 | 默认值 | 含义 |
|---|---|---|---|---|
| `num_points` | bool | 否 | `false` | 是否统计设备或点位分组下的点位数量。为 `true` 时返回对象中的 `num_points` 有实际统计值。 |
| `format` | string | 否 | 空 | 返回格式。普通 JSON 列表不传；传 `xlsx` 时进入导出逻辑，返回 zip/xlsx 文件流。 |
| `id` | int[] | 否 | 空数组 | 仅 `format=xlsx` 时使用，指定要导出的设备 ID。可重复传参：`id=1&id=2`。普通 JSON 列表模式不使用。 |
| `group_id` | int[] | 否 | 空数组 | 仅 `format=xlsx` 时使用，指定要导出的设备分组 ID。可重复传参：`group_id=10&group_id=11`。普通 JSON 列表模式不使用。 |
| `bacnet_lan` | bool | 否 | `false` | 为 `true` 时执行 BACnet Who-Is 扫描并返回扫描到的 BACnet 设备，不走普通设备树列表逻辑。 |
| `batch` | bool | 否 | `false` | 当前 GET 普通列表逻辑未使用该参数。 |
| `buffer` | bool | 否 | `false` | 当前 GET 普通列表逻辑未使用该参数；POST 导入场景使用。 |

### 请求示例

- 查询普通设备树

```http
GET /api/collector/device
```

- 查询设备树并统计点位数量

```http
GET /api/collector/device?num_points=true
```

### 响应示例

```json
{
  "state": 0,
  "state_info": "",
  "devices": [
    {
      "id": 10,
      "name": "现场设备分组",
      "type": "devicegroup",
      "created_time": "2026-06-16T10:00:00+08:00",
      "updated_time": "2026-06-16T10:00:00+08:00",
      "sort_index": 0,
      "group_id": 0,
      "num_points": 0,
      "groups": [
        {
          "id": 1,
          "name": "modbus_tcp_1",
          "type": "modbus",
          "created_time": "2026-06-16T10:01:00+08:00",
          "updated_time": "2026-06-16T10:01:00+08:00",
          "sort_index": 0,
          "group_id": 10,
          "alarm_interval": 0,
          "collect_interval": 0,
          "status": 1,
          "running_status": 0,
          "connect_status": 0,
          "is_persistent": true,
          "device_type": 1,
          "ip": "127.0.0.1",
          "port": 5502,
          "slave_id": 1,
          "byte_order": 1,
          "word_order": 1,
          "timeout": 3,
          "address_offset": 0,
          "retry_times": 0,
          "num_points": 3,
          "groups": [
            {
              "id": 100,
              "name": "默认点位分组",
              "type": "pointgroup",
              "created_time": "2026-06-16T10:02:00+08:00",
              "sort_index": 0,
              "group_collect": false,
              "num_points": 3
            }
          ]
        }
      ]
    }
  ],
  "refresh_msg": ""
}
```

- 响应字段说明

| 字段 | 类型 | 含义 |
|---|---|---|
| `state` | int | 业务状态码。成功时为 `0`；绑定 query 失败时返回失败响应。 |
| `state_info` | string | 状态描述。普通成功列表当前为空字符串。 |
| `devices` | array | 顶层设备或设备分组列表。只包含 `group_id=0` 的顶层对象，其子节点在 `groups` 内。 |
| `refresh_msg` | string | 刷新消息字段，当前普通列表逻辑通常为空字符串。 |

失败响应示例：

```json
{
  "state": 500,
  "state_info": "失败"
}
```

- `devices[]` / `groups[]` 对象通用字段

返回对象使用同一个结构 `DeviceOrGroup` 表示设备、设备分组和点位分组。不同 `type` 会返回不同字段；带 `omitempty` 的字段在无值时可能不出现。

| 字段 | 类型 | 适用对象 | 含义 |
|---|---|---|---|
| `id` | int | 全部 | 对象 ID。设备/设备分组来自设备表 ID；点位分组来自点位分组 ID。 |
| `name` | string | 全部 | 名称。 |
| `type` | string | 全部 | 对象类型或协议类型，见设备类型枚举。 |
| `created_time` | string | 全部 | 创建时间，RFC3339/Go JSON time 格式。 |
| `updated_time` | string | 设备/设备分组 | 更新时间。点位分组一般不返回。 |
| `sort_index` | int | 全部 | 排序序号，数值越小越靠前。 |
| `group_id` | int | 设备/设备分组 | 父设备分组 ID。顶层对象为 `0`。点位分组对象通常不返回该字段。 |
| `alarm_interval` | int | 设备 | 告警间隔，来自设备内部配置。 |
| `collect_interval` | int | 设备 | 采集周期，来自设备内部配置。 |
| `operation_time` | string/null | 设备 | 最近一次设备操作时间，例如连接、采集、断开。 |
| `operation_flag` | string | 设备 | 最近一次设备操作标记，见操作标记枚举。 |
| `buffer_id` | string | 导入缓冲对象/设备 | 导入缓冲 ID。普通已保存设备通常为空字符串但可能仍返回。 |
| `group_collect` | bool | 点位分组 | 点位分组是否按组采集。设备对象该字段通常为 `false`。 |
| `num_points` | int | 设备/点位分组 | 点位数量。受 `num_points` query 参数影响。 |
| `status` | int | 设备 | 设备连接状态，见设备 `status` 枚举。 |
| `running_status` | int | 设备 | 设备运行/采集状态，见 `running_status` 枚举。 |
| `connect_status` | int | 设备 | 最近连接状态，见 `connect_status` 枚举。 |
| `is_persistent` | bool | 设备 | 是否持久化设备。 |
| `next_reconnect_time` | string | 设备 | 下次重连时间。 |
| `groups` | array | 设备/设备分组 | 子节点列表，包含点位分组和子设备/子设备分组。 |

### 注意事项

- 该接口普通 JSON 模式不支持分页、关键字搜索或按协议过滤。
- 返回数据来自运行时内存中的设备集合，不是每次直接查询数据库。
- `groups` 字段同时承载设备分组子设备和点位分组，需要通过子节点 `type` 区分。
- `format=xlsx` 时响应不是 JSON，而是 `application/octet-stream` 文件下载。
- `bacnet_lan=true` 时响应是 BACnet Who-Is 扫描结果，不包含普通设备树中的点位分组结构。
- 当前普通列表可能返回 `password`、`auth_pwd`、`priv_pwd` 等敏感字段，调用方展示或日志记录时需要注意脱敏。