eHome App 端详细需求设计文档
M11 语音生态对接（对应需求：FR-1101~1106）
| 项目 | 内容 |
|---|---|
| 所属项目 | eHome 智能家居硬件配套 APP + 云端后台定制开发项目 |
| 设计依据 | 《eHome智能家居项目需求文档（PRD V1.1）》语音生态章节、第8章、NFR-01/02/03/06；《eHome项目页面功能工时费用明细表》M11模块 |
| 范围说明 | 本模块覆盖第三方语音平台（Amazon Alexa、Google Assistant/Google Home）的云云对接授权、设备能力映射与同步、解除授权与重授权、故障排查，以及 Siri 快捷指令（P1）；不包含设备控制逻辑本身（属 M04）、场景自动化（属 M06）、推送通道（属 M10） |
| 优先级 | Alexa / Google Home 对接为 P0（海外主销区核心卖点）；Siri 快捷指令、IFTTT 为 P1（本期预留入口与数据结构，不实现） |
| 里程碑 | M2 完整功能期开发（依赖 M01 账号体系、M02 家庭/设备数据、M04 设备能力模型；平台认证周期长，开发者账号与认证申请须 M0 启动） |
| 文档用途 | 直接交付 UI 设计、Flutter 开发（APP端）、云端开发、平台认证专员、测试QA |
需求编号映射（编号按 PRD 语音生态章节对齐，如与 PRD 出入以 PRD 为准）：
| 需求编号 | 功能项 |
|---|---|
| FR-1101 | 语音生态对接管理页（平台卡片、授权状态、地区可用性） |
| FR-1102 | 第三方平台账号授权绑定（OAuth 2.0 全流程、异常处理） |
| FR-1103 | 设备能力映射与同步（品类能力表、别名规范、同步状态与重试） |
| FR-1104 | 解除授权与重授权（token 过期、账号注销联动、影响告知） |
| FR-1105 | Siri 快捷指令（P1，App Intents 暴露设备控制） |
| FR-1106 | 语音对接故障排查与 FAQ（H5 帮助、工单联动） |
1. 模块概述与设计原则
1.1 模块范围
| 序号 | 页面/功能项 | 需求编号 | 类型 | 优先级 |
|---|---|---|---|---|
| 1 | 语音助手对接管理页（平台卡片列表+状态） | FR-1101 | APP | P0 |
| 2 | 平台授权绑定页（OAuth 应用内浏览器+回跳） | FR-1102 | APP+云端 | P0 |
| 3 | 绑定引导页（平台侧 App 启用 Skill/Action 分步指引） | FR-1102 | APP | P0 |
| 4 | 设备同步与能力映射页（同步清单、命名规范、重试） | FR-1103 | APP+云端 | P0 |
| 5 | 解除授权/重授权流程（确认弹窗、影响告知） | FR-1104 | APP+云端 | P0 |
| 6 | Siri 快捷指令配置页 | FR-1105 | APP | P1 |
| 7 | 故障排查与 FAQ 页 | FR-1106 | APP+H5 | P0 |
| 8 | 语音生态对接流程 UI 设计（双主题、7语种） | 第8章 | UI | P0 |
边界与衔接说明：
- 入口A：「我的」Tab（M04）→【语音助手】→ 本模块 Y01；
- 入口B：设备详情页（M04）→【更多设置】→「可用语音控制」提示条 → Y01（未绑定时引导绑定）；
- 出口：绑定成功后设备经云端映射同步至 Alexa/Google 平台，用户在对方 App/音箱直接语音控制，控制结果经云端回写设备影子（M02 设备影子同源），eHome APP 列表状态 ≤3s 同步（NFR-02）。
1.2 设计原则
- 云云对接（Cloud-to-Cloud）为一期唯一方案：不要求设备端集成 Alexa/Google SDK，不增加固件成本；通过 eHome 云端作为设备能力代理接入两平台。
- 能力映射一致性：语音平台展示的设备名称/房间/能力必须与 eHome APP 内 M02/M04 数据实时一致；用户在 APP 改名/换房间后自动触发增量同步。
- 授权安全红线（NFR-03）：OAuth 2.0 授权码模式；access token 加密存储（KMS），refresh token 轮换；语音平台仅获得设备控制所需最小 scope，不获取手机号/邮箱明文（返回平台专用脱敏账号标识）；解绑即时吊销全部 token。
- 地区可用性：按渠道包与账号地区（M01 注册信息）控制平台卡片展示——海外渠道展示 Alexa/Google；国内渠道一期不展示（天猫精灵/小爱同学列入 P2 评估），避免不可用入口造成客诉。
- 失败可归因：授权失败、同步失败均带错误码与可执行下一步；全量埋点上报支撑绑定成功率运营监控（目标绑定成功率 ≥90%）。
- 双主题 + 7语种：全部文案（含授权说明、同步状态、FAQ 摘要）走多语言资源文件；第三方平台商标文案遵守 Alexa/Google 品牌规范（认证要求）。
1.3 用户与前置条件
- 用户状态：必须已登录（M01）；未登录点击入口 → 跳转 M01 登录，成功后回跳 Y01。
- 设备前置：至少绑定 1 台在线设备方可完成有意义的首次同步（0 台设备允许绑定但同步页给出引导提示）。
- 平台账号前置：用户需持有 Amazon / Google 账号；无账号时授权页由平台侧引导注册（本模块不代办）。
- 受限账号（M01-P09 未补绑手机/邮箱）：允许语音绑定，但 Y01 顶部展示风险提示条（账号找回受限，建议补绑）。
2. 页面结构与流程图
2.1 页面导航结构
入口A：「我的」Tab → [语音助手] ──► Y01
入口B：设备详情页[可用语音控制]提示条 ──► Y01（未绑定时高亮引导卡片）
Y01 语音助手对接管理页（按地区/渠道过滤平台卡片）
├─ Amazon Alexa 卡片[未连接/已连接/授权过期]
│ ├─(未连接)[连接]──► Y02a 授权页(OAuth LWA)──(成功)──► Y02b 绑定引导页
│ │ └─► Y03 设备同步页
│ ├─(已连接)点击──► Y04 连接详情页（同步状态/重新同步/解除连接）
│ └─(授权过期)[重新授权]──► Y02a（refresh失败降级重走授权）
├─ Google Assistant 卡片（同上，Y02 走 Google OAuth + Home Action 启用引导）
├─ Siri 快捷指令卡片（P1：置灰+"即将上线"角标；P1上线后→ Y05）
├─ IFTTT 卡片（P1预留，同上）
└─ 底部[对接遇到问题？]──► Y06 故障排查与FAQ（H5）──► [联系客服]（M10工单）
Y03 设备同步页
├─ 同步进度（云端推送）──► 成功：设备清单+语音示例指令 ──► [完成]回Y01
└─ 部分/全部失败：失败设备列表+原因+ [重新同步]
2.2 核心状态机一：平台授权状态（账号×平台维度）
[未连接]
│
├──(用户点击连接，跳转OAuth授权)──► [授权中]
│ │
│ ├──(授权成功，云端换取并存储token)──► [已连接]
│ │ │
│ │ ├──(access token过期)──► [已连接·刷新中]（refresh token静默续期）
│ │ │ │
│ │ │ ├──(刷新成功)──► [已连接]
│ │ │ └──(refresh token失效/平台侧撤销)──► [授权过期]
│ │ │
│ │ ├──(用户在平台侧App解除Skill/Action)──► [授权过期]（平台撤销回调）
│ │ │
│ │ └──(用户在Y04主动解除连接)──► [已吊销] ──► [未连接]
│ │
│ └──(授权失败/用户取消/超时)──► [未连接]（错误码上报，Y02展示失败原因）
│
├──[授权过期]──(用户点击重新授权)──► [授权中]（重新OAuth）
│
└──(eHome账号注销·M01联动)──► [已吊销]（云端自动解除全部平台授权并通知平台）
2.3 核心状态机二：设备同步状态（家庭维度）
[待同步]
│
├──(授权成功后自动触发全量同步)──► [同步中]
│ │
│ ├──(全部设备映射成功)──► [已同步]
│ │ │
│ │ ├──(APP内设备改名/换房间/图标→M02事件)──► [增量同步中] ──► [已同步]
│ │ ├──(新增设备绑定→M03事件)──► [增量同步中] ──► [已同步]
│ │ ├──(设备移除/家庭删除→M02事件)──► [增量同步中(下线指令)] ──► [已同步]
│ │ └──(平台侧发起Discovery/SYNC请求)──► [按需响应]（云端实时生成能力快照）
│ │
│ └──(部分设备失败)──► [部分同步]
│ │
│ ├──(用户点击重新同步)──► [同步中]（仅重试失败项）
│ └──(连续3次失败)──► [同步异常] → Y06排查引导+工单入口
│
└──(解除授权)──► [已清除]（向平台发送全部设备下线/解绑事件）
3. 页面级详细需求
Y01 语音助手对接管理页（FR-1101）
页面目标：集中展示可对接语音平台、授权状态与快捷操作，是语音生态唯一管理入口。
页面元素：
| 元素 | 规格与规则 |
|---|---|
| 顶部导航 | 返回箭头 + 标题"语音助手"；右侧"?"图标 → Y06 |
| 顶部说明卡 | 一句话价值文案"连接 Alexa 或 Google Home，用语音控制你的 eHome 设备"+ 示意插画 |
| 受限账号提示条 | 仅 M01 受限账号展示（黄色横幅）："账号未绑定手机/邮箱，影响找回，建议先补绑"→ 跳 M01-P09 |
| 平台卡片：Amazon Alexa | 官方Logo+平台名+状态徽标（未连接=灰/已连接=绿/授权过期=橙）+右侧按钮（[连接]/[管理]/[重新授权]）；已连接卡片副标题显示"已同步 N 台设备 · 最近同步时间" |
| 平台卡片：Google Assistant | 同上（Google Home/Assistant 品牌规范Logo） |
| 平台卡片：Siri 快捷指令 | P0 阶段：置灰 + "即将上线"角标，点击 Toast"功能开发中，敬请期待"；P1 上线后 → Y05 |
| 平台卡片：IFTTT | 同 Siri（P1 预留） |
| 底部帮助链 | "对接遇到问题？查看常见问题" → Y06 |
逻辑规则：
- 卡片展示过滤：按渠道包配置 + 账号地区（云端下发 platform_availability 配置）决定 Alexa/Google 卡片是否展示；国内渠道包两张卡片均隐藏，页面仅显示"即将支持"占位；
- 状态数据：进入页面拉取 GET /voice/integrations（返回每平台：状态、同步设备数、最近同步时间、token 健康度）；下拉刷新；
- 授权过期状态由云端探测（refresh 失败/平台撤销回调）标记，APP 展示橙色徽标+推送提醒（复用 M10 推送，24h 最多 1 条防打扰）；
- 埋点：页面曝光、各卡片点击、连接发起来源（入口A/入口B）。
异常与边界：平台配置拉取失败 → 展示缓存配置；无缓存且无网络 → 骨架屏+重试；地区判定失败（账号无地区信息）→ 默认展示海外双平台。
验收要点：地区/渠道过滤正确；三态徽标与云端状态一致；受限账号提示条联动 M01；P1 卡片占位不可用态明确。
Y02 平台授权绑定页（FR-1102）
页面目标：以 OAuth 2.0 授权码模式完成 eHome 账号与平台账号绑定，流程内聚、失败可归因。
Y02a OAuth 授权页（应用内浏览器）
流程步骤：
- 用户在 Y01 点击[连接] → APP 弹出授权前说明弹窗（合规要求）：展示"即将跳转 Amazon/Google 登录授权；eHome 将获取：设备控制代理授权；不会获取：你的平台账号密码、邮箱手机号明文"；【同意并继续】/【取消】；
- 同意后打开应用内安全浏览器（iOS：ASWebAuthenticationSession；Android：Chrome Custom Tabs，禁止普通 WebView 以通过平台认证与防钓鱼）加载云端授权端点 /voice/oauth/
{platform}/authorize → 302 至平台官方 OAuth 页； - 用户在平台页完成登录与授权 → 平台回调云端 redirect_uri → 云端用授权码换取 token → 建立绑定记录（UID × platform × token 加密存储）→ 302 至 APP 深链 ehome://voice/callback?platform=alexa&result=success&bindId=xxx；
- APP 捕获深链 → 关闭浏览器 → 跳转 Y02b 绑定引导页；
- 失败回跳：result=fail&code=XXX → Y02 失败态（原因映射见下）。
授权失败原因映射表：
| 错误码 | 场景 | 用户文案（示例） | 动作 |
|---|---|---|---|
| USER_CANCEL | 用户在平台页取消 | 授权已取消 | [重新连接] |
| TIMEOUT | 授权流程超 5 分钟未完成 | 授权超时，请重试 | [重新连接] |
| TOKEN_EXCHANGE_FAIL | 云端换 token 失败（网络/平台异常） | 服务暂时不可用，请稍后重试 | [重试]+[联系客服] |
| ALREADY_BOUND_OTHER | 该平台账号已绑定其他 eHome 账号 | 此 Amazon/Google 账号已绑定其他 eHome 账号，请先在原账号解绑 | [查看帮助Y06] |
| ACCOUNT_FROZEN | eHome 账号被后台冻结（联动M01） | 账号状态异常，请联系客服 | [联系客服] |
| REGION_BLOCK | 账号地区与平台服务区不匹配 | 当前地区暂不支持该平台 | [查看支持地区Y06] |
| UNKNOWN | 兜底 | 授权失败，请重试 | [重试]+[联系客服] |
Y02b 绑定引导页（平台侧启用指引）
页面目标：授权成功≠可用——还需用户在平台 App 启用 eHome Skill/Action 并发现设备，本页以分步图文引导闭环。
页面元素：
- 成功横幅："eHome 账号已连接"（绿色对勾）；
- 分步引导卡片（按平台动态加载，云端可热更新图文）：
- Alexa：①打开 Alexa App ②更多 → 技能与游戏（Skills & Games）③搜索"eHome"④点击启用（Enable to Use）⑤自动发现设备或说"Alexa, discover devices"；
- Google：①打开 Google Home App ②点击 + → 添加设备 ③选择"Works with Google"④搜索"eHome"⑤登录即完成（Google 授权后即自动触发 SYNC，步骤更少）；
- 每步配图（平台UI截图按品牌规范处理）+【复制平台名称/搜索词】按钮；
- [我已完成，去同步设备] → Y03；[稍后再说] → 回 Y01（状态保持已连接，Y01 卡片展示"待完成平台侧启用"副标题提醒）；
- 底部说明：Skill/Action 未通过平台搜索找到时的排查提示（认证上线前灰度期通过测试账号白名单体验——见第8章风险）。
逻辑规则：
- Alexa 链路中云端在绑定成功后主动调用 Alexa Smart Home Skill 的事件网关推送 Discovery 响应准备；Google 链路依赖 Google 侧发起 SYNC 请求，云端按需响应；
- 用户点击[我已完成]时云端探测平台侧启用状态（Alexa：查询 Skill 启用事件；Google：是否收到过 SYNC 请求）——探测到已启用 → Y03；未探测到 → 提示"尚未检测到启用，请确认已在平台 App 完成步骤"并提供[仍要继续]与[重看引导]；
- 绑定成功事件埋点（平台、耗时、来源入口）。
验收要点：双平台 OAuth 全链路（含深链回跳）真机通过；7 个错误码注入测试；应用内浏览器合规（无普通 WebView）；已绑定其他账号冲突提示正确；引导页图文云端热更新生效。
Y03 设备同步与能力映射页（FR-1103）
页面目标：可视化同步进度与结果，教会用户"怎么说"，闭环首次体验。
页面元素：
| 元素 | 规格与规则 |
|---|---|
| 同步进度区 | 环形进度+文案"正在同步 N 台设备…"（云端经 MQTT/轮询推送进度）；超时 60s 未完成转"同步较慢"提示+[刷新] |
| 同步结果清单 | 每台设备：图标+APP内名称+所属房间+同步状态（✔已同步/✘失败+原因）；失败项支持单项[重试] |
| 语音示例指令卡 | 按已同步设备品类动态生成（多语言按平台语种规则）：如灯带→"Alexa, turn on 客厅灯带" / "Hey Google, set 卧室灯带 to 50%"；插座→开关指令；传感器→查询类指令说明 |
| 命名规范提示 | 说明卡："语音平台使用设备在 eHome 中的名称与房间；建议使用简短易读名称（如'客厅灯带'而非'LED Strip Light XG-03A'）"，附[去改名]入口 → M02-Q04 |
| 能力映射说明 | 折叠面板：展示该品类在语音平台支持的能力表（见下方映射规则） |
| [完成] | 主按钮 → 回 Y01（卡片刷新为"已同步 N 台设备"） |
设备能力映射规则（云端能力模型，APP 只读展示）：
| eHome 品类 | Alexa Capability | Google Trait | 语音可控能力 |
|---|---|---|---|
| 灯带/灯泡/吸顶灯 | BrightnessController、ColorController、ColorTemperatureController、PowerController | OnOff、Brightness、ColorSetting | 开关、亮度、颜色、色温 |
| 智能插座 | PowerController | OnOff | 开关 |
| 智能开关 | PowerController | OnOff | 开关 |
| 传感器（温湿度等） | TemperatureSensor、百分比状态只读上报 | 仅状态查询（Sensor trait） | 查询（"温度是多少"），不可控 |
| 场景（M06） | SceneController | Scene 指令 | 语音触发场景（P1，随M06交付后开放） |
逻辑规则：
- 同步触发时机：①首次绑定成功后自动全量同步 ②APP 内设备增删改名/换房间（M02/M03 事件总线）→ 云端自动增量同步（无需用户操作，延迟 ≤10s）③用户手动[重新同步]（Y03/Y04）④平台侧发起 Discovery/SYNC → 云端按需响应实时快照；
- 不同步项：离线 >7 天的设备仍同步（保留映射，语音控制时由平台报"设备不响应"）；被移除设备即时发送下线事件；OTA 升级中的设备保留映射但能力临时降级为只读（联动 M09 升级锁定）；
- 同步失败原因：设备影子数据异常（重试）、平台接口限流（退避重试）、能力不支持（标记并提示固件升级）；
- 名称冲突：同一平台账号下家庭内设备重名 → 语音平台侧自动追加房间前缀消歧，同步清单中展示消歧后名称并提示。
验收要点：首次全量/四种增量触发链路闭环；失败单项重试；能力映射表与实际控制结果一致（真音箱抽测）；改名后 10s 内平台侧生效；消歧规则正确。
Y04 连接详情页 / 解除授权与重授权（FR-1104）
入口：Y01 已连接卡片[管理]。
页面元素：
| 元素 | 规格与规则 |
|---|---|
| 连接信息区 | 平台Logo+已连接徽标；平台账号标识（脱敏，如 j***@gmail.com，来自平台返回的账号信息）；绑定时间；最近同步时间 |
| 同步状态区 | 已同步设备数 + [立即同步]按钮（手动全量同步 → Y03）；[查看设备清单] → 只读列表 |
| [重新授权] | 次按钮；token 健康度异常或授权过期态时升为主按钮；点击 → Y02a（重新 OAuth，绑定关系平滑替换，无需重新同步） |
| [解除连接] | 红色文字按钮（底部）→ 解除确认弹窗 |
解除连接确认弹窗（多语言完整列出后果）：
- 语音平台将立即失去对所有 eHome 设备的控制权限；
- 平台 App 中已同步的设备将从其设备列表移除；
- 云端将吊销全部授权 token，恢复需重新绑定；
- 不影响 eHome APP 内的设备与数据；
- 操作需身份验证（短信/邮箱验证码或密码，复用 M01 验证服务）→ 确认 → POST /voice/integrations/
{platform}/unbind → 云端吊销 token + 向平台发送全量设备下线事件 → Toast"已解除连接" → Y01 卡片回未连接态。
账号联动规则（云端自动执行，无需用户操作）：
- eHome 账号注销（M01）→ 自动解除全部平台绑定并通知平台；
- eHome 账号被后台冻结 → 云端暂停代理（平台控制请求返回错误），解冻恢复；授权状态标记"受限"，Y01 展示灰色徽标+提示联系客服；
- 用户在平台侧 App 卸载 Skill/断开 Action → 平台撤销回调 → 云端标记[授权过期] → APP 推送提醒重授权；
- 设备被移除/家庭被删除（M02）→ 对应下线事件即时同步平台，与解绑无关。
验收要点：解除连接五步后果告知+身份验证双闸门；吊销后平台侧控制立即失效（真音箱验证）；账号注销/冻结/平台侧撤销三条联动链路；重新授权平滑替换不丢同步。
Y05 Siri 快捷指令配置页（FR-1105，P1）
P0 阶段仅预留：Y01 卡片置灰占位（见 Y01）。P1 实现时需求如下：
- 基于 iOS App Intents 将已绑定设备的核心操作（开关/亮度/场景触发）暴露给快捷指令 App，支持 Siri 语音执行；
- 页面提供：设备-指令列表（每设备默认指令短语+自定义短语录入）、[添加到Siri]一键捐赠入口、短语冲突检测（与系统及其他App短语重复时提示）；
- 纯本地能力（不走云端授权），随 APP 内设备数据变化自动更新 Intent 捐赠列表；
- 多语言短语模板（7语种）。
Y06 故障排查与 FAQ 页（FR-1106）
页面形态：H5 帮助中心（复用 M10 H5 容器与工单能力），APP 内原生入口。
内容结构（云端可维护，多语言）：
- 绑定类 FAQ：找不到 eHome Skill/Action？授权页打不开？提示"已绑定其他账号"怎么办？
- 同步类 FAQ：设备在平台 App 不显示？名称/房间不同步？新设备没同步？
- 控制类 FAQ：语音说"设备不响应"排查（设备离线→M02 排查引导、Wi-Fi 异常、平台服务波动）；控制延迟说明；
- 解除类 FAQ：如何彻底断开？换手机/换平台账号怎么办？
- 每条 FAQ 底部[未解决？联系客服] → M10 工单（自动携带：平台、绑定状态、最近同步结果、错误码上下文）。
逻辑规则：从各失败场景跳转 Y06 时携带锚点参数直达对应 FAQ；工单上下文自动填充无需用户复述。
4. 通用交互与视觉规范（UI设计输入，序号8）
- 双主题：浅色/深色两套；平台卡片、三态徽标（绿/橙/灰）、成功横幅在深色下满足 WCAG AA；平台 Logo 使用官方素材并按其品牌规范（不可改色，深色主题用官方深色版素材）。
- 组件清单：平台卡片（Logo+状态徽标+动作按钮）、授权前说明弹窗、OAuth 浏览器容器加载态、绑定引导分步卡片（图文+复制按钮）、同步环形进度、同步结果清单（成功/失败/重试）、语音示例指令卡、能力映射折叠面板、解除连接警示弹窗（复用 M02 红色警示样式）、P1 占位卡片（置灰+即将上线角标）。
- 动效：同步进度环形动画；同步完成逐项打勾（300ms/项）；成功横幅渐入；徽标状态切换渐变。
- 多语言：授权说明、错误码文案、引导步骤、FAQ 摘要、语音示例指令全部资源文件；语音示例指令按平台语种习惯本地化（不是直译）；德/法预留 1.4 倍空间。
- 合规展示：授权前说明弹窗为强制展示不可跳过；第三方商标标注 "Amazon Alexa and all related logos are trademarks of Amazon.com, Inc." 等规范脚注（认证提交要求）。
- 无障碍：状态不只靠颜色（徽标含文字）；同步进度提供读屏播报；引导分步卡片焦点顺序正确。
5. 客户端技术要求（Flutter）
- OAuth 容器：iOS ASWebAuthenticationSession（EphemeralSession 防会话污染）、Android Chrome Custom Tabs；统一封装为 voice_oauth_plugin 接口：startAuthorize(platform) → 深链回调监听 → 结果解析；严禁普通 WebView 加载平台登录页（平台政策+钓鱼风险+认证驳回项）。
- 深链与回跳：注册 ehome://voice/callback scheme（iOS Universal Links / Android App Links 双通道，防被其他 App 劫持）；回跳参数校验（bindId 与本地发起会话匹配，防 CSRF：发起时本地生成 state 随机串，回跳核对）。
- 状态管理：集成状态（BLoC/Riverpod）与 Y01/Y03/Y04 共享；MQTT 订阅 voice-sync topic 接收增量同步结果推送 + HTTP 轮询兜底（复用 M02/M04 连接层）。
- P1 预留：iOS App Intents 扩展 target 工程结构预留；Android 侧 Google Assistant 免 App Intents（云云对接已覆盖）。
- 安全：不落盘存储任何平台 token（token 仅在云端）；深链参数不含敏感信息；H5 容器白名单校验（仅 eHome 域与平台官方域，NFR-03）。
- 埋点与监控：绑定漏斗（发起→授权成功→平台启用探测→首次同步成功）、各步骤耗时、错误码分布、FAQ 点击热区；崩溃与异常上报 Sentry（脱敏）。
- 兼容性：iOS 13+ / Android 7.0+（NFR-06）；Custom Tabs 不可用设备（无 Chrome）降级系统浏览器+回跳说明文案。
6. 云端需求（语音网关服务）
6.1 接口清单
| 接口 | 方法 | 说明 |
|---|---|---|
| /voice/platforms | GET | 平台可用性配置（按渠道/地区下发卡片列表、P1占位标记、品牌素材URL） |
| /voice/integrations | GET | 当前用户各平台绑定状态（状态/脱敏平台账号/绑定时间/同步设备数/最近同步/token健康度） |
/voice/oauth/{platform}/authorize | GET | OAuth 发起端点（生成 state+PKCE → 302 平台授权页） |
/voice/oauth/{platform}/callback | GET | 平台回调（授权码换 token → 加密存储 → 绑定记录 → 302 APP 深链，携带 result/code/bindId/state） |
/voice/integrations/{platform}/unbind | POST | 解除绑定（身份验证凭证校验 → 吊销 token → 向平台发送全量下线事件 → 更新状态） |
/voice/integrations/{platform}/reauth | POST | 重授权（新 token 平滑替换旧绑定，保留同步关系） |
/voice/integrations/{platform}/enable-status | GET | 平台侧启用探测（Alexa：Skill enablement 事件；Google：是否收到 SYNC） |
/voice/sync/{platform} | POST | 手动触发同步（全量/失败项重试；返回任务ID） |
/voice/sync/{platform}/status | GET | 同步进度与结果（设备级明细+失败原因码；MQTT 推送优先，长轮询兜底） |
| /voice/capability-map | GET | 品类能力映射表（供 Y03 展示与 FAQ 引用；云端配置可热更新） |
| （平台入站）Alexa Smart Home Skill 端点 | — | Discovery / PowerController / Brightness / Color 等 directive 处理 → 转设备影子与 MQTT 下行 → 事件回报 |
| （平台入站）Google Smart Home Action 端点 | — | SYNC / QUERY / EXECUTE / DISCONNECT 请求处理，HomeGraph API 主动上报状态变更 |
6.2 关键策略
- 双平台适配器架构：统一内部设备能力模型（与 M02 设备影子同源）→ 平台适配层（Alexa Capability 映射 / Google Trait 映射）双向转换；新平台（IFTTT/天猫精灵）以新增适配器扩展，不动核心模型。
- Token 安全：授权码模式+PKCE；access/refresh token KMS 加密存储；refresh 轮换（每次刷新旧 refresh token 作废）；平台侧撤销回调（Alexa Skill disable / Google DISCONNECT）即时清理绑定；token 不出云端。
- 控制链路与时延：平台 directive → 云端鉴权（校验绑定有效性/设备归属/冻结状态）→ MQTT 下行设备 → 设备执行回报 → 云端事件回平台；端到端目标 P90 ≤2s；同时回写设备影子，eHome APP 各端 ≤3s 刷新（NFR-02）——语音控制与 APP 控制状态永远一致。
- 同步一致性：订阅 M02/M03 设备事件总线（增删改名/换房间/解绑）→ 10s 内增量同步平台（Alexa 走 Change Report/事件，Google 走 HomeGraph requestSync）；对账任务每日全量比对一次，漂移自动修复并告警。
- 唯一绑定：一个平台账号同一时刻仅绑定一个 eHome 账号（冲突返回 ALREADY_BOUND_OTHER）；一个 eHome 账号每平台仅一条绑定记录。
- 限流与防护：平台入站接口防重放（时间戳+签名校验，按平台规范）；对单绑定同步请求限频（手动同步 60s 冷却）；异常控制量（单设备 1 分钟 >30 次指令）触发风控冻结并告警。
- 数据合规：向平台仅暴露设备名/房间名/品类/能力状态；不含用户 PII；控制日志留存 30 天（脱敏）供排障；GDPR 数据删除请求（M10 合规通道）覆盖语音网关日志。
- 运营监控看板：绑定漏斗成功率（目标 ≥90%）、同步成功率、控制指令成功率与时延（按平台/地区/型号聚合）；低于阈值告警工单。
7. 验收标准核对表
| 需求 | 验收标准 | 本设计落点 |
|---|---|---|
| FR-1101 | 平台卡片按地区/渠道过滤；三态状态与云端一致；受限账号提示联动 | Y01；platforms 配置接口；徽标状态机 2.2 |
| FR-1102 | OAuth 2.0 授权码+PKCE 全链路；应用内安全浏览器；深链回跳+state 防CSRF；7 错误码闭环；平台侧启用探测与图文引导 | Y02a/Y02b；authorize/callback 接口；探测接口 |
| FR-1103 | 能力映射表准确（灯/插座/开关/传感器四品类）；四种同步触发；增量 ≤10s；失败单项重试；重名消歧；语音示例指令本地化 | Y03；能力映射策略 6.2-1；同步状态机 2.3 |
| FR-1104 | 解除连接身份验证+后果告知；token 吊销即时生效（真音箱验证控制失效）；注销/冻结/平台侧撤销三联动；重授权平滑替换 | Y04；账号联动规则；unbind/reauth 接口 |
| FR-1105 | （P1）App Intents 设备指令捐赠与短语冲突检测 | Y05 预留；工程结构预留 |
| FR-1106 | FAQ 云端可维护多语言；锚点直达；工单自动携带上下文 | Y06；M10 联动 |
QA测试要点（专项）：
- OAuth 全矩阵：双平台 × 授权成功/用户取消/超时/换token失败/已绑他人/账号冻结/地区拦截，真机验证深链回跳与 state 校验（构造错误 state 必须被拒绝）；
- 安全专项：普通 WebView 拦截验证（抓包确认走 ASWebAuthenticationSession/Custom Tabs）；token 不出云端（APP 抓包无任何 token 字段）；深链劫持测试（伪造 bindId/state）；H5 容器白名单越域拦截；
- 同步一致性：APP 改名/换房间/移除设备/新增设备（M03 配网）四操作后 10s 内平台侧生效；每日对账任务漂移注入与自动修复；OTA 升级中能力降级只读；
- 控制链路：真音箱（Echo 3代以上 / Nest Mini）× 全品类 × 开关/亮度/颜色/色温/查询指令；端到端时延 P90 ≤2s 压测；语音控制后 APP 状态 ≤3s 同步（NFR-02 联动验证）；设备离线时语音控制的错误播报；
- 撤销联动：平台侧卸载 Skill / 断开 Action → APP 状态转"授权过期"+推送；eHome 注销 → 平台侧设备全部消失；冻结 → 控制被拒；
- 并发与限流：双手机同时发起同平台绑定；手动同步 60s 冷却；风控冻结阈值触发；
- 展示走查：双主题 × 7语种（重点：语音示例指令的本地化地道性抽查）；平台品牌规范合规检查（Logo 用法/商标脚注，认证前置自查）；
- 弱网与降级：Custom Tabs 缺失设备降级路径；同步推送丢失时轮询兜底；MQTT 断连期间平台控制仍可达（云端直连设备通道验证）。
8. 依赖与风险
| 项 | 说明 | 责任/时点 |
|---|---|---|
| 平台开发者账号 | Amazon Developer 账号 + Alexa Smart Home Skill 创建；Google Cloud 项目 + Smart Home Action 创建；账号主体用甲方公司名义注册（资产归属甲方） | 甲方配合提供资质，乙方 M0 启动申请 |
| 平台认证周期 | Alexa Skill 认证约 1 | M1 中期提交预审；认证与开发并行 |
| 灰度期体验 | 认证完成前 Skill/Action 不可公开搜索，仅测试账号白名单可用——影响内测节奏 | Y02b 文案区分灰度/正式态；白名单机制 |
| M02/M04 能力模型 | 设备影子、能力集定义（调光/调色范围）、事件总线为本模块数据源；能力映射表需与 M04 控制能力对齐 | M1 接口契约冻结；M2 联调 |
| M01 账号体系 | 身份验证凭证（解绑）、受限账号标记、注销联动 | M1 已交付 |
| M10 推送/H5/工单 | 授权过期推送、FAQ H5 容器、工单上下文携带 | M2 并行 |
| M09 OTA | 升级锁定期间能力降级只读的联动 | M2 联调 |
| 固件下行时延 | 语音控制端到端 ≤2s 依赖 MQTT 下行与设备响应性能，需固件侧压测配合 | M2 联合压测 |
| 平台政策变更 | Alexa/Google 接口与政策更新（如 OAuth 要求、Discovery 协议版本）——适配器架构隔离影响面，仍需预留年度维护 | 运营期跟踪 |
| 国内平台（P2） | 天猫精灵/小爱同学对接涉及国内云云协议与账号体系差异，一期不做 | P2 评估 |
以上为 M11 语音生态对接（FR-11011106）完整详细需求设计：Alexa/Google 双平台云云对接 OAuth 全链路、绑定引导与启用探测、四种触发的设备同步与能力映射、解除/撤销多路联动、真音箱专项验收与平台认证风险均已落点；与 M01/M02/M03/M04 文档格式及衔接协议一致（事件总线、身份验证复用、设备影子同源），可直接交付 UI 与开发。如确认无误，可按同样格式继续输出其余模块（如 M04 设备控制与状态展示、M05M10 等）。