设备控制接口文档（ControlDevices）
ControlDevices 设备控制接口文档
功能简介
ControlDevices 是智能家居后端的统一设备控制接口，支持窗帘、灯管等多种设备类型的控制。接口会校验用户 token、家庭组权限、设备归属关系，并根据设备类型分发控制命令。请求说明
/device/case/controlPOSTapplication/jsonAuthorization Token请求参数
| 参数名 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| device_id | string | 是 | 设备唯一标识 |
| family_id | string | 是 | 家庭组唯一标识 |
| function | string | 是 | 控制功能（如窗帘/灯光 等） |
| params | object | 是 | 具体功能参数，结构随功能变化 |
支持的功能与用法
1. 窗帘控制（curtain）
execute_curtain_commandCurtainControlRequest 结构体请求示例
{
"device_id": "curtain001",
"family_id": "family001",
"function": "execute_curtain_command",
"params": {
"action": "open_curtain",
"position": 100
}
}响应示例
{
"code": 200,
"message": "窗帘控制命令执行成功"
}{
"code": 400,
"message": "[handler:ControlDevices] 参数解析失败: ..."
}2. 智能灯管控制（light）
execute_light_commandLightControlRequest 结构体请求示例
{
"device_id": "light001",
"family_id": "family001",
"function": "execute_light_command",
"params": {
"on": true,
"brightness": 80
}
}响应示例
{
"code": 200,
"message": "智能灯管控制命令执行成功"
}{
"code": 403,
"message": "[handler:ControlDevices] 设备无权访问该家庭组"
}通用响应结构
| 字段 | 类型 | 说明 |
|---|---|---|
| code | int | 状态码 |
| message | string | 提示信息 |
错误码说明
| code | 说明 |
|---|---|
| 200 | 操作成功 |
| 400 | 请求参数错误 |
| 401 | 无效token |
| 403 | 无权限 |
| 500 | 服务内部错误 |
典型错误响应示例
{
"code": 401,
"message": "[handler:ControlDevices] 无效的访问令牌: ..."
}{
"code": 403,
"message": "[handler:ControlDevices] 用户无权访问该家庭组"
}{
"code": 500,
"message": "[handler:ControlDevices] 校验设备与家庭组关系失败: ..."
}{
"code": 400,
"message": "[handler:ControlDevices] 不支持的设备类型: ..."
}设备类型扩 展
switch deviceType 处扩展对应 case，并实现参数结构体与控制逻辑。结构体参考
CurtainControlRequest、LightControlRequest 结构体定义请参考 service/device/case/entity/equip/curtain 和 service/device/case/entity/equip/light 目录下的相关文件。修改于 2025-07-27 06:10:14