VWED_server/VWED任务模块接口文档/呼叫器设备接口文档.md

880 lines
20 KiB
Markdown
Raw Normal View History

2025-07-14 10:29:37 +08:00
# VWED呼叫器设备接口文档
## 接口概述
本文档描述了VWED系统中呼叫器设备管理相关的API接口。这些接口用于管理系统中的呼叫器设备包括新增、修改、删除、查询等操作。
## 接口列表
### 1. 新增呼叫器设备
#### 接口描述
新增一个呼叫器设备及其按钮配置。一个呼叫器设备可以配置多个按钮,每个按钮可以绑定不同的任务。
#### 请求方式
- **HTTP方法**: POST
- **接口路径**: `/api/vwed-calldevice/add`
#### 请求参数
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|-----|------|
| protocol | String | 是 | 协议类型 |
| brand | String | 是 | 品牌 |
| ip | String | 是 | IP地址 |
| port | Integer | 是 | 端口号 |
| device_name | String | 是 | 设备名称 |
| status | Integer | 否 | 状态(0:禁用,1:启用)默认为1 |
| slave_id | String | 否 | 从机ID默认为"1" |
| buttons | Array | 否 | 按钮配置列表 |
**buttons数组中的元素结构**
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|-----|------|
| signal_name | String | 是 | 信号名称 |
| signal_type | Integer | 是 | 信号类型 1:按钮 2:灯 |
| signal_length | String | 是 | 信号长度 |
| register_address | String | 是 | 寄存器地址 |
| function_code | String | 否 | 功能码 |
| remark | String | 否 | 备注 |
| vwed_task_id | String | 否 | 按下灯亮绑定的VWED任务ID |
| long_vwed_task_id | String | 否 | 长按取消后触发VWED任务ID |
#### 请求示例
```json
{
"protocol": "TCP",
"brand": "艾智威",
"ip": "10.2.0.10",
"port": 5020,
"device_name": "呼叫器-A区",
"status": 1,
"slave_id": "1",
"buttons": [
{
"signal_name": "button1",
"signal_type": 1,
"signal_length": "1",
"register_address": "1",
"function_code": "6",
"remark": "A区1号按钮",
"vwed_task_id": "193f8412-fa0d-4b6d-9648-70bceacd6629",
"long_vwed_task_id": "734749d1-0fdf-4a06-9fb7-8f991953d5e5"
},
{
"signal_name": "led1",
"signal_type": 2,
"signal_length": "1",
"register_address": "2",
"function_code": "6",
"remark": "A区1号指示灯",
"vwed_task_id": "7c6aac36-652b-4314-9433-f5788e9e7adb"
}
]
}
```
#### 响应参数
```json
{
"code": 200,
"message": "新增呼叫器设备成功",
"data": {
"id": "modbus_device_8f7e6d5c-4b3a-2c1d-0e9f-8a7b6c5d4e3f",
"protocol": "TCP",
"brand": "艾智威",
"ip": "10.2.0.10",
"port": 5020,
"device_name": "呼叫器-A区",
"status": 1,
"slave_id": "1",
"buttons": [
{
"id": "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p",
"signal_name": "button1",
"signal_type": 1,
"signal_length": "1",
"register_address": "1",
"function_code": "6",
"remark": "A区1号按钮",
"vwed_task_id": "193f8412-fa0d-4b6d-9648-70bceacd6629",
"long_vwed_task_id": "734749d1-0fdf-4a06-9fb7-8f991953d5e5"
},
{
"id": "6p5o4n3m-2l1k-0j9i-8h7g-6f5e4d3c2b1a",
"signal_name": "led1",
"signal_type": 2,
"signal_length": "1",
"register_address": "2",
"function_code": "6",
"remark": "A区1号指示灯",
"vwed_task_id": "7c6aac36-652b-4314-9433-f5788e9e7adb",
"long_vwed_task_id": null
}
]
}
}
```
#### 错误码
| 错误码 | 描述 |
|-------|------|
| 400 | 参数错误如设备名称或IP地址已存在 |
| 500 | 服务器内部错误 |
#### 错误响应示例
```json
{
"code": 400,
"message": "设备名称 '呼叫器-A区' 已存在",
"data": null
}
```
```json
{
"code": 400,
"message": "IP地址 '10.2.0.10' 已存在",
"data": null
}
```
```json
{
"code": 400,
"message": "以下任务ID不存在: 193f8412-fa0d-4b6d-9648-70bceacd6629, 734749d1-0fdf-4a06-9fb7-8f991953d5e5",
"data": null
}
```
### 2. 更新呼叫器设备
#### 接口描述
更新指定ID的呼叫器设备信息及其按钮配置。更新时会替换所有原有的按钮配置。
#### 请求方式
- **HTTP方法**: PUT
- **接口路径**: `/api/vwed-calldevice/update/{device_id}`
#### 请求参数
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|-----|------|
| device_id | String | 是 | 设备ID路径参数 |
| protocol | String | 是 | 协议类型 |
| brand | String | 是 | 品牌 |
| ip | String | 是 | IP地址 |
| port | Integer | 是 | 端口号 |
| device_name | String | 是 | 设备名称 |
| status | Integer | 否 | 状态(0:禁用,1:启用)默认为1 |
| slave_id | String | 否 | 从机ID默认为"1" |
| buttons | Array | 否 | 按钮配置列表 |
**buttons数组中的元素结构**
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|-----|------|
| signal_name | String | 是 | 信号名称 |
| signal_type | Integer | 是 | 信号类型 1:按钮 2:灯 |
| signal_length | String | 是 | 信号长度 |
| register_address | String | 是 | 寄存器地址 |
| function_code | String | 否 | 功能码 |
| remark | String | 否 | 备注 |
| vwed_task_id | String | 否 | 按下灯亮绑定的VWED任务ID |
| long_vwed_task_id | String | 否 | 长按取消后触发VWED任务ID |
#### 请求示例
```json
{
"protocol": "TCP",
"brand": "艾智威-更新",
"ip": "10.2.0.11",
"port": 5021,
"device_name": "呼叫器-A区-更新",
"status": 1,
"slave_id": "1",
"buttons": [
{
"signal_name": "button1",
"signal_type": 1,
"signal_length": "1",
"register_address": "1",
"function_code": "6",
"remark": "A区1号按钮-更新",
"vwed_task_id": "193f8412-fa0d-4b6d-9648-70bceacd6629",
"long_vwed_task_id": "734749d1-0fdf-4a06-9fb7-8f991953d5e5"
},
{
"signal_name": "led1",
"signal_type": 2,
"signal_length": "1",
"register_address": "2",
"function_code": "6",
"remark": "A区1号指示灯-更新",
"vwed_task_id": "7c6aac36-652b-4314-9433-f5788e9e7adb"
},
{
"signal_name": "button2",
"signal_type": 1,
"signal_length": "1",
"register_address": "3",
"function_code": "6",
"remark": "A区2号按钮-新增",
"vwed_task_id": "9a8b7c6d-5e4f-3g2h-1i0j-9k8l7m6n5o4p"
}
]
}
```
#### 响应参数
```json
{
"code": 200,
"message": "更新呼叫器设备成功",
"data": {
"id": "modbus_device_8f7e6d5c-4b3a-2c1d-0e9f-8a7b6c5d4e3f",
"protocol": "TCP",
"brand": "艾智威-更新",
"ip": "10.2.0.11",
"port": 5021,
"device_name": "呼叫器-A区-更新",
"status": 1,
"slave_id": "1",
"buttons": [
{
"id": "2b3c4d5e-6f7g-8h9i-0j1k-2l3m4n5o6p7q",
"signal_name": "button1",
"signal_type": 1,
"signal_length": "1",
"register_address": "1",
"function_code": "6",
"remark": "A区1号按钮-更新",
"vwed_task_id": "193f8412-fa0d-4b6d-9648-70bceacd6629",
"long_vwed_task_id": "734749d1-0fdf-4a06-9fb7-8f991953d5e5"
},
{
"id": "7q6p5o4n-3m2l-1k0j-9i8h-7g6f5e4d3c2b",
"signal_name": "led1",
"signal_type": 2,
"signal_length": "1",
"register_address": "2",
"function_code": "6",
"remark": "A区1号指示灯-更新",
"vwed_task_id": "7c6aac36-652b-4314-9433-f5788e9e7adb",
"long_vwed_task_id": null
},
{
"id": "8r7q6p5o-4n3m-2l1k-0j9i-8h7g6f5e4d3c",
"signal_name": "button2",
"signal_type": 1,
"signal_length": "1",
"register_address": "3",
"function_code": "6",
"remark": "A区2号按钮-新增",
"vwed_task_id": "9a8b7c6d-5e4f-3g2h-1i0j-9k8l7m6n5o4p",
"long_vwed_task_id": null
}
]
}
}
```
#### 错误码
| 错误码 | 描述 |
|-------|------|
| 400 | 参数错误如设备不存在、IP地址已被其他设备使用 |
| 500 | 服务器内部错误 |
#### 错误响应示例
```json
{
"code": 400,
"message": "未找到ID为 'modbus_device_8f7e6d5c-4b3a-2c1d-0e9f-8a7b6c5d4e3f' 的呼叫器设备",
"data": null
}
```
```json
{
"code": 400,
"message": "IP地址 '10.2.0.11' 已被其他设备使用",
"data": null
}
```
```json
{
"code": 400,
"message": "以下任务ID不存在: 9a8b7c6d-5e4f-3g2h-1i0j-9k8l7m6n5o4p",
"data": null
}
```
### 4. 删除呼叫器设备
#### 接口描述
批量删除多个呼叫器设备及其所有按钮配置(软删除)。
#### 请求方式
- **HTTP方法**: POST
- **接口路径**: `/api/vwed-calldevice/batch-delete`
#### 请求参数
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|-----|------|
| ids | Array | 是 | 要删除的设备ID列表 |
#### 请求示例
```json
{
"ids": [
"modbus_device_8f7e6d5c-4b3a-2c1d-0e9f-8a7b6c5d4e3f",
"modbus_device_1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p"
]
}
```
#### 响应参数
```json
{
"code": 200,
"message": "成功删除 2 个呼叫器设备",
"data": {
"ids": [
"modbus_device_8f7e6d5c-4b3a-2c1d-0e9f-8a7b6c5d4e3f",
"modbus_device_1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p"
]
}
}
```
#### 错误码
| 错误码 | 描述 |
|-------|------|
| 400 | 参数错误如设备ID不存在或ID列表为空 |
| 500 | 服务器内部错误 |
#### 错误响应示例
```json
{
"code": 400,
"message": "设备ID列表不能为空",
"data": null
}
```
```json
{
"code": 400,
"message": "未找到以下ID的呼叫器设备: modbus_device_8f7e6d5c-4b3a-2c1d-0e9f-8a7b6c5d4e3f, modbus_device_1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p",
"data": null
}
```
### 5. 获取呼叫器设备列表
#### 接口描述
获取系统中的呼叫器设备列表支持分页、设备名称搜索、IP地址搜索和状态过滤。
#### 请求方式
- **HTTP方法**: GET
- **接口路径**: `/api/vwed-calldevice/list`
#### 请求参数
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|-----|------|
| page | Integer | 否 | 页码默认为1 |
| page_size | Integer | 否 | 每页数量默认为10最大100 |
| device_name | String | 否 | 设备名称搜索 |
| ip | String | 否 | IP地址搜索 |
| protocol | String | 否 | 协议类型搜索 |
| status | Integer | 否 | 状态过滤(0:禁用,1:启用) |
#### 请求示例
```
GET /api/vwed-calldevice/list?page=1&page_size=10&device_name=呼叫器&ip=10.2&protocol=TCP
```
#### 响应参数
```json
{
"code": 200,
"message": "获取呼叫器设备列表成功",
"data": {
"list": [
{
"id": "modbus_device_8f7e6d5c-4b3a-2c1d-0e9f-8a7b6c5d4e3f",
"protocol": "TCP",
"brand": "艾智威",
"ip": "10.2.0.10",
"port": 5020,
"device_name": "呼叫器-A区",
"status": 1,
"slave_id": "1",
"created_at": "2023-06-15 10:30:45",
"button_count": 2
},
{
"id": "modbus_device_1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p",
"protocol": "TCP",
"brand": "艾智威",
"ip": "10.2.0.11",
"port": 5021,
"device_name": "呼叫器-B区",
"status": 1,
"slave_id": "2",
"created_at": "2023-06-14 14:20:30",
"button_count": 3
}
],
"pagination": {
"total": 5,
"page": 1,
"page_size": 10,
"total_pages": 1
}
}
}
```
#### 错误码
| 错误码 | 描述 |
|-------|------|
| 400 | 参数错误 |
| 500 | 服务器内部错误 |
#### 错误响应示例
```json
{
"code": 400,
"message": "获取呼叫器设备列表失败: 参数错误",
"data": null
}
```
### 6. 获取呼叫器设备详情
#### 接口描述
根据设备ID获取呼叫器设备的详细信息包括设备基本信息和按钮配置。
#### 请求方式
- **HTTP方法**: GET
- **接口路径**: `/api/vwed-calldevice/detail/{device_id}`
#### 请求参数
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|-----|------|
| device_id | String | 是 | 设备ID路径参数 |
#### 请求示例
```
GET /api/vwed-calldevice/detail/modbus_device_8f7e6d5c-4b3a-2c1d-0e9f-8a7b6c5d4e3f
```
#### 响应参数
```json
{
"code": 200,
"message": "获取呼叫器设备详情成功",
"data": {
"id": "modbus_device_8f7e6d5c-4b3a-2c1d-0e9f-8a7b6c5d4e3f",
"protocol": "TCP",
"brand": "艾智威",
"ip": "10.2.0.10",
"port": 5020,
"device_name": "呼叫器-A区",
"status": 1,
"slave_id": "1",
"created_at": "2023-06-15 10:30:45",
"updated_at": "2023-06-16 09:15:20",
"buttons": [
{
"id": "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p",
"signal_name": "button1",
"signal_type": 1,
"signal_length": "1",
"register_address": "1",
"function_code": "6",
"remark": "A区1号按钮",
"vwed_task_id": "193f8412-fa0d-4b6d-9648-70bceacd6629",
"long_vwed_task_id": "734749d1-0fdf-4a06-9fb7-8f991953d5e5",
"created_at": "2023-06-15 10:30:45"
},
{
"id": "6p5o4n3m-2l1k-0j9i-8h7g-6f5e4d3c2b1a",
"signal_name": "led1",
"signal_type": 2,
"signal_length": "1",
"register_address": "2",
"function_code": "6",
"remark": "A区1号指示灯",
"vwed_task_id": "7c6aac36-652b-4314-9433-f5788e9e7adb",
"long_vwed_task_id": null,
"created_at": "2023-06-15 10:30:45"
}
]
}
}
```
#### 错误码
| 错误码 | 描述 |
|-------|------|
| 400 | 参数错误如设备ID不存在 |
| 500 | 服务器内部错误 |
#### 错误响应示例
```json
{
"code": 400,
"message": "未找到ID为 'modbus_device_8f7e6d5c-4b3a-2c1d-0e9f-8a7b6c5d4e3f' 的呼叫器设备",
"data": null
}
```
### 7. 批量导出呼叫器设备
#### 接口描述
将选定的多个呼叫器设备导出为加密格式的文件,便于跨系统迁移或备份。
#### 请求方式
- **HTTP方法**: POST
- **接口路径**: `/api/vwed-calldevice/export-batch`
#### 请求参数
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|-----|------|
| ids | Array | 是 | 要导出的设备ID列表 |
#### 请求示例
```json
{
"ids": [
"modbus_device_8f7e6d5c-4b3a-2c1d-0e9f-8a7b6c5d4e3f",
"modbus_device_1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p"
]
}
```
#### 响应参数
文件下载响应,包含加密的设备配置文件。
#### 错误码
| 错误码 | 描述 |
|-------|------|
| 400 | 参数错误如设备ID不存在或ID列表为空 |
| 500 | 服务器内部错误 |
#### 错误响应示例
```json
{
"code": 400,
"message": "未找到以下ID的呼叫器设备: modbus_device_8f7e6d5c-4b3a-2c1d-0e9f-8a7b6c5d4e3f, modbus_device_1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p",
"data": null
}
```
### 8. 导入呼叫器设备
#### 接口描述
从加密的配置文件导入呼叫器设备配置,支持同时导入多个设备。导入的设备名称会自动添加后缀以避免与已有设备冲突。
#### 请求方式
- **HTTP方法**: POST
- **接口路径**: `/api/vwed-calldevice/import`
#### 请求参数
表单提交,包含文件字段:
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|-----|------|
| file | File | 是 | 呼叫器设备配置文件,加密专有格式 |
#### 响应参数
```json
{
"code": 200,
"message": "成功导入 2 个呼叫器设备",
"data": {
"success_count": 2,
"failed_count": 0,
"failed_devices": [],
"imported_devices": [
{
"id": "modbus_device_8f7e6d5c-4b3a-2c1d-0e9f-8a7b6c5d4e3f",
"device_name": "呼叫器-A区-备份-168332148391872",
"original_name": "呼叫器-A区"
},
{
"id": "modbus_device_1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p",
"device_name": "呼叫器-B区-备份-168332148391872",
"original_name": "呼叫器-B区"
}
]
}
}
```
#### 部分导入成功示例
```json
{
"code": 200,
"message": "部分导入成功: 成功 1 个, 失败 1 个",
"data": {
"success_count": 1,
"failed_count": 1,
"failed_devices": [
{
"index": 1,
"device_name": "呼叫器-B区-备份-168332148391872",
"reason": "IP地址 '10.2.0.11' 已存在"
}
],
"imported_devices": [
{
"id": "modbus_device_8f7e6d5c-4b3a-2c1d-0e9f-8a7b6c5d4e3f",
"device_name": "呼叫器-A区-备份-168332148391872",
"original_name": "呼叫器-A区"
}
]
}
}
```
#### 错误码
| 错误码 | 描述 |
|-------|------|
| 400 | 参数错误,如文件格式不正确或无法解析 |
| 500 | 服务器内部错误 |
#### 错误响应示例
```json
{
"code": 400,
"message": "无法导入呼叫器设备: 文件格式无效或已损坏",
"data": null
}
```
### 9. 启动呼叫器
#### 接口描述
启动呼叫器。开启一个监控线程,持续监控设备按钮状态,当检测到按钮按下时触发对应任务。
#### 请求方式
- **HTTP方法**: POST
- **接口路径**: `/api/vwed-calldevice/monitor/start/{device_id}`
#### 请求参数
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|-----|------|
| device_id | String | 是 | 设备ID路径参数 |
#### 请求示例
```
POST /api/vwed-calldevice/monitor/start/modbus_device_8f7e6d5c-4b3a-2c1d-0e9f-8a7b6c5d4e3f
```
#### 响应参数
```json
{
"code": 200,
"message": "启动设备监控成功",
"data": {
"device_id": "modbus_device_8f7e6d5c-4b3a-2c1d-0e9f-8a7b6c5d4e3f",
"device_name": "呼叫器-A区",
"monitor_status": "running",
"started_at": "2023-06-18 10:15:30"
}
}
```
#### 错误码
| 错误码 | 描述 |
|-------|------|
| 400 | 参数错误如设备ID不存在或设备已在监控中 |
| 500 | 服务器内部错误 |
#### 错误响应示例
```json
{
"code": 400,
"message": "启动设备监控失败: 未找到ID为 'modbus_device_8f7e6d5c-4b3a-2c1d-0e9f-8a7b6c5d4e3f' 的呼叫器设备",
"data": null
}
```
```json
{
"code": 400,
"message": "启动设备监控失败: 设备监控已在运行中",
"data": null
}
```
### 10. 停止呼叫器
#### 接口描述
停止呼叫器监控
#### 请求方式
- **HTTP方法**: POST
- **接口路径**: `/api/vwed-calldevice/monitor/stop/{device_id}`
#### 请求参数
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|-----|------|
| device_id | String | 是 | 设备ID路径参数 |
#### 请求示例
```
POST /api/vwed-calldevice/monitor/stop/modbus_device_8f7e6d5c-4b3a-2c1d-0e9f-8a7b6c5d4e3f
```
#### 响应参数
```json
{
"code": 200,
"message": "停止设备监控成功",
"data": {
"device_id": "modbus_device_8f7e6d5c-4b3a-2c1d-0e9f-8a7b6c5d4e3f",
"device_name": "呼叫器-A区",
"monitor_status": "stopped",
"stopped_at": "2023-06-18 11:30:45"
}
}
```
#### 错误码
| 错误码 | 描述 |
|-------|------|
| 400 | 参数错误如设备ID不存在或设备未在监控中 |
| 500 | 服务器内部错误 |
#### 错误响应示例
```json
{
"code": 400,
"message": "停止设备监控失败: 未找到ID为 'modbus_device_8f7e6d5c-4b3a-2c1d-0e9f-8a7b6c5d4e3f' 的呼叫器设备",
"data": null
}
```
```json
{
"code": 400,
"message": "停止设备监控失败: 设备监控未运行",
"data": null
}
```
### 11. 获取设备监控状态
#### 接口描述
获取指定设备的监控状态信息。
#### 请求方式
- **HTTP方法**: GET
- **接口路径**: `/api/vwed-calldevice/monitor/status/{device_id}`
#### 请求参数
| 参数名 | 类型 | 必填 | 描述 |
|-------|------|-----|------|
| device_id | String | 是 | 设备ID路径参数 |
#### 请求示例
```
GET /api/vwed-calldevice/monitor/status/modbus_device_8f7e6d5c-4b3a-2c1d-0e9f-8a7b6c5d4e3f
```
#### 响应参数
```json
{
"code": 200,
"message": "获取设备监控状态成功",
"data": {
"device_id": "modbus_device_8f7e6d5c-4b3a-2c1d-0e9f-8a7b6c5d4e3f",
"device_name": "呼叫器-A区",
"monitor_status": "running",
"started_at": "2023-06-18 10:15:30",
"uptime_seconds": 4500,
"button_triggers": {
"total": 15,
"details": [
{
"button_address": "1",
"trigger_count": 8,
"last_triggered_at": "2023-06-18 11:20:45"
},
{
"button_address": "2",
"trigger_count": 7,
"last_triggered_at": "2023-06-18 11:15:30"
}
]
}
}
}
```
#### 错误码
| 错误码 | 描述 |
|-------|------|
| 400 | 参数错误如设备ID不存在 |
| 500 | 服务器内部错误 |
#### 错误响应示例
```json
{
"code": 400,
"message": "获取设备监控状态失败: 未找到ID为 'modbus_device_8f7e6d5c-4b3a-2c1d-0e9f-8a7b6c5d4e3f' 的呼叫器设备",
"data": null
}
```