data-collector-mcp/docs/接口汇总.md

1. 采集网关接口说明

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

采集网关服务器请求地址

http://127.0.0.1:8000

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

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

示例：

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

通用约定

请求格式

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

Content-Type: application/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 协议的地址计算方式如下：

protocol_address = address + address_base

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

"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 设备之间的原始通信报文。

示例：

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 服务是否启动。

成功返回

{
  "status": "ok"
}

返回字段说明：

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

调用示例

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 设备发起一次读取请求，只返回通信报文，不返回解析后的业务值。

请求体结构

{
  "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 数量。

成功返回示例

{
  "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 报文列表。

失败返回示例

设备无响应或通信失败：

{
  "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"
    ]
  }
}

请求字段校验失败：

{
  "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[]	失败前已经捕获到的通信报文。字段校验失败时通常为空数组。

调用示例

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 等业务值。

请求体结构

{
  "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 读取寄存器指定位。
不允许额外字段	请求对象中出现未定义字段会校验失败。

成功返回示例

{
  "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 决定。

失败返回示例

设备连接失败：

{
  "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": []
  }
}

读取部分点位后失败：

{
  "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[]	失败前已成功读取的点位。字段校验失败或连接失败时通常为空数组。

调用示例

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

{
  "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

{
  "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
}

成功响应

{
  "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 设备

{
  "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 设备

{
  "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
}

成功响应

{
  "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

{
  "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

{
  "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
}

请求示例：线圈点位

{
  "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
}

成功响应

{
  "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 点位

{
  "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

{
  "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
}

成功响应

{
  "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 设备

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

请求示例：断开 Modbus 设备

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

成功响应

{
  "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	连接失败时可能返回底层错误消息；成功时通常为空字符串。

失败响应示例

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

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

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

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

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

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

设备连接或断开失败：

{
  "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 设备全部点位

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

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

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

Modbus 成功响应示例

{
  "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 不支持：

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

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

{
  "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 导入场景使用。

请求示例

• 查询普通设备树

GET /api/collector/device

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

GET /api/collector/device?num_points=true

响应示例

{
  "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	刷新消息字段，当前普通列表逻辑通常为空字符串。

失败响应示例：

{
  "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 等敏感字段，调用方展示或日志记录时需要注意脱敏。