# Showen Flutter App PRD ## 1. 文档信息 - 产品名称：Showen Flutter App - 版本：v0.1 - 阶段：Phase 2 立项准备 - 负责人：刘建国（PM） - 目标平台：iOS / Android - 技术栈：Flutter 3.x + Dart 3.x ## 2. 产品背景 ShowenV2 当前已具备 HTTP API、WebSocket 推送与 BLE GATT 配网能力，能够支撑移动端从首次接入到日常远程控制的完整链路。现阶段需要为 Flutter 客户端形成统一产品定义与开发拆解，降低多端接入成本，并为 iOS/Android 双平台提供同一套体验与交付节奏。 Flutter App 定位为 Showen 设备的移动控制器，重点解决三类问题： 1. 首次接入困难：用户不知道设备 IP，必须通过 BLE 近场配网完成入网。 2. 日常控制分散：播放控制、状态机触发、场景切换、WiFi/视频/配置管理需要统一入口。 3. 状态反馈滞后：必须通过 WebSocket 获得设备状态、状态机、WiFi 状态的实时变化。 ## 3. 产品目标 ### 3.1 业务目标 - 建立移动端首次接入闭环：BLE 发现 -> WiFi 配网 -> 获取设备 IP -> HTTP/WebSocket 连接。 - 建立移动端高频控制闭环：首页快捷控制 + 播放控制 + 状态机触发。 - 建立移动端设备管理闭环：设备发现、连接、切换、网络设置、配置与视频管理。 ### 3.2 用户目标 - 3 分钟内完成新设备首次配网。 - 1 次点击完成播放/暂停等高频控制。 - 2 秒内看到设备状态变化反馈。 ### 3.3 成功指标 - 首次配网成功率 >= 85%。 - 核心控制接口成功率 >= 99%（局域网正常环境）。 - WebSocket 断线自动重连成功率 >= 95%。 - 首页高频操作平均响应感知时间 <= 800ms。 ## 4. 用户与场景 ### 4.1 目标用户 - 设备主人：日常使用 Showen 设备的普通用户。 - 调试人员：需要快速完成设备联网、视频切换、配置更新的部署人员。 - 高级用户：需要手动输入 IP、管理视频和配置的深度用户。 ### 4.2 核心使用场景 1. 新设备首次开机，用户通过 BLE 扫描到名为 `Showen` 的设备并完成 WiFi 配网。 2. 用户在局域网内通过首页直接查看设备状态并做播放控制。 3. 用户进入状态机页触发 `trigger` 或切换 `scene`，立即看到状态变化。 4. 用户进入网络设置页查看 WiFi 状态、扫描网络、切换网络，必要时使用 BLE 近场控制。 5. 用户进入设置页查看/更新配置，管理视频资源。 ## 5. 产品范围 ### 5.1 本期范围（MVP） - BLE 蓝牙配网 - 设备发现（BLE + 手动输入 IP） - HTTP 远程控制 - WebSocket 实时状态订阅 - 首页、播放控制页、状态机页、网络设置页、设置页 - WiFi 管理、视频管理、配置管理 - 多设备本地记录与快速切换 ### 5.2 暂不纳入本期 - 用户账号体系与云端同步 - 设备远程广域网访问 - 推送通知 - 视频预览/在线播放 - 固件升级 OTA - 平板/桌面专属布局优化 ## 6. 依赖与约束 ### 6.1 服务端依赖 - HTTP Base URL：`http://:8080/api` - WebSocket：`ws://:8080/ws` - 当前局域网环境默认无认证 - 依赖服务端已支持：播放、场景、触发器、配置、视频、WiFi、BLE 状态相关接口 ### 6.2 BLE GATT 协议 - Service UUID：`12345678-1234-5678-1234-56789abcdef0` - SSID 特征：`12345678-1234-5678-1234-56789abcdef1`（write） - Password 特征：`12345678-1234-5678-1234-56789abcdef2`（write） - Command 特征：`12345678-1234-5678-1234-56789abcdef3`（write） - Status 特征：`12345678-1234-5678-1234-56789abcdef4`（read/notify） Command 写入格式： - 配网：`connect:ssid:password` - 控制：`play` / `pause` / `next` / `prev` Status JSON： ```json { "ok": true, "action": "connect", "state": "connected", "error": null } ``` ## 7. 信息架构底部导航建议 5 个 Tab： 1. 首页 2. 播放控制 3. 状态机 4. 网络设置 5. 设置全局能力： - 顶部当前设备切换入口 - 全局连接状态提示 - 全局 Toast / 错误弹层 - 全局 WebSocket 重连状态条 ## 8. 功能需求 ### 8.1 设备发现与连接 #### 目标让用户能够发现附近设备、手动接入已有设备，并在 App 内维护最近连接设备列表。 #### 功能点 - BLE 扫描发现广播名为 `Showen` 的设备。 - 支持显示扫描中、扫描失败、未发现设备状态。 - 支持手动输入设备 IP 直接连接。 - 支持保存最近使用设备（名称、IP、上次连接时间、连接方式）。 - 支持切换当前控制设备。 #### 验收标准 - BLE 扫描 10 秒内可展示发现结果。 - 手动输入 IP 成功后可自动拉取 `/api/status` 验证设备可达。 - 最近设备列表支持至少 10 条本地缓存。 ### 8.2 BLE 蓝牙配网 #### 目标在设备未联网或未知 IP 时，让用户通过手机蓝牙完成 WiFi 入网。 #### 功能点 - 扫描并连接 BLE 设备。 - 展示手机权限状态（蓝牙、定位）。 - 输入或选择 WiFi SSID、输入密码。 - 按协议写入 SSID/Password/Command 特征值。 - 监听 Status 特征值读取或 notify，显示配网中/成功/失败。 - 配网成功后提示用户切换到 WiFi 控制模式，并记录返回状态。 #### 交互流程 1. 用户进入网络设置页 -> 点击 BLE 配网。 2. App 扫描附近 `Showen` 设备并展示列表。 3. 用户选择设备，输入 WiFi SSID/密码。 4. App 写入 GATT 特征并发送 `connect:ssid:password`。 5. App 监听 `Status` 返回： - 成功：提示联网成功，并引导发现/填写设备 IP。 - 失败：显示错误原因并支持重试。 #### 验收标准 - BLE 配网流程在弱网/失败情况下有明确错误提示。 - 配网状态页能展示至少 4 类状态：连接中、发送中、成功、失败。 - 重试不需要重新进入页面。 ### 8.3 首页 #### 目标作为高频控制入口，快速查看设备状态并执行最常用操作。 #### 功能点 - 展示设备在线状态、当前 IP、WiFi 状态、WebSocket 状态。 - 展示播放状态：运行中、暂停中、当前视频、当前索引。 - 提供快捷按钮：播放、暂停、上一首、下一首。 - 展示最近一次状态机状态。 - 展示关键告警：未连接、WiFi 异常、WebSocket 断开。 #### 相关接口 - `GET /api/status` - `GET /api/wifi/status` - WebSocket：`status_update`、`state_update`、`wifi_update` ### 8.4 播放控制页 #### 目标提供完整播放控制和播放列表跳转能力。 #### 功能点 - 大按钮控制：播放、暂停、上一个、下一个。 - 播放状态信息：当前视频、总数、当前索引。 - 播放列表展示与点击跳转。 - 支持 `goto(index)` 精准切换。 - 支持下拉刷新播放状态。 #### 相关接口 - `POST /api/play` - `POST /api/pause` - `POST /api/next` - `POST /api/previous` - `POST /api/goto/:index` - `GET /api/playlist` - `GET /api/status` ### 8.5 状态机页 #### 目标让用户能够感知当前状态并显式触发状态机行为。 #### 功能点 - 展示当前状态、最近状态变化时间。 - 展示可用 `trigger` 列表，支持无值与带值触发。 - 展示常用 `scene` 列表，支持快速切换。 - 显示触发结果反馈和状态更新记录。 #### 相关接口 - `POST /api/trigger/:name` - `POST /api/trigger/:name/:value` - `POST /api/scene/:name` - WebSocket：`state_update` ### 8.6 网络设置页 #### 目标统一管理 BLE 配网与 WiFi 能力，降低设备联网操作门槛。 #### 功能点 - BLE 配网入口。 - 显示当前 WiFi 连接状态、SSID、IP。 - 扫描可用 WiFi 列表。 - 选择 WiFi 并通过 HTTP 发起连接。 - 启动/关闭热点。 - 显示 BLE 运行状态。 - 提供 BLE 简单控制命令入口（如 play/pause/next/prev）用于近场调试。 #### 相关接口 - `GET /api/wifi/status` - `GET /api/wifi/scan` - `POST /api/wifi/connect` - `POST /api/wifi/ap/start` - `POST /api/wifi/ap/stop` - `GET /api/ble/status` - WebSocket：`wifi_update` ### 8.7 设置页 #### 目标承载低频但必要的管理能力。 #### 功能点 - 查看完整配置。 - 编辑并提交配置。 - 查看视频列表。 - 上传视频（若移动端能力与后端联调稳定则纳入；否则本期先只读 + 删除）。 - 删除视频。 - 展示设备信息、App 版本、接口地址。 - 关于页与排障说明。 #### 相关接口 - `GET /api/config` - `POST /api/config` - `GET /api/videos` - `POST /api/videos/upload` - `DELETE /api/videos/:filename` ## 9. 实时状态设计 ### 9.1 WebSocket 事件 - `status_update`：播放状态更新 - `state_update`：状态机状态更新 - `wifi_update`：WiFi 状态更新 ### 9.2 客户端处理要求 - 建立单例 WebSocket 连接。 - 支持自动重连（退避策略）。 - 断线期间显示弱提示，不阻塞已缓存页面操作。 - 收到推送后更新首页、播放控制页、状态机页、网络设置页的对应状态。 ## 10. 非功能需求 ### 10.1 性能 - 首页首屏可交互时间 <= 2s（已连接设备场景）。 - 单次控制请求超时默认 5s。 - BLE 扫描页进入后 1s 内显示扫描中状态。 ### 10.2 可用性 - 所有关键操作必须有加载态、成功态、失败态。 - 断网、设备离线、接口超时必须有用户可理解提示。 - 关键页面支持下拉刷新或重试。 ### 10.3 兼容性 - Android 10+ - iOS 15+ - 适配主流手机尺寸 ### 10.4 安全与隐私 - WiFi 密码仅在本地临时使用，不长期明文持久化。 - 本地仅缓存必要设备信息，不缓存敏感配置副本。 - 预留后续接入 Token/Auth 的网络层扩展点。 ## 11. 设计要求基于 `clients/docs/DESIGN.md`，Flutter App 延续以下方向： - 默认暗色科技风。 - 强调状态反馈与动效流畅。 - 移动优先、触控友好。 - 大按钮、清晰卡片分组、底部导航稳定。同时补充移动端实现约束： - 首页、播放控制页优先单手操作。 - 关键按钮点击区域 >= 48x48dp。 - 状态颜色必须与文案双重表达，避免只靠颜色区分。 ## 12. 埋点与日志 MVP 至少记录以下本地日志事件，用于调试和测试： - BLE 扫描开始/结束/失败 - BLE 连接成功/失败 - 配网命令发送结果 - HTTP 控制请求成功/失败 - WebSocket 连接/断开/重连 - 设备切换 ## 13. 风险与应对 ### 13.1 技术风险 1. BLE notify 行为可能依赖服务端实现完整性。 - 应对：客户端同时支持 read + notify 两种状态获取模式。 2. WebSocket 推送事件命名与文档存在潜在偏差。 - 应对：建立兼容解析层，并在联调阶段冻结事件模型。 3. `/api/playlist`、配置热重载等能力可能与服务端行为存在细微差异。 - 应对：MVP 先以“展示 + 控制成功反馈”为主，复杂行为以联调结果修正文档。 ### 13.2 产品风险 1. 首次配网流程过长导致流失。 - 应对：提供分步引导、权限解释、失败重试。 2. 设备 IP 获取链路不清晰。 - 应对：BLE 配网成功后明确提示“请在路由器管理页或设备屏幕查看 IP”，并支持手动输入。 ## 14. 验收标准 ### 14.1 功能验收 - 能发现并连接 BLE `Showen` 设备。 - 能完成 WiFi SSID/密码写入与 `connect` 命令发送。 - 能通过 HTTP 完成播放控制、状态机触发、场景切换、WiFi 管理、视频管理、配置管理。 - 能通过 BLE 扫描与手动 IP 两种方式建立设备连接。 - 能通过 WebSocket 实时接收并刷新 `status_update` / `state_update` / `wifi_update`。 ### 14.2 体验验收 - 五个核心页面链路完整，无死路由。 - 核心控制操作均有反馈。 - 网络异常和权限异常均有可理解提示。 ## 15. 里程碑建议 - M1：项目脚手架 + 基础架构 + 设备发现 - M2：BLE 配网 + HTTP 控制闭环 - M3：WebSocket 实时状态 + 五大页面完成 - M4：视频/配置管理 + 稳定性优化 + 测试发布 ## 16. 开发协作说明 - 产品文档：`clients/flutter/PRD.md` - 开发看板：`clients/flutter/TASKS.md` - 团队沟通记录：`.showen/TEAM_CHAT.md` 本 PRD 用于 Flutter App 立项、设计、研发与测试的统一输入，后续联调如发现 API 差异，以服务端实际行为校正文档并增量更新版本记录。