# 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 } ```