228 lines
7.4 KiB
Markdown
228 lines
7.4 KiB
Markdown
# 设备模块开发文档
|
||
|
||
## 概述
|
||
|
||
设备模块主要负责设备的管理、用户设备绑定和设备交互功能，包括设备的批量创建、查询、绑定和解绑等操作。
|
||
|
||
## 数据模型
|
||
|
||
### 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) - 设备模块错误代码和处理方法 |