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,也可独立提供网络功能
- 新增双架构设计原则
This commit is contained in:
showen
2026-03-12 06:46:05 +08:00
parent 7aa42cc9af
commit fa692cd873
5 changed files with 959 additions and 37 deletions

View File

@@ -14,6 +14,8 @@
**示例**:
- screen - 屏幕管理(唤醒锁、光标控制)
- wifi - WiFi 管理(扫描、连接、热点)
- video - 视频播放(状态机、渲染)
- ble - 蓝牙服务GATT、配网**双架构**:既可配置 WiFi也可独立提供网络功能
### 依赖插件Dependent Plugins
**定义**: 依赖其他插件的功能,需要特定插件先启动
@@ -25,7 +27,6 @@
- 通过消息机制与依赖插件通信
**示例**:
- ble - 依赖 wifi通过 BLE 配置 WiFi
- http - 依赖 video通过 HTTP API 控制视频播放)
---
@@ -33,27 +34,36 @@
## 依赖关系图
```
独立插件层:
┌─────────┐ ┌─────────┐ ┌─────────┐
│ screen │ │ wifi │ │ video │
└─────────┘ └─────────┘ └─────────┘
↑ ↑ ↑
│ │ │
└────────────────────────┘
core
独立插件层(双架构):
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
│ screen │ │ wifi │ │ video │ │ ble │
└─────────┘ └─────────┘ └─────────┘ └─────────┘
↑ ↑ ↑
│ │ │
└────────────────────────┘
↕ │
│ (双架构通信) │
│ │
└─────────────────────────┘
core
依赖插件层:
┌─────────┐ ┌─────────┐
│ ble │ │ http │
│ (依赖 │ │ (依赖 │
│ wifi) │ │ video) │
└─────────┘ └─────────┘
└────────────┘
core
┌─────────┐
│ http │
│ (依赖 │
│ video) │
└─────────┘
core
```
**双架构说明**
- WiFi 和 BLE 是两套独立的网络架构
- BLE 可以配置 WiFi通过消息通信
- BLE 也可以独立提供网络功能(不依赖 WiFi
- 用户可以选择使用 WiFi 或 BLE 进行网络连接
---
## 插件依赖声明
@@ -77,23 +87,29 @@ pub trait Plugin: Send {
### 依赖声明示例
```rust
impl Plugin for BlePlugin {
fn dependencies(&self) -> Vec<&'static str> {
vec!["wifi"] // BLE 依赖 WiFi 插件
}
}
impl Plugin for HttpPlugin {
fn dependencies(&self) -> Vec<&'static str> {
vec!["video"] // HTTP 依赖 Video 插件
}
}
impl Plugin for BlePlugin {
fn dependencies(&self) -> Vec<&'static str> {
vec![] // BLE 是独立插件,通过消息与 WiFi 通信
}
}
impl Plugin for WifiPlugin {
fn dependencies(&self) -> Vec<&'static str> {
vec![] // WiFi 是独立插件
}
}
impl Plugin for VideoPlugin {
fn dependencies(&self) -> Vec<&'static str> {
vec![] // Video 是独立插件
}
}
```
---
@@ -118,13 +134,13 @@ impl Plugin for WifiPlugin {
### 示例启动顺序
```
Phase 1: 独立插件
Phase 1: 独立插件(并行启动)
- screen.init() → screen.start()
- wifi.init() → wifi.start()
- video.init() → video.start()
- ble.init() → ble.start()
Phase 2: 依赖插件
- ble.init() → ble.start() (依赖 wifi)
- http.init() → http.start() (依赖 video)
```
@@ -144,16 +160,30 @@ Phase 2: 依赖插件
### 消息路由示例
```rust
// BLE 请求 WiFi 扫描
ble_plugin.send(Message::WifiCommand(WifiCommand::Scan));
// WiFi 返回扫描结果(Broadcast
wifi_plugin.send(Message::WifiResult(result));
// BLE 接收到 WifiResult 消息
// 场景1: BLE 配置 WiFi(双架构协作)
ble_plugin.send(Message::WifiCommand(WifiCommand::Connect { ssid, password }));
wifi_plugin.handle_message(Message::WifiCommand(...));
wifi_plugin.send(Message::WifiResult(result)); // Broadcast
ble_plugin.handle_message(Message::WifiResult(result));
// 场景2: BLE 独立提供网络功能(不依赖 WiFi
// 用户通过 BLE 直接与设备通信,不需要 WiFi
ble_plugin.handle_gatt_request(request);
ble_plugin.send_gatt_response(response);
// 场景3: HTTP 控制 Video强依赖
http_plugin.send(Message::PlayerCommand(PlayerCommand::Play));
video_plugin.handle_message(Message::PlayerCommand(...));
video_plugin.send(Message::PlayerStatus(status)); // Broadcast
```
**关键区别**
- **双架构WiFi + BLE**:两套独立的网络方案,可以互相配置,也可以独立工作
- BLE 可以配置 WiFi松耦合通过消息
- BLE 可以独立提供网络功能(不依赖 WiFi
- WiFi 可以独立工作(不依赖 BLE
- **强依赖HTTP → Video**HTTP 必须在 Video 启动后才能工作
---
## 当前插件分类
@@ -162,15 +192,23 @@ ble_plugin.handle_message(Message::WifiResult(result));
| 插件 | 功能 | 依赖 | 状态 |
|------|------|------|------|
| screen | 屏幕管理 | core | ✅ 完成 |
| wifi | WiFi 管理 | core | ✅ 完成 |
| wifi | WiFi 网络 | core | ✅ 完成 |
| video | 视频播放 | core | ✅ 完成 |
| ble | 蓝牙网络 | core | ✅ 完成 |
**双架构说明**
- **WiFi 架构**:通过 WiFi 连接网络,支持扫描、连接、热点
- **BLE 架构**:通过蓝牙连接网络,支持 GATT 服务、配网
- **协作模式**BLE 可以配置 WiFi通过消息通信
- **独立模式**BLE 和 WiFi 都可以独立提供网络功能
### 依赖插件
| 插件 | 功能 | 依赖 | 状态 |
|------|------|------|------|
| ble | 蓝牙配网 | core + wifi | ✅ 完成 |
| http | HTTP API | core + video | ✅ 完成 |
**说明**HTTP 必须依赖 Video因为 HTTP API 的核心功能是控制视频播放。
---
## 未来插件规划
@@ -214,6 +252,12 @@ ble_plugin.handle_message(Message::WifiResult(result));
- 独立插件可以单独测试
- 依赖插件可以集成测试
### 5. 双架构原则(新增)
- 支持多套独立架构并存(如 WiFi + BLE
- 架构之间可以协作(通过消息)
- 架构之间可以独立工作(不强依赖)
- 用户可以选择使用哪套架构
---
## 实现任务