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 创建设备与创建点位接口文档

枚举汇总

• 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 取某一位。

• 状态枚举

接口创建时会写入初始状态，调用方通常不需要传。

字段	值	含义
设备 status	1	disconnected，未连接
设备 status	2	connected，已连接
设备 status	3	error，异常
设备 running_status	0	idle，未采集
设备 running_status	1	running，采集中
设备 running_status	2	error，运行异常
点位 status	0	idle，未采集
点位 status	1	working，采集正常
点位 status	2	error，采集异常

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/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":"新增失败"}

查询设备列表接口

基本信息

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