eHome App 端详细需求设计文档

M13 桌面小组件（对应需求：FR-2201~2206）

项目	内容
所属项目	eHome 智能家居硬件配套 APP + 云端后台定制开发项目
设计依据	《eHome智能家居项目需求文档（PRD V1.1）》桌面入口与快捷交互章节、第8章、NFR-02（性能，组件刷新≤2s）/NFR-04（可用性）/NFR-07（国际化7语种）；《eHome项目页面功能工时费用明细表》M13模块；Apple WidgetKit / Android AppWidget 平台规范
范围说明	本模块覆盖 iOS/Android 桌面小组件（设备控制卡、场景一键执行卡、环境摘要卡）、组件配置页（APP内编辑组件内容/排序/可见性）、数据同步机制（App Group/SharedPrefs + MQTT增量推送）、离线与登录态降级、锁屏/待机模式适配（iOS StandBy/Android Always-On）；不包含通知中心快捷操作（属M06）、Siri/语音助手快捷指令（属M11）、平板专属大尺寸组件（P2预留）
编号衔接说明	M04 设备控制、M08 场景执行为本模块动作源；M02 家庭/房间为组件数据域；M10 气象与环境传感器为环境摘要卡数据源；M01 登录态决定组件是否展示真实数据；本文档 FR 编号按工时表 M13 行顺延为 FR-2201~2206
优先级	P1（非MVP阻断，但为高频体验差异化核心；"不打开APP即可控"是智能家居留存关键指标；依赖M04/M08/M10稳定后实施）
里程碑	M3 体验增强期开发（依赖 M01 账号、M02 家庭、M04 设备状态、M08 场景、M10 环境数据全部就绪；M2期间完成App Group/SharedPrefs基建预埋）
文档用途	直接交付 UI 设计、Flutter 开发（APP端配置页）、iOS 原生开发（Widget Extension）、Android 原生开发（AppWidget）、云端开发、测试QA

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

需求编号	功能项
FR-2201	设备控制卡组件（单设备开关/调光/窗帘位置，支持iOS 17+交互/Android RemoteViews点击）
FR-2202	场景一键执行卡组件（单场景触发+反馈动画，支持批量场景横向滚动）
FR-2203	环境摘要卡组件（温湿度/AQI/天气图标+数值，多传感器融合展示）
FR-2204	组件配置页（APP内选择组件类型/绑定设备或场景/排序/可见性开关/预览）
FR-2205	数据同步与状态一致性（App Group/SharedPrefs共享存储+MQTT增量+主APP前台刷新兜底）
FR-2206	组件UI与平台适配规范（双主题/7语种/RTL/iOS StandBy/Android Always-On/锁屏隐私）

1. 模块概述与设计原则

1.1 模块范围

序号	页面/功能项	需求编号	类型	优先级
1	设备控制卡组件（小/中尺寸）	FR-2201	iOS原生+Android原生	P1
2	场景一键执行卡组件（小/中/横向滚动）	FR-2202	iOS原生+Android原生	P1
3	环境摘要卡组件（小/中尺寸）	FR-2203	iOS原生+Android原生	P1
4	组件配置页 W01	FR-2204	APP(Flutter)+云端	P1
5	数据同步基建（共享存储+MQTT桥接）	FR-2205	原生+云端	P1
6	组件UI与平台适配规范	FR-2206	UI+原生	P1

边界与衔接说明：

入口A：「我的」Tab →【桌面小组件】→ W01（组件配置页）；
入口B：系统桌面长按添加小组件 → 选择eHome组件 → 首次添加跳转W01引导配置；
入口C：M04-R01 设备详情页【⋮】→【添加到桌面】→ W01预填该设备；
入口D：M08-S01 场景列表长按 →【添加到桌面】→ W01预填该场景；
出口：组件点击动作 → 复用M04设备控制/M08场景执行通道（不新建API）；组件点击非动作区域 → 深链回跳APP对应详情页；未登录/无家庭 → 组件展示引导态+点击跳转M01/M02。

1.2 设计原则

零延迟感知：组件数据从共享存储读取（毫秒级），不依赖网络请求；动作执行走本地乐观更新+异步确认，用户感知即时响应。
平台原生优先：iOS用WidgetKit+SwiftUI（支持iOS 17+ Interactive Widgets），Android用AppWidget+RemoteViews/Glance（Jetpack）；不强行跨平台一致，尊重各平台设计规范与交互范式。
数据最小化：组件仅缓存展示所需字段（设备名/状态/场景名/环境值），不缓存完整设备模型或用户PII；共享存储加密，Token不落盘。
优雅降级：未登录→引导登录卡片；无家庭→引导创建/加入；设备离线→灰色态+最后更新时间；数据过期（>5min未同步）→显示"…"占位+时间戳；网络恢复/主APP前台自动刷新。
隐私安全：锁屏/待机模式下敏感信息（摄像头画面/门锁状态/精确位置）默认模糊或隐藏，需生物识别解锁后显示；组件不展示密码/Token/手机号等PII。
配置即所见：W01配置页提供实时预览（模拟组件渲染），保存后立即生效；组件内容与APP内设备/场景变更联动（删除设备→组件自动移除该槽位+提示）。

1.3 用户与前置条件

用户状态：组件展示依赖主APP登录态（共享存储中的session flag）；未登录时组件渲染引导态，点击跳转M01。
家庭前置：至少一个家庭且为成员；无家庭→组件渲染引导态"创建或加入家庭"，点击跳转M02。
系统版本：iOS ≥16.0（Interactive Widgets需≥17.0，低版本降级为点击跳转）；Android ≥8.0（Glance需≥12，低版本用RemoteViews兼容）。
权限前置：组件无需额外系统权限；数据同步依赖主APP后台刷新能力（iOS Background Fetch/Android WorkManager），需在W01引导用户开启。
内容前置：设备控制卡需至少1个可控设备；场景卡需至少1个已创建场景；环境卡需至少1个环境传感器或气象数据源；否则组件显示空态+引导添加。

2. 页面结构与流程图

2.1 页面导航结构

入口A：我的→[桌面小组件] ──► W01
入口B：系统添加组件 ──► W01(首次引导)
入口C：M04-R01[添加到桌面] ──► W01(预填设备)
入口D：M08-S01[添加到桌面] ──► W01(预填场景)

W01 组件配置页
 ├─ 顶部：当前家庭选择器（多家庭切换，组件绑定当前家庭）
 ├─ 组件类型Tab：设备控制 / 场景执行 / 环境摘要
 ├─ 已添加组件列表（可拖拽排序/长按编辑/滑动删除）
 │    ├─ 每项：组件预览缩略图+名称+绑定内容摘要+[编辑]
 │    └─ 空态："还没有添加组件"+[快速添加]按钮
 ├─ [添加组件]按钮 → 底部Sheet
 │    ├─ 设备控制：选择设备（多选，上限4）→ 预览 → 保存
 │    ├─ 场景执行：选择场景（多选，上限6）→ 预览 → 保存
 │    └─ 环境摘要：选择数据源（传感器/气象，多选，上限3）→ 预览 → 保存
 ├─ 全局设置
 │    ├─ 锁屏显示敏感信息（开关，默认关）
 │    ├─ 数据同步频率（实时/5min/15min，默认实时）
 │    └─ 后台刷新引导（检测未开启时显示[去设置]深链）
 └─ 底部：[保存配置]（批量写入共享存储+触发组件刷新）

系统桌面组件实例（非APP页面）
 ├─ 设备控制卡·小(2x2)：单设备开关+名称+状态图标
 ├─ 设备控制卡·中(4x2)：双设备开关/单设备调光滑块+名称
 ├─ 场景执行卡·小(2x2)：单场景图标+名称+触发反馈
 ├─ 场景执行卡·中(4x2)：2x2四场景网格
 ├─ 场景执行卡·横向(4x1)：横向滚动场景条（最多6个）
 ├─ 环境摘要卡·小(2x2)：单指标（温度/AQI）+图标
 └─ 环境摘要卡·中(4x2)：三指标横排+天气图标+更新时间

2.2 核心状态机一：组件数据同步

[组件渲染请求]（系统定时/用户交互/主APP触发）
   │
   ├──(读取共享存储)──► [数据有效？]
   │        │
   │        ├──有效(TTL≤5min)──► [渲染正常态]
   │        │
   │        ├──过期(TTL>5min)──► [渲染陈旧态]（数值+"…"占位+时间戳）
   │        │        └──(主APP前台/MQTT到达)──► 刷新共享存储──► 重新渲染
   │        │
   │        ├──缺失(首次/清除数据)──► [渲染引导态]（"打开eHome同步数据"）
   │        │        └──(主APP启动)──► 全量拉取──► 写入共享存储──► 触发组件刷新
   │        │
   │        └──登录态失效──► [渲染未登录引导态]──► 点击跳转M01
   │
   └──(MQTT增量推送到达)──► [合并更新共享存储]──► 触发组件刷新（节流1s）

TTL策略：设备状态30s / 场景状态60s / 环境数据5min / 气象15min；
刷新触发：MQTT消息/主APP前台/系统Background Fetch/WorkManager周期任务；
节流：同一组件1s内多次刷新合并为一次渲染。

2.3 核心状态机二：组件事件执行（以设备开关为例）

[用户点击组件开关]
   │
   ├──(iOS 17+ Interactive Widget)──► [本地乐观更新]（开关立即翻转+loading微动效）
   │        │
   │        ├──► [AppIntent执行]──► 调用主APP设备控制通道(M04)
   │        │        │
   │        │        ├──成功──► MQTT回执到达──► 确认终态──► 取消loading
   │        │        ├──失败──► 回滚开关状态──► Toast"执行失败"+错误码
   │        │        └──超时(5s)──► 回滚──► Toast"响应超时，请检查网络"
   │        │
   │        └──(iOS <17)──► [点击跳转APP]──► 深链M04-R01设备详情页
   │
   └──(Android RemoteViews/Glance)──► [PendingIntent广播]
            │
            ├──► [BroadcastReceiver接收]──► 启动前台Service执行设备控制
            │        │
            │        ├──成功──► 更新共享存储──► 触发组件刷新──► 开关终态
            │        ├──失败──► 更新共享存储(错误态)──► 组件显示重试按钮
            │        └──超时──► 同上
            │
            └──(低版本兼容)──► 点击跳转APP深链

乐观更新规则：仅开关/调光等幂等操作乐观更新；非幂等操作（如场景执行）仅显示loading不改变状态；
失败回滚：乐观更新后5s内未收到MQTT确认→自动回滚+提示；
并发控制：同一设备1s内重复点击丢弃后续请求（防抖）。

3. 页面/组件级详细需求

W01 组件配置页（FR-2204）

页面目标：让用户直观理解每种组件的能力，快速完成内容绑定与排序，所见即所得。

页面元素：

元素	规格与规则
家庭选择器	顶部下拉，仅显示当前用户有权限的家庭；切换家庭→已添加组件列表过滤为该家庭下配置；新家庭无配置时显示空态
组件类型Tab	三段Tab：设备控制/场景执行/环境摘要；切换保留各Tab独立列表状态
已添加组件列表	可拖拽排序（长按拖动）；左滑删除（二次确认）；点击[编辑]进入内容重选Sheet；每项显示：组件类型图标+名称+绑定内容摘要（如"客厅灯·卧室空调"）+尺寸标识
空态	插画+"让常用功能触手可及"+[快速添加]→展开添加Sheet
添加Sheet	底部弹出；设备控制：设备多选列表（按房间分组，仅显示可控设备）；场景执行：场景多选列表（按使用频率排序）；环境摘要：数据源多选（传感器按房间分组+气象选项）；选中项实时预览区（模拟组件渲染）；[保存]校验通过→写入配置
全局设置	锁屏敏感信息开关（说明文案："关闭后锁屏/待机模式下摄像头、门锁等敏感信息将模糊显示"）；同步频率单选（实时推荐/省电模式15min）；后台刷新状态检测（未开启时显示黄色提示条+[去设置]→系统设置深链）
保存按钮	底部固定；点击→批量写入共享存储→触发所有已添加组件刷新→Toast"配置已保存"；保存失败→回滚配置+错误提示

逻辑规则：

配置存储：组件配置存云端/user/widget-configs（换机恢复）+ 本地共享存储（组件读取）；保存时双写，云端失败不影响本地生效，后台重试同步；
内容联动：APP内删除设备/场景→下次打开W01时自动检测并标记失效项（红色感叹号）+[替换]按钮；组件侧检测到失效内容→渲染占位符+"内容已失效"；
预览渲染：W01内预览使用Flutter自绘模拟组件样式（与原生组件视觉一致），数据取自真实设备/场景/环境快照；预览不执行真实动作；
数量限制：每家庭每类型组件上限10个；总组件数上限30个；超限添加拦截+提示；
埋点：W01访问来源（入口A/B/C/D）、各类型添加率、平均组件数、排序调整频次、锁屏开关状态分布、同步频率选择分布、后台刷新引导转化率。

异常与边界：共享存储写入失败→重试3次仍失败→提示"存储空间不足，请清理后重试"；云端同步失败→本地配置生效+顶部黄色提示条"配置未同步至云端，换机可能丢失"；设备/场景列表加载失败→重试+空态兜底；预览渲染异常→降级为文字描述。

验收要点：三类型Tab切换流畅；多选列表按房间/频率排序正确；预览实时联动选择；拖拽排序持久化；删除二次确认；失效项检测与替换；锁屏开关生效验证；后台刷新引导深链可达；双写一致性（杀进程重进配置仍在）。

设备控制卡组件（FR-2201）

组件目标：桌面一键控制高频设备，状态实时可视，交互零延迟感知。

组件规格：

尺寸	布局	交互能力
小(2x2)	设备图标+名称(单行截断)+状态标签(开/关/百分比)+开关Toggle	iOS17+: Toggle直接控制; iOS<17: 点击跳转设备详情; Android: Toggle PendingIntent
中(4x2)	左:设备图标+名称+状态; 右:调光滑块(亮度/窗帘位置)或双开关(两设备)	iOS17+: 滑块/双Toggle; iOS<17: 点击跳转; Android: 滑块/双Toggle PendingIntent

逻辑规则：

数据来源：共享存储 device/{deviceId}/state（字段：name/icon/status/brightness/position/online/lastUpdate）；TTL 30s；
状态渲染：在线→正常色；离线→灰色+最后更新时间；状态未知→"…"占位；调光设备显示百分比+滑块；开关设备显示开/关标签+Toggle；
交互反馈：Toggle点击→立即翻转+loading环（0.5s淡入）；MQTT确认→loading消失；失败→回滚+振动反馈（Haptic）；滑块拖动→实时预览亮度（本地模拟）→松手后发送控制指令→确认终态；
深链：点击非交互区域（名称/图标）→ ehome://device/{deviceId} → M04-R01；
隐私：门锁/摄像头设备在锁屏模式下状态标签显示"🔒"而非具体状态，需解锁后显示（读取共享存储中的lockScreenPrivacy标志）；
埋点：组件曝光（系统回调）、Toggle点击次数/成功率、滑块使用次数、深链跳转次数、离线态曝光占比。

异常与边界：设备被删除→组件渲染"设备已移除"+[编辑]深链W01；控制指令发送失败→回滚+Toast（Android用组件内TextView短暂显示错误）；MQTT断连期间操作→乐观更新+5s超时回滚；多设备中尺寸组件其中一个离线→仅该设备灰色，其余正常。

场景一键执行卡组件（FR-2202）

组件目标：高频场景桌面一键触发，执行反馈明确，支持多场景紧凑布局。

组件规格：

尺寸	布局	交互能力
小(2x2)	场景图标+名称(两行截断)+执行反馈动画	点击→触发场景+涟漪动画+✓确认
中(4x2)	2x2网格，每格同小尺寸	四场景独立触发
横向(4x1)	横向滚动胶囊列表，每胶囊图标+名称	横向滑动浏览，点击触发

逻辑规则：

数据来源：共享存储 scene/{sceneId}/meta（字段：name/icon/color/lastExecuted）；TTL 60s（场景元数据变化低频）；
执行反馈：点击→涟漪扩散动画（300ms）→图标短暂替换为✓（1s）→恢复原图标；执行失败→图标替换为✗（1s）+振动；
防误触：相邻场景间距≥8dp；横向滚动惯性阻尼防止误点；执行中禁用重复点击（1s冷却）；
深链：长按场景（iOS 17+ Long Press Gesture / Android Long Click）→弹出菜单[编辑场景][查看详情]→深链M08-S02/M08-S03；短按=执行；
动态排序：横向滚动模式下，最近执行的场景自动置顶（共享存储记录lastExecuted时间戳，组件读取时排序）；
埋点：场景执行次数/成功率、各尺寸使用分布、横向滚动深度、长按菜单使用率、冷却期拦截次数。

异常与边界：场景被删除→槽位显示"场景已失效"+灰色图标+点击跳转W01；执行超时（10s无回执）→✗反馈+Toast"场景执行超时"；网络不可用→点击无反应+组件底部短暂显示"无网络连接"；多场景中部分失效→仅失效槽位灰色，其余正常。

环境摘要卡组件（FR-2203）

组件目标：桌面一眼掌握室内/室外环境关键指标，数据新鲜度透明。

组件规格：

尺寸	布局	内容
小(2x2)	单指标：大字号数值+单位+图标(温度/AQI/湿度)	点击→深链M04-R01传感器详情或M10气象详情
中(4x2)	三指标横排+左侧天气图标(如有气象源)+右下角更新时间	点击任一指标→对应详情页

逻辑规则：

数据来源：共享存储 env/{sourceId}/data（字段：type/value/unit/icon/timestamp）；传感器TTL 5min，气象TTL 15min；多数据源时按W01配置顺序展示；
数值格式化：温度保留1位小数（24.5℃）；AQI整数+色标（优绿/良黄/污染红）；湿度整数+%；风速1位小数+单位；单位跟随M12用户设置（℃/℉、km/h/mph）；
新鲜度指示：更新时间≤TTL→正常色；>TTL→数值灰色+"…"后缀；>30min→隐藏数值仅显示图标+"--"；
天气图标：气象源存在时显示动态天气图标（晴/雨/云等SVG）；纯传感器模式显示房型图标；
深链：点击指标区域→ehome://sensor/{sourceId}或ehome://weather→M04-R01/M10-W06；
埋点：各指标曝光/点击率、数据陈旧态占比、气象vs传感器使用比例、单位制分布。

异常与边界：传感器离线→数值显示"--"+灰色图标；气象服务不可用（M10降级）→天气图标位置显示"气象暂不可用"；所有数据源失效→组件渲染"暂无环境数据"+[添加]深链W01；单位切换（M12）→共享存储更新→组件下次刷新自动转换。

4. 数据同步与状态一致性（FR-2205）

4.1 共享存储Schema

Key模式	数据类型	TTL	写入方	读取方
session/auth	JSON`{userId, familyId, expiresAt}`	Token有效期	主APP登录/刷新	组件(判断登录态)
widget/config	JSON`{components[]}`	永久	W01保存	组件(渲染结构)
device/`{id}`/state	JSON`{name,icon,status,brightness,position,online,lastUpdate}`	30s	MQTT桥接/主APP	设备控制卡
scene/`{id}`/meta	JSON`{name,icon,color,lastExecuted}`	60s	MQTT桥接/主APP	场景执行卡
env/`{id}`/data	JSON`{type,value,unit,icon,timestamp}`	5min/15min	MQTT桥接/主APP	环境摘要卡
widget/privacy	JSON`{lockScreenBlur, sensitiveDeviceIds[]}`	永久	W01设置	组件(隐私过滤)
sync/meta	JSON`{lastFullSync, mqttConnected}`	永久	主APP	组件(同步状态)

4.2 同步机制

触发源	机制	节流	适用场景
MQTT消息到达	主APP解析→写入共享存储→触发组件刷新	同Key 1s合并	实时状态变更
主APP前台	全量拉取设备/场景/环境→覆盖写入→触发刷新	进入前台首次	长时间后台后恢复
iOS Background Fetch	系统调度→主APP后台拉取增量→写入	系统决定(≈15min)	iOS后台保活
Android WorkManager	周期任务(15min)→拉取增量→写入	15min最小间隔	Android后台保活
W01保存配置	写入widget/config→触发所有组件重载	无	配置变更
用户手动刷新	W01下拉刷新→全量拉取→写入	10s防抖	用户主动

4.3 一致性保障

乐观更新回滚：组件执行动作后启动5s定时器，超时未收到MQTT确认→回滚本地状态+错误提示；MQTT确认到达→取消定时器；
冲突解决：共享存储写入采用Last-Write-Wins+版本号（version字段），高版本覆盖低版本；MQTT消息携带服务端时间戳作为版本；
登录态校验：组件每次渲染前检查session/auth.expiresAt，过期→渲染未登录引导态；主APP Token刷新后同步更新共享存储；
数据完整性：共享存储写入事务化（iOS NSUserDefaults synchronize/Android DataStore atomic），避免半写状态；读取时JSON解析失败→降级为引导态+日志上报；
隐私过滤：组件渲染前读取widget/privacy，lockScreenBlur=true且设备在sensitiveDeviceIds中→锁屏模式下模糊处理；解锁后正常显示。

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

双主题：跟随系统浅色/深色模式；iOS使用@Environment(.colorScheme)，Android使用Configuration.uiMode；颜色语义化（success/warning/error/surface）；深色模式背景不使用纯黑（#121212起）减少OLED烧屏。
7语种与RTL：组件文案走M12 ARB资源管线；德语/俄语长文本截断策略（名称≤12字符省略，指标单位缩写）；RTL布局镜像（图标/文字/滑块方向）；阿拉伯语数字使用Eastern Arabic numerals；日期时间格式跟随locale。
iOS平台适配：WidgetKit Family(.systemSmall/.systemMedium/.systemLarge)；iOS 17+ Interactive Widgets使用Button/Toggle/Slider(intent:)；iOS 16降级为widgetURL深链；StandBy模式(.accessoryRectangular/.accessoryCircular)适配，敏感信息默认隐藏；Dynamic Island(.compactLeading/.compactTrailing/.expanded) P2预留。
Android平台适配：AppWidget minWidth/minHeight遵循4x4网格；Glance（Android 12+）优先，RemoteViews兼容层（8-11）；Material You动态取色（dynamicColors）；Always-On Display低功耗模式（仅显示单色图标+关键数值）；圆角遵循系统radius。
动效规范：iOS组件内动画仅限Interactive Widgets反馈（涟漪/✓✗切换），禁止持续动画（耗电）；Android Glance支持有限动画（AnimatedVisibility）；加载态使用静态占位符而非旋转loading（省电）；所有动效受系统"减弱动态效果"设置约束。
无障碍：iOS VoiceOver标签完整（"客厅灯，已打开，双击切换"）；Android TalkBack contentDescription；触控目标≥44pt/48dp；颜色不作为唯一信息载体（状态配图标+文字）；字体缩放支持（iOS Dynamic Type/Android sp）。
隐私视觉：锁屏模糊使用高斯模糊(radius=10)+遮罩；解锁过渡动画200ms淡入；敏感设备图标加锁标识；模糊态仍可识别组件类型（不完全遮挡）。

6. 客户端技术要求

6.1 Flutter侧（W01配置页）

状态管理：Riverpod；WidgetConfigProvider（云端+本地双源合并）；DeviceListProvider/SceneListProvider/EnvSourceProvider（缓存TTL 1min）；PreviewProvider（模拟组件渲染数据）。
共享存储桥接：MethodChannel('com.ehome.widgets')；方法：saveConfig/readConfig/writeDeviceState/writeSceneMeta/writeEnvData/readSession/setPrivacy；原生侧实现App Group(iOS)/SharedPrefs(Android)读写。
预览渲染：CustomPainter/Self-drawn Widget模拟原生组件样式；数据快照取自真实Provider；预览不触发真实动作；尺寸按比例缩放适配屏幕。
深链注册：ehome://widgets（W01）、ehome://device/{id}（设备详情）、ehome://scene/{id}（场景详情）、ehome://sensor/{id}（传感器详情）、ehome://weather（气象详情）；系统组件点击回调解析scheme路由。
后台刷新引导：检测iOS Background Refresh Status/Android Battery Optimization白名单；未开启时显示引导卡片+深链系统设置；检测逻辑封装为BackgroundRefreshChecker。
埋点：WidgetAnalytics封装，事件widget_*；配置保存/组件添加/排序调整/预览查看/后台刷新引导点击；统一上报通道。

WidgetKit：TimelineProvider实现getTimeline/getSnapshot/placeholder；Entry包含date/relevanceScore/data；Timeline策略.atEnd+after(30s)混合；
Interactive Widgets（iOS 17+）：AppIntent定义ControlDeviceIntent/RunSceneIntent；perform()内调用主APP共享框架执行动作；返回结果更新视图；
共享存储：App Group(suiteName: "group.com.ehome.app")；UserDefaults(suiteName:)读写；JSON Codable序列化；写入synchronize()确保落盘；
隐私：WidgetConfiguration.supportsFamilies包含.accessoryRectangular/.accessoryCircular（StandBy）；isLocked属性判断锁屏态；敏感内容条件渲染；
刷新触发：NotificationCenter监听"kWidgetRefreshNotification"（主APP发送）→WidgetCenter.reloadAllTimelines()；节流DispatchQueue.debounce(1s)；
包体优化：Widget Extension Target仅链接必要框架；资源Assets.xcassets精简（仅组件图标）；代码复用通过Shared Framework实现。

6.3 Android原生侧（AppWidget）

Glance（Android 12+）：GlanceAppWidget+GlanceAppWidgetReceiver；Composable DSL构建UI；ActionCallback处理点击/滑动；StateDefinition<Datastore<State>>持久化状态；
RemoteViews兼容（8-11）：AppWidgetProvider+RemoteViews布局XML；PendingIntent绑定点击事件；updateAppWidget手动刷新；Glance与RemoteViews双实现通过SDK版本分支；
共享存储：Context.MODE_PRIVATE SharedPreferences/DataStore；ContentProvider跨进程读取（可选）；JSON序列化kotlinx.serialization；
后台同步：WorkManager PeriodicWorkRequest(15min)；Constraints(NetworkType.CONNECTED)；doWork()内HTTP拉取增量→写入SharedPrefs→触发AppWidgetManager.notifyAppWidgetViewDataChanged()；
Always-On Display：onAppWidgetOptionsChanged检测EXTRA_APPWIDGET_OPTIONS；低功耗模式仅渲染单色Bitmap+关键数值；
动态取色：DynamicColors.applyToActivitiesIfAvailable()；GlanceTheme.colorScheme自动适配Material You。

7. 云端需求

7.1 接口清单

接口	方法	说明
/user/widget-configs	GET/PUT	组件配置云端同步（换机恢复）
/devices/states/batch	POST	批量获取设备状态（主APP前台/Background Fetch调用）
/scenes/metas/batch	POST	批量获取场景元数据
/env/data/batch	POST	批量获取环境数据（传感器+气象）
/widgets/sync-token	GET	获取增量同步游标（基于lastUpdate时间戳）
（MQTT下行）device/state	—	设备状态变更推送（主APP消费写共享存储）
（MQTT下行）scene/executed	—	场景执行结果推送
（MQTT下行）env/update	—	环境数据更新推送
（内部）配置清理Worker	—	用户注销/家庭解散时清理关联widget-configs

7.2 关键策略

增量同步：/widgets/sync-token返回服务端最新时间戳；batch接口支持since参数，仅返回变更后数据；减少后台拉取流量；
配置漫游：PUT /user/widget-configs全量覆盖；冲突以客户端lastModified为准（客户端优先）；换机首次GET拉取云端配置→合并本地；
数据裁剪：batch接口响应仅包含组件所需字段（非完整模型）；字段白名单由客户端声明；减少传输体积；
隐私合规：batch接口不返回敏感设备原始数据（摄像头流/门锁密码）；仅返回状态枚举/数值；GDPR/CCPA用户数据导出包含widget-configs；
性能SLA：batch接口P99≤500ms（50设备/20场景/10传感器）；MQTT推送端到端P90≤1s；共享存储读写P99≤10ms；
运营看板：组件添加率/活跃率/各类型使用分布、交互成功率/延迟P90、数据陈旧率、后台刷新开启率、锁屏隐私开关分布、7日组件留存。

8. 验收标准核对表

需求	验收标准	本设计落点
FR-2201	设备控制卡小/中尺寸渲染正确；开关/调光交互即时反馈；离线/删除降级；锁屏隐私模糊	第3章设备控制卡；共享存储schema
FR-2202	场景卡三尺寸布局正确；执行反馈动画；防误触；长按菜单；动态排序	第3章场景执行卡；交互状态机
FR-2203	环境卡数值格式化正确；新鲜度指示；多数据源融合；单位跟随设置	第3章环境摘要卡；数据同步TTL
FR-2204	W01三类型添加/编辑/排序/删除闭环；预览实时；失效检测；后台刷新引导	W01页面元素；配置存储规则
FR-2205	共享存储schema完整；同步触发源全覆盖；乐观更新回滚；登录态校验；隐私过滤	第4章；一致性保障
FR-2206	双主题/7语种/RTL/iOS StandBy/Android AOD/无障碍全达标	第5章；原生技术要求

QA测试要点（专项）：

组件渲染矩阵：iOS 16/17/18 × 小/中/大尺寸 × 浅/深色 × 7语种 × RTL 真机截图比对；Android 8/12/14 × Glance/RemoteViews × Material You/经典主题 × 7语种；
交互执行：设备开关乐观更新→MQTT确认→终态；失败回滚+振动；场景执行涟漪+✓✗反馈；滑块拖动实时预览+松手确认；5s超时回滚真机验证（弱网模拟）；
数据同步：MQTT推送→共享存储写入→组件刷新≤2s；主APP前台全量刷新；Background Fetch/WorkManager周期触发；TTL过期陈旧态渲染；登录态失效引导态；
配置闭环：W01添加/编辑/排序/删除→共享存储持久化→组件重载；失效设备/场景检测+替换；预览与真机组件视觉一致性；数量上限拦截；
隐私安全：锁屏模式下敏感设备模糊→解锁后淡入；StandBy/AOD模式隐私验证；共享存储加密验证（文件级/Keychain）；Token不落盘扫描；
降级与异常：未登录/无家庭/设备离线/数据过期/网络不可用/组件内容失效六态渲染正确；共享存储损坏→引导态自愈；JSON解析失败兜底；
性能压测：50设备状态MQTT高频推送（10条/s）→共享存储写入不丢消息；组件刷新节流1s生效；batch接口50设备P99≤500ms；W01预览渲染帧率≥30fps；
换机恢复：新设备登录→云端配置拉取→组件自动恢复；配置冲突时间戳仲裁；注销后云端配置清理；
无障碍：VoiceOver/TalkBack全流程；触控目标尺寸；字体缩放1.5x布局不破；颜色盲模式状态可辨识；
厂商兼容：小米/华为/OV/三星后台限制下WorkManager存活率；电池优化白名单引导有效性；Always-On Display功耗实测（≤1%/h）。

9. 依赖与风险

项	说明	责任/时点
M04/M08/M10 数据稳定性	组件消费方能力必须稳定；设备状态/场景执行/环境数据API契约冻结	M2 末冻结；M3 联调
App Group/SharedPrefs基建	iOS App Group entitlements配置；Android SharedPrefs跨进程方案；预埋M2	原生负责人 M2 完成
iOS Interactive Widgets	iOS 17+独占；低版本降级体验落差；审核指南合规	产品接受降级；UI M3适配
Android碎片化	Glance vs RemoteViews双实现成本；厂商后台杀进程影响同步	双实现排期+1周缓冲；白名单引导
共享存储大小限制	iOS App Group UserDefaults ≈1MB；Android SharedPrefs无硬限但建议<1MB	数据裁剪+分页；超限告警
MQTT推送可靠性	弱网/后台推送延迟→组件状态滞后；兜底轮询耗电	增量同步+智能轮询；电量监控
乐观更新信任度	回滚闪烁损害用户体验；网络差时频繁回滚	回滚动效弱化；网络质量预判
隐私合规审计	锁屏模糊有效性；共享存储加密强度；GDPR数据导出覆盖	安全团队 M3 审计
组件测试自动化	系统桌面环境无法常规UI自动化；矩阵机型成本高	快照测试+核心链路手工用例
后台刷新用户教育	用户未开启Background Fetch/电池优化白名单→同步失效	W01强引导+首次使用弹窗
包体增长	Widget Extension+双端原生代码+资源→安装包增大约5-8MB	资源精简；On-Demand评估
StandBy/AOD烧屏风险	常亮模式静态内容OLED烧屏	像素偏移+内容轮换+亮度限制

以上为 M13 桌面小组件（FR-2201~2206）完整详细需求设计：三类组件规格与交互、W01配置闭环、共享存储同步基建、乐观更新与降级策略、双平台原生适配、隐私与无障碍均已落点；与 M01/M02/M04/M08/M10/M12 文档格式及衔接协议一致（动作通道复用、数据源同源、国际化资源管线、隐私策略联动），可直接交付 UI 与双端原生开发。如确认无误，可按同样格式继续输出后续模块（如 M11 语音生态接入、运营后台各模块），或对已完成模块做交叉引用总表与集成测试计划。

M13 桌面小组件（对应需求：FR-2201~2206）​

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

1.1 模块范围​

1.2 设计原则​

1.3 用户与前置条件​

2. 页面结构与流程图​

2.1 页面导航结构​

2.2 核心状态机一：组件数据同步​

2.3 核心状态机二：组件事件执行（以设备开关为例）​

3. 页面/组件级详细需求​

W01 组件配置页（FR-2204）​

设备控制卡组件（FR-2201）​

场景一键执行卡组件（FR-2202）​

环境摘要卡组件（FR-2203）​

4. 数据同步与状态一致性（FR-2205）​

4.1 共享存储Schema​

4.2 同步机制​

4.3 一致性保障​

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

6. 客户端技术要求​

6.1 Flutter侧（W01配置页）​

6.2 iOS原生侧（Widget Extension）​

6.3 Android原生侧（AppWidget）​

7. 云端需求​

7.1 接口清单​

7.2 关键策略​

8. 验收标准核对表​

9. 依赖与风险​

M13 桌面小组件（对应需求：FR-2201~2206）

1. 模块概述与设计原则

1.1 模块范围

1.2 设计原则

1.3 用户与前置条件

2. 页面结构与流程图

2.1 页面导航结构

2.2 核心状态机一：组件数据同步

2.3 核心状态机二：组件事件执行（以设备开关为例）

3. 页面/组件级详细需求

W01 组件配置页（FR-2204）

设备控制卡组件（FR-2201）

场景一键执行卡组件（FR-2202）

环境摘要卡组件（FR-2203）

4. 数据同步与状态一致性（FR-2205）

4.1 共享存储Schema

4.2 同步机制

4.3 一致性保障

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

6. 客户端技术要求

6.1 Flutter侧（W01配置页）

6.2 iOS原生侧（Widget Extension）

6.3 Android原生侧（AppWidget）

7. 云端需求

7.1 接口清单

7.2 关键策略

8. 验收标准核对表

9. 依赖与风险