pulsareon/ShowenV2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
bff9ec535dc02bae26d0a75eda7d8a9dd395c47a
ShowenV2/clients/flutter/PRD.md
showen bff9ec535d feat: Flutter 客户端 App + Web UI APK 下载入口 
- 新增 Flutter 跨平台客户端项目 (clients/flutter/)
  - 29 个 Dart 文件: 服务层/状态管理/5个页面/BLE配网
  - BLE 蓝牙配网: 扫描设备、写入WiFi凭据、配网状态监听
  - HTTP API 客户端: 覆盖全部端点 (播放/场景/WiFi/视频/配置/文件/插件)
  - WebSocket 实时通信: 事件流 + 自动重连
  - 暗色主题 Material 3 UI, 中文界面
  - Android 配置: minSdkVersion 21, BLE/网络权限
  - PRD 产品需求文档 + 开发任务看板
- Web UI 添加 APK 下载入口 (routes.rs)
  - 下载弹窗 + 二维码 + /download/{filename} 静态文件路由
- BLE 插件增加自动重连循环 (ble/mod.rs)
- BLE 默认设备名修正为 'Showen' (config.rs)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-14 02:09:52 +08:00

12 KiB
Raw Blame History

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://<device-ip>:8080/api
  • WebSocket：ws://<device-ip>: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：

{
  "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 差异，以服务端实际行为校正文档并增量更新版本记录。

Reference in New Issue View Git Blame Copy Permalink