eHome App 端详细需求设计文档

M09 OTA升级（对应需求：FR-1801~1806）

项目	内容
所属项目	eHome 智能家居硬件配套 APP + 云端后台定制开发项目
设计依据	《eHome智能家居项目需求文档（PRD V1.1）》OTA固件升级章节、第8章、NFR-03（升级成功率≥99%）/NFR-04（可用性）/NFR-05（安全性，签名校验）；《eHome项目页面功能工时费用明细表》M09模块
范围说明	本模块覆盖固件版本检测、升级详情与更新日志、下载/安装全流程、灰度发布与强制升级策略、批量升级、自动升级设置、升级历史与失败恢复（回滚）；不包含设备配网（属 M03）、传感器校准（属 M07，本模块仅提供升级锁定状态与能力变更通知）、APP自身版本更新（属 M01 应用内升级，复用本章下载组件规范但独立发布通道）
编号衔接说明	M07/M08 文档中引用的"OTA 锁定""最低固件版本""能力变更通知"均由本模块提供；本文档 FR 编号按工时表 M09 行顺延为 FR-1801~1806
优先级	P0（MVP必须；固件缺陷修复与功能迭代依赖OTA通道，无OTA则硬件售后成本不可控；同时是安全漏洞修补的生命线）
里程碑	M2 完整功能期开发（依赖 M01 账号、M02 家庭/设备、M03 配网、M04 设备状态；固件升级协议与分区方案须 M1 冻结；灰度策略依赖 M12 运营后台）
文档用途	直接交付 UI 设计、Flutter 开发（APP端）、云端开发、固件联调、测试QA、运维（发布流程）

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

需求编号	功能项
FR-1801	升级检测与状态总览（红点提醒、可升级列表、当前版本、强制升级拦截）
FR-1802	升级详情页（版本号、更新日志、包大小、预计耗时、注意事项、灰度标识）
FR-1803	下载与安装全流程（进度展示、断点续传、升级锁定、失败重试与自动回滚）
FR-1804	升级设置（自动升级开关、升级时间窗、仅Wi-Fi下载、通知偏好）
FR-1805	批量升级与升级历史（多设备并行、逐台进度、历史记录与结果追溯）
FR-1806	OTA升级流程 UI 设计（进度组件、双主题、7语种、无障碍）

1. 模块概述与设计原则

1.1 模块范围

序号	页面/功能项	需求编号	类型	优先级
1	升级中心页（状态总览+可升级列表）	FR-1801	APP+云端	P0
2	升级详情页（更新日志+确认升级）	FR-1802	APP+云端	P0
3	下载与安装进度页（含失败恢复）	FR-1803	APP+云端+固件	P0
4	升级设置页	FR-1804	APP+云端	P0
5	批量升级页+升级历史页	FR-1805	APP+云端	P0
6	OTA UI 规范	FR-1806	UI	P0

边界与衔接说明：

入口A：「我的」Tab →【固件升级】（含可升级数量红点）→ 本模块 O01（升级中心）；
入口B：M04-R01 设备详情页【检查更新】/【有新版本】横幅 → O02（该设备升级详情）；
入口C：M07 校准页"固件不支持校准"→ [升级固件] 携带目标版本 → O02；
入口D：M06 推送"固件更新可用/升级完成/升级失败"→ 深链 O02/O03/O06；
入口E：M02 设备列表固件过旧标记 → O02；
出口：升级成功后能力模型刷新（通知 M02/M07/M08 重拉能力）→ 返回来源页；升级锁定状态供 M07/M08 事务前置校验查询；灰度与发布配置由 M12 运营后台管理；失败工单 → M10。

1.2 设计原则

升级不打断生活：默认下载不打扰、安装在用户确认或时间窗内执行；升级中设备功能明确降级提示（锁定态），而非无响应假死。
变砖零容忍：固件 A/B 双分区 + 签名校验 + 安装失败自动回滚旧分区；APP 侧任何异常（断网/杀进程/低电量）都不允许设备停留在不可用状态；回滚结果必须可确认。
灰度可控可停：所有发布走灰度管道（内部→1%→10%→50%→100%），云端可一键暂停/撤回发布；强制升级仅限安全漏洞级别且需产品+安全双审批。
信息透明：更新日志用户可读（价值导向文案，非工程术语）；包大小/预计耗时/电量与网络要求前置告知；失败原因映射用户可懂文案+自助恢复指引。
一致性单源：版本号、能力声明、最低支持版本全部以云端设备影子（Device Shadow）为唯一事实源；APP 不缓存版本判定逻辑，只消费云端"可升级/强制/灰度中"结论。
低功耗设备适配：电池设备（传感器/门窗磁）升级耗时长且失败风险高——强制电量阈值（≥50%或充电中）、仅在网关代理下升级、明示"升级期间设备不可用约X分钟"。
双主题 + 7语种：更新日志 CMS 按 7 语种维护，缺失回退英文并标记；进度文案、注意事项、失败原因全资源文件。

1.3 用户与前置条件

用户状态：必须已登录（M01）；未登录拦截，成功回跳来源页。
权限前置：手动升级/批量升级需家庭管理员或设备编辑权限成员；自动升级设置仅管理员可改；普通成员 O01 为只读态（可见版本与历史，升级按钮置灰+提示）。
设备前置：设备在线（离线设备展示"待设备上线后升级"，支持预约）；电量≥30%（电池设备≥50%）；未处于其他事务（校准 M07/场景执行 M08）——升级开始前云端做事务互斥锁定。
网络前置：固件包下载走云端 CDN；设备侧下载需 Wi-Fi/网关在线；APP 侧"仅Wi-Fi下载"设置约束预下载行为。
版本前置：跨版本升级路径由云端判定（是否需中间版本逐级升级），APP 仅展示结论；不允许降级（云端拒绝旧版本包）。

2. 页面结构与流程图

2.1 页面导航结构

入口A：我的→[固件升级](红点N) ──► O01
入口B：M04-R01[检查更新/新版本横幅] ──► O02
入口C：M07[升级固件] ──► O02(携带目标版本)
入口D：M06推送 ──► O02/O03/O06深链
入口E：M02设备列表[固件过旧] ──► O02

O01 升级中心页
 ├─ 汇总卡（N台可升级 / 全部最新 / M台升级中）
 ├─ 可升级列表（设备+当前版本→新版本+强制标记+灰度标记）
 ├─ 升级中列表（实时进度缩略）
 ├─ [全部升级] ──► O05 批量升级
 ├─ [升级设置] ──► O04
 ├─ [升级历史] ──► O06
 └─ 待上线预约区（离线设备+预约开关）

O02 升级详情页（单设备）
 ├─ 版本信息卡（当前vX → 新版vY、包大小、预计耗时、发布日期）
 ├─ 更新日志（分段：新功能/优化/修复；多语言CMS）
 ├─ 升级前置检查结果（电量/网络/事务锁定/存储，逐项✓✘）
 ├─ 注意事项（升级期间设备不可用/勿断电/预计时长）
 ├─ [下载并升级] / [仅下载]（按设置）
 ├─ [预约升级]（离线设备/时间窗）
 └─ 强制升级态：不可关闭弹窗+倒计时+唯一[立即升级]

O03 下载与安装进度页
 ├─ 阶段步骤条：下载→校验→传输至设备→安装→重启验证
 ├─ 环形进度+阶段文案+剩余时间
 ├─ 后台执行提示（可离开页面，M06推送结果）
 ├─ 失败态：原因+自助恢复指引+[重试]/[联系客服]
 └─ 成功态：新版本摘要+[完成]（能力变更提示）

O04 升级设置页
 ├─ 自动升级总开关（默认关）
 ├─ 自动下载新固件（仅Wi-Fi开关）
 ├─ 自动安装时间窗（默认02:00-05:00，可改）
 ├─ 升级完成通知/失败通知开关（经M06）
 ├─ 灰度计划说明入口（H5）
 └─ 家庭级设置（管理员）与设备级覆盖（P1）

O05 批量升级页
 ├─ 设备多选（全选/按房间/按品类）
 ├─ 前置检查汇总（N台就绪 / M台电量不足 / K台离线）
 ├─ 并行策略展示（网关子设备串行、Wi-Fi设备并行≤5）
 ├─ 逐台进度列表（阶段+百分比+状态）
 └─ 汇总结果（成功N/失败M+[失败项重试]）

O06 升级历史页
 ├─ 时间线（设备+版本vX→vY+时间+结果徽标+耗时）
 ├─ 详情（失败原因/回滚记录/重试次数）
 ├─ 筛选（设备/结果/时间范围）
 └─ 空态+30天保留说明（云端保留全生命周期，APP默认展示近30天可加载更多）

2.2 核心状态机一：设备升级任务生命周期

[无可用更新]（当前=最新已发布版本）
   │
   ├──(云端灰度命中该设备)──► [更新可用] ──► O01红点/M06推送(按设置)
   │        │
   │        ├──(用户确认升级 / 自动升级时间窗触发 / 预约到时)──► [前置检查]
   │        │        │
   │        │        ├──检查失败(电量/网络/事务锁定)──► [条件不满足] ──► 提示具体原因
   │        │        │        ├──(电量不足)──► "请充电至50%以上" + 条件满足后自动恢复流程
   │        │        │        └──(校准/场景事务中)──► "设备正在执行其他任务" + 事务结束后重试
   │        │        │
   │        │        └──检查通过──► [下载中]（CDN，断点续传）
   │        │                 │
   │        │                 ├──下载失败(网络)──► [下载失败] ──► 自动重试3次(指数退避) ──► 仍失败提示用户
   │        │                 └──下载完成──► [校验中]（签名+哈希）
   │        │                          │
   │        │                          ├──校验失败──► [升级失败·包损坏] ──► 丢弃包+重新下载1次+告警运维
   │        │                          └──校验通过──► [传输中]（云→设备/网关→子设备）
   │        │                                   │
   │        │                                   └──► [安装中]（写入备用分区）
   │        │                                            │
   │        │                                            ├──(固件自检通过→切换分区→重启)──► [验证中]
   │        │                                            │        │
   │        │                                            │        ├──(新版本上线+影子版本回读一致)──► [升级成功]
   │        │                                            │        │        └──► 刷新能力模型+通知M02/M07/M08+M06推送+写历史
   │        │                                            │        └──(超时10min未上线/版本不符)──► [升级失败·验证超时]
   │        │                                            │
   │        │                                            └──(自检失败)──► [自动回滚]（切回旧分区重启）
   │        │                                                     ├──(旧版本上线确认)──► [已回滚·升级失败] ──► 设备可正常使用+M06通知+告警运维
   │        │                                                     └──(回滚后仍未上线·罕见)──► [设备异常] ──► 强提示联系客服+工单(M10)+运维介入
   │        │
   │        ├──(用户取消，仅下载/传输阶段可取消)──► [已取消]（清理临时包）
   │        └──(云端撤回发布)──► [更新已撤回] ──► 列表移除+已下载包作废
   │
   └──(强制升级命中)──► [强制更新] ──► 设备功能锁定+APP不可关闭弹窗+倒计时 ──► 唯一路径[立即升级]

2.3 核心状态机二：发布与灰度管道（云端-运营视角）

[固件包上传]（M12运营后台，研发签名+哈希登记）
   │
   ├──(安全扫描+签名验证)──► [待发布]
   │        │
   │        └──(发布审批：普通=产品审批 / 强制=产品+安全双审批)──► [灰度中]
   │                 │
   │                 ├──阶段1：内部白名单设备（员工/测试机）──► 观察24h
   │                 ├──阶段2：1% 用户设备 ──► 观察指标
   │                 ├──阶段3：10% ──► 观察指标
   │                 ├──阶段4：50% ──► 观察指标
   │                 └──阶段5：100% ──► [全量发布]
   │
   ├──(灰度熔断指标：升级成功率<98% / 回滚率>1% / 设备异常率>0.5%)──► [自动暂停]
   │        ├──(运维确认修复后)──► [恢复灰度]
   │        └──(确认版本缺陷)──► [撤回发布] ──► 已升级设备保持（不可降级）/未升级设备移除入口+公告
   │
   └──(全量发布后持续监控7天)──► [发布归档]

灰度命中规则：按 deviceId 哈希分桶 + 地区 + 硬件批次(HW revision) + 白名单；
同一硬件批次绑定固件兼容性矩阵，禁止跨批次误发（云端强校验）。

3. 页面级详细需求

O01 升级中心页（FR-1801）

页面目标：一屏掌握全家庭固件健康度，可升级设备清晰可操作，红点驱动触达。

页面元素：

元素	规格与规则
顶部导航	返回+标题"固件升级"；右侧[升级设置]→O04、[历史]→O06
汇总卡	三态：N台可升级（主态，含强制升级警示色）/全部已是最新版本（绿色✓插画）/M台升级中（进度摘要）；[全部升级]主按钮（N≥2时展示）→O05
可升级列表	每项：设备图标+名称+房间+当前版本→新版本+徽标（[强制]红/[灰度]蓝/[推荐]橙）+[升级]按钮；点击条目→O02；排序：强制>升级中>推荐>灰度
升级中列表	置顶分组：设备名+阶段文案+进度条缩略；点击→O03
待上线预约区	离线可升级设备折叠区："设备上线后自动提醒/自动升级（按O04设置）"；预约开关
检查更新按钮	底部[手动检查全部设备更新]；触发全家庭版本比对，loading后刷新列表；节流：60s内不重复请求
权限只读态	普通成员：[全部升级]/[升级]置灰+顶部提示"仅管理员可执行升级"；可查看版本与历史
空态	全部最新：插画+"所有设备固件均为最新版本"+上次检查时间；无设备：引导M03

逻辑规则：

数据来源：GET /ota/devices?familyId=（返回逐设备：当前版本/最新可用版本/是否命中灰度/是否强制/升级任务状态/电量/在线状态）；进入拉取+下拉刷新+MQTT ota/status/{deviceId} 增量更新；
红点链路：云端推送"更新可用"→M01 我的Tab红点→O01角标数量；用户进入O01后消除红点（升级动作完成或明确忽略均消）；强制升级红点不可消，直至完成；
检测时机：APP冷启动静默检查（节流12h）+进入O01检查+用户手动检查；静默检查仅刷新角标不推送（推送由云端灰度事件经M06按O04设置分发）；
强制升级拦截：任一设备强制升级→O01顶部红色横幅不可dismiss+设备项置顶；进入该设备任何控制页（M04-R01）弹不可关闭弹窗（见O02）；
版本判定单源：APP不做版本比较逻辑，直接消费云端 canUpgrade/forced/graying 字段；硬件批次兼容由云端保证；
离线设备：展示"待设备上线"；预约开关=上线后自动进入升级流程（受O04时间窗约束）；
埋点：O01曝光、红点点击转化、全部升级点击、单设备升级点击、强制横幅曝光→升级转化、检查更新使用率。

异常与边界：接口失败→展示缓存+重试；升级中设备被移除（M02）→云端终止任务并通知，列表移除+Toast；家庭无设备→空态引导配网；大量设备（>50台）列表虚拟化。

验收要点：三态汇总卡正确；四类徽标与云端一致；红点产生/消除链路（含强制不可消）；权限只读；预约离线设备；手动检查节流；升级中实时进度缩略。

O02 升级详情页（FR-1802）

页面目标：升级决策信息完备透明，前置检查通过才允许发起，强制升级唯一路径。

页面元素：

元素	规格与规则
版本信息卡	设备名+房间；当前 vX.Y.Z → 新版 vA.B.C（大字号）；包大小（MB）；预计耗时（下载+安装，按设备类型预置）；发布日期；灰度/强制徽标
更新日志	分段Tab或分节：新功能/体验优化/问题修复/安全更新；CMS多语言内容；安全更新段红色强调；日志缺失回退英文+反馈入口"日志未翻译"
前置检查清单	逐项自动检查：①电量≥30%（电池设备≥50%）②设备在线③网络质量（RSSI/网关连通）④无进行中事务（M07校准/M08场景执行）⑤存储空间；每项✓/✘+失败原因+[去处理]深链（充电提示/离线→M02-Q04/事务中→等待）
注意事项	固定文案：升级期间设备不可用约X分钟；请勿断电；其他家庭成员将同步看到升级状态；子设备经网关升级时网关勿断电
[下载并升级]	主按钮；前置检查全✓才激活，任一✘置灰+锚点定位到失败项；点击→确认弹窗（注意事项+预计时长）→O03
[仅下载]	次按钮（O04允许时展示）：先下载校验，安装待用户确认或时间窗
[预约升级]	离线设备或用户选择稍后：时间选择器（今晚/明天/自定义，受时间窗约束）
强制升级弹窗	不可关闭、返回键拦截、蒙层不可点穿；内容：安全原因简述+倒计时（默认72h，云端可配）+[立即升级]唯一按钮；倒计时归零→云端锁定设备功能（M04控制置灰"待安全升级"）
已是最新态	无可用更新时展示"当前已是最新版本 vX.Y.Z"+[检查更新]

逻辑规则：

数据来源：GET /ota/devices/{deviceId}/update（版本对比/日志/包大小/预计耗时/强制标记/倒计时/灰度阶段）+ GET /ota/devices/{deviceId}/precheck（前置检查实时结果，30s轮询刷新或MQTT推送）；
前置检查联动：电量/在线/事务状态实时刷新；事务锁定查询 M07/M08 事务管理器（升级与校准/场景执行互斥，先到先得，升级优先于新事务创建）；
强制升级：倒计时云端存储（设备维度）；APP多端同步展示；归零后设备功能锁定由云端影子标记，M04 消费；完成升级自动解锁；
跨版本路径：云端判定需逐级升级时（如 v1.2→v2.0 需先 v1.5），O02 展示"本次升级包含 N 个中间版本"并按序执行（对用户表现为一次任务，云端编排多段）；
预约：POST /ota/devices/{deviceId}/schedule（time）；到点云端触发，前置不满足则顺延并通知；预约可取消；
撤回联动：浏览中发布被撤回→页面刷新为"更新暂不可用"+说明（云端推送驱动）；
埋点：详情页曝光、日志展开阅读率、前置失败项分布（驱动硬件/固件改进）、下载并升级转化、仅下载占比、预约使用率、强制弹窗曝光→升级时长。

异常与边界：日志CMS缺失→英文回退+占位说明；预计耗时无法估算（新品类）→"约5~15分钟"兜底文案；检查接口失败→按钮置灰+重试；用户在强制倒计时中移除设备→需先完成升级或管理员确认风险（二次强提示，记录审计日志）。

验收要点：版本卡信息与云端一致；日志7语种回退正确；五项前置检查实时性与失败深链；强制弹窗不可逃逸（返回/蒙层/杀进程重进仍弹）+倒计时多端一致+归零锁定M04；逐级升级编排透明；预约创建/取消/顺延通知。

O03 下载与安装进度页（FR-1803）

页面目标：五阶段进度透明可离开，失败可解释可恢复，回滚结果可确认。

页面元素：

元素	规格与规则
阶段步骤条	五段：①下载固件 ②安全校验 ③传输至设备 ④安装中 ⑤重启验证；当前段高亮+loading，完成段✓，失败段✘
环形进度	总进度百分比（按阶段权重：下载40%/校验5%/传输20%/安装25%/验证10%）；当前阶段文案+剩余时间估算
阶段文案	"正在下载固件（45.2MB/120MB）…"/"正在校验固件完整性…"/"正在传输至设备…"/"设备正在安装，请勿断电…"/"设备重启验证中…"
后台执行提示	常驻说明："可安全离开此页面，升级将在后台继续，完成后通知您"；[后台运行]按钮最小化；返回拦截弹窗确认
取消按钮	仅下载/校验/传输阶段可取消（安装开始后隐藏+文案"安装已开始，无法取消"）；取消二次确认
成功态	绿色✓动画+新版本号+耗时；能力变更提示（若本次升级新增能力："设备新增XX功能，已同步至场景编辑器"→M08）；[完成]回来源页/[查看设备]→M04-R01
失败态	红色✘+阶段定位+原因文案（下载失败/校验失败/传输超时/安装失败/验证超时）+自助指引（检查网络/靠近网关/充电重试）+[重试]（保留已下载包）/[联系客服]（携taskId→M10）
回滚态	橙色："新版本安装未通过自检，设备已自动恢复至 vX.Y.Z，可正常使用"+回滚确认结果+[我知道了]/[反馈问题]；同时云端已告警运维
设备异常态	红色强提示："设备重启后未恢复响应，正在尝试恢复…（自动重试3次）"→仍失败→"请联系客服处理"+工单入口+设备诊断信息一键复制

逻辑规则：

任务驱动：POST /ota/devices/{deviceId}/upgrade 创建任务返回 taskId；进度来源 MQTT ota/progress/{taskId}（阶段+百分比+错误码，设备/网关上报经云端转发）+ HTTP GET /ota/tasks/{taskId} 轮询兜底（3s间隔，MQTT断连时）；
断点续传：设备侧下载支持 Range 续传（CDN）；APP杀进程/断网不影响设备侧任务（任务主体在云-设备链路，APP只是观察者）；APP重进O03按taskId恢复展示；
阶段超时：下载30min/传输15min/安装20min/验证10min，云端超时判定→失败态；安装阶段设备静默属正常（固件写Flash不通信），文案安抚"请勿断电"；
回滚确认：固件自检失败自动切回旧分区；云端以"旧版本号重新上线"为回滚成功判据；回滚后设备状态、场景（M08）、校准参数（M07）自动恢复旧版本兼容态并触发对账；
能力刷新：升级成功→云端更新设备影子能力模型→推送 device/capability 变更（M02/M07/M08 消费）；O03成功态展示能力变更摘要（diff由云端计算）；
完成通知：按O04设置经M06推送"升级成功/失败/已回滚"（失败与回滚默认推送，成功默认推送可关）；
幂等：同设备同时仅一个任务；重复请求返回进行中taskId；重试复用taskId+断点；
埋点：各阶段到达率/耗时P50/P90、失败阶段分布、错误码分布、回滚率、重试成功率、页面停留/后台化比例。

异常与边界：进度长时间不动（>5min同百分比）→展示"网络较慢，请耐心等待"+[刷新]；MQTT与HTTP结果冲突→以云端任务终态为准；升级中设备被移除→任务终止标记失败；升级中家庭被解散→任务终止+设备恢复出厂流程（M02）；批量升级并行时O03为单设备视图，批量进度见O05。

验收要点：五阶段进度真实映射设备侧状态；杀APP/断网后任务不受影响且重进恢复展示；取消窗口正确（安装后不可取消）；四类失败注入（下载/校验/安装/验证超时）文案与指引正确；回滚真机验证（刷入坏包→自动回旧版→设备可用→通知）；能力变更通知M07/M08联动刷新；通知按设置分发。

O04 升级设置页（FR-1804）

页面目标：把"自动升级"的控制权与知情权交给用户，默认保守。

页面元素：

元素	规格与规则
自动升级总开关	默认关；开启时弹窗说明："将在时间窗内自动安装新固件，升级期间设备短暂不可用"；强制升级不受此开关约束（明示文案）
自动下载开关	默认开（有更新时静默下载并校验，安装仍需确认/时间窗）；子项[仅Wi-Fi下载]默认开
安装时间窗	默认02:00-05:00；时间范围选择器（起止，跨零点支持）；说明"时间窗内设备空闲才执行，被占用则顺延至下一晚"
通知设置	[升级完成通知]默认开/[升级失败通知]默认开（强制开，不可关，安全考量）/[灰度新功能预告]默认关；均经M06渠道，尊重全局免打扰（失败通知为重要级可穿透）
灰度计划说明	入口→H5：什么是灰度/您的设备何时收到更新/如何申请优先体验（白名单报名，P1）
设备级覆盖（P1）	列表逐设备：跟随家庭设置/单独关闭自动升级（安防类设备默认建议关，提示原因）

逻辑规则：

设置作用域：家庭级（全家庭设备默认策略），存储云端家庭配置；修改权限=管理员；
自动升级执行：云端调度器在时间窗扫描"已下载+设备空闲+前置满足"任务→自动安装；前置不满足顺延次夜并记录（连续顺延3晚→M06提醒用户处理）；
设置即时生效：修改后云端调度策略实时更新；关闭自动升级不影响已确认的手动任务；
强制升级优先：任何设置不阻断强制升级（弹窗文案已声明）；
埋点：自动升级开启率、时间窗修改分布、通知开关变更、灰度H5访问、设备级覆盖使用。

异常与边界：时间窗非法（起=止/窗口<1h）→校验拦截+建议值；家庭无管理员时设置只读；设置接口失败→回滚开关态+Toast。

验收要点：默认值正确（自动升级关/自动下载开/仅Wi-Fi开/时间窗02:00-05:00）；权限控制；顺延3晚提醒；强制升级不受设置影响真机验证；通知穿透免打扰策略正确。

O05 批量升级页 + O06 升级历史页（FR-1805）

O05 批量升级页

页面目标：多设备一次升级，前置检查批量预演，并行策略透明，失败可批量重试。

页面元素：

元素	规格与规则
设备多选列表	全选/按房间/按品类快捷选择；每项：设备+版本对比+就绪状态（就绪✓/电量不足/离线/事务中）；不可就绪项默认不勾选+原因
汇总条	"已选N台 · 就绪M台 · 预计总耗时约X分钟（并行估算）"
并行策略说明	"同一网关下子设备逐台升级（避免网关过载），Wi-Fi设备最多5台并行"；[开始升级]确认弹窗含注意事项
逐台进度列表	每台：设备名+阶段文案+进度条+状态徽标（等待/下载/安装/成功/失败/已回滚）；总进度条置顶
控制区	[暂停]（暂停未开始的任务，进行中任务继续完成）/[取消全部]（仅未安装阶段）
结果汇总	完成态：成功N/失败M/回滚K+失败清单+[失败项全部重试]+[查看历史]；后台化支持（同O03）

逻辑规则：

批量接口：POST /ota/batch（deviceIds[]）→返回 batchId+逐台taskId；云端编排：网关分组串行、跨网关并行、Wi-Fi并行≤5、总并发≤20/家庭；
版本异构：不同设备不同固件包各自独立任务；同网关子设备包合并传输（网关缓存一次分发，省带宽）；
失败隔离：单台失败不影响其余；失败原因逐台记录；重试仅针对失败台；
前置批量预演：开始前云端批量precheck，不就绪台自动剔除并告知（用户可手动保留"等待就绪"）；
埋点：批量使用率、平均批量台数、批量成功率、暂停/取消使用。

O06 升级历史页

页面元素：

元素	规格与规则
时间线列表	每条：时间+设备名+vX→vY+结果徽标（成功绿/失败红/已回滚橙/已取消灰）+耗时；按日分组
筛选	设备多选+结果+时间范围；搜索设备名
详情展开	任务ID+各阶段耗时+失败原因/回滚记录+重试次数+[复制诊断信息]（taskId/设备SN/版本/错误码，供M10工单）
统计条	近30天：升级N次/成功率X%/平均耗时
保留说明	默认展示近30天，[加载更多]拉取全生命周期记录（分页）

逻辑规则：历史来源 GET /ota/history?familyId=&deviceId=&status=&cursor=；成功/失败/回滚/取消全记录；回滚记录必须含回滚后确认版本；权限：管理员全量，成员仅自己发起的任务；数据回流 M12 运营看板（升级成功率/回滚率按固件版本聚合）。

验收要点（O05/O06）：批量前置预演剔除正确；并行策略真机验证（网关串行/Wi-Fi并行≤5）；失败隔离与批量重试；暂停/取消窗口正确；历史四类结果完整；回滚记录含确认版本；诊断信息复制字段齐全；30天/全量分页。

4. 通用交互与视觉规范（UI设计输入，FR-1806）

双主题：浅色/深色两套；状态徽标四色（强制红/灰度蓝/推荐橙/成功绿）深色模式调亮满足WCAG AA；进度环与步骤条双主题适配；强制升级弹窗深色模式蒙层不透明度单独调优（保证警示感）。
组件清单：汇总卡（三态）、设备升级列表项（版本对比+徽标）、前置检查清单（✓/✘+深链按钮）、更新日志分段容器、版本对比卡（当前→新）、环形进度（阶段权重）、五段步骤条、后台运行提示条、强制升级弹窗（不可关闭+倒计时）、批量多选列表（就绪状态）、逐台进度列表项、结果汇总卡、历史时间线条目（徽标+详情展开）、设置项（开关/时间窗选择器）、空态插画（全部最新/无历史两款）。
动效规范：进度环平滑推进（300ms插值，禁止跳变）；阶段切换步骤条渐入；成功✓打勾动画+轻震动；失败✘抖动1次；下载剩余时间每秒刷新节流；强制弹窗倒计时数字翻牌；全部提供"减弱动效"降级。
多语言：更新日志由CMS按7语种维护（研发提供中文母版→本地化团队翻译→CMS录入）；版本号不翻译；包大小单位（MB）locale格式；注意事项/失败原因/阶段文案资源文件；德/法/俄预留1.4倍空间；倒计时格式按locale（时:分:秒）。
无障碍：进度环+百分比文字双通道（读屏播报"下载中，45%"）；步骤条当前阶段播报；强制弹窗焦点锁定+[立即升级]默认焦点；前置检查清单逐项可读；徽标图标+文字不依赖颜色；倒计时提供剩余时间文字播报（每分钟）。
响应式：平板/折叠屏宽屏下 O01 左侧列表+右侧详情分栏（点击设备直接展示O02内容）；O05 批量页左侧选择+右侧进度分栏；O06 左列表+右详情。
品牌一致性：设备图标复用M02/M04统一图标系统；版本号字体用等宽数字避免跳动；强制升级警示色与安全类告警（M06紧急级）同色系。

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

状态管理：Riverpod/BLoC；升级任务用 TaskStreamProvider（MQTT ota/progress 流+HTTP轮询兜底合并去重）；O01列表 FutureProvider+缓存（TTL 5min）；前置检查30s定时刷新Provider（页面可见时）；批量任务 BatchTaskNotifier（逐台状态map）。
MQTT：复用 M02/M04 连接层；订阅 ota/progress/{taskId}、ota/status/{deviceId}（任务终态/撤回）、device/capability/{deviceId}（能力变更转发M08）；断连期间自动切HTTP轮询（3s），恢复后回流；QoS1。
任务恢复：taskId 持久化（Hive，键=deviceId+taskId，TTL 7天）；APP重启/重进按taskId拉取终态恢复O03展示；杀进程不影响云-设备链路任务（APP纯观察者模式）。
进度渲染：百分比插值动画（AnimationController，300ms）；剩余时间估算=已用时间/进度比例外推（阶段内），跨阶段用云端预置权重；渲染节流1s。
强制升级弹窗：全局 Overlay 管理（根路由监听 forced 状态推送）；返回键拦截（PopScope）；蒙层不可点穿；多页面均触发（路由守卫）；倒计时与云端时间戳同步（NTP校准手机时间偏差）。
深链路由：注册 ehome://ota/{deviceId}（O02）、ehome://ota/task/{taskId}（O03）、ehome://ota/batch/{batchId}（O05）、ehome://ota/history（O06）；M06推送携带深链直达。
本地缓存：Hive 存储设备版本快照（红点计算辅助）、设置项、taskId映射；账号注销联动清除；无PII。
性能：批量50台进度列表虚拟化+局部rebuild（仅变更台重建）；O01大量设备（>50）分页+虚拟滚动；进度页帧率≥55fps。
安全：所有升级操作HTTPS；APP不经手固件包（下载与安装全在云-设备链路，APP仅展示）杜绝中间人风险面；诊断信息复制不含密钥/签名；Sentry上报脱敏。
埋点：见各页；统一 OtaAnalytics 封装，事件命名 ota_*；核心漏斗（红点→O01→O02→发起→成功）；质量指标（各阶段耗时P90、失败率、回滚率）实时上报支撑灰度熔断看板。

6. 云端需求（OTA服务）

6.1 接口清单

接口	方法	说明
/ota/devices	GET	家庭设备升级状态总览（当前版本/可用版本/灰度/强制/任务状态/电量/在线）
/ota/devices/`{id}`/update	GET	单设备升级详情（版本对比/多语言日志/包大小/预计耗时/强制倒计时/逐级路径）
/ota/devices/`{id}`/precheck	GET	前置检查（电量/在线/网络质量/事务互斥/存储）
/ota/devices/`{id}`/upgrade	POST	创建升级任务（幂等，返回taskId）；仅下载模式参数 downloadOnly
/ota/devices/`{id}`/schedule	POST/DELETE	预约升级（创建/取消）
/ota/tasks/`{taskId}`	GET	任务状态与进度（轮询兜底）
/ota/tasks/`{taskId}`/cancel	POST	取消（仅下载/校验/传输阶段）
/ota/tasks/`{taskId}`/retry	POST	失败重试（断点复用）
/ota/batch	POST	批量升级（返回batchId+逐台taskId；编排策略云端执行）
/ota/batch/`{batchId}`	GET	批量进度汇总
/ota/batch/`{batchId}`/pause	POST	暂停未开始任务
/ota/history	GET	升级历史（游标分页；30天默认/全量可拉）
/ota/settings	GET/PUT	家庭升级设置（自动升级/时间窗/仅Wi-Fi/通知偏好；管理员）
/ota/lock/`{deviceId}`	GET	升级锁定状态查询（供M07校准/M08场景事务前置互斥校验）
（MQTT下行）ota/notify	—	新固件可用通知→设备（携带版本/包URL/哈希/签名/强制标记）
（MQTT上行）ota/progress	—	设备/网关上报进度（阶段/百分比/错误码）→云端转发APP
（内部）发布管理	—	固件包登记/签名验证/硬件批次兼容矩阵/逐级升级路径计算/灰度分桶/熔断与撤回（对接M12运营后台）
（内部）升级调度器	—	时间窗自动安装/预约触发/顺延重试（3晚提醒）/离线设备上线触发/批量并发编排（网关串行/Wi-Fi并行≤5/家庭并发≤20）
（内部）事务互斥锁	—	设备级分布式锁（OTA vs 校准 vs 场景执行）；升级优先；锁超时自动释放（任务终态兜底）
（内部）质量监控	—	按固件版本聚合成功率/回滚率/异常率；熔断阈值自动暂停灰度+告警运维

6.2 关键策略

发布安全：固件包上传强制签名（私钥KMS保管）+SHA256哈希登记；设备端验签+哈希双校验后才写分区；APP与设备均不可获取签名私钥；硬件批次兼容矩阵强校验，禁止跨批次误发（发布时双重确认）。
灰度管道：deviceId哈希分桶（稳定分桶，同设备始终同桶）；五阶段推进（白名单→1%→10%→50%→100%），每阶段观察窗与熔断指标（成功率<98%/回滚率>1%/异常率>0.5%自动暂停）；一键撤回：未升级设备移除入口+已下载包作废+公告；强制升级需产品+安全双审批且默认72h倒计时。
升级事务：taskId全链路主键（创建→前置→下载→校验→传输→安装→验证→终态）；阶段超时判定；A/B分区+自检失败自动回滚+回滚确认（旧版本上线判据）；回滚后触发M07参数对账与M08规则兼容性检查；任务终态写历史+通知分发。
事务互斥：设备级分布式锁（Redis，TTL=任务超时上限）；OTA启动前查询校准/场景事务，进行中则等待或拒绝（用户侧文案明示）；OTA锁定期间M07/M08新事务被拒（/ota/lock查询）；锁泄漏兜底：任务终态强制释放+定时巡检。
版本一致性单源：设备影子（Device Shadow）存储 reported/desired 版本；升级成功以影子回读新版本为最终判据（非设备自报成功）；影子与设备每日对账，不一致自动标记异常。
性能SLA：/ota/devices P99≤400ms（家庭50台内）；任务创建≤500ms；进度推送端到端（设备→APP）P90≤2s；批量50台编排稳定；CDN下载带宽按发布峰值弹性扩容（全量发布日峰值预估模型）。
运营看板（回流M12）：发布漏斗（命中→下载→安装→成功率）、各阶段耗时分布、失败错误码Top、回滚率按固件版本/硬件批次聚合、灰度熔断事件时间线、强制升级完成率与倒计时归零锁定数；异常自动告警（企业微信/邮件双通道）。

7. 验收标准核对表

需求	验收标准	本设计落点
FR-1801	三态汇总/四类徽标/红点链路（强制不可消）/预约/权限只读/版本判定单源	O01；/ota/devices；红点规则1
FR-1802	版本卡+日志7语种回退；五项前置检查实时+深链；强制弹窗不可逃逸+倒计时+归零锁定；逐级升级透明	O02；precheck接口；强制弹窗全局Overlay
FR-1803	五阶段真实映射；杀进程/断网不影响任务；取消窗口；四类失败注入；回滚真机验证；能力变更联动	O03；任务驱动规则；A/B分区回滚
FR-1804	默认值正确；时间窗调度+顺延3晚提醒；强制不受设置影响；通知穿透策略	O04；升级调度器
FR-1805	批量预演剔除；网关串行/Wi-Fi并行策略；失败隔离与批量重试；历史四类结果+回滚确认版本+诊断复制	O05/O06；/ota/batch；/ota/history
FR-1806	双主题/7语种/无障碍/响应式全达标；强制弹窗警示规范	第4章；组件清单

QA测试要点（专项）：

升级全链路真机验证：单设备五阶段完整走通（Wi-Fi设备+网关子设备两种链路）；影子版本回读判据；能力变更通知M07（校准能力刷新）/M08（场景能力刷新）联动生效；
回滚与变砖防护：注入坏包（自检失败）→自动回滚→旧版本上线→设备全功能可用→回滚通知+历史记录含确认版本；回滚后M07校准参数对账、M08场景兼容检查触发；
中断矩阵：下载中断网（续传恢复）/校验中杀APP（重进恢复展示）/传输中设备断电（超时失败+重试）/安装中拔网线（设备侧继续，联网后进度回流）/验证中移除设备（任务终止）；
强制升级：弹窗不可逃逸（返回/蒙层/杀进程重进/多页面路由守卫）；倒计时多端一致（两台手机同账号）；归零后M04控制锁定"待安全升级"；完成升级自动解锁；
事务互斥：校准进行中发起升级→等待/拒绝文案；升级锁定中发起校准（M07）/场景执行（M08）→被拒且提示；锁超时自动释放（人为制造泄漏）；
批量升级：50台混合（网关子设备+Wi-Fi）编排验证（网关内串行/跨网关并行/Wi-Fi≤5/家庭≤20）；单台失败隔离；批量重试仅失败台；暂停/取消窗口；
灰度与熔断：分桶稳定性（同设备重复检查不跳桶）；模拟成功率<98%触发自动暂停；撤回后入口移除+已下载包作废；硬件批次不匹配发布被拦截；
预约与时间窗：预约到点触发；前置不满足顺延次夜+连续3晚提醒；时间窗内设备忙顺延；跨零点窗口（23:00-02:00）正确；
多语言与无障碍：日志7语种CMS回退链；读屏播报进度/阶段/倒计时；强制弹窗焦点锁定；减弱动效；深色模式徽标对比度；
性能与兼容：iOS 13+/Android 7.0+真机；/ota/devices 50台家庭P99≤400ms；批量进度列表帧率≥55fps；进度推送端到端P90≤2s；全量发布日CDN压测（模拟10万设备并发下载）。

8. 依赖与风险

项	说明	责任/时点
固件A/B分区与升级协议	双分区方案、自检逻辑、断点续传、验签实现、进度上报协议——回滚能力的基石	固件团队 M1 冻结（含 bootloader 防降级）；M2 联调（最大风险项，预留3周缓冲）
签名与KMS	固件签名私钥管理、密钥轮换预案；私钥泄漏=全线设备风险	安全团队 M1 方案；上线前渗透测试
硬件批次兼容矩阵	同型号不同HW revision固件兼容性登记；误发变砖风险	硬件团队提供矩阵；发布流程双重确认
M12 运营后台	发布管理/灰度配置/日志CMS/熔断看板/强制升级审批流	M2 前交付发布最小闭环；CMS多语言流程就绪
M02 设备影子	版本/能力/在线状态单源；影子对账任务	M1 影子服务就绪
M04/M07/M08 事务互斥	锁定状态消费方改造（控制置灰/校准拒绝/场景抑制）	M2 联调（三方契约：/ota/lock）
M06 通知渠道	更新可用/成功/失败/回滚/顺延提醒推送；失败通知穿透免打扰	M2 并行
M10 工单	失败/设备异常携带诊断上下文建单	M2 联调
CDN 与带宽成本	固件包分发峰值（全量发布日）；成本与扩容预案	运维 M1 容量规划
电池设备升级风险	传感器类升级耗电与失败率高于常供电设备；电量阈值50%仍可能中途断电	固件评估功耗曲线；灰度阶段重点观察电池品类回滚率
逐级升级复杂度	跨多版本路径编排（v1.2→v1.5→v2.0）中间版本包维护	云端路径计算；发布规范约束（禁止跨大版本直跳）
用户知情与打扰平衡	自动升级默认关→渗透率低→安全版本覆盖慢；强制升级体验强硬	运营策略：安全更新文案强化+灰度预告；产品评审强制升级触发标准（仅CVE级）

以上为 M09 OTA升级（FR-1801~1806）完整详细需求设计：升级中心与红点链路、升级详情与前置检查、五阶段进度与A/B回滚、自动升级设置与时间窗调度、批量升级编排、灰度发布管道与熔断、强制升级与事务互斥均已落点；与 M01/M02/M04/M06/M07/M08/M10/M12 文档格式及衔接协议一致（设备影子单源、MQTT复用、锁定状态契约、通知复用），可直接交付 UI 与开发。如确认无误，可按同样格式继续输出后续模块（如 M10 帮助中心与工单、M11 语音生态接入、M12 运营后台等）。

M09 OTA升级（对应需求：FR-1801~1806）​

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

1.1 模块范围​

1.2 设计原则​

1.3 用户与前置条件​

2. 页面结构与流程图​

2.1 页面导航结构​

2.2 核心状态机一：设备升级任务生命周期​

2.3 核心状态机二：发布与灰度管道（云端-运营视角）​

3. 页面级详细需求​

O01 升级中心页（FR-1801）​

O02 升级详情页（FR-1802）​

O03 下载与安装进度页（FR-1803）​

O04 升级设置页（FR-1804）​

O05 批量升级页 + O06 升级历史页（FR-1805）​

O05 批量升级页​

O06 升级历史页​

4. 通用交互与视觉规范（UI设计输入，FR-1806）​

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

6. 云端需求（OTA服务）​

6.1 接口清单​

6.2 关键策略​

7. 验收标准核对表​

8. 依赖与风险​

M09 OTA升级（对应需求：FR-1801~1806）

1. 模块概述与设计原则

1.1 模块范围

1.2 设计原则

1.3 用户与前置条件

2. 页面结构与流程图

2.1 页面导航结构

2.2 核心状态机一：设备升级任务生命周期

2.3 核心状态机二：发布与灰度管道（云端-运营视角）

3. 页面级详细需求

O01 升级中心页（FR-1801）

O02 升级详情页（FR-1802）

O03 下载与安装进度页（FR-1803）

O04 升级设置页（FR-1804）

O05 批量升级页 + O06 升级历史页（FR-1805）

O05 批量升级页

O06 升级历史页

4. 通用交互与视觉规范（UI设计输入，FR-1806）

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

6. 云端需求（OTA服务）

6.1 接口清单

6.2 关键策略

7. 验收标准核对表

8. 依赖与风险