huangyicao/banban
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

add banbanmini backend

Browse Source
This commit is contained in:
HycJack
2026-03-24 15:04:36 +08:00
parent 0d0f995dc2
commit 7510ca6df1
197 changed files with 13008 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

225
talkingq-url/test/TalkingQ智能设备激活与使用流程文档.md Normal file
View File

@@ -0,0 +1,225 @@
# 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信息，其他都由系统自动完成。