# DisplayFlow 架构设计文档

本文档详细描述 DisplayFlow 系统的架构设计。

## 1. 整体架构

DisplayFlow 采用分层架构设计，从下到上分为：

1. **传输层（Transport Layer）**：物理网络连接
   - 局域网连接（USB RNDIS、Wi-Fi、以太网）
   - 互联网连接（通过 STUN/TURN/ICE）
2. **核心层（Core Layer）**：跨平台业务逻辑
3. **平台适配层（Platform Adapter Layer）**：平台特定实现
4. **角色层（Role Layer）**：业务角色实现
5. **应用层（Application Layer）**：用户界面和应用逻辑

**网络连接方式：**
- **局域网直连**：优先使用，延迟最低（< 5ms）
- **公网直连**：通过 STUN 发现，中等延迟（10-50ms）
- **TURN 中继**：当直连失败时使用，延迟较高（50-200ms）但最可靠

## 2. 核心层设计

### 2.1 网络抽象层

提供统一的网络接口，屏蔽底层网络差异。

**NAT 穿透模块：**
- **STUN 客户端**：用于 NAT 类型检测和获取公网 IP 地址
- **TURN 客户端**：当直连失败时，通过 TURN 服务器中继流量
- **ICE 代理**：实现 ICE (Interactive Connectivity Establishment) 协议
  - 收集候选地址（本地、服务器反射、中继）
  - 执行连接检查
  - 选择最佳连接路径
- **连接建立**：自动尝试多种连接方式，选择最优路径

### 2.2 协议层

基于 FlatBuffers 的跨平台序列化协议。

### 2.3 会话管理层

管理显示会话的生命周期。

### 2.4 编解码抽象层

统一的编解码器接口，支持多种编解码器。

### 2.5 文件传输模块

提供设备间文件传输功能：
- 文件传输协议定义
- 断点续传机制
- 多文件并发传输
- 传输进度跟踪
- 文件完整性校验

## 3. 平台适配层设计

### 3.1 Android 适配层

- 屏幕捕获：MediaProjection API
- 摄像头捕获：Camera2 API / NDK Camera API
- 输入处理：触摸事件
- 网络：USB RNDIS、Wi-Fi

### 3.2 Windows 适配层

- 虚拟显示器：IddCx 驱动框架
- 摄像头捕获：DirectShow / Media Foundation
- 渲染：DirectX
- 输入处理：键盘、鼠标
- 网络：USB RNDIS、Wi-Fi、以太网

## 4. 角色层设计

### 4.1 Host 角色

负责屏幕捕获、编码、发送。

### 4.2 Client 角色

负责接收、解码、渲染。

### 4.3 Peer 角色

同时运行 Host 和 Client 逻辑。

## 5. 数据流

### 5.1 Host -> Client 数据流

1. 平台层捕获屏幕帧
2. 编码器编码视频帧
3. 协议层序列化
4. 网络层发送
5. 客户端网络层接收
6. 协议层反序列化
7. 解码器解码
8. 平台层渲染

### 5.2 Client -> Host 输入流

1. 平台层捕获输入事件
2. 协议层序列化
3. 网络层发送
4. 主机网络层接收
5. 协议层反序列化
6. 平台层注入输入事件

### 5.3 文件传输流

1. 发送端选择文件
2. 文件分块（Chunk）
3. 协议层封装文件块
4. 网络层发送（可靠传输）
5. 接收端接收并重组
6. 文件完整性校验
7. 保存到目标位置

### 5.4 远程摄像头流

1. Host 端枚举摄像头设备
2. 选择并启动摄像头
3. 摄像头捕获视频帧
4. 编码器编码（复用屏幕共享编码器）
5. 协议层序列化
6. 网络层发送
7. Client 端接收、解码、渲染
8. 显示摄像头画面（可叠加在屏幕共享上）

## 6. 扩展功能设计

### 6.1 文件传输模块

**架构设计：**
- 复用现有的网络抽象层和协议层
- 使用可靠传输协议（TCP 或可靠 UDP）
- 支持断点续传，记录传输状态
- 多文件队列管理，支持优先级

**协议设计：**
- 文件元数据（文件名、大小、校验和）
- 文件块（Chunk）传输
- 传输控制消息（开始、暂停、恢复、取消）
- 进度报告机制

### 6.2 远程摄像头模块

**架构设计：**
- 复用现有的编码和传输机制
- 摄像头作为新的视频源类型
- 支持与屏幕共享同时进行（多路视频流）
- 摄像头参数控制（分辨率、帧率、对焦、曝光等）

**实现方式：**
- Android：使用 Camera2 API 或 NDK Camera API
- Windows：使用 DirectShow 或 Media Foundation
- 视频流复用屏幕共享的编码和传输通道
- 在协议中区分视频源类型（屏幕/摄像头）

### 6.3 NAT 穿透模块（TURN/STUN）

**架构设计：**
- 集成到网络抽象层，对上层透明
- 支持局域网、公网直连、TURN 中继三种连接方式
- 自动选择最佳连接路径
- 支持自定义 STUN/TURN 服务器配置

**连接建立流程：**

1. **候选地址收集**
   - 收集本地网络接口地址
   - 通过 STUN 服务器获取服务器反射地址
   - 通过 TURN 服务器获取中继地址

2. **ICE 连接检查**
   - 向所有候选地址发送连接检查
   - 等待对端响应
   - 测量延迟和带宽

3. **路径选择**
   - 优先选择局域网直连（延迟最低）
   - 其次选择公网直连（通过 STUN）
   - 最后选择 TURN 中继（最可靠但延迟较高）

4. **连接建立**
   - 使用选定的路径建立连接
   - 开始数据传输

**协议支持：**
- STUN (Session Traversal Utilities for NAT) - RFC 5389
- TURN (Traversal Using Relays around NAT) - RFC 5766
- ICE (Interactive Connectivity Establishment) - RFC 8445

**配置选项：**
- STUN 服务器地址和端口
- TURN 服务器地址、端口、用户名、密码
- ICE 连接超时时间
- 候选地址收集超时时间

**使用场景：**
1. **局域网场景**：自动检测并使用局域网直连（最快）
2. **互联网场景**：通过 STUN/TURN 服务器建立连接
3. **混合场景**：优先尝试局域网，失败后自动切换到互联网连接

**集成方式：**
- NAT 穿透模块集成到网络抽象层
- 对上层应用完全透明
- 自动选择最佳连接路径
- 支持连接方式动态切换