# 设备交互模块 API 文档 本文档详细说明设备交互模块的 API 接口。所有接口基于 RESTful 设计原则。 ## 接口基础信息 - **基础路径**: `/api/device/` - **认证方式**: Token 认证（除特别说明外） - **返回格式**: JSON ## 1. 设备类型管理 ### 1.1 获取设备类型列表 获取所有设备类型的列表。 - **URL**: `/api/device/device-types/` - **方法**: `GET` - **认证**: 需要 - **响应**: ```json [ { "id": 1, "name": "智能音箱", "code": "SP01", "description": "AI智能音箱设备", "created_at": "2023-01-01T00:00:00Z", "updated_at": "2023-01-01T00:00:00Z" } ] ``` ### 1.2 创建设备类型 创建新的设备类型。 - **URL**: `/api/device/device-types/` - **方法**: `POST` - **认证**: 需要 - **请求体**: ```json { "name": "智能音箱", "code": "SP01", "description": "AI智能音箱设备" } ``` - **响应**: ```json { "id": 1, "name": "智能音箱", "code": "SP01", "description": "AI智能音箱设备", "created_at": "2023-01-01T00:00:00Z", "updated_at": "2023-01-01T00:00:00Z" } ``` ### 1.3 获取设备类型详情 根据ID获取设备类型详情。 - **URL**: `/api/device/device-types/{id}/` - **方法**: `GET` - **参数**: - `id` (路径参数): 设备类型ID - **认证**: 需要 - **响应**: ```json { "id": 1, "name": "智能音箱", "code": "SP01", "description": "AI智能音箱设备", "created_at": "2023-01-01T00:00:00Z", "updated_at": "2023-01-01T00:00:00Z" } ``` ### 1.4 更新设备类型 更新现有设备类型。 - **URL**: `/api/device/device-types/{id}/` - **方法**: `PUT` - **参数**: - `id` (路径参数): 设备类型ID - **请求体**: ```json { "name": "智能音箱", "code": "SP01", "description": "更新后的描述" } ``` - **认证**: 需要 - **响应**: ```json { "id": 1, "name": "智能音箱", "code": "SP01", "description": "更新后的描述", "created_at": "2023-01-01T00:00:00Z", "updated_at": "2023-01-02T00:00:00Z" } ``` ### 1.5 删除设备类型 删除现有设备类型。 - **URL**: `/api/device/device-types/{id}/` - **方法**: `DELETE` - **参数**: - `id` (路径参数): 设备类型ID - **认证**: 需要 - **响应**: 204 No Content ## 2. 设备批次管理 ### 2.1 获取设备批次列表 获取所有设备批次的列表。 - **URL**: `/api/device/device-batches/` - **方法**: `GET` - **认证**: 需要 - **响应**: ```json [ { "id": 1, "device_type": 1, "device_type_name": "智能音箱", "batch_number": "BSP0101", "production_date": "2023-01-01", "quantity": 500, "description": "第一批智能音箱", "created_at": "2023-01-01T00:00:00Z", "updated_at": "2023-01-01T00:00:00Z" } ] ``` ### 2.2 创建设备批次 创建新的设备批次。 - **URL**: `/api/device/device-batches/` - **方法**: `POST` - **认证**: 需要 - **请求体**: ```json { "device_type": 1, "batch_number": "BSP0101", "production_date": "2023-01-01", "quantity": 500, "description": "第一批智能音箱" } ``` - **响应**: ```json { "id": 1, "device_type": 1, "device_type_name": "智能音箱", "batch_number": "BSP0101", "production_date": "2023-01-01", "quantity": 500, "description": "第一批智能音箱", "created_at": "2023-01-01T00:00:00Z", "updated_at": "2023-01-01T00:00:00Z" } ``` ### 2.3 获取设备批次详情 根据ID获取设备批次详情。 - **URL**: `/api/device/device-batches/{id}/` - **方法**: `GET` - **参数**: - `id` (路径参数): 设备批次ID - **认证**: 需要 - **响应**: ```json { "id": 1, "device_type": 1, "device_type_name": "智能音箱", "batch_number": "BSP0101", "production_date": "2023-01-01", "quantity": 500, "description": "第一批智能音箱", "created_at": "2023-01-01T00:00:00Z", "updated_at": "2023-01-01T00:00:00Z" } ``` ### 2.4 更新设备批次 更新现有设备批次。 - **URL**: `/api/device/device-batches/{id}/` - **方法**: `PUT` - **参数**: - `id` (路径参数): 设备批次ID - **请求体**: ```json { "device_type": 1, "batch_number": "BSP0101", "production_date": "2023-01-01", "quantity": 600, "description": "更新后的描述" } ``` - **认证**: 需要 - **响应**: ```json { "id": 1, "device_type": 1, "device_type_name": "智能音箱", "batch_number": "BSP0101", "production_date": "2023-01-01", "quantity": 600, "description": "更新后的描述", "created_at": "2023-01-01T00:00:00Z", "updated_at": "2023-01-02T00:00:00Z" } ``` ### 2.5 删除设备批次 删除现有设备批次。 - **URL**: `/api/device/device-batches/{id}/` - **方法**: `DELETE` - **参数**: - `id` (路径参数): 设备批次ID - **认证**: 需要 - **响应**: 204 No Content ## 3. 设备管理 ### 3.1 获取设备列表 获取所有设备的列表。 - **URL**: `/api/device/devices/` - **方法**: `GET` - **认证**: 需要 - **响应**: ```json [ { "id": 1, "device_type": 1, "device_type_name": "智能音箱", "batch": 1, "batch_number": "BSP0101", "serial_number": "00001", "device_code": "SP0100001", "mac_address": "00:11:22:33:44:55", "is_active": false, "activated_at": null, "created_at": "2023-01-01T00:00:00Z", "updated_at": "2023-01-01T00:00:00Z" } ] ``` ### 3.2 创建单个设备 创建新的设备。 - **URL**: `/api/device/devices/` - **方法**: `POST` - **认证**: 需要 - **请求体**: ```json { "device_type": 1, "batch": 1, "serial_number": "00001", "mac_address": "00:11:22:33:44:55" } ``` - **响应**: ```json { "id": 1, "device_type": 1, "device_type_name": "智能音箱", "batch": 1, "batch_number": "BSP0101", "serial_number": "00001", "device_code": "SP0100001", "mac_address": "00:11:22:33:44:55", "is_active": false, "activated_at": null, "created_at": "2023-01-01T00:00:00Z", "updated_at": "2023-01-01T00:00:00Z" } ``` ### 3.3 批量创建设备 批量创建指定数量的设备，自动生成序列号和MAC地址。 - **URL**: `/api/device/devices/batch_create/` - **方法**: `POST` - **认证**: 需要 - **请求体**: ```json { "device_type": 1, "batch": 1, "start_serial": "00001", "count": 100, "mac_prefix": "00:11:22" } ``` - **响应**: ```json { "status": "success", "message": "成功创建100个设备", "data": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, ..., 100] } ``` ### 3.4 获取设备详情 根据ID获取设备详情。 - **URL**: `/api/device/devices/{id}/` - **方法**: `GET` - **参数**: - `id` (路径参数): 设备ID - **认证**: 需要 - **响应**: ```json { "id": 1, "device_type": 1, "device_type_name": "智能音箱", "batch": 1, "batch_number": "BSP0101", "serial_number": "00001", "device_code": "SP0100001", "mac_address": "00:11:22:33:44:55", "is_active": false, "activated_at": null, "created_at": "2023-01-01T00:00:00Z", "updated_at": "2023-01-01T00:00:00Z" } ``` ### 3.5 更新设备 更新现有设备。 - **URL**: `/api/device/devices/{id}/` - **方法**: `PUT` - **参数**: - `id` (路径参数): 设备ID - **请求体**: ```json { "device_type": 1, "batch": 1, "serial_number": "00001", "mac_address": "00:11:22:33:44:55" } ``` - **认证**: 需要 - **响应**: ```json { "id": 1, "device_type": 1, "device_type_name": "智能音箱", "batch": 1, "batch_number": "BSP0101", "serial_number": "00001", "device_code": "SP0100001", "mac_address": "00:11:22:33:44:55", "is_active": false, "activated_at": null, "created_at": "2023-01-01T00:00:00Z", "updated_at": "2023-01-02T00:00:00Z" } ``` ### 3.6 删除设备 删除现有设备。 - **URL**: `/api/device/devices/{id}/` - **方法**: `DELETE` - **参数**: - `id` (路径参数): 设备ID - **认证**: 需要 - **响应**: 204 No Content ## 4. 用户设备管理 ### 4.1 获取用户设备列表 获取当前用户绑定的所有设备列表。 - **URL**: `/api/device/user-devices/` - **方法**: `GET` - **认证**: 需要 - **响应**: ```json [ { "id": 1, "user": 1, "device": 1, "device_code": "SP0100001", "device_type": "智能音箱", "nickname": "我的设备", "is_primary": true, "bound_at": "2023-01-01T00:00:00Z" } ] ``` ### 4.2 绑定设备 将设备绑定到当前用户。 - **URL**: `/api/device/user-devices/bind/` - **方法**: `POST` - **认证**: 需要 - **请求体**: ```json { "mac_address": "00:11:22:33:44:55", "nickname": "我的设备", "is_primary": true } ``` - **响应**: ```json { "id": 1, "user": 1, "device": 1, "device_code": "SP0100001", "device_type": "智能音箱", "nickname": "我的设备", "is_primary": true, "bound_at": "2023-01-01T00:00:00Z" } ``` ### 4.3 设置主要设备 将某个绑定的设备设置为主要设备。 - **URL**: `/api/device/user-devices/{id}/set_primary/` - **方法**: `POST` - **参数**: - `id` (路径参数): 用户设备关联ID - **认证**: 需要 - **响应**: ```json { "status": "success", "message": "成功设置主要设备", "data": { "id": 1, "user": 1, "device": 1, "device_code": "SP0100001", "device_type": "智能音箱", "nickname": "我的设备", "is_primary": true, "bound_at": "2023-01-01T00:00:00Z" } } ``` ### 4.4 解绑设备 解除用户与设备的绑定关系。 - **URL**: `/api/device/user-devices/{id}/` - **方法**: `DELETE` - **参数**: - `id` (路径参数): 用户设备关联ID - **认证**: 需要 - **响应**: 204 No Content ## 5. 火山引擎Token管理 ### 5.1 生成Token 为当前用户生成火山引擎Token，用于语音交互。 - **URL**: `/api/device/rtc-token/generate/` - **方法**: `POST` - **认证**: 需要 - **请求体**: ```json { "expire_time": 86400 } ``` - **响应**: ```json { "status": "success", "message": "Token生成成功", "data": { "token": "示例Token字符串", "room_id": "12345678", "user_id": "1", "app_id": "xxxxxxxx", "expire_time": 86400, "task_id": "task-12345", "device_code": "SP0100001", "device_type": "智能音箱" } } ``` ### 5.2 根据MAC地址获取Token 设备通过MAC地址获取Token，无需用户登录认证。 - **URL**: `/api/device/rtc-token/get_by_mac/` - **方法**: `GET` - **参数**: - `mac_address` (查询参数): 设备MAC地址 - `expire_time` (查询参数, 可选): Token过期时间（秒） - **认证**: 不需要 - **响应**: ```json { "status": "success", "message": "Token生成成功", "data": { "token": "示例Token字符串", "room_id": "12345678", "user_id": "1", "app_id": "xxxxxxxx", "expire_time": 86400, "task_id": "task-12345", "device_code": "SP0100001", "device_type": "智能音箱" } } ``` ## 6. 消息管理 ### 6.1 发送消息 发送消息到用户绑定的设备。 - **URL**: `/api/device/messages/` - **方法**: `POST` - **认证**: 需要 - **请求体**: ```json { "type": "text", "message": { "content": "你好，世界！" }, "user_id": "1" } ``` - **响应**: ```json { "status": "success", "message": "消息已发送", "data": { "type": "text", "message": { "content": "你好，世界！" }, "user_id": "1", "timestamp": "2023-01-01T00:00:00Z" } } ``` ### 6.2 发送天气消息 发送天气查询消息到用户绑定的设备。 - **URL**: `/api/device/messages/` - **方法**: `POST` - **认证**: 需要 - **请求体**: ```json { "type": "weather", "message": { "city": "北京" }, "user_id": "1" } ``` - **响应**: ```json { "status": "success", "message": "天气信息已发送", "data": { "city": "北京", "weather": "晴", "temperature": "25°C", "humidity": "50%", "wind": "东北风3级" } } ``` ### 6.3 发送唱歌消息 发送唱歌指令到用户绑定的设备。 - **URL**: `/api/device/messages/` - **方法**: `POST` - **认证**: 需要 - **请求体**: ```json { "type": "sing", "message": { "song": "歌曲名称", "artist": "歌手名称" }, "user_id": "1" } ``` - **响应**: ```json { "status": "success", "message": "唱歌指令已发送", "data": { "type": "sing", "message": { "song": "歌曲名称", "artist": "歌手名称" }, "user_id": "1" } } ``` ### 6.4 发送跳舞消息 发送跳舞指令到用户绑定的设备。 - **URL**: `/api/device/messages/` - **方法**: `POST` - **认证**: 需要 - **请求体**: ```json { "type": "dance", "message": { "dance": "舞蹈名称", "style": "舞蹈风格", "duration": "30秒" }, "user_id": "1" } ``` - **响应**: ```json { "status": "success", "message": "跳舞指令已发送", "data": { "type": "dance", "message": { "dance": "舞蹈名称", "style": "舞蹈风格", "duration": "30秒" }, "user_id": "1" } } ``` ## 7. WebSocket 通信 ### 7.1 WebSocket 连接 WebSocket 连接用于实时通信。 - **URL**: `ws://domain/api/device/messages/{user_id}/` - **参数**: - `user_id` (路径参数): 用户ID - **认证**: 通过查询参数 `token` 进行认证 ### 7.2 WebSocket 消息格式 WebSocket 消息基本格式如下： ```json { "type": "消息类型", "message": { // 消息内容，根据类型不同而不同 }, "user_id": "用户ID" } ``` 支持的消息类型： - `text`: 文本消息 - `weather`: 天气查询 - `sing`: 唱歌指令 - `dance`: 跳舞指令 ## 8. 错误响应 所有API在出错时会返回统一格式的错误响应： ```json { "status": "error", "message": "错误信息", "code": "错误代码（可选）" } ``` 常见错误状态码： - `400 Bad Request`: 请求参数错误 - `401 Unauthorized`: 未认证 - `403 Forbidden`: 无权限 - `404 Not Found`: 资源不存在 - `500 Internal Server Error`: 服务器内部错误 详细错误码及处理方法参见 [设备错误文档](device_errors.md)