PRD: Flutter AIoT 用户端 App（海外兼容）与家庭设备体验

[ronger-x]

问题陈述

Mortise 当前已经具备较完整的 AIoT 后台、设备侧接入、OTA、会员登录与 Web 管理能力，但还缺少一套面向普通用户的移动端产品闭环。对于面向国内与海外市场的消费级 IoT 场景，仅有后台与站点端并不能支撑用户从“拿到设备”到“完成配网、绑定、控制、接收告警、执行 OTA”的完整体验。

当前缺口主要体现在四个方面：

1. 缺少独立移动端底座。现有前端是 Nuxt Web 应用，并不适合作为 BLE 配网、移动端实时连接与原生体验的承载层。
2. 缺少家庭协作模型。现有 member 模块没有“家庭”实体、成员邀请/移除、当前家庭上下文等消费级 IoT 常见能力。
3. 缺少 member 视角的用户端设备 API。现有 mortise-aiot 主要提供设备侧与后台管理接口，普通用户无法安全地查看自己的家庭设备、控制设备、查看告警与绑定结果。
4. 缺少 App 视角的实时连接与 OTA 能力。当前 MQTT 网关偏设备侧，OTA 也偏设备侧与后台侧，无法直接满足移动 App 在家庭上下文中的实时状态与升级体验。

解决方案

建立独立仓库 rymcu/aiot-app，使用 Flutter 实现面向国内与海外市场的 AIoT 用户端 App；同时在 Mortise 后端补齐消费级 IoT 所需的家庭模型、用户端设备 API、App 侧 MQTT over WebSocket 接入，以及用户端 OTA 查询/触发能力。

方案的核心原则：

• 移动端独立仓库：不把移动端建立在 Nuxt 或 uni-app 之上，直接以 Flutter 承载 iOS/Android 双端。
• 家庭优先：设备归属绑定到家庭，而不是绑定到个人账号，支持管理员邀请/移除成员，成员默认共享设备查看与控制权限。
• 成员令牌访问：所有用户端设备能力均使用 member token 访问，不暴露设备长期密钥、设备 JWT 或后台管理员权限。
• 实时体验分层：控制操作继续走 REST API，实时状态、告警、OTA 进度通过 App 侧 MQTT over WebSocket 回推。
• 全球化兼容：MVP 默认支持中文与英文，登录路径同时覆盖国内手机号验证码与海外 Email + 密码。

子仓库 Issue

仓库	Issue	说明
rymcu/mortise	#8	家庭模型与成员协作
rymcu/mortise-aiot	rymcu/mortise-aiot#16	用户端设备 API 与家庭设备控制
rymcu/mortise-aiot-gateway-mqtt	rymcu/mortise-aiot-gateway-mqtt#1	App 侧 MQTT over WebSocket 接入与成员鉴权
rymcu/mortise-ota	rymcu/mortise-ota#1	用户端 OTA 查询、触发与进度接口
rymcu/aiot-app	rymcu/aiot-app#1	Flutter AIoT 用户端 App MVP

用户故事

1. 作为首次购入设备的普通用户，我希望打开 App 后可以用手机号验证码或 Email 登录，以便快速进入设备使用流程。
2. 作为家庭管理员，我希望创建家庭并邀请家人加入，以便多人共同管理同一批设备。
3. 作为家庭成员，我希望在加入家庭后立即看到该家庭的设备列表与状态，以便快速上手。
4. 作为用户，我希望通过 BLE 完成设备配网，并在配网成功后自动绑定到当前家庭，以便减少手工录入和后台操作。
5. 作为用户，我希望查看设备在线状态、关键遥测数据和当前开关/模式，以便知道设备是否正常工作。
6. 作为用户，我希望在 App 中直接控制设备，并立刻看到状态回流，以便确认操作已经生效。
7. 作为用户，我希望收到设备告警和异常提醒，以便尽快处理异常。
8. 作为用户，我希望查看固件版本、升级说明，并在允许时发起 OTA，以便保持设备安全和功能最新。
9. 作为海外用户，我希望使用英文界面、Email 登录和符合当地习惯的文案/时间格式，以便无障碍使用产品。
10. 作为平台团队，我希望移动端能力与现有 AIoT、OTA、会员体系保持边界清晰，以便后续持续演进而不引入同层硬依赖。

实现决策

• 仓库与模块划分

  • 新建独立仓库 rymcu/aiot-app 承载 Flutter App。
  • mortise-member 扩展家庭模型、成员关系与邀请流程，不新建独立 household 模块。
  • mortise-aiot 新增 member 视角的用户端设备 API、设备认领/自动绑定闭环、成员侧告警视图。
  • mortise-aiot-gateway-mqtt 新增 App 侧 MQTT over WebSocket 接入、短期会话与 ACL 设计。
  • mortise-ota 新增 member 视角的 OTA 查询、触发、进度与历史接口。

• 架构边界

  • 家庭属于 member 领域，AIoT/OTA/MQTT 网关通过稳定接口或 SPI 获取家庭归属与权限判定能力，不新增同层强耦合。
  • 设备控制语义继续复用设备影子与命令模型，不为 App 再造一套控制体系。
  • OTA 仍归属 OTA 领域；App 只获得“是否可升、为什么可升、如何触发、进度如何”的成员视图。

• 实时链路

  • App 不直接复用设备 MQTT 凭证。
  • App 使用 member token 交换短期 MQTT 会话信息，通过 WSS 订阅家庭设备状态、告警、OTA 进度。
  • 控制指令继续走 REST，实时结果通过 MQTT 回推，降低越权风险。

• BLE 配网与自动绑定

  • 配网流程由 App、设备、云端协作完成：App 建立配网会话，设备联网后完成云端注册/激活/认领，后端自动把设备绑定到当前家庭。
  • App 不持有设备长期密钥，只使用短期 claim/session 信息参与配网闭环。

• 安全策略

  • 所有用户侧接口必须以 member token 鉴权，并校验家庭归属。
  • 不向 App 返回设备 credentialKey、credentialSecret、设备 JWT、后台管理权限字段。
  • MQTT 会话为短期有效；成员被移除或切换家庭后，新会话权限立即收敛，旧会话尽快失效。

• 国际化策略

  • MVP 支持中文、英文。
  • 登录流程同时支持国内手机号验证码与海外 Email + 密码。
  • 文案、时间、数字、时区展示按本地化体系输出，不把中国区假设写死在通用逻辑里。

测试决策

• mortise-member：测试家庭创建、邀请、接受/拒绝、移除、退出、管理员权限边界。
• mortise-aiot：测试家庭隔离、设备列表/详情、控制、告警、自动认领流程。
• mortise-aiot-gateway-mqtt：测试会话签发、WSS 连接、ACL 授权、越权订阅拒绝、家庭切换后的权限收敛。
• mortise-ota：测试成员侧可升级判断、主动触发升级、进度查询、异常路径。
• aiot-app：测试关键旅程（登录 → 家庭 → 配网 → 控制 → 告警 → OTA）、BLE 失败恢复、MQTT 重连、token 刷新、中英文本地化。
• 测试只验证外部行为和契约，不耦合具体实现细节。

垂直切片拆分

切片 1：登录与 App 壳

• 覆盖的用户故事：1、9
• 验收标准：用户可完成手机号验证码登录或 Email + 密码登录；App 有可用的导航壳、鉴权态恢复与中英文切换。
• 依赖关系：无，作为起始切片。

切片 2：家庭创建与成员协作

• 覆盖的用户故事：2、3、10
• 验收标准：管理员可创建家庭并邀请成员；成员可接受/拒绝邀请；加入家庭后可在 App 中切换当前家庭并看到家庭摘要。
• 依赖关系：依赖切片 1。

切片 3：BLE 配网与设备自动绑定

• 覆盖的用户故事：4、10
• 验收标准：用户可通过 BLE 发起配网；设备联网后自动认领并绑定到当前家庭；失败时可获得明确原因并重试。
• 依赖关系：依赖切片 1、2。

切片 4：设备列表、详情与控制

• 覆盖的用户故事：3、5、6、10
• 验收标准：用户可查看家庭设备列表、设备详情、关键遥测和影子状态；可发起控制并看到状态回流；不同家庭之间数据严格隔离。
• 依赖关系：依赖切片 2、3。

切片 5：实时告警与 MQTT 状态流

• 覆盖的用户故事：5、6、7
• 验收标准：App 可通过 WSS 订阅有权限的家庭设备状态、告警、控制结果；网络波动后可自动重连；越权订阅会被拒绝。
• 依赖关系：依赖切片 4。

切片 6：用户端 OTA 体验

• 覆盖的用户故事：8
• 验收标准：用户可查看固件版本与升级说明，可在满足条件时触发 OTA，并查看实时进度与最终结果。
• 依赖关系：依赖切片 4、5。

范围外

• 微信小程序或 H5 版用户端
• 离线推送（FCM、厂商推送、APNs）
• Apple / Google / 微信第三方登录
• 本地局域网直连控制、视频流、地图、地理围栏等高级能力
• 复杂家庭角色体系（除管理员与普通成员外的更多细粒度角色）
• 企业/组织模式设备分配
• 固件包上传、审核、后台运营能力改造

补充说明

• 本 PRD 默认优先保证“从开箱到日常使用”的闭环：登录、家庭、配网、绑定、查看状态、控制、告警、OTA。
• 为避免模块边界失真，所有跨模块协作优先通过现有 SPI、应用服务接口或聚合层装配完成，不用“直接加依赖”来换取短期速度。
• 新建仓库 rymcu/aiot-app 已创建，可直接承载 Flutter MVP 落地。