帮我写一份websocket设备控制api接口文档

WebSocket 设备控制 API 接口文档

**标题:** WebSocket 设备管理API - 实时通信与远程操控

**概述:**
本文档描述了用于设备实时监控与远程操作的WebSocket API，它允许客户端（如网页应用、移动应用等）通过持久化的连接与服务器进行双向数据传输。

**版本:**
1.0

**协议:**
HTTP/1.1, WebSocket (WSS for secure connections)

**基础URL:**

https://yourserver.com/device-control/websocket/

### 接口端点:

#### 1. 连接建立:
- **GET** /connect?token=<access_token>
- 参数:
- `access_token` : 用户凭据验证后的唯一标识符
- 成功响应:

     {
       "status": "success",
       "connection_id": "<unique_connection_id>"
     }

- 错误响应:

     {"status": "error", "message": "Invalid token or connection failed"}

#### 2. 发送控制指令:
- 请求体示例:

     {
       "connection_id": "<connection_id>",
       "command": {
         "action": "turn_on/off", // 动作如开启/关闭
         "device_id": "<device_unique_id>", // 设备标识
         "payload": {} // 具体操作参数（例如温度设置）
       }
     }

- 成功响应:

     {"status": "success", "response": "Command sent"}

#### 3. 接收设备状态更新:
- **SUBSCRIBE** /status/<connection_id>
- 客户端需要发送此请求来开始接收设备状态流（需保持连接活跃）
- 更新事件推送:

     {
       "type": "event",
       "data": {
         "connection_id": "<connection_id>",
         "device_id": "<device_unique_id>",
         "status": { ... } // 当前设备状态
       }
     }

#### 4. 断开连接:
- **DELETE** /disconnect/<connection_id>
- 成功响应:

     {"status": "success", "message": "Connection closed"}

**安全性注意事项:**
所有敏感数据（如access_token）应在加密传输（WSS）下传递，并且定期更换令牌保证账户安全。

**相关问题:**
1. 如何处理连接超时?
2. 接收更新事件时有哪些频率限制?
3. 如何设计错误码及含义以便于客户端解析?