# 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信息，其他都由系统自动完成。