# 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：

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