225 lines
14 KiB
Markdown
225 lines
14 KiB
Markdown
# TalkingQ智能设备激活与使用流程文档
|
||
|
||
## 一、流程概述
|
||
|
||
TalkingQ智能设备的激活与使用流程主要分为四个阶段：
|
||
1. 设备预置与准备
|
||
2. 设备配网与连接
|
||
3. 设备认证与激活
|
||
4. 日常使用与管理
|
||
|
||
## 二、详细流程
|
||
|
||
### 1. 设备预置与准备阶段
|
||
- **设备出厂预置**：
|
||
- 每台设备出厂时预置唯一的设备ID（基于MAC地址，格式："TalkingQ_MAC地址"，如"TalkingQ_AABBCCDDEEFF"）
|
||
- 预置唯一序列号（格式："批次前缀_ChipID"，批次前缀通常为8位日期格式YYYYMMDD）
|
||
- 设备信息已通过管理员API（`/api/auth/register-device`或`/api/auth/register-devices-batch`）在后端服务器预先注册
|
||
|
||
- **安全存储**：
|
||
- 设备使用ESP32的NVS加密存储区存储凭据
|
||
- 后端在`device_auth`表中安全存储设备信息（包括device_id、serial_number、batch_id和is_active）
|
||
|
||
### 2. 设备配网与连接阶段
|
||
- **启动配网**：
|
||
- 用户打开微信进入TalkingQ小程序
|
||
- 用户选择"设备配网"功能
|
||
|
||
- **WiFi信息传输**：
|
||
- 小程序使用AirKiss协议进行配网
|
||
- 用户选择家庭WiFi并输入密码
|
||
- 小程序将WiFi信息通过AirKiss协议发送
|
||
|
||
- **设备接收配置**：
|
||
- 设备使用SmartConfig技术（支持AirKiss和ESPTouch）接收配置
|
||
- 设备连接到指定WiFi网络
|
||
- 连接成功后，设备返回MAC地址给小程序
|
||
|
||
### 3. 设备认证与激活阶段
|
||
- **获取设备凭据**：
|
||
- 小程序通过`/api/auth/query-serial`接口发送MAC地址给后端
|
||
- 请求头中携带`X-Client-Key`验证小程序身份
|
||
- 后端返回对应的设备ID和序列号
|
||
- 小程序安全存储设备凭据
|
||
|
||
- **设备WebSocket连接**：
|
||
- 设备使用预置的ID和序列号向服务器发起WebSocket连接(`/ws`)
|
||
- 设备在10秒内发送JSON格式认证消息：
|
||
```json
|
||
{
|
||
"device_id": "TalkingQ_AABBCCDDEEFF",
|
||
"serial_number": "20240101_12345678"
|
||
}
|
||
```
|
||
- 后端通过`device_auth_manager.authenticate_device`验证设备凭据
|
||
- 认证成功后，通过`connection_manager.add_connection`建立正式连接
|
||
- 设备播放成功提示音
|
||
|
||
- **激活状态确认**：
|
||
- 小程序通过`/api/auth/verify-device/{device_id}`轮询设备状态
|
||
- 后端确认设备已激活并连接
|
||
- 小程序显示"激活成功"提示
|
||
|
||
### 4. 日常使用与管理阶段
|
||
- **设备管理**：
|
||
- 用户打开小程序查看已激活设备列表
|
||
- 选择设备进入管理界面
|
||
- 小程序在API请求中使用`X-Device-ID`和`X-Device-Serial`头部传递凭据
|
||
- 后端通过`api_auth`依赖项验证设备身份
|
||
|
||
- **设备控制功能**：
|
||
- 角色配置：通过`/api/roles/device/{device_id}`设置对话角色和首选语言
|
||
- 音量控制：通过`/api/device/volume/{device_id}`调整设备音量(0-100)
|
||
- 网络重置：通过`/api/device/reset-network/{device_id}`远程重置设备网络配置
|
||
- 对话历史：通过`/api/roles/history/{device_id}`和`/api/roles/history-summary/{device_id}`获取历史记录
|
||
|
||
- **实时通信**：
|
||
- 设备保持WebSocket连接接收控制指令（如"VOLUME:70"、"RESET_NETWORK"等）
|
||
- 设备通过WebSocket发送语音数据（带有设备ID和会话ID的二进制数据包）
|
||
- 后端通过WebSocket发送TTS_START、TTS_END等状态通知和音频URL
|
||
|
||
## 三、流程图
|
||
|
||
```
|
||
+-------------+ +----------------+ +---------------+ +----------------+
|
||
| 用户 | | 微信小程序 | | TalkingQ设备 | | 后端服务 |
|
||
+-------------+ +----------------+ +---------------+ +----------------+
|
||
| | | |
|
||
| | | 【设备预置阶段】 |
|
||
| | | 出厂预置设备ID和序列号 |
|
||
| | |------------------------ |
|
||
| | | | 管理员API预注册设备信息
|
||
| | | | (/api/auth/register-device)
|
||
| | | |------------------------
|
||
| | | |
|
||
| | | |
|
||
| 【设备配网阶段】 | |
|
||
| 打开微信小程序 | | |
|
||
|-------------------------->| | |
|
||
| 选择"设备配网" | | |
|
||
|-------------------------->| | |
|
||
| 选择WiFi并输入密码 | | |
|
||
|-------------------------->| | |
|
||
| | 使用AirKiss协议发送WiFi信息 | |
|
||
| |---------------------------->| |
|
||
| | | 通过SmartConfig接收配置 |
|
||
| | |------------------------ |
|
||
| | | 连接到指定WiFi网络 |
|
||
| | |------------------------ |
|
||
| | | 连接成功返回MAC地址 |
|
||
| |<----------------------------| |
|
||
| | | |
|
||
| 【设备认证与激活阶段】 | |
|
||
| | /api/auth/query-serial | |
|
||
| | (含MAC地址+X-Client-Key) | |
|
||
| |----------------------------------------------------------->|
|
||
| | | | 验证小程序身份
|
||
| | | | 查询对应设备信息
|
||
| | 返回设备ID和序列号| |
|
||
| |<-----------------------------------------------------------|
|
||
| | 本地安全存储设备凭据 | |
|
||
| |------------------------ | |
|
||
| | | 发起WebSocket连接(/ws) |
|
||
| | |---------------------------->|
|
||
| | | 发送JSON认证消息 |
|
||
| | |---------------------------->|
|
||
| | | | authenticate_device验证
|
||
| | | | connection_manager注册
|
||
| | | 认证成功确认 |
|
||
| | |<----------------------------|
|
||
| | | 播放welcome提示音 |
|
||
| | |------------------------ |
|
||
| | /api/auth/verify-device | |
|
||
| |----------------------------------------------------------->|
|
||
| | 设备已激活状态| |
|
||
| |<-----------------------------------------------------------|
|
||
| 显示"激活成功"提示 | | |
|
||
|<--------------------------| | |
|
||
| | | |
|
||
| 【日常使用与管理阶段】 | |
|
||
| 打开小程序查看设备列表 | | |
|
||
|-------------------------->| | |
|
||
| 选择并进入设备管理 | | |
|
||
|-------------------------->| | |
|
||
| | 请求设备信息 | |
|
||
| | (含X-Device-ID和X-Device-Serial) |
|
||
| |----------------------------------------------------------->|
|
||
| | 设备详细信息 | |
|
||
| |<-----------------------------------------------------------|
|
||
| 执行设备管理操作 | | |
|
||
| (角色/音量/网络设置) | | |
|
||
|-------------------------->| | |
|
||
| | 发送管理请求 | |
|
||
| | (含设备凭据头部) | |
|
||
| |----------------------------------------------------------->|
|
||
| | 处理结果 | |
|
||
| |<-----------------------------------------------------------|
|
||
| | | 实时WebSocket控制指令 |
|
||
| | |<----------------------------|
|
||
| | | 执行指令并提供服务 |
|
||
| | |------------------------ |
|
||
```
|
||
|
||
## 四、安全特性
|
||
|
||
整个流程具有以下安全特性：
|
||
|
||
1. **一物一密**：
|
||
- 每台设备使用唯一ID（格式："TalkingQ_MAC地址"）和序列号（格式："批次前缀_ChipID"）
|
||
- 设备认证需同时验证设备ID和序列号
|
||
- 通过`device_auth_manager.authenticate_device`方法严格验证设备凭据
|
||
|
||
2. **安全存储**：
|
||
- 设备使用ESP32的NVS加密存储区保护凭据
|
||
- 后端在MySQL数据库的`device_auth`表中安全存储设备信息
|
||
- 实现安全启动和Flash加密保护敏感信息
|
||
|
||
3. **分层认证**：
|
||
- 小程序使用`X-Client-Key`认证身份（由settings.client_api_key提供）
|
||
- 设备管理API使用`X-Device-ID`和`X-Device-Serial`认证（api_auth依赖项）
|
||
- 管理员API使用`X-Admin-API-Key`认证（admin_auth依赖项）
|
||
- WebSocket连接通过JSON格式认证消息验证，认证超时时间为10秒
|
||
|
||
4. **权限隔离**：
|
||
- 只有管理员API密钥才能注册设备（`admin_auth`依赖项）
|
||
- 用户只能管理自己配网过的设备（使用`admin_or_api_auth`依赖项验证权限）
|
||
- 设备配置修改需通过`api_auth`认证，防止未授权访问
|
||
|
||
5. **通信加密**：
|
||
- 所有API通过HTTPS传输
|
||
- WebSocket连接安全验证
|
||
- 敏感信息不明文传输
|
||
|
||
6. **设备状态跟踪**：
|
||
- 通过`connection_manager`跟踪所有活跃的设备连接
|
||
- 通过`device_auth_manager`支持设备禁用功能（设置`is_active=False`）
|
||
- 提供设备状态验证接口（`/api/auth/verify-device/{device_id}`）
|
||
|
||
## 五、开发关键点
|
||
|
||
1. **ESP32端**：
|
||
- 实现SmartConfig配网（同时支持AirKiss和ESPTouch）
|
||
- 在NVS加密区域安全存储设备凭据
|
||
- 实现WebSocket认证流程和10秒内发送认证消息
|
||
- 处理来自后端的实时控制指令（VOLUME、RESET_NETWORK等）
|
||
- 实现二进制音频数据包发送格式，包含设备ID和会话ID
|
||
|
||
2. **微信小程序**：
|
||
- 实现AirKiss配网协议
|
||
- 通过`/api/auth/query-serial`获取设备凭据
|
||
- 在HTTP请求头中添加`X-Client-Key`或者`X-Device-ID`和`X-Device-Serial`组合
|
||
- 使用`/api/roles/device/{device_id}`管理设备角色和语言设置
|
||
- 使用`/api/device/volume/{device_id}`管理设备音量
|
||
|
||
3. **后端服务**：
|
||
- 通过`device_auth_manager.authenticate_device`验证设备身份
|
||
- 使用`connection_manager`管理WebSocket连接
|
||
- 实现多种语音识别、语言模型和语音合成服务对接
|
||
- 提供丰富的API接口：
|
||
- `/api/roles/device/{device_id}` - 角色配置
|
||
- `/api/device/volume/{device_id}` - 音量控制
|
||
- `/api/device/reset-network/{device_id}` - 网络重置
|
||
- `/api/roles/history/{device_id}` - 对话历史
|
||
- `/api/auth/verify-device/{device_id}` - 设备验证
|
||
|
||
此流程设计确保非技术用户也能轻松完成设备激活和管理，同时在背后实现了高级别的安全保障。整个激活过程只需要几分钟，用户只需要提供WiFi信息，其他都由系统自动完成。 |