eHome App 端详细需求设计文档
M10 气象差异化（对应需求：FR-1901~1906）
| 项目 | 内容 |
|---|---|
| 所属项目 | eHome 智能家居硬件配套 APP + 云端后台定制开发项目 |
| 设计依据 | 《eHome智能家居项目需求文档（PRD V1.1）》气象服务与地域差异化章节、第8章、NFR-04（可用性99.9%）/NFR-06（合规，GDPR/CCPA/中国个保法）；《eHome项目页面功能工时费用明细表》M10模块 |
| 范围说明 | 本模块覆盖多源气象数据接入与融合、家庭位置绑定与隐私合规、7语种+单位制+时区地域适配、气象驱动场景触发器（联动M08）、极端天气告警（联动M06）、APP内气象卡片与设置；不包含设备本地传感器读数展示（属M04/M07）、地图选点UI（复用M02家庭地址组件）、第三方语音助手气象查询（属M11） |
| 编号衔接说明 | M08 场景编辑器"定时触发-日出日落偏移""传感器阈值-室外温湿度"依赖本模块气象数据；M06 告警规则"极端天气触发"消费本模块事件流；M02 家庭地址为本模块位置源；本文档 FR 编号按工时表 M10 行顺延为 FR-1901~1906 |
| 优先级 | P0（MVP必须；气象是"离家/回家/睡眠/节能/安防"五大核心场景的关键上下文，无气象则自动化退化为纯定时/纯传感，体验断层；同时是海外合规红线） |
| 里程碑 | M2 完整功能期开发（依赖 M01 账号、M02 家庭地址与时区、M04 设备状态、M06 告警、M08 场景引擎；气象供应商合同与API Key须M1到位；合规评审M1完成） |
| 文档用途 | 直接交付 UI 设计、Flutter 开发（APP端）、云端开发、气象数据工程师、法务合规、测试QA |
需求编号映射（以工时表 M10 功能项为准）：
| 需求编号 | 功能项 |
|---|---|
| FR-1901 | 气象数据源管理与融合（多供应商、主备切换、数据校验、缓存策略） |
| FR-1902 | 家庭位置绑定与隐私合规（位置授权、模糊化、数据最小化、撤回同意） |
| FR-1903 | 地域适配引擎（7语种、单位制℃/℉、风速km/h/mph、时区、日出日落算法） |
| FR-1904 | 气象驱动场景触发器（室外温湿度/降水/紫外线/AQI/日出日落作为M08触发源） |
| FR-1905 | 极端天气告警与推送（暴雨/高温/寒潮/AQI爆表→M06联动，分级免打扰） |
| FR-1906 | APP气象卡片与设置页（首页/房间详情嵌入、数据源选择、隐私开关、单位覆盖） |
1. 模块概述与设计原则
1.1 模块范围
| 序号 | 页面/功能项 | 需求编号 | 类型 | 优先级 |
|---|---|---|---|---|
| 1 | 气象数据融合服务（云端） | FR-1901 | 云端 | P0 |
| 2 | 位置绑定与合规流程（APP+云端） | FR-1902 | APP+云端+法务 | P0 |
| 3 | 地域适配引擎（云端+APP） | FR-1903 | 云端+APP | P0 |
| 4 | 气象触发器能力注册（供M08消费） | FR-1904 | 云端 | P0 |
| 5 | 极端天气告警事件流（供M06消费） | FR-1905 | 云端 | P0 |
| 6 | APP气象卡片+设置页 | FR-1906 | APP | P0 |
边界与衔接说明：
- 入口A：首页 Tab「首页」顶部气象卡片 → W06（气象卡片）；
- 入口B：M02-R01 房间详情页【室外环境】→ W06（该房间关联家庭气象）；
- 入口C：M08-S02 场景编辑器触发器选择 → 气象触发器类目（室外温湿度/降水/UV/AQI/日出日落）；
- 入口D：M06-A02 告警规则创建 → 极端天气事件选择；
- 入口E：「我的」→【气象与位置】→ W07（设置页）；
- 出口：气象数据写入设备影子（M02）供离线场景/网关本地规则消费；极端天气事件推 M06 告警引擎；气象触发器变更通知 M08 能力刷新；位置撤回→气象功能降级+M08相关场景停用提示。
1.2 设计原则
- 隐私优先与合规底线：位置数据仅用于气象查询，不做画像/广告/轨迹存储；默认模糊到3km网格；用户可随时撤回同意并立即删除位置缓存；欧盟/加州/中国三地合规要求取并集最严标准执行。
- 多源融合与韧性：至少2家气象供应商（主+备），实时健康检查+自动故障转移；数据交叉校验防异常值；缓存分层（分钟级实时/小时级预报/天级气候）保障断供时基础可用。
- 地域无感适配：单位制/语言/时区/日出日落算法全部跟随家庭设置（M02），非手机系统设置；跨国旅行不影响家庭自动化；新地区接入零APP发版（配置驱动）。
- 气象即能力：气象指标统一抽象为"虚拟传感器"注册进能力模型，M08 场景编辑器像选设备一样选气象触发器；新品类气象指标（如花粉/雷暴）接入仅需云端配置。
- 告警分级不打扰：极端天气告警按严重度分三级（提醒/警告/紧急），仅紧急级穿透免打扰；同一事件24h内不重复推送；告警文案本地化+行动建议（如"AQI>300，建议关闭新风并开启净化器"→可一键执行M08场景）。
- 数据可解释：气象卡片展示数据来源标识（供应商logo/名称）+更新时间；异常值（如温度突变20℃）标记"数据待确认"而非静默展示错误。
1.3 用户与前置条件
- 用户状态：必须已登录（M01）；未登录拦截，成功回跳来源页。
- 家庭前置：已创建家庭且设置地址（M02）；无地址→W06展示引导态"设置家庭地址以获取气象"+跳转M02地址编辑。
- 位置授权前置：首次使用气象功能触发位置权限申请（iOS精确/模糊可选，Android精细/粗略）；拒绝→降级模式（仅展示手动输入城市级气象，精度降低+提示）；撤回→立即停止定位+删除缓存+气象功能停用。
- 合规前置：首次启用气象前展示隐私摘要弹窗（数据用途/保留期/第三方供应商/撤回方式）+明确同意按钮；欧盟用户额外展示GDPR条款链接；不同意→降级模式。
- 网络前置：气象数据拉取需网络；离线时展示缓存数据+灰色标识"数据更新于X分钟前"；缓存过期（>2h）隐藏数值仅展示"--"。
- 供应商前置：云端至少1家主供应商API Key有效；全部失效→W06展示"气象服务暂时不可用"+告警运维。
2. 页面结构与流程图
2.1 页面导航结构
入口A：首页Tab[首页]顶部 ──► W06(气象卡片)
入口B：M02-R01[室外环境] ──► W06
入口C：M08-S02触发器选择 ──► 气象触发器类目
入口D：M06-A02告警规则 ──► 极端天气事件
入口E：我的→[气象与位置] ──► W07
W06 气象卡片（嵌入式组件，非独立页）
├─ 当前天气：图标+温度+体感+天气描述（多语言）
├─ 关键指标行：湿度/风速/AQI/UV（按家庭设置单位）
├─ 24h趋势折线（温度+降水概率）
├─ 数据来源标识+更新时间
├─ 点击展开 → 气象详情页（7日预报+逐小时+生活指数）
├─ 无位置态："设置家庭地址获取气象"+[去设置]→M02
├─ 降级态（位置拒绝/缓存过期）：灰色+"数据不可用"+[重试]/[手动选城市]
└─ 极端天气横幅（置顶，可关闭单次）：等级色+摘要+[查看详情]→M06告警详情
W07 气象与位置设置页
├─ 位置授权状态（已授权精确/模糊/未授权）+[前往系统设置]
├─ 隐私控制
│ ├─ 位置模糊化开关（默认开，3km网格）
│ ├─ 数据保留期选择（24h/7天/30天，默认24h）
│ ├─ 第三方供应商列表+隐私政策链接
│ └─ [撤回同意并删除数据]（红色危险操作，二次确认+密码验证）
├─ 单位制覆盖（跟随家庭/手动℃℉/风速km/h mph m/s/气压hPa inHg）
├─ 数据源偏好（自动推荐/手动指定主供应商，高级选项）
├─ 极端天气告警开关（总开关+分级开关：提醒/警告/紧急）
├─ 气象驱动场景提示："已有N个场景使用气象触发器"+[查看]→M08-S01预筛
└─ 关于气象服务（版本号/合规声明/反馈入口）
2.2 核心状态机一：气象数据获取与融合
[请求气象数据]（APP卡片加载 / M08触发器求值 / M06告警扫描 / 定时刷新）
│
├──(位置可用+合规同意有效)──► [主供应商请求]
│ │
│ ├──成功+数据校验通过──► [写入缓存+更新影子] ──► 返回融合结果
│ │
│ ├──失败(超时/错误码/限流)──► [健康检查标记] ──► [备供应商请求]
│ │ │
│ │ ├──成功──► [写入缓存+告警主供应商异常] ──► 返回
│ │ └──也失败──► [读取缓存]
│ │ │
│ │ ├──缓存有效(TTL内)──► 返回缓存+标记"数据可能过时"
│ │ └──缓存过期──► [返回空+降级标识] ──► APP展示"--"
│ │
│ └──数据校验失败(异常值/格式错)──► [丢弃+记录] ──► 走备供应商/缓存同上
│
├──(位置不可用/未授权)──► [降级模式]
│ ├──用户手动选城市──► 按城市中心点查询（精度低+明示）
│ └──未选城市──► 返回空+引导设置
│
└──(合规同意已撤回)──► [立即停止] ──► 删除所有位置缓存+影子气象字段置空+返回空
数据校验规则：温度[-90,60]℃、湿度[0,100]%、风速[0,120]m/s、AQI[0,500]、UV[0,15]；
超范围/NaN/负数(除温度)→标记异常；连续3次异常→供应商健康分扣减+告警。
缓存分层：实时观测TTL=10min / 逐小时预报TTL=1h / 日预报TTL=6h / 气候平均TTL=24h；
影子写入：每次成功获取后异步更新设备影子weather节点（供离线场景/网关消费）。
2.3 核心状态机二：位置合规生命周期
[首次启用气象] ──► [隐私摘要弹窗]
│
├──同意──► [请求系统位置权限]
│ │
│ ├──授权精确──► [精确位置模式]（实际仍模糊化处理后使用）
│ ├──授权模糊(iOS)/粗略(Android)──► [模糊位置模式]（原生模糊+服务端二次模糊）
│ └──拒绝──► [降级模式]（手动选城市）
│
├──不同意隐私条款──► [降级模式]（不请求位置权限）
│
└──[任意时刻]用户撤回同意(W07)
│
├──二次确认+密码验证──► [立即执行]
│ ├──停止所有定位请求
│ ├──删除APP本地位置缓存(Hive)
│ ├──调用云端 DELETE /weather/location（删除服务端缓存+影子weather字段）
│ ├──通知M08停用气象触发器场景（标记"位置数据不可用"）
│ └──W06切换降级态+Toast"已撤回位置授权，气象数据已删除"
│
└──取消──► 维持现状
合规审计：每次同意/撤回/位置访问写审计日志（userId/familyId/action/timestamp/IP哈希，不含坐标）；
审计日志保留2年；支持监管调阅接口（M12运营后台合规模块）。
3. 页面级详细需求
W06 气象卡片（FR-1906）
页面目标：首页/房间页轻量嵌入，一眼掌握室外环境，极端天气强提醒，降级优雅。
页面元素：
| 元素 | 规格与规则 |
|---|---|
| 当前天气区 | 天气图标（动态SVG，双主题适配）+温度（大字号，单位随家庭设置）+体感温度（小字）+天气描述（多语言，如"多云转晴"） |
| 关键指标行 | 4格：湿度%/风速(单位)/AQI(色标)/UV(等级文案)；点击单指标→气象详情页对应Tab |
| 24h趋势 | 迷你折线图（温度实线+降水概率虚线）；横轴时间标签按家庭时区；触摸显示具体时间点数值 |
| 数据来源 | 右下角小字："数据来源：OpenWeatherMap · 更新于 10:23"；多供应商时展示当前生效源 |
| 展开交互 | 点击卡片任意非按钮区域→气象详情页（全屏，7日预报+逐小时+生活指数+历史） |
| 极端天气横幅 | 置顶橙色/红色条（按等级）："⚠️ 暴雨黄色预警 · 未来2h降水量>30mm"+[详情]→M06告警详情+[关闭]（本次会话不再展示，下次刷新恢复） |
| 无位置态 | 插画+"设置家庭地址以获取精准气象"+[去设置]→M02地址编辑 |
| 降级态 | 整体灰度+遮罩"气象数据暂时不可用"+[重试]+[手动选择城市]（下拉搜索，仅城市级精度） |
| 缓存过期态 | 数值显示但灰色+"数据更新于2小时前"+下拉刷新手势 |
逻辑规则：
- 数据来源：GET /weather/current?familyId=（返回融合后当前天气+24h趋势+极端天气事件+数据源标识+更新时间）；进入首页/房间页拉取+下拉刷新+MQTT weather/update/
{familyId}增量推送（10min节流）； - 单位与语言：响应体已按家庭设置（M02）转换完毕，APP直接渲染；家庭设置变更→MQTT推送触发卡片刷新；
- 极端天气横幅：仅当存在未读且未关闭的活跃告警时展示；关闭状态存本地（sessionId级别，杀进程重置）；点击详情跳M06-A03告警详情（携带weatherAlertId）；
- 降级策略：位置拒绝/缓存过期/供应商全挂三态区分文案；手动选城市后记住选择（Hive，键=familyId+manualCity），优先级低于自动定位；
- 性能：卡片首屏渲染≤300ms（缓存优先）；折线图Canvas绘制，数据点≤48；图片资源CDN+WebP；
- 无障碍：天气图标含alt文本（"多云，26摄氏度"）；指标行读屏逐项播报；折线图提供数据表格替代视图（长按触发）；极端天气横幅读屏优先播报；
- 埋点：卡片曝光/点击展开率、极端天气横幅点击率、降级态重试/手动选城市转化、数据源分布（监控供应商健康）。
异常与边界：接口超时（>5s）→展示缓存+loading指示器；返回数据字段缺失→该指标显示"--"不崩溃；家庭地址变更→旧缓存立即失效+重新拉取；多家庭成员不同手机时区→按家庭时区统一展示（非手机时区）。
验收要点：当前天气+四指标+趋势+数据源完整渲染；单位/语言随家庭设置切换即时生效；极端天气横幅展示/关闭/深链正确；三态降级文案与交互闭环；无障碍读屏+表格替代；缓存过期灰色标识；性能达标。
W07 气象与位置设置页（FR-1902 + FR-1906）
页面目标：隐私控制权完全交还用户，合规透明，单位/告警个性化可调。
页面元素：
| 元素 | 规格与规则 |
|---|---|
| 位置授权状态 | 三态：已授权精确/已授权模糊/未授权；右侧[前往系统设置]深链（iOS/Android各自scheme） |
| 隐私控制组 | ①位置模糊化开关（默认开，说明"您的精确位置将被模糊至3km范围后再查询气象"）②数据保留期单选（24h/7天/30天，默认24h，说明"超期数据自动删除"）③第三方供应商列表（名称+隐私政策外链+当前是否启用）④[撤回同意并删除数据]红色按钮 |
| 撤回确认 | 点击→密码/生物识别验证→二次确认弹窗（列出将删除的数据项+影响说明"气象功能将停用，相关场景将暂停"）→确认后执行删除+跳转降级态 |
| 单位制覆盖 | 温度（跟随家庭/℃/℉）、风速（跟随家庭/km/h/mph/m/s/Bft）、气压（跟随家庭/hPa/inHg/mmHg）；修改即时生效+MQTT广播 |
| 数据源偏好 | 默认"自动推荐"；高级模式展开→手动指定主/备供应商（仅管理员）；说明"自动模式下系统将选择您所在地区最准确的供应商" |
| 极端天气告警 | 总开关+三个子开关（提醒/警告/紧急）；紧急级说明"将穿透免打扰模式"；[测试推送]按钮（发送模拟告警验证通道） |
| 气象场景提示 | "当前有N个场景使用气象触发器"+[查看]→M08-S01预筛气象相关场景；撤回位置后变为"气象触发器已停用，请编辑相关场景" |
| 关于 | 气象服务版本号+合规声明摘要+完整隐私政策链接+[反馈问题]→M10工单（预填weather类别） |
逻辑规则：
- 权限检测：进入页实时查询系统位置权限状态（permission_handler）；状态变更监听（appLifecycle resume重检）；
- 撤回原子性：本地删除+云端DELETE /weather/location+影子清空+M08场景停用通知 四步事务；任一步失败→回滚+Toast"撤回未完成，请重试"+记录异常；
- 单位变更广播：PUT /weather/settings → 成功后 MQTT weather/settings/
{familyId}推送 → W06/M08编辑器/S04日志等消费方刷新； - 数据源手动指定：仅当家庭管理员+高级模式开启；选择后立即触发一次数据拉取验证可用性；不可用时阻断保存+提示；
- 告警测试：POST /weather/alerts/test → M06发送模拟告警（标记test=true，不计入统计）；30s内未收到→提示"推送可能延迟，请检查通知权限"；
- 合规审计：所有隐私操作（同意/撤回/保留期变更/数据源切换）写审计日志；
- 埋点：隐私弹窗同意率、模糊化开关切换、保留期分布、撤回转化率、单位覆盖使用率、数据源手动指定率、告警开关分布、测试推送成功率。
异常与边界：系统设置深链失败（厂商ROM限制）→Toast"请手动前往设置-应用-eHome-权限"；撤回中网络失败→本地先删+云端加入重试队列（后台worker，最多5次，仍失败告警运维）；单位非法值→服务端校验拒绝+回滚；非管理员访问高级选项→隐藏而非置灰。
验收要点：权限三态检测准确+深链可达；隐私四项控制全功能；撤回四步原子性真机验证（本地+云端+影子+M08联动）；单位变更即时广播生效；数据源手动指定验证；告警测试推送到达；合规审计日志完整；非管理员权限隔离。
4. 气象触发器与极端天气告警（FR-1904 + FR-1905）
4.1 气象触发器能力注册（供M08消费）
气象指标作为"虚拟设备"注册进能力模型（M02/M09），deviceId=weather_{familyId}，能力列表：
| 能力标识 | 类型 | 触发器支持 | 说明 |
|---|---|---|---|
| outdoor_temp | number | ✓ | 室外温度（℃/℉，按家庭单位） |
| outdoor_humidity | number | ✓ | 室外相对湿度（%） |
| precipitation | enum | ✓ | none/light/moderate/heavy/storm |
| aqi | number | ✓ | 空气质量指数（0-500） |
| uv_index | number | ✓ | 紫外线指数（0-15） |
| wind_speed | number | ✓ | 风速（单位随家庭） |
| sunrise_sunset | enum | ✓ | sunrise/sunset/golden_hour/blue_hour |
| weather_alert | enum | ✓ | advisory/watch/warning/emergency |
M08-S02 场景编辑器触发器选择页新增「室外环境」分类，内含上述8项；参数配置复用M08动态表单（阈值/枚举/持续时间）；日出日落支持偏移分钟（-120~+120）。
能力刷新：气象供应商变更/家庭地址变更/单位变更 → 推送 device/capability/weather_{familyId} → M08编辑器刷新选项；触发器值变更经MQTT weather/trigger/{familyId} 实时推送 → M08规则引擎消费。
4.2 极端天气告警事件流（供M06消费）
告警分级与推送策略：
| 等级 | 触发条件示例 | 推送策略 | 免打扰 | 行动建议 |
|---|---|---|---|---|
| 提醒(advisory) | UV>8 / AQI>150 / 阵风>40km/h | APP内通知+角标 | 遵守免打扰 | "建议涂抹防晒"/"建议减少户外活动" |
| 警告(watch) | 暴雨蓝色/高温橙色/AQI>200 | APP+系统推送 | 遵守免打扰 | "建议关窗并开启净化器"+[一键执行场景] |
| 紧急(emergency) | 暴雨红色/台风/寒潮红色/AQI>300 | APP+系统+短信(可选) | 穿透免打扰 | "请立即关闭门窗"+[一键执行安防场景] |
事件流：云端气象服务解析供应商预警API → 标准化为 WeatherAlertEvent（level/type/description/start/end/actionSceneId）→ 写入Kafka topic weather.alerts → M06告警引擎消费 → 按分级策略分发；同一alertId 24h内去重；alert结束自动发送"解除"通知（仅warning/emergency级）。
行动建议场景联动：actionSceneId指向M08预置场景（如"暴雨关窗"）；用户点击[一键执行]→POST /scenes/{actionSceneId}/execute；场景不存在/停用→降级为纯文案。
5. 通用交互与视觉规范（UI设计输入，FR-1906）
- 双主题：天气图标SVG双套配色；温度/AQI色标深色模式调亮；折线图网格线深色模式降低对比度；极端天气横幅深色模式背景色饱和度降低避免刺眼。
- 组件清单：气象卡片（当前+指标+趋势+数据源）、极端天气横幅（三级色）、气象详情页（7日预报列表+逐小时横向滚动+生活指数网格）、设置项（权限状态/模糊化开关/保留期单选/供应商列表/单位选择器/告警分级开关）、降级态遮罩、隐私摘要弹窗、撤回确认弹窗、手动城市搜索下拉。
- 动效规范：天气图标微动画（云朵飘动/雨滴下落，2s循环，减弱动效降级为静态）；折线图触摸反馈点放大+数值气泡；极端天气横幅滑入300ms；单位切换数值渐变过渡200ms；全部提供"减弱动效"降级。
- 多语言：天气描述/生活指数/告警文案由CMS按7语种维护；温度单位符号不翻译；AQI等级文案本地化（中国"优/良/轻度污染" vs 美国"Good/Moderate/Unhealthy"）；德/法/俄预留1.4倍空间；日期格式跟随locale。
- 无障碍：天气图标alt文本含温度+描述；指标行读屏逐项；折线图长按弹出数据表格（可焦点遍历）；极端天气横幅读屏优先+振动反馈（紧急级）；设置页所有控件label完整；撤回按钮红色+文字双重标识。
- 响应式：平板宽屏下气象详情页左7日列表+右逐小时/指数分栏；设置页左导航+右内容；卡片宽度自适应容器。
- 品牌一致性：天气图标风格与APP图标系统统一；AQI色标沿用国家/地区标准色（中国绿黄橙红紫褐 / 美国绿黄橙红紫栗）；极端天气横幅色与M06告警等级色一致。
6. 客户端技术要求（Flutter）
- 状态管理：Riverpod；气象数据 WeatherProvider（Future+缓存TTL 10min+MQTT stream合并）；设置页 SettingsNotifier（乐观更新+MQTT广播监听）；位置权限 PermissionProvider（lifecycle resume重检）。
- MQTT：复用 M02/M04 连接层；订阅 weather/update/
{familyId}（数据刷新）、weather/alert/{familyId}（极端天气推送）、weather/settings/{familyId}（设置变更）、device/capability/weather_{familyId}（触发器能力刷新）；QoS1。 - 本地缓存：Hive 存储气象当前数据（TTL 10min）、24h趋势（TTL 1h）、手动城市选择、隐私同意状态与时间戳、告警关闭状态（sessionId）；账号注销联动清除；位置坐标永不落盘（仅存模糊化后网格ID）。
- 位置处理：使用 geolocator+geocoding；iOS请求whenInUse+precise/fuzzy用户选择；Android请求ACCESS_COARSE_LOCATION默认，用户主动开启精确才请求FINE；获取坐标后立即在服务端模糊化（客户端不存精确值）；撤回时clearCache+deleteLocation API。
- 折线图：CustomPainter实现，数据点≤48，触摸热区20px，气泡动画150ms；大数据量降采样（LTTB算法）；深色模式网格线alpha 0.1。
- 深链路由：ehome://weather（W06详情）、ehome://weather/settings（W07）、ehome://weather/alert/
{alertId}（M06告警详情）；M06推送携带深链。 - 合规实现：隐私摘要弹窗版本化（版本号存Hive，条款更新强制重弹）；撤回操作生物识别/密码验证（local_auth）；审计日志本地暂存+加密上传（失败重试队列）。
- 性能：卡片首屏≤300ms（缓存命中）；详情页7日预报列表虚拟化；折线图渲染≤16ms；MQTT消息节流（同familyId 10min内合并）。
- 安全：位置传输HTTPS+TLS1.3；API Key存Keystore/Keychain不落SharedPreferences；Sentry上报脱敏（不含坐标/家庭地址）；合规审计日志AES加密。
- 埋点：WeatherAnalytics封装，事件weather_*；核心漏斗（隐私弹窗→同意→卡片曝光→展开→场景创建）；质量指标（数据刷新成功率/延迟P90/降级率）；合规指标（撤回率/保留期分布）。
7. 云端需求（气象融合服务）
7.1 接口清单
| 接口 | 方法 | 说明 |
|---|---|---|
| /weather/current | GET | 当前天气+24h趋势+极端天气事件+数据源+更新时间（按家庭单位/语言/时区转换） |
| /weather/forecast | GET | 7日预报+逐小时（24h）+生活指数 |
| /weather/location | POST/DELETE | 绑定/撤回家庭位置（POST接收坐标立即模糊化存储；DELETE删除所有缓存+影子） |
| /weather/settings | GET/PUT | 家庭气象设置（单位/数据源偏好/告警开关） |
| /weather/alerts/test | POST | 发送模拟告警（test=true） |
| /weather/consent | POST/GET | 隐私同意记录（版本/时间/IP哈希）；GET查询当前同意状态 |
| /weather/audit | GET | 合规审计日志查询（监管调阅，M12运营后台） |
| （MQTT下行）weather/update | — | 气象数据刷新推送（10min节流） |
| （MQTT下行）weather/alert | — | 极端天气告警推送 |
| （MQTT下行）weather/settings | — | 设置变更广播 |
| （内部）供应商适配器 | — | OpenWeatherMap/Visual Crossing/和风天气等统一接口抽象；健康检查+自动故障转移 |
| （内部）数据融合引擎 | — | 多源交叉校验+异常值过滤+缓存分层写入+影子同步 |
| （内部）告警解析器 | — | 供应商预警API→标准化WeatherAlertEvent→Kafka weather.alerts |
| （内部）日出日落计算 | — | 基于家庭经纬度+天文算法（sunrise-sunset库）+夏令时处理 |
| （内部）合规Worker | — | 数据保留期到期自动删除；撤回请求异步执行+重试；审计日志归档 |
7.2 关键策略
- 多源融合：主备供应商配置化（YAML/etcd热加载）；健康检查每30s探活+错误率滑动窗口；主供应商错误率>10%持续2min→自动切备+告警；恢复后观察5min再切回；数据交叉校验：两源温差>5℃标记异常取主源+告警。
- 隐私与合规：位置接收后立即GeoHash模糊到3km网格（precision=5）存储；原始坐标内存处理不落盘；数据保留期到期自动清理（定时worker每小时扫描）；撤回请求同步删缓存+影子+审计；GDPR/CCPA/个保法取并集（最短保留期/最强删除权/最广知情权）；合规审计日志独立存储加密，保留2年。
- 地域适配：单位/语言/时区/日出日落全部服务端转换；新地区接入仅需配置供应商覆盖范围+本地化文案（CMS）；日出日落算法考虑大气折射+海拔修正；夏令时切换日正确处理（不跳变）。
- 触发器能力：气象虚拟设备能力模型JSON Schema与物理设备一致；能力变更推送device/capability；触发器值变更经Kafka→规则引擎→MQTT下发；延迟P90≤3s。
- 告警管道：供应商预警API轮询（5min）+WebSocket实时流（如有）双通道；告警去重（alertId+familyId 24h窗口）；分级推送策略配置化；行动建议场景ID有效性校验（不存在降级文案）。
- 性能SLA：/weather/current P99≤500ms；融合引擎吞吐≥1000 QPS；MQTT推送端到端P90≤2s；缓存命中率≥95%；供应商故障转移≤30s。
- 运营看板（回流M12）：供应商健康分/切换次数、数据异常率、缓存命中率、告警触发量/分级分布、隐私同意率/撤回率、单位覆盖分布、地域覆盖率；异常自动告警（供应商全挂/撤回率突增/告警风暴）。
8. 验收标准核对表
| 需求 | 验收标准 | 本设计落点 |
|---|---|---|
| FR-1901 | 多源主备切换≤30s；数据校验异常值过滤；缓存分层TTL正确；影子同步 | 融合引擎；缓存策略；影子写入 |
| FR-1902 | 隐私弹窗同意/撤回闭环；模糊化3km；保留期自动删除；撤回四步原子性；审计日志完整 | W07；/weather/location；合规Worker |
| FR-1903 | 7语种/单位/时区/日出日落服务端转换；新地区零发版；夏令时正确处理 | 地域适配引擎；CMS |
| FR-1904 | 8项气象触发器M08可选；能力刷新联动；触发延迟P90≤3s | 虚拟设备能力；Kafka→规则引擎 |
| FR-1905 | 三级告警分级推送；紧急穿透免打扰；24h去重；行动建议场景联动 | 告警解析器；M06联动 |
| FR-1906 | 卡片+设置页全功能；降级三态；无障碍；双主题；性能达标 | W06/W07；第5章 |
QA测试要点（专项）：
- 数据融合真机验证：主供应商正常→数据正确；注入主供应商超时/错误→30s内切备+告警+数据连续；两源数据冲突→取主源+异常标记；缓存TTL各层验证（10min/1h/6h/24h）；影子同步延迟≤5s；
- 隐私合规全流程：首次同意→位置获取→模糊化验证（抓包确认无精确坐标）；保留期24h→25h后数据自动删除；撤回四步原子性（本地+云端+影子+M08场景停用）真机验证；撤回中网络中断→重试队列恢复；审计日志完整性；欧盟/加州/中国三地合规条款覆盖；
- 地域适配矩阵：7语种天气描述/告警文案人工评审；℃/℉/km/h/mph/m/s/hPa/inHg全组合切换验证；跨时区家庭（北京/纽约/伦敦）日出日落时间正确；夏令时切换日（美东3月第二个周日）不跳变；新地区配置接入零代码验证；
- 气象触发器联动：M08编辑器选气象触发器→保存→触发条件满足→场景执行；单位变更后触发器阈值自动换算（26℃→78.8℉）；位置撤回→气象触发器场景标记停用+用户提示；能力刷新延迟≤3s；
- 极端天气告警：模拟三级告警→推送策略验证（提醒静默/警告普通/紧急穿透免打扰）；同一alertId 24h去重；告警解除通知；行动建议[一键执行]→M08场景触发；场景不存在降级文案；
- 降级与异常：位置拒绝→降级态+手动选城市；缓存过期→灰色标识；供应商全挂→"服务不可用"；数据字段缺失→"--"不崩溃；家庭地址变更→旧缓存失效+新数据拉取；
- 无障碍与主题：读屏播报天气/指标/告警；折线图数据表格替代；极端天气振动反馈；深色模式全组件对比度WCAG AA；减弱动效生效；
- 性能压测：/weather/current P99≤500ms（100并发）；卡片首屏≤300ms；MQTT推送端到端P90≤2s；缓存命中率≥95%；供应商故障转移≤30s（混沌工程注入）；
- 兼容性：iOS 13+/Android 7.0+真机；位置权限iOS精确/模糊、Android精细/粗略四组合；折叠屏/平板分栏；
- 安全渗透：API Key提取测试（反编译/内存dump）；位置数据传输抓包验证TLS+无明文坐标；撤回后数据残留扫描；Sentry上报脱敏验证。
9. 依赖与风险
| 项 | 说明 | 责任/时点 |
|---|---|---|
| 气象供应商合同与API Key | 至少2家签约（主+备）；SLA/配额/合规条款/费用模型；Key轮换预案 | 商务+法务 M1 到位；最大外部依赖 |
| M02 家庭地址与时区 | 位置源+单位/语言/时区基准；地址变更事件 | M1 已交付 |
| M08 场景引擎 | 气象触发器消费方；能力刷新联动 | M2 联调 |
| M06 告警引擎 | 极端天气事件消费方；分级推送策略 | M2 联调 |
| M09 OTA | 固件升级可能影响本地气象传感器读数（如有） | M2 联调 |
| M12 运营后台 | 供应商配置/CMS多语言/合规审计/运营看板 | M2 前交付最小可用 |
| 合规法律评审 | GDPR/CCPA/个保法条款落地；隐私摘要文案法务签字 | 法务 M1 评审完成 |
| 供应商API稳定性 | 第三方服务不可控；熔断/降级/缓存策略必须健壮 | 云端架构 M1 评审 |
| 位置精度与体验平衡 | 模糊化3km可能影响微气候准确性（如山谷/沿海）；用户感知"不准" | 产品决策模糊粒度；W07提供精确模式选项（合规告知风险） |
| 日出日落算法准确性 | 天文算法误差+大气折射模型；高纬度地区极昼极夜处理 | 算法选型 M1 验证；极端纬度兜底文案 |
| 告警误报/漏报风险 | 供应商预警延迟/误报→用户信任受损；漏报→安全风险 | 多源交叉验证；告警置信度评分；误报反馈通道 |
| 单位换算精度 | ℃↔℉/km/h↔mph浮点误差累积；触发器阈值换算后偏移 | 服务端统一换算+精度保留；前端仅展示 |
| 数据成本 | 高频拉取+多源冗余→API调用费超预算 | 缓存策略优化；用量监控+告警；商务谈判阶梯价 |
以上为 M10 气象差异化（FR-1901~1906）完整详细需求设计：多源融合与韧性、隐私合规全生命周期、7语种+单位+时区地域适配、气象触发器能力化、极端天气分级告警、APP卡片与设置页均已落点；与 M01/M02/M04/M06/M08/M09/M12 文档格式及衔接协议一致（能力模型同源、MQTT复用、影子同步、告警联动），可直接交付 UI 与开发。如确认无误，可按同样格式继续输出后续模块（如 M11 语音生态接入、M12 运营后台等）。