lty/qy_lty/docs/device_api.md

# 设备交互模块 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)