lty/qy_lty/docs/device_module.md

设备模块开发文档

概述

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

数据模型

1. 设备类型 (DeviceType)

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

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)

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

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)

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

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)

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

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接口

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. 通过管理命令

详见 设备管理命令文档

用户绑定设备流程

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

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

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

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

开发示例

创建设备类型

from device_interaction.models import DeviceType

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

创建设备批次

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="第一批智能音箱"
)

创建设备

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

绑定设备到用户

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. 用户可以指定一个主要设备，如不指定，第一个绑定的设备将自动设为主要设备

相关文档

• 设备管理命令文档 - 设备管理命令的使用说明
• 设备错误文档 - 设备模块错误代码和处理方法