eHome App 端详细需求设计文档

M03 设备配网（对应需求：FR-121~125）

项目	内容
所属项目	eHome 智能家居硬件配套 APP + 云端后台定制开发项目
设计依据	《eHome智能家居项目需求文档（PRD V1.1）》5.3节、第8章、NFR-01/02/03/06（配网成功率≥95%）；《eHome项目页面功能工时费用明细表》M03模块
范围说明	本模块覆盖设备添加向导入口、扫码/型号选择、蓝牙扫描发现、Wi-Fi配网（蓝牙辅助主链路）、AP配网兜底、配网结果与失败诊断全流程；不包含家庭/房间管理、设备信息设置与移除解绑（属 M02），不包含设备控制页（属 M04）
优先级	P0（MVP必须；配网是设备使用的唯一入口链路，成功率≥95%为硬性NFR）
里程碑	M1 MVP开发（依赖 M01 登录态、M02 家庭/房间数据；与固件团队 M1 联调专项）
文档用途	直接交付 UI 设计、Flutter 开发（APP端）、云端开发、固件联调、测试QA

需求编号映射（以工时表 M03 功能项为准）：

需求编号	功能项
FR-121	设备添加向导入口、扫码添加、按型号选择
FR-122	蓝牙扫描/搜索设备、配网准备（权限收敛与重置引导）
FR-123	Wi-Fi 配网主链路（蓝牙辅助下发凭证、分步进度、超时处理）
FR-124	AP 配网兜底流程（设备热点、本地凭证下发、回连云确认）
FR-125	配网成功页、配网失败诊断页（原因码映射、重试、埋点监控）

1. 模块概述与设计原则

1.1 模块范围

序号	页面/功能项	需求编号	类型	优先级
1	设备添加向导入口页（自动发现/扫码/按型号三方式收敛）	FR-121	APP	P0
2	扫码页（机身二维码识别、SN手动输入、绑定冲突校验）	FR-121	APP+云端	P0
3	型号选择页（云端型号库、品类分组、搜索）	FR-121	APP+云端	P0
4	蓝牙扫描/搜索设备页（权限收敛、雷达扫描、结果列表）	FR-122	APP	P0
5	配网准备页（重置引导、5GHz警示、重配网模式）	FR-122	APP	P0
6	Wi-Fi 配网执行页（BLE加密下发凭证、五步进度、120s超时）	FR-123	APP+固件+云端	P0
7	AP 配网兜底流程页（热点连接、本地下发、回连确认）	FR-124	APP+固件+云端	P0
8	配网成功页（命名/分配房间/固件版本/继续添加）	FR-125	APP+云端	P0
9	配网失败诊断页（原因码映射、重试/兜底/帮助、失败上报）	FR-125	APP+云端	P0
10	配网流程UI设计（动画、组件、双主题、7语种）	第8章	UI	P0

边界与衔接说明：

入口A：首页 [+添加设备]（M02 定义入口）→ 本模块 W01；
入口B：M02 设备空态【添加设备】→ 本模块 W01；
入口C：M02-Q04 离线排查【重新配网】→ 本模块 W03（携带原绑定上下文，绑定关系保留，不产生重复绑定）；
出口：配网成功 → 云端建立绑定 → 全局事件总线通知 M02/M04 刷新设备列表 → 本模块 W05 →【完成】跳转设备详情/控制页（M04）。

1.2 设计原则

成功率优先：配网成功率 ≥95%（NFR）为第一设计约束；主链路（蓝牙辅助配网）全流程用户操作 ≤4 步；任何失败必须给出"可执行的下一步"，禁止只报"失败"二字。
主备双链路：默认蓝牙辅助配网（手机全程保持原 Wi-Fi，结果经云端回传，成功率与体验最优）；BLE 不可用或主链路多次失败时提供 AP 配网兜底。
安全红线：Wi-Fi 密码经 BLE 加密通道或本地 HTTPS 下发，禁止明文广播；密码仅存内存，不落盘、不打日志、不上报；绑定 token 一次性、10 分钟有效。
失败可归因：每一步骤独立计时与原因码，全量上报云端，支撑成功率按型号/固件版本/地区/路由器的运营监控看板。
固件协议解耦：APP 侧配网能力封装为协议抽象层（扫描过滤、凭证下发、结果确认三接口），固件协议变更不扩散到页面层。
双主题 + 7语种：全部文案（含诊断建议、重置引导）走多语言资源文件（简中/繁中/英/德/法/西/日）；深色/浅色双主题。

1.3 用户与前置条件

用户状态：必须已登录（M01）；未登录点击添加入口 → 跳转 M01 登录，登录成功回跳 W01。
家庭前置：云端保证登录用户必有默认家庭（M02 规则），配网绑定写入"当前家庭"；多家庭用户在 W01 顶部展示目标家庭名（点击可切换）。
设备状态：出厂态或已恢复出厂（未绑定）；处于配网模式（BLE 广播配网标识 / AP 热点开启）；SN 未被其他账号绑定（冲突走申诉链路）。
环境要求：2.4GHz Wi-Fi 网络（一期设备不支持 5GHz）；手机开启蓝牙（主链路）；路由器无 AP 隔离/MAC 过滤（失败诊断覆盖）。

2. 页面结构与流程图

2.1 页面导航结构

入口A：首页[+添加设备]（M02） ──► W01
入口B：设备空态[添加设备]（M02-Q03） ──► W01
入口C：[重新配网]（M02-Q04，携带设备上下文） ──► W03（重配网模式）

W01 设备添加向导入口页（顶部显示目标家庭，可切换）
 ├─ [自动发现]（推荐，默认高亮）──► W02 蓝牙搜索页
 ├─ [扫码添加] ──► W01a 扫码页 ──(识别SN+型号)──► W03 配网准备页
 │                     └─(SN已被绑定)──► 绑定冲突提示 → 申诉工单（M10）
 └─ [按型号添加] ──► W01b 型号选择页 ──(选定型号)──► W03 配网准备页
      └─ 底部"添加帮助" ──► H5 帮助中心（M10）

W02 蓝牙搜索页（权限收敛 → 雷达扫描 → 结果列表）
 ├─(命中唯一设备)──► 自动进入 W03
 ├─(命中多台)──► 列表选择 ──► W03
 ├─(已被绑定设备)──► 置灰不可选，标注"已被绑定"
 └─(60s无结果)──► 空态排查清单 + [重试] / [改用AP配网→W07] / [帮助]

W03 配网准备页（权限终检 + 重置引导 + 5GHz警示）
 └─[设备已重置，下一步]──► W04 Wi-Fi配网执行页

W04 Wi-Fi配网执行页（SSID带入 → 输密码 → 五步进度条，总超时120s）
 ├─(成功)──► W05 配网成功页
 │             ├─[完成]──► 设备详情/控制页（M04），事件总线刷新M02列表
 │             └─[继续添加]──► W01
 └─(失败)──► W06 配网失败诊断页（按原因码展示建议）
               ├─[重新配网]──► W03（保留SSID与型号上下文）
               ├─[改用AP配网]──► W07
               ├─[查看图文教程]──► H5（M10）
               └─[联系客服]──► 工单（M10，自动携带型号/SN/原因码/耗时）

W07 AP配网兜底流程页（引导连热点eHome-XXXX → 本地下发凭证 → 回连等待）
 ├─(云端确认绑定成功)──► W05
 └─(失败/超时60s)──► W06（原因码标注AP链路）

2.2 核心状态机一：设备配网状态（设备侧视角）

[未配网(出厂态)]
   │
   ├──(开启配网模式：BLE广播配网标识 / AP热点开启)──► [配网模式]
   │        │
   │        ├──(APP BLE连接成功)──► [待配网(BLE已连接)]
   │        │        │
   │        │        ├──(收到加密凭证，校验通过)──► [配网中]
   │        │        │        │
   │        │        │        ├──(连路由器成功→连云端成功→上报绑定结果)──► [已绑定(在线)]
   │        │        │        │
   │        │        │        ├──(路由器连接失败：密码错/信号弱/5GHz)
   │        │        │        │        ──► [配网失败] → 回报原因码 → 回[配网模式]可重试
   │        │        │        │
   │        │        │        └──(连云失败/超时120s)
   │        │        │                 ──► [配网失败] → 回报原因码 → 回[配网模式]可重试
   │        │        │
   │        │        └──(凭证校验失败/BLE断开)──► [配网模式]
   │        │
   │        └──(AP链路：手机连接设备热点→本地HTTP收到凭证)──► [配网中]（同上分支）
   │
   ├──(配网模式超时10分钟无操作)──► [未配网(出厂态)]（自动退出配网模式）
   │
   └──(SN已被绑定：云端拒绝)──► [绑定冲突]
              ──(原账号移除/客服申诉强制解绑·M02)──► [未配网(出厂态)]

2.3 核心状态机二：配网任务（APP侧视角）

[空闲]
   │
   ├──(进入W02/W04，创建云端配网会话sessionId)──► [会话已创建]
   │        │
   │        ├──(扫描/选择设备)──► [目标已锁定]
   │        │        │
   │        │        ├──(BLE连接，重试≤3次)──► [BLE已连接]
   │        │        │        │
   │        │        │        ├──(加密下发SSID/密码/绑定token)──► [凭证已下发]
   │        │        │        │        │
   │        │        │        │        ├──(轮询/推送获取云端结果)──► [等待设备回报]
   │        │        │        │        │        │
   │        │        │        │        │        ├──(成功+正式绑定)──► [配网成功] ──► W05
   │        │        │        │        │        │
   │        │        │        │        │        └──(失败/总超时120s，携带原因码)
   │        │        │        │        │                 ──► [配网失败] ──► W06
   │        │        │        │        │                       │
   │        │        │        │        │                       ├──(重试，自动≤2次/手动不限)──► [目标已锁定]
   │        │        │        │        │                       ├──(切换AP链路)──► [AP配网中]
   │        │        │        │        │                       └──(放弃)──► [空闲]（设备侧自然超时回出厂态）
   │        │        │        │
   │        │        │        └──(下发失败/BLE中途断开)──► [配网失败(BLE原因码)] ──► W06
   │        │
   │        └──(会话过期30分钟)──► [空闲]（重新进入时新建会话）

3. 页面级详细需求

W01 设备添加向导入口页（FR-121）

页面目标：三种添加方式统一收敛入口，明确目标家庭，最短路径进入配网。

页面元素：

元素	规格与规则
顶部导航	返回箭头 + 标题"添加设备"；右侧"帮助"图标 → H5 帮助中心（M10）
目标家庭条	显示"设备将添加到：【家庭名】"，点击 → 弹出家庭切换列表（数据来自 M02 GET /families）；切换后即时更新
[自动发现]卡片	推荐标签（品牌蓝角标"推荐"）；蓝牙图标+文案"自动搜索附近的eHome设备"；默认高亮，点击 → W02
[扫码添加]卡片	相机图标+文案"扫描机身或说明书二维码"；点击 → W01a
[按型号添加]卡片	列表图标+文案"按产品品类选择型号"；点击 → W01b
底部说明	"找不到设备？查看配网帮助"文字链 → H5

逻辑规则：

未登录进入 → 拦截跳转 M01 登录页，登录成功回跳本页（携带原路由参数）。
入口来源埋点区分：首页/空态/重新配网，用于转化漏斗分析。
页面加载时预检手机蓝牙开关状态：关闭 → 自动发现卡片下方黄色提示"蓝牙未开启，建议开启以获得最佳体验"（不阻断，可走扫码/型号路径后再引导）。
重配网模式（入口C）不经过本页，直达 W03。

异常与边界：家庭列表拉取失败 → 目标家庭条显示本地缓存的当前家庭名；型号库拉取失败 → W01b 展示缓存+重试（详见 W01b）。

验收要点：三方式入口均可达且收敛到统一配网链路；目标家庭可切换；未登录拦截回跳；埋点来源区分正确。

W01a 扫码页（FR-121）

页面元素：全屏取景框+扫描线动画；【相册选择】入口（读取二维码图片识别）；【手动输入SN】文字链；无相机权限 → 权限用途说明弹窗 →【去设置】/【改用手动输入】；弱光环境提供手电筒开关。

二维码内容协议（与固件/产线对齐）：JSON 或约定分隔符字符串，含 productModel（型号ID）、sn（设备序列号）、hwVer（可选）、qrVer（协议版本）。

逻辑规则：

识别成功 → 调用云端 SN 校验（GET /provision/devices/scan）：SN 合法且未绑定 → 携带型号+SN 进入 W03；SN 不存在于型号库 → 提示"无法识别该设备，请手动选择型号"→ W01b；
SN 已被绑定 → 弹窗"该设备已被其他账号绑定"：①若为本账号在其他家庭绑定的设备 → 提示设备所在位置并提供【移入当前家庭】快捷操作（走 M02 换家庭逻辑）；②他人绑定 → 【发起申诉】生成工单（M10，携带SN与二维码凭证），人工核实后云端强制解绑（M02 待清除机制）；
识别失败（模糊/反光）连续 2 次 → 自动推荐手动输入 SN；手动输入：SN 格式校验（长度/字符集按型号库规则），校验通过同上流程。

验收要点：二维码/相册/手动输入三路径闭环；SN冲突两类分支（本账号/他人）处理正确；相机权限拒绝降级可用。

W01b 型号选择页（FR-121）

页面元素：顶部搜索框（型号名/品类关键字，本地+云端混合搜索）；品类分组列表（灯带/灯泡/吸顶灯/插座/开关/传感器等，品类与型号由云端型号库下发，后台 FR-405 内容管理可增删）；每型号项：产品图（云端素材）、型号名、支持配网方式标签（BLE/AP/BLE+AP）。

逻辑规则：

型号库冷启动全量拉取并本地缓存（含素材URL），24小时增量更新；无网络时用缓存展示，标注"数据可能不是最新"；
选择型号 → 携带 productModel 进入 W03（该型号的重置引导素材、配网能力随之确定）；
列表底部"没有你的设备型号？"→ 反馈入口（M10 工单，用于型号库运营补全）；
仅展示"在售+支持配网"的型号；下架型号不出现在列表，但已绑定设备不受影响。

验收要点：型号库云端下发与缓存降级；搜索命中；选择后 W03 素材正确加载；反馈入口可用。

W02 蓝牙扫描/搜索设备页（FR-122）

页面目标：通过 BLE 扫描发现处于配网模式的设备，锁定配网目标。

权限收敛（进入本页立即依序执行，每项均有用途说明弹窗，先说明后申请）：

权限/开关	平台	拒绝/关闭时处理
蓝牙权限	iOS：NSBluetoothAlwaysUsageDescription；Android 12+：BLUETOOTH_SCAN/BLUETOOTH_CONNECT 运行时权限	用途弹窗→系统设置引导；最终拒绝→提示无法自动发现，提供[扫码/型号路径]与[AP配网]降级
定位权限	Android 11及以下（BLE扫描必需）；iOS 读取SSID时亦需	同上；Android 12+免定位
蓝牙开关	双端	弹窗引导开启（Android可代发起系统开启请求）；坚持关闭→降级路径
定位服务开关	Android（系统级）	引导开启，说明用途

页面元素：

雷达扫描动画 + 状态文案"正在搜索附近设备…"（循环）；
已发现设备列表项：设备图标（按型号）、设备名/型号名、信号强度（三档图标）、"距离近/中/远"提示；信号最强置顶；新发现项淡入+提示音（可静音）；
已被绑定设备：置灰，标注"已被绑定"，不可选；
顶部提示条（定向模式）：从扫码/型号路径进入时显示"正在搜索：【型号名】"，扫描结果按型号过滤；
【手动刷新】按钮（重新扫描60s周期）；
60s 无结果空态：插画+排查清单——①确认设备已通电并进入配网模式（指示灯快闪）②将手机靠近设备1米内 ③确认设备未被他人绑定 ④路由器为2.4GHz网络；操作：【重试】【改用AP配网→W07】【图文教程】。

逻辑规则：

扫描过滤：仅展示携带 eHome 厂商广播标识（manufacturerData 匹配）且处于配网模式标志位的设备；已配网在网设备不展示；
命中唯一设备 → 1s 停留确认后自动进入 W03；命中多台 → 用户点选（点选即停扫描）；
扫描周期 60s 自动停止（省电），停止后展示当前结果+【继续搜索】；
进入 W03 时仅携带设备广播信息（BLE地址/SN/型号），BLE 正式连接在 W04 开始时建立（避免准备页长时间持连超时断开）；
后台/锁屏 → 停止扫描，回前台自动恢复；
埋点：扫描时长、发现数量、是否命中、跳转路径。

异常与边界（QA重点）：蓝牙中途被关闭 → 即时提示并停止；Android 各厂商 ROM 权限差异（华为/小米/OPPO 定位服务联动）；扫描限频（连续刷新间隔 ≥5s）；同名多台设备以 SN 后4位区分显示。

验收要点：权限四分支（授予/拒绝/引导后授予/彻底拒绝降级）全机型覆盖；过滤规则准确（不显示非eHome/非配网态设备）；唯一命中自动跳转；空态排查与降级入口可用。

W03 配网准备页（FR-122）

页面目标：确保设备处于配网模式、环境满足要求，最后一步用户确认后进入配网执行。

页面元素：

元素	规格与规则
设备图示区	按型号从云端拉取产品图+重置操作动画/分步图示（如"长按重置键5秒至指示灯快闪"）；素材缺失时展示通用图文兜底
重置引导文案	分步骤编号文案（多语言）；"指示灯状态说明"：快闪=配网模式就绪 / 慢闪=待连接 / 常亮=已配网
5GHz警示横幅	检测到手机当前 Wi-Fi 的 SSID 含"-5G/5GHz"等后缀 → 顶部黄色横幅"当前设备仅支持2.4GHz Wi-Fi，请切换网络后继续"；SSID 读取失败（iOS无定位权限）→ 改为确认式文案"请确认当前连接的是2.4GHz网络"+勾选框
确认勾选	复选框"设备已重置，指示灯快闪"；未勾选时【下一步】置灰
[下一步]主按钮	进入 W04
帮助链	"找不到重置键？"→ H5 图文教程（按型号定位锚点）

重配网模式（入口C，M02-Q04 跳转）：

顶部展示原设备信息（名称/型号/SN脱敏/所属房间）；
说明文案"重新配网将保留设备名称、房间与图标设置，仅更新网络配置"；
云端创建"重配网会话"（验证操作者为该设备所属家庭成员，携带原绑定ID），绑定关系不解除；
成功后回到设备详情页（而非 W05 新建流程），状态恢复在线。

逻辑规则：进入本页时后台静默创建云端配网会话（POST /provision/sessions，返回 sessionId、一次性绑定token、BLE加密密钥），会话 TTL 30 分钟；会话创建失败（无网络）→ 阻断并提示重试（配网强依赖云端）。

验收要点：重置引导素材按型号正确加载；5GHz 两种检测分支（SSID识别/用户确认）；勾选闸门；重配网模式绑定保留且入口权限校验（非本家庭成员不可重配）。

W04 Wi-Fi 配网执行页（FR-123，核心页）

页面目标：输入 Wi-Fi 凭证，经 BLE 加密通道下发，分步可视化推进直至绑定完成。

页面元素：

元素	规格与规则
当前Wi-Fi名称	自动带入手机所连 SSID（network_info_plus）；读取失败 → 显示"请确认当前Wi-Fi"并允许手动输入SSID；SSID 旁展示信号强度图标
Wi-Fi密码输入框	默认聚焦；眼睛图标切换明文；不缓存、不落盘；错误提示就近展示
[开始配网]	主按钮；密码为空置灰；点击后按钮转 loading 并禁用
五步进度条	①蓝牙已连接 → ②凭证已下发 → ③设备连接路由器 → ④设备连接云端 → ⑤绑定完成；每步完成打勾+耗时展示；当前步转圈动画
提示文案区	按当前步骤动态提示（如"正在将设备接入网络，请保持设备通电，勿关闭页面"）；全程屏幕常亮（wakelock）
取消按钮	左上角返回需二次确认"配网进行中，确定退出？退出后需重新开始"；确认退出 → 中止会话（云端标记 APP_EXIT），设备侧超时自动回配网模式

配网执行时序（技术链路）：

BLE 连接：按 W02 锁定的设备发起 GATT 连接（重试 ≤3 次，单次超时 15s）；连接失败 → W06（原因码 BLE_CONNECT_FAIL）；
密钥协商：使用云端会话下发的加密密钥建立加密通道（协议与固件对齐，禁止明文 GATT 写密码）；
凭证下发：加密写入 SSID + 密码 + 绑定token + sessionId；设备校验通过进入配网中；下发失败 → W06（BLE_WRITE_FAIL）；
结果确认（关键设计）：手机全程保持原 Wi-Fi 不切换；设备连路由器→连云端→用绑定token向云端上报结果（成功/失败原因码）；APP 通过 MQTT 推送优先 + HTTP 长轮询（2s间隔）兜底获取结果——不依赖 BLE 保持连接，兼容设备配网中 BLE 断开的正常现象；
成功：云端校验 token → 正式绑定（POST /devices/bind：SN+familyId+roomId=未分配+默认名"型号名+序号"）→ 推送绑定成功事件 → M02/M04 列表刷新 → 跳转 W05；
超时与重试：总超时 120s；步骤③超时（典型密码错误）→ 自动原地重试 1 次（重新下发凭证）后仍失败 → W06（WIFI_PASS_WRONG 首位建议）；步骤④超时 → W06（CLOUD_TIMEOUT）；自动重试全程进度条不回跳，文案提示"正在重试…"。

异常与边界（QA重点）：

配网中 APP 退后台：iOS BLE 可能挂起 → 结果确认走云端推送/轮询不受影响，回前台恢复进度展示；
配网中手机 Wi-Fi 被切换/断开：不影响 BLE 下发，结果轮询切换为蜂窝网络继续；
设备连上路由器但云端不可达（DNS/防火墙）：设备侧回报失败原因码 CLOUD_TIMEOUT；
并发：两台手机同时对同一设备下发凭证 → 设备只接受配网模式期间第一个有效凭证，后者收到 DEVICE_BUSY；
绑定冲突：云端 bind 时 SN 已被绑定（扫描后被人抢先）→ W06（SN_BOUND）+申诉入口；
密码含特殊字符/中文SSID/隐藏SSID：UTF-8 编码下发；隐藏 SSID 支持手动输入；非常规加密（64位Hex WEP等）提示兼容性风险。

验收要点：五步进度与真实链路一一对应；密码错自动重试1次后精准归因；120s总超时生效；结果确认不依赖BLE保持；成功即绑定且M02列表实时刷新；退出二次确认与会话中止。

W07 AP 配网兜底流程页（FR-124）

触发场景：①BLE 权限被彻底拒绝或手机蓝牙故障 ②设备不支持 BLE（型号库标注）③主链路失败后用户在 W06 主动选择"改用AP配网"。

流程分步（单页面内步骤切换，非多页跳转）：

步骤	APP行为	用户操作	超时/失败
①重置设备进入AP模式	展示型号对应AP模式激活指引（如长按10秒至指示灯交替闪烁）	按指引操作+勾选确认	—
②连接设备热点	Android：WifiNetworkSpecifier 系统弹窗引导连接 eHome-XXXX（XXXX=SN后4位）；iOS：NEHotspotConfiguration 自动加入（需用户点"加入"）；手动连接图文指引兜底（设置→WLAN→eHome-XXXX，密码规则与固件对齐）	允许连接	热点连接超时60s → W06（AP_HOTSPOT_FAIL）
③下发凭证	连接成功后 APP 经本地 HTTP（192.168.4.1，凭 sessionId 鉴权）下发加密的 SSID/密码/绑定token	密码需重新输入一次（安全要求：不跨链路缓存明文，SSID沿用）	下发失败 → W06（AP_PROVISION_FAIL）
④等待设备回连	设备切换回目标路由器并连云；APP 提示"请手动切回原Wi-Fi"（Android 部分机型自动回切；iOS 必然需手动）并开始经蜂窝/原Wi-Fi轮询云端结果	切回原Wi-Fi（图文指引）	总超时60s → W06（CLOUD_TIMEOUT，标注AP链路）
⑤完成	云端确认绑定 → 同 W04 成功链路 → W05	—	—

逻辑规则：

步骤②期间手机无互联网，页面所有云端交互暂停，仅本地指引；系统弹"无网络Wi-Fi"提示的处理文案需预先说明（"保持连接，配网需要"）；
iOS 与 Android 热点连接体验差异大，两条平台链路分别设计文案与兜底（手动连接指引永远可用）；
AP 链路失败原因码统一带 AP_ 前缀，W06 诊断区分链路展示；
用户中途退出 → 二次确认；设备热点 10 分钟无连接自动关闭回出厂态。

验收要点：iOS/Android 热点连接双链路（系统API+手动兜底）全通过；无网阶段页面不报错；切回原Wi-Fi引导清晰；60s超时归因准确；成功率埋点区分BLE/AP链路。

W05 配网成功页（FR-125）

页面元素：

元素	规格与规则
成功动效	对勾动画 ≤1.5s，设备图标+设备名
设备名称	就地编辑输入框（默认"型号名+序号"，云端生成保证家庭内不重名）；1~20字符校验（M02 规则）；修改即时保存
分配到房间	下拉选择当前家庭房间列表+【未分配】（默认）；选择即时保存；旁设[+新建房间]快捷入口（弹 M02-Q02 房间弹窗组件，创建后自动选中）
固件版本信息	当前版本号；检测到新版本 → 红点+"建议立即升级"【去升级】→ M09 OTA 流程（可跳过）
配网摘要	配网方式（蓝牙/热点）、总耗时（如"用时38秒"）——增强成功感知
[完成]	主按钮 → 设备详情/控制页（M04）
[继续添加]	次按钮 → W01（会话重新创建）

逻辑规则：本页任何编辑失败（改名/房间）不阻断完成，Toast 提示并可稍后在 M02-Q04 修改；事件总线已通知 M02/M04 刷新，返回首页可见新设备（含"新设备"角标 24h）。

验收要点：命名/房间编辑即时生效且与 M02 数据一致；新建房间快捷入口闭环；OTA 联动跳转；完成/继续添加双出口。

W06 配网失败诊断页（FR-125）

页面目标：按失败原因码给出精准、可执行的恢复建议，闭环"重试/兜底/求助"三出口，并完成失败上报。

原因码-文案-动作映射表（全部多语言，云端可配置热更新）：

原因码	触发环节	用户可见文案（示例）	首选动作
BLE_CONNECT_FAIL	W04步骤①	蓝牙连接设备失败，请靠近设备后重试	[重新配网]
BLE_WRITE_FAIL	W04步骤②	与设备通信异常，请重试	[重新配网]
WIFI_PASS_WRONG	W04步骤③超时/设备回报	Wi-Fi密码可能错误，请检查后重新输入	[重新输入密码]→W04（保留SSID，密码框清空聚焦）
WIFI_5G	设备回报不支持频段	当前网络为5GHz，设备仅支持2.4GHz	[查看切换教程H5] + [重新配网]
ROUTER_RESTRICT	设备回报连接被拒	路由器可能开启了AP隔离/MAC过滤/黑名单	[查看路由器设置教程H5] + [重新配网]
WIFI_SIGNAL_WEAK	设备回报信号弱	设备与路由器距离过远或信号弱	建议靠近路由器 + [重新配网]
CLOUD_TIMEOUT	W04步骤④/W07步骤④	设备已连网但连接云端超时	[重试] + [联系客服]
SN_BOUND	云端bind校验	设备已被其他账号绑定	[发起申诉]→M10工单
DEVICE_NOT_READY	设备回报未就绪	设备未处于配网模式	重看重置引导 + [重新配网]→W03
DEVICE_BUSY	并发配网	设备正被其他手机配网	[重新配网]
AP_HOTSPOT_FAIL	W07步骤②	未能连接设备热点	手动连接指引 + [重试]
AP_PROVISION_FAIL	W07步骤③	热点通道下发失败	[重试] + [联系客服]
APP_EXIT	用户中止	配网已取消	[重新配网]
UNKNOWN	兜底	配网失败，请重试或联系客服	[重新配网] + [联系客服]

页面元素：失败插画（弱化处理避免挫败感）；失败原因卡片（原因文案+图示）；建议清单（有序编号，按原因码动态生成）；操作按钮组：【重新配网】（主按钮，回 W03 保留上下文）/【重新输入密码】（密码类失败时替代主按钮）/【改用AP配网】（BLE链路失败且设备支持AP时展示）/【查看图文教程】（H5 按原因码定位锚点）/【联系客服】（M10 工单，自动携带：型号、SN脱敏、原因码、配网方式、各步骤耗时、固件版本、手机机型与OS版本）。

失败上报（自动，无需用户操作）：POST /provision/failures——sessionId、原因码、链路（BLE/AP）、各步骤耗时、设备型号/固件版本、RSSI、手机机型/OS、地区；数据进入云端配网成功率看板（按型号/固件/地区/路由器维度聚合），成功率 <95% 触发告警（联动后台运营监控）。

逻辑规则：

同一会话连续失败 ≥3 次 → 页面追加"仍无法配网？"强化引导（客服入口升为主按钮之一）；
原因码文案支持云端热更新（新增固件错误码无需发版）；
埋点：W06 曝光原因码分布、各出口按钮点击率（评估诊断有效性）。

验收要点：14 个原因码全量注入测试且文案/动作映射正确；密码类失败一键回 W04 保留 SSID；≥3 次失败强化引导；失败上报字段完整可查；文案云端热更新生效。

4. 通用交互与视觉规范（UI设计输入，序号10）

双主题：浅色/深色两套；进度条、警示横幅（黄）、失败卡片（红弱化）、成功动效（绿/品牌蓝）在深色下满足 WCAG AA。
组件清单：方式选择卡片（W01）、扫码取景框、型号列表项（含配网方式标签）、雷达扫描动画、设备发现列表项（信号三档/置灰态）、权限用途说明弹窗（先说明后申请，复用 M01 封装）、5GHz警示横幅、五步进度条（完成/进行/失败三态）、AP步骤指示器、成功对勾动效、失败诊断卡片、原因建议清单。
动效规范：雷达扫描循环（2s/圈）；进度打勾 300ms；成功动效 ≤1.5s；失败插画静态；步骤切换渐变。
表单：密码框不缓存明文、不自动填充历史；SSID 手动输入支持中文/特殊字符；勾选闸门（W03/W07确认框）统一样式。
多语言：重置引导、步骤提示、14组诊断文案全部资源文件；德/法预留 1.4 倍空间；进度条步骤文案提供超短别名（如"已连接/已下发/连路由/连云/完成"）适配窄屏。
无障碍：进度不仅靠颜色（打勾图标+步骤序号）；扫描动画提供"正在搜索"文字替代；警示横幅可被读屏焦点捕获。
屏幕常亮：W04/W07 全程 wakelock；其余页面不启用。

5. 客户端技术要求（Flutter）

BLE 能力封装（协议抽象层）：flutter_blue_plus（或同类）统一封装——扫描（manufacturerData 过滤 eHome 标识+配网模式位）、GATT 连接（超时15s/重试3次）、MTU 协商、加密写（密钥来自云端会话，与固件对齐 AES 方案）、断连事件；页面层只调用 discover/connect/provision/observeResult 四接口，固件协议变更不外溢。
权限管理：permission_handler 统一收敛蓝牙/定位/相机权限；iOS Info.plist：NSBluetoothAlwaysUsageDescription、NSBluetoothPeripheralUsageDescription、NSLocationWhenInUseUsageDescription（SSID读取）、NSCameraUsageDescription（扫码）；Android：12+ BLUETOOTH_SCAN/BLUETOOTH_CONNECT，≤11 ACCESS_FINE_LOCATION + BLUETOOTH/BLUETOOTH_ADMIN，相机 CAMERA；权限申请前必出用途说明弹窗（复用 M01 组件，应用商店合规要求）。
Wi-Fi 信息：network_info_plus 读取 SSID/BSSID（iOS 需定位权限，失败降级手动确认）；5GHz 识别：SSID 后缀规则（-5G/_5G/5GHz）+ 频段探测（Android WifiInfo.frequency 可用时优先）。
AP 配网：Android WifiNetworkSpecifier（10+）/WifiManager 降级方案；iOS NEHotspotConfigurationManager（配置加入+失败回调）；本地 HTTP 通道（192.168.4.1，session 鉴权，超时10s）；热点连接状态监听与"无网络保持连接"处理。
结果确认通道：MQTT 订阅配网结果 topic（优先，复用 M02/M04 连接层）+ HTTP 长轮询（2s 间隔）双通道；APP 层做结果去重（以 sessionId 幂等）。
安全：Wi-Fi 密码仅内存变量，禁止写入本地存储/日志/埋点/Sentry；BLE 下发前加密；全链路 TLS（NFR-03）；绑定 token 一次性使用。
屏幕与生命周期：W04/W07 wakelock 常亮；前后台切换处理（扫描暂停恢复、进度状态保持、BLE 挂起降级云端通道）；页面销毁时会话中止通知云端。
埋点与监控：入口来源、每步骤耗时与结果码、总耗时、配网方式（BLE/AP）、失败出口点击，全部上报数据埋点服务；崩溃与异常上报 Sentry（脱敏）。

6. 云端需求（配网服务）

6.1 接口清单

接口	方法	说明
/provision/models	GET	型号库（品类分组、产品图/重置引导/AP指引素材URL、支持配网方式、SN格式规则；后台FR-405维护，支持增量版本号）
/provision/devices/scan	GET	SN校验（存在性/是否已绑定/绑定者是否本账号，供扫码与手动输入调用）
/provision/sessions	POST	创建配网会话（入参：productModel、SN可空、familyId、模式=新配/重配；返回 sessionId、一次性绑定token(10min)、BLE加密密钥、结果topic；TTL 30分钟；重配模式校验操作者为设备所属家庭成员并携带原绑定ID）
/provision/sessions/`{id}`/result	POST	设备侧结果上报（设备调用，绑定token鉴权；成功/失败原因码/RSSI/耗时）
/provision/sessions/`{id}`/status	GET	APP轮询配网结果（长轮询2s；与MQTT推送互为兜底）
/devices/bind	POST	正式绑定（sessionId+绑定token校验 → SN唯一性 → 写入绑定关系：SN-familyId-roomId(默认未分配)-名称(型号名+序号)-绑定者UID；返回设备完整信息；与M02设备数据模型同源）
/devices/`{id}`/rebind-network	POST	重配网完成确认（原绑定保留，仅更新网络信息与最近配网时间）
/provision/failures	POST	失败事件上报（原因码/链路/分步耗时/型号固件/机型OS/地区；入成功率看板）
/devices/`{id}`/appeal	POST	SN绑定冲突申诉（生成M10工单，携带二维码凭证；人工核实后强制解绑走M02待清除机制）
/provision/diagnosis-texts	GET	诊断文案配置（原因码→多语言文案/建议/教程锚点；支持热更新）

6.2 关键策略

绑定唯一性：SN 数据库唯一索引；bind 并发以先到为准，后到返回 SN_BOUND；绑定 token 一次性，使用即作废。
会话管理：sessionId 贯穿全链路（APP-设备-云端三方对账）；TTL 30 分钟；同用户并发会话 ≤3；会话状态机与 2.3 对齐。
结果回传双通道：设备上报结果后，云端经 MQTT 推送 APP（结果topic）+ 轮询接口兜底；结果幂等去重。
重配网通道：不解除原绑定，校验操作者家庭成员身份；成功后仅更新网络信息；重配期间设备状态标记"配网中"，M02 列表不置为离线告警。
成功率监控看板：按型号/固件版本/地区/路由器BSSID前缀/链路(BLE-AP)/原因码多维聚合；日成功率 <95% 或单型号 <90% 触发告警工单；看板供甲乙双方 M1 验收使用。
密钥安全：BLE 加密密钥按会话下发、会话结束即失效；token/密钥传输全程 TLS；服务端不留存 Wi-Fi 密码（设备上报中禁止携带密码字段，云端入参校验拒绝）。
型号库灰度：新型号/新素材支持按渠道灰度发布（配合甲方新品节奏）。

7. 验收标准核对表（对齐 PRD 5.3）

需求	PRD验收标准	本设计落点
FR-121	添加向导三方式（自动发现/扫码/型号）统一收敛；扫码识别SN与绑定冲突校验；型号库云端可维护	W01/W01a/W01b；SN两类冲突分支；型号库接口+缓存降级
FR-122	蓝牙扫描仅发现配网模式eHome设备；权限收敛合规（先说明后申请）；60s空态排查与降级；重置引导按型号展示	W02过滤规则/权限四分支；W03素材与勾选闸门
FR-123	蓝牙辅助配网主链路步骤≤4、总超时120s、密码错自动重试1次并精准归因；密码加密下发不落盘；结果确认不依赖BLE保持；成功率≥95%	W04五步时序；双通道结果确认；安全红线；云端看板监控
FR-124	AP配网兜底全链路（热点连接/本地下发/回连确认）iOS与Android双平台可用；手动连接指引永远可用；60s超时归因	W07五步表；平台差异双链路；AP_前缀原因码
FR-125	成功页命名/分房/OTA联动；失败页原因码文案动作映射完整、三出口闭环、失败全量上报、文案热更新	W05/W06；映射表；/provision/failures；诊断文案配置接口

QA测试要点（专项）：

故障注入矩阵：密码错/5GHz/AP隔离/MAC过滤/弱信号(-80dBm)/隐藏SSID/中文SSID/特殊字符密码/配网中路由器重启/配网中设备断电，逐项验证原因码与W06文案；
权限分支真机：iOS 13~~18、Android 7~~15（含华为/小米/OPPO/vivo ROM 权限差异），蓝牙/定位/相机三权限 × 授予/拒绝/设置引导；
并发与冲突：双手机同配一台设备（DEVICE_BUSY）；扫描后SN被抢先绑定（SN_BOUND）；同用户3会话上限；
生命周期：配网中退后台/锁屏/杀APP/来电中断/切蜂窝，回前台状态恢复与结果最终一致；
AP兜底全链路：iOS NEHotspot 与 Android WifiNetworkSpecifier 各版本行为、"无网络Wi-Fi保持"提示处理、手动指引可达性；
重配网模式：绑定保留、名称房间图标不丢、非家庭成员拦截、M02列表不误报离线；
性能与成功率：主流路由器（TP-Link/小米/华为/华硕/运营商光猫≥20款）× 全型号样机，各50次配网统计成功率≥95%（M1末专项验收）；分步耗时基线（BLE链路P90≤60s）；
上报与看板：失败上报字段完整性、看板维度聚合正确性、<95%告警触发；
展示走查：双主题×7语种（含诊断文案热更新回归）、超长德语文案、进度条窄屏适配。

8. 依赖与风险

项	说明	责任/时点
固件配网协议	BLE广播格式/GATT服务定义/加密密钥协商/凭证报文格式/设备侧原因码集/AP热点规格（SSID与密码规则）/结果上报协议——本模块最大外部依赖	固件团队 M0 提供协议文档；M1 前2周联调窗口
型号库与素材	首批在售型号清单、产品图、重置引导动画/图示、AP指引素材	甲方提供；后台FR-405录入（M2前以配置表临时方案先行）
M02 家庭服务	目标家庭/房间数据、bind后设备归属、绑定冲突申诉后的强制解绑（待清除机制）、重配网权限校验	M1 并行，接口契约先行冻结
M01 账号体系	登录态、未登录拦截回跳；受限账号（未补绑）可配网但绑定至UID，风险提示文案	M1 已交付
MQTT 通道	配网结果推送复用 M02/M04 连接层；结果topic规范	M1 联调
路由器兼容实验室	≥20款主流路由器真机（含AP隔离/MAC过滤可配置环境）、全型号样机	甲方提供样机；乙方搭建；M1末成功率专项
iOS 平台限制	NEHotspot 弹窗体验、SSID读取需定位权限、蓝牙后台挂起——已在设计中降级兜底，仍为体验风险点	设计已覆盖；真机回归验证
Android 碎片化	各ROM蓝牙/定位权限联动差异、热点API版本差异——手动指引兜底	真机测试池 ≥15款机型
成功率≥95%达成	依赖固件稳定性+路由器兼容+文案引导有效性，需三方联调专项而非单端保障	甲乙双方 M1 末联合验收，看板数据为准

以上为 M03 设备配网（FR-121~125）完整详细需求设计：三入口收敛、BLE主链路+AP兜底双通道、五步进度与14原因码诊断闭环、重配网保留绑定、成功率\≥95%的监控与专项验收均已落点；与 M01/M02 文档格式及衔接协议一致（入口跳转、事件总线回调、绑定冲突申诉复用M02），可直接交付 UI 与开发。如确认无误，可按同样格式继续输出 M04 设备控制与状态展示模块。

M03 设备配网（对应需求：FR-121~125）​

1. 模块概述与设计原则​

1.1 模块范围​

1.2 设计原则​

1.3 用户与前置条件​

2. 页面结构与流程图​

2.1 页面导航结构​

2.2 核心状态机一：设备配网状态（设备侧视角）​

2.3 核心状态机二：配网任务（APP侧视角）​

3. 页面级详细需求​

W01 设备添加向导入口页（FR-121）​

W01a 扫码页（FR-121）​

W01b 型号选择页（FR-121）​

W02 蓝牙扫描/搜索设备页（FR-122）​

W03 配网准备页（FR-122）​

W04 Wi-Fi 配网执行页（FR-123，核心页）​

W07 AP 配网兜底流程页（FR-124）​

W05 配网成功页（FR-125）​

W06 配网失败诊断页（FR-125）​

4. 通用交互与视觉规范（UI设计输入，序号10）​

5. 客户端技术要求（Flutter）​

6. 云端需求（配网服务）​

6.1 接口清单​

6.2 关键策略​

7. 验收标准核对表（对齐 PRD 5.3）​

8. 依赖与风险​

M03 设备配网（对应需求：FR-121~125）

1. 模块概述与设计原则

1.1 模块范围

1.2 设计原则

1.3 用户与前置条件

2. 页面结构与流程图

2.1 页面导航结构

2.2 核心状态机一：设备配网状态（设备侧视角）

2.3 核心状态机二：配网任务（APP侧视角）

3. 页面级详细需求

W01 设备添加向导入口页（FR-121）

W01a 扫码页（FR-121）

W01b 型号选择页（FR-121）

W02 蓝牙扫描/搜索设备页（FR-122）

W03 配网准备页（FR-122）

W04 Wi-Fi 配网执行页（FR-123，核心页）

W07 AP 配网兜底流程页（FR-124）

W05 配网成功页（FR-125）

W06 配网失败诊断页（FR-125）

4. 通用交互与视觉规范（UI设计输入，序号10）

5. 客户端技术要求（Flutter）

6. 云端需求（配网服务）

6.1 接口清单

6.2 关键策略

7. 验收标准核对表（对齐 PRD 5.3）

8. 依赖与风险