zyc/lty

Fork 0

zyc 0c610c1e49 first commit

2026-03-17 13:17:02 +08:00

15 KiB

Raw Blame History

设备交互模块 API 文档

本文档详细说明设备交互模块的 API 接口。所有接口基于 RESTful 设计原则。

接口基础信息

基础路径: /api/device/
认证方式: Token 认证（除特别说明外）
返回格式: JSON

1. 设备类型管理

1.1 获取设备类型列表

获取所有设备类型的列表。

URL: /api/device/device-types/
方法: GET
认证: 需要

响应:

[
  {
    "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
认证: 需要

请求体:

{
  "name": "智能音箱",
  "code": "SP01",
  "description": "AI智能音箱设备"
}

响应:

{
  "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
认证: 需要

响应:

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

请求体:

{
  "name": "智能音箱",
  "code": "SP01",
  "description": "更新后的描述"
}

认证: 需要

响应:

{
  "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
认证: 需要

响应:

[
  {
    "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
认证: 需要

请求体:

{
  "device_type": 1,
  "batch_number": "BSP0101",
  "production_date": "2023-01-01",
  "quantity": 500,
  "description": "第一批智能音箱"
}

响应:

{
  "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
认证: 需要

响应:

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

请求体:

{
  "device_type": 1,
  "batch_number": "BSP0101",
  "production_date": "2023-01-01",
  "quantity": 600,
  "description": "更新后的描述"
}

认证: 需要

响应:

{
  "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
认证: 需要

响应:

[
  {
    "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
认证: 需要

请求体:

{
  "device_type": 1,
  "batch": 1,
  "serial_number": "00001",
  "mac_address": "00:11:22:33:44:55"
}

响应:

{
  "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
认证: 需要

请求体:

{
  "device_type": 1,
  "batch": 1,
  "start_serial": "00001",
  "count": 100,
  "mac_prefix": "00:11:22"
}

响应:

{
  "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
认证: 需要

响应:

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

请求体:

{
  "device_type": 1,
  "batch": 1,
  "serial_number": "00001",
  "mac_address": "00:11:22:33:44:55"
}

认证: 需要

响应:

{
  "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
认证: 需要

响应:

[
  {
    "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
认证: 需要

请求体:

{
  "mac_address": "00:11:22:33:44:55",
  "nickname": "我的设备",
  "is_primary": true
}

响应:

{
  "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
认证: 需要

响应:

{
  "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
认证: 需要
请求体:
```
{
  "expire_time": 86400
}
```

响应:

{
  "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过期时间（秒）
认证: 不需要

响应:

{
  "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
认证: 需要

请求体:

{
  "type": "text",
  "message": {
    "content": "你好，世界！"
  },
  "user_id": "1"
}

响应:

{
  "status": "success",
  "message": "消息已发送",
  "data": {
    "type": "text",
    "message": {
      "content": "你好，世界！"
    },
    "user_id": "1",
    "timestamp": "2023-01-01T00:00:00Z"
  }
}

6.2 发送天气消息

发送天气查询消息到用户绑定的设备。

URL: /api/device/messages/
方法: POST
认证: 需要

请求体:

{
  "type": "weather",
  "message": {
    "city": "北京"
  },
  "user_id": "1"
}

响应:

{
  "status": "success",
  "message": "天气信息已发送",
  "data": {
    "city": "北京",
    "weather": "晴",
    "temperature": "25°C",
    "humidity": "50%",
    "wind": "东北风3级"
  }
}

6.3 发送唱歌消息

发送唱歌指令到用户绑定的设备。

URL: /api/device/messages/
方法: POST
认证: 需要

请求体:

{
  "type": "sing",
  "message": {
    "song": "歌曲名称",
    "artist": "歌手名称"
  },
  "user_id": "1"
}

响应:

{
  "status": "success",
  "message": "唱歌指令已发送",
  "data": {
    "type": "sing",
    "message": {
      "song": "歌曲名称",
      "artist": "歌手名称"
    },
    "user_id": "1"
  }
}

6.4 发送跳舞消息

发送跳舞指令到用户绑定的设备。

URL: /api/device/messages/
方法: POST
认证: 需要

请求体:

{
  "type": "dance",
  "message": {
    "dance": "舞蹈名称",
    "style": "舞蹈风格",
    "duration": "30秒"
  },
  "user_id": "1"
}

响应:

{
  "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 消息基本格式如下：

{
  "type": "消息类型",
  "message": {
    // 消息内容，根据类型不同而不同
  },
  "user_id": "用户ID"
}

支持的消息类型：

text: 文本消息
weather: 天气查询
sing: 唱歌指令
dance: 跳舞指令

8. 错误响应

所有API在出错时会返回统一格式的错误响应：

{
  "status": "error",
  "message": "错误信息",
  "code": "错误代码（可选）"
}

常见错误状态码：

400 Bad Request: 请求参数错误
401 Unauthorized: 未认证
403 Forbidden: 无权限
404 Not Found: 资源不存在
500 Internal Server Error: 服务器内部错误

15 KiB Raw Blame History Unescape Escape

设备交互模块 API 文档

接口基础信息

1. 设备类型管理

1.1 获取设备类型列表

1.2 创建设备类型

1.3 获取设备类型详情

1.4 更新设备类型

1.5 删除设备类型

2. 设备批次管理

2.1 获取设备批次列表

2.2 创建设备批次

2.3 获取设备批次详情

2.4 更新设备批次

2.5 删除设备批次

3. 设备管理

3.1 获取设备列表

3.2 创建单个设备

3.3 批量创建设备

3.4 获取设备详情

3.5 更新设备

3.6 删除设备

4. 用户设备管理

4.1 获取用户设备列表

4.2 绑定设备

4.3 设置主要设备

4.4 解绑设备

5. 火山引擎Token管理

5.1 生成Token

5.2 根据MAC地址获取Token

6. 消息管理

6.1 发送消息

6.2 发送天气消息

6.3 发送唱歌消息

6.4 发送跳舞消息

7. WebSocket 通信

7.1 WebSocket 连接

7.2 WebSocket 消息格式

8. 错误响应

15 KiB

Raw Blame History