feat: 新增客户端应用目录结构

新增 clients/ 目录： - 外部控制应用的统一目录 - 支持多种客户端类型： - 移动端：iOS, Android, Flutter - 小程序：微信、支付宝、抖音 - Web：响应式 Web 应用、桌面应用 - 智能设备：手表、音箱、智能家居目录结构： - shared/ - 共享代码（API 客户端、数据模型） - web/ - Web 应用 - flutter/ - Flutter 跨平台应用 - ios/ - iOS 原生应用 - android/ - Android 原生应用 - wechat-miniapp/ - 微信小程序 - desktop/ - Electron 桌面应用 - docs/ - 客户端开发文档文档： - clients/README.md - 客户端总览和开发计划 - clients/docs/API.md - HTTP API 完整文档 - clients/docs/DESIGN.md - 设计规范和组件库更新 PLUGIN_DEPENDENCY.md： - 明确 WiFi + BLE 双架构模型 - BLE 既可配置 WiFi，也可独立提供网络功能 - 新增双架构设计原则
2026-03-12 06:46:05 +08:00
parent 7aa42cc9af
commit fa692cd873
5 changed files with 959 additions and 37 deletions
--- a/clients/README.md
+++ b/clients/README.md
@@ -0,0 +1,191 @@
+# ShowenV2 客户端应用
+
+本目录包含 ShowenV2 的外部控制应用，用户可以通过这些客户端远程控制 ShowenV2 设备。
+
+## 客户端类型
+
+### 1. 移动端应用
+- **iOS App** - `ios/` - 原生 iOS 应用（Swift/SwiftUI）
+- **Android App** - `android/` - 原生 Android 应用（Kotlin/Jetpack Compose）
+- **Flutter App** - `flutter/` - 跨平台移动应用（iOS + Android）
+
+### 2. 小程序
+- **微信小程序** - `wechat-miniapp/` - 微信生态
+- **支付宝小程序** - `alipay-miniapp/` - 支付宝生态
+- **抖音小程序** - `douyin-miniapp/` - 抖音生态
+
+### 3. Web 应用
+- **Web App** - `web/` - 响应式 Web 应用（React/Vue）
+- **桌面应用** - `desktop/` - Electron 桌面应用（Windows/macOS/Linux）
+
+### 4. 智能设备
+- **智能手表** - `watch/` - Apple Watch / Wear OS
+- **智能音箱** - `voice/` - 语音控制集成
+- **智能家居** - `smarthome/` - HomeKit / 米家 / 小度
+
+## 通信协议
+
+所有客户端通过以下方式与 ShowenV2 设备通信：
+
+### HTTP API
+- **地址**: `http://<device-ip>:8080/api/`
+- **协议**: RESTful API
+- **格式**: JSON
+- **认证**: Token / API Key
+
+### WebSocket
+- **地址**: `ws://<device-ip>:8080/ws`
+- **用途**: 实时状态推送
+- **格式**: JSON
+
+### BLE (蓝牙)
+- **协议**: GATT
+- **用途**: 近场控制、配网
+- **服务**: 自定义 GATT Service
+
+## 核心功能
+
+### 设备管理
+- 设备发现和配对
+- WiFi 配置
+- 设备状态监控
+
+### 播放控制
+- 播放/暂停/停止
+- 上一个/下一个
+- 跳转到指定视频
+- 音量控制
+
+### 状态机控制
+- 触发状态切换
+- 场景切换
+- 查看当前状态
+
+### 配置管理
+- 查看配置
+- 修改配置
+- 导入/导出配置
+
+### 内容管理
+- 浏览视频列表
+- 上传新视频
+- 删除视频
+- 视频预览
+
+## 开发计划
+
+### Phase 1（当前）
+- [ ] Web App - 基础控制界面
+- [ ] HTTP API 文档
+
+### Phase 2（3个月）
+- [ ] Flutter App - 跨平台移动应用
+- [ ] 微信小程序 - 快速访问
+- [ ] WebSocket 实时推送
+
+### Phase 3（6个月）
+- [ ] iOS 原生 App
+- [ ] Android 原生 App
+- [ ] 智能音箱集成
+
+### Phase 4（12个月）
+- [ ] 智能手表应用
+- [ ] 智能家居集成
+- [ ] 桌面应用
+
+## 技术栈
+
+### 移动端
+- **iOS**: Swift 5.9+, SwiftUI, Combine
+- **Android**: Kotlin 1.9+, Jetpack Compose, Coroutines
+- **Flutter**: Flutter 3.x, Dart 3.x
+
+### Web 端
+- **前端**: React 18+ / Vue 3+, TypeScript
+- **状态管理**: Redux / Pinia
+- **UI 框架**: Ant Design / Element Plus
+- **构建工具**: Vite / Webpack
+
+### 小程序
+- **微信**: 原生小程序框架 / uni-app
+- **支付宝**: 原生小程序框架
+- **抖音**: 原生小程序框架
+
+### 桌面端
+- **Electron**: Electron 28+, React/Vue
+- **Tauri**: Tauri 1.x, Rust + Web
+
+## 目录结构
+
+```
+clients/
+├── README.md                 # 本文件
+├── shared/                   # 共享代码
+│   ├── api/                  # API 客户端库
+│   ├── models/               # 数据模型
+│   └── utils/                # 工具函数
+├── web/                      # Web 应用
+│   ├── package.json
+│   ├── src/
+│   └── public/
+├── flutter/                  # Flutter 应用
+│   ├── pubspec.yaml
+│   ├── lib/
+│   └── assets/
+├── ios/                      # iOS 应用
+│   ├── ShowenV2.xcodeproj
+│   └── ShowenV2/
+├── android/                  # Android 应用
+│   ├── build.gradle
+│   └── app/
+├── wechat-miniapp/          # 微信小程序
+│   ├── app.json
+│   └── pages/
+├── desktop/                  # 桌面应用
+│   ├── package.json
+│   └── src/
+└── docs/                     # 客户端开发文档
+    ├── API.md                # API 文档
+    ├── DESIGN.md             # 设计规范
+    └── DEVELOPMENT.md        # 开发指南
+```
+
+## 快速开始
+
+### Web App
+```bash
+cd clients/web
+npm install
+npm run dev
+```
+
+### Flutter App
+```bash
+cd clients/flutter
+flutter pub get
+flutter run
+```
+
+### 微信小程序
+```bash
+cd clients/wechat-miniapp
+# 使用微信开发者工具打开
+```
+
+## API 文档
+
+详见 `docs/API.md`
+
+## 设计规范
+
+详见 `docs/DESIGN.md`
+
+## 贡献指南
+
+欢迎贡献新的客户端实现！请参考 `docs/DEVELOPMENT.md`
+
+---
+
+**文档版本**: v1.0  
+**最后更新**: 2026-03-12  
+**负责人**: 赵雨薇 (前端 & 屏幕工程师)