# 设备模块开发文档

## 概述

设备模块主要负责设备的管理、用户设备绑定和设备交互功能，包括设备的批量创建、查询、绑定和解绑等操作。

## 数据模型

### 1. 设备类型 (DeviceType)

设备类型是设备的基本分类，用于区分不同种类的设备。

```python
class DeviceType(models.Model):
    name = models.CharField('类型名称', max_length=100, unique=True)
    code = models.CharField('类型代码', max_length=10, unique=True)
    description = models.TextField('类型描述', blank=True, null=True)
    created_at = models.DateTimeField('创建时间', auto_now_add=True)
    updated_at = models.DateTimeField('更新时间', auto_now=True)
```

### 2. 设备批次 (DeviceBatch)

设备批次用于管理设备的生产批次信息。

```python
class DeviceBatch(models.Model):
    device_type = models.ForeignKey(DeviceType, on_delete=models.CASCADE, verbose_name='设备类型', related_name='batches')
    batch_number = models.CharField('批次号', max_length=20, unique=True)
    production_date = models.DateField('生产日期')
    quantity = models.PositiveIntegerField('数量')
    description = models.TextField('批次描述', blank=True, null=True)
    created_at = models.DateTimeField('创建时间', auto_now_add=True)
    updated_at = models.DateTimeField('更新时间', auto_now=True)
```

### 3. 设备 (Device)

设备是核心实体，记录每台设备的详细信息。

```python
class Device(models.Model):
    device_type = models.ForeignKey(DeviceType, on_delete=models.CASCADE, verbose_name='设备类型', related_name='devices')
    batch = models.ForeignKey(DeviceBatch, on_delete=models.CASCADE, verbose_name='设备批次', related_name='devices')
    serial_number = models.CharField('序列号', max_length=50)
    device_code = models.CharField('设备码', max_length=100, unique=True)
    mac_address = models.CharField('MAC地址', max_length=17, unique=True)
    is_active = models.BooleanField('是否激活', default=False)
    activated_at = models.DateTimeField('激活时间', null=True, blank=True)
    created_at = models.DateTimeField('创建时间', auto_now_add=True)
    updated_at = models.DateTimeField('更新时间', auto_now=True)
```

### 4. 用户设备 (UserDevice)

用户设备关联表，记录用户与设备的绑定关系。

```python
class UserDevice(models.Model):
    user = models.ForeignKey(ParadiseUser, on_delete=models.CASCADE, verbose_name='用户', related_name='devices')
    device = models.ForeignKey(Device, on_delete=models.CASCADE, verbose_name='设备', related_name='users')
    nickname = models.CharField('设备昵称', max_length=100, blank=True, null=True)
    bound_at = models.DateTimeField('绑定时间', auto_now_add=True)
    is_primary = models.BooleanField('是否主要设备', default=False)
```

## API 接口

设备模块提供以下RESTful API接口：

### 1. 设备类型管理

- **获取设备类型列表**: `GET /api/device-types/`
- **创建设备类型**: `POST /api/device-types/`
- **获取设备类型详情**: `GET /api/device-types/{id}/`
- **更新设备类型**: `PUT /api/device-types/{id}/`
- **删除设备类型**: `DELETE /api/device-types/{id}/`

### 2. 设备批次管理

- **获取设备批次列表**: `GET /api/device-batches/`
- **创建设备批次**: `POST /api/device-batches/`
- **获取设备批次详情**: `GET /api/device-batches/{id}/`
- **更新设备批次**: `PUT /api/device-batches/{id}/`
- **删除设备批次**: `DELETE /api/device-batches/{id}/`

### 3. 设备管理

- **获取设备列表**: `GET /api/devices/`
- **创建单个设备**: `POST /api/devices/`
- **批量创建设备**: `POST /api/devices/batch_create/`
- **获取设备详情**: `GET /api/devices/{id}/`
- **更新设备**: `PUT /api/devices/{id}/`
- **删除设备**: `DELETE /api/devices/{id}/`

### 4. 用户设备管理

- **获取用户设备列表**: `GET /api/user-devices/`
- **绑定设备**: `POST /api/user-devices/bind/`
- **设置主要设备**: `POST /api/user-devices/{id}/set_primary/`
- **解绑设备**: `DELETE /api/user-devices/{id}/`

### 5. 火山引擎Token管理

- **生成Token**: `POST /api/rtc-token/generate/`
- **根据设备MAC地址获取Token**: `GET /api/rtc-token/get_by_mac/?mac_address=00:11:22:33:44:55`
  - 无需鉴权，设备可直接调用
  - 必须提供有效的设备MAC地址
  - 设备必须已绑定到用户
  - 可选参数 `expire_time` 指定Token过期时间（秒）

## 批量创建设备

批量创建设备支持两种方式：

### 1. 通过API接口

```http
POST /api/devices/batch_create/
Content-Type: application/json

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

### 2. 通过管理命令

详见 [设备管理命令文档](device_commands.md)

## 用户绑定设备流程

1. 用户购买设备后，通过扫描设备MAC地址或输入设备码绑定设备
2. 调用绑定API接口：

```http
POST /api/user-devices/bind/
Content-Type: application/json

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

3. 绑定成功后，设备状态会被标记为激活，并记录激活时间
4. 用户可以通过设置主要设备接口将某个设备设为主要设备

## 开发示例

### 创建设备类型

```python
from device_interaction.models import DeviceType

device_type = DeviceType.objects.create(
    name="智能音箱",
    code="SP01",
    description="AI智能音箱设备"
)
```

### 创建设备批次

```python
from device_interaction.models import DeviceType, DeviceBatch
from django.utils import timezone

device_type = DeviceType.objects.get(code="SP01")
batch = DeviceBatch.objects.create(
    device_type=device_type,
    batch_number="BSP0101",
    production_date=timezone.now().date(),
    quantity=500,
    description="第一批智能音箱"
)
```

### 创建设备

```python
from device_interaction.models import DeviceType, DeviceBatch, Device

device_type = DeviceType.objects.get(code="SP01")
batch = DeviceBatch.objects.get(batch_number="BSP0101")

device = Device.objects.create(
    device_type=device_type,
    batch=batch,
    serial_number="00001",
    mac_address="00:11:22:33:44:55"
)
```

### 绑定设备到用户

```python
from device_interaction.models import Device, UserDevice
from userapp.models import ParadiseUser

user = ParadiseUser.objects.get(username="example_user")
device = Device.objects.get(mac_address="00:11:22:33:44:55")

user_device = UserDevice.objects.create(
    user=user,
    device=device,
    nickname="客厅音箱",
    is_primary=True
)
```

## 注意事项

1. 设备码格式为：类型代码-批次号-序列号，如 "SP01-BSP0101-00001"
2. MAC地址必须是有效格式，推荐使用冒号分隔的十六进制格式，如 "00:11:22:33:44:55"
3. 每个用户可以绑定多个设备，但每个设备只能被一个用户绑定
4. 设备激活时间在首次绑定时自动设置
5. 用户可以指定一个主要设备，如不指定，第一个绑定的设备将自动设为主要设备

## 相关文档

- [设备管理命令文档](device_commands.md) - 设备管理命令的使用说明
- [设备错误文档](device_errors.md) - 设备模块错误代码和处理方法