jzw/VWED_server

Fork 0

靳中伟 2899453300 add api

2025-07-14 10:29:37 +08:00

20 KiB

Raw Permalink Blame History

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

请求示例

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

响应参数

{
  "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	服务器内部错误

错误响应示例

{
  "code": 400,
  "message": "设备名称 '呼叫器-A区' 已存在",
  "data": null
}

{
  "code": 400,
  "message": "IP地址 '10.2.0.10' 已存在",
  "data": null
}

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

请求示例

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

响应参数

{
  "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	服务器内部错误

错误响应示例

{
  "code": 400,
  "message": "未找到ID为 'modbus_device_8f7e6d5c-4b3a-2c1d-0e9f-8a7b6c5d4e3f' 的呼叫器设备",
  "data": null
}

{
  "code": 400,
  "message": "IP地址 '10.2.0.11' 已被其他设备使用",
  "data": null
}

{
  "code": 400,
  "message": "以下任务ID不存在: 9a8b7c6d-5e4f-3g2h-1i0j-9k8l7m6n5o4p",
  "data": null
}

4. 删除呼叫器设备

接口描述

批量删除多个呼叫器设备及其所有按钮配置（软删除）。

请求方式

HTTP方法: POST
接口路径: /api/vwed-calldevice/batch-delete

请求参数

参数名	类型	必填	描述
ids	Array	是	要删除的设备ID列表

请求示例

{
  "ids": [
    "modbus_device_8f7e6d5c-4b3a-2c1d-0e9f-8a7b6c5d4e3f", 
    "modbus_device_1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p"
  ]
}

响应参数

{
  "code": 200,
  "message": "成功删除 2 个呼叫器设备",
  "data": {
    "ids": [
      "modbus_device_8f7e6d5c-4b3a-2c1d-0e9f-8a7b6c5d4e3f", 
      "modbus_device_1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p"
    ]
  }
}

错误码

错误码	描述
400	参数错误，如设备ID不存在或ID列表为空
500	服务器内部错误

错误响应示例

{
  "code": 400,
  "message": "设备ID列表不能为空",
  "data": null
}

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

响应参数

{
  "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	服务器内部错误

错误响应示例

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

响应参数

{
  "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	服务器内部错误

错误响应示例

{
  "code": 400,
  "message": "未找到ID为 'modbus_device_8f7e6d5c-4b3a-2c1d-0e9f-8a7b6c5d4e3f' 的呼叫器设备",
  "data": null
}

7. 批量导出呼叫器设备

接口描述

将选定的多个呼叫器设备导出为加密格式的文件，便于跨系统迁移或备份。

请求方式

HTTP方法: POST
接口路径: /api/vwed-calldevice/export-batch

请求参数

参数名	类型	必填	描述
ids	Array	是	要导出的设备ID列表

请求示例

{
  "ids": [
    "modbus_device_8f7e6d5c-4b3a-2c1d-0e9f-8a7b6c5d4e3f", 
    "modbus_device_1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p"
  ]
}

响应参数

文件下载响应，包含加密的设备配置文件。

错误码

错误码	描述
400	参数错误，如设备ID不存在或ID列表为空
500	服务器内部错误

错误响应示例

{
  "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	是	呼叫器设备配置文件，加密专有格式

响应参数

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

部分导入成功示例

{
  "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	服务器内部错误

错误响应示例

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

响应参数

{
  "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	服务器内部错误

错误响应示例

{
  "code": 400,
  "message": "启动设备监控失败: 未找到ID为 'modbus_device_8f7e6d5c-4b3a-2c1d-0e9f-8a7b6c5d4e3f' 的呼叫器设备",
  "data": null
}

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

响应参数

{
  "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	服务器内部错误

错误响应示例

{
  "code": 400,
  "message": "停止设备监控失败: 未找到ID为 'modbus_device_8f7e6d5c-4b3a-2c1d-0e9f-8a7b6c5d4e3f' 的呼叫器设备",
  "data": null
}

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

响应参数

{
  "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	服务器内部错误

错误响应示例

{
  "code": 400,
  "message": "获取设备监控状态失败: 未找到ID为 'modbus_device_8f7e6d5c-4b3a-2c1d-0e9f-8a7b6c5d4e3f' 的呼叫器设备",
  "data": null
}

20 KiB Raw Permalink Blame History Unescape Escape

VWED呼叫器设备接口文档

接口概述

接口列表

1. 新增呼叫器设备

接口描述

请求方式

请求参数

请求示例

响应参数

错误码

错误响应示例

2. 更新呼叫器设备

接口描述

请求方式

请求参数

请求示例

响应参数

错误码

错误响应示例

4. 删除呼叫器设备

接口描述

请求方式

请求参数

请求示例

响应参数

错误码

错误响应示例

5. 获取呼叫器设备列表

接口描述

请求方式

请求参数

请求示例

响应参数

错误码

错误响应示例

6. 获取呼叫器设备详情

接口描述

请求方式

请求参数

请求示例

响应参数

错误码

错误响应示例

7. 批量导出呼叫器设备

接口描述

请求方式

请求参数

请求示例

响应参数

错误码

错误响应示例

8. 导入呼叫器设备

接口描述

请求方式

请求参数

响应参数

部分导入成功示例

错误码

错误响应示例

9. 启动呼叫器

接口描述

请求方式

请求参数

请求示例

响应参数

错误码

错误响应示例

10. 停止呼叫器

接口描述

请求方式

请求参数

请求示例

响应参数

错误码

错误响应示例

11. 获取设备监控状态

接口描述

请求方式

请求参数

20 KiB

Raw Permalink Blame History