# DisplayFlow 项目结构说明

## 目录结构

```
DisplayFlow/
├── CMakeLists.txt              # 根 CMake 配置文件
├── .gitignore                  # Git 忽略文件配置
├── README.md                   # 项目概述和技术方案
├── DEVELOPMENT_PLAN.md         # 详细开发计划
├── README_BUILD.md             # 构建指南
├── PROJECT_STRUCTURE.md        # 本文件：项目结构说明
│
├── core/                       # 跨平台核心库
│   ├── CMakeLists.txt
│   ├── include/
│   │   └── displayflow/
│   │       └── core/
│   │           ├── common/     # 通用类型和常量
│   │           │   ├── types.h
│   │           │   └── constants.h
│   │           ├── network/    # 网络抽象层
│   │           │   ├── network_manager.h
│   │           │   ├── network_interface.h
│   │           │   ├── nat_traversal/  # NAT 穿透模块
│   │           │   │   ├── stun_client.h
│   │           │   │   ├── turn_client.h
│   │           │   │   ├── ice_agent.h
│   │           │   │   ├── candidate.h
│   │           │   │   └── nat_type.h
│   │           ├── protocol/   # 协议层
│   │           │   ├── protocol_handler.h
│   │           │   └── message_serializer.h
│   │           ├── session/    # 会话管理
│   │           │   ├── session_manager.h
│   │           │   └── session.h
│   │           ├── codec/      # 编解码抽象
│   │           │   ├── codec_manager.h
│   │           │   └── codec_interface.h
│   │           ├── role/       # 角色管理
│   │           │   ├── role_manager.h
│   │           │   ├── role_interface.h
│   │           │   ├── host_role.h
│   │           │   ├── client_role.h
│   │           │   └── peer_role.h
│   │           ├── file_transfer/  # 文件传输模块
│   │           │   ├── file_transfer_manager.h
│   │           │   ├── file_transfer_session.h
│   │           │   ├── file_chunk.h
│   │           │   └── transfer_progress.h
│   │           └── utils/      # 工具类
│   │               ├── logger.h
│   │               └── timer.h
│   └── src/                    # 对应的源文件实现
│       ├── network/
│       │   └── nat_traversal/
│       ├── protocol/
│       ├── session/
│       ├── codec/
│       ├── role/
│       ├── file_transfer/
│       └── utils/
│
├── platforms/                  # 平台适配层
│   ├── android/                # Android 平台实现
│   │   ├── CMakeLists.txt
│   │   ├── include/
│   │   │   └── displayflow/
│   │   │       └── platform/
│   │   │           └── android/
│   │   │               ├── platform_adapter.h
│   │   │               ├── capture/      # 捕获模块
│   │   │               │   ├── screen_capture.h
│   │   │               │   ├── media_projection_wrapper.h
│   │   │               │   └── camera_capture.h  # 摄像头捕获
│   │   │               ├── render/       # 渲染引擎
│   │   │               │   └── render_engine.h
│   │   │               ├── input/        # 输入处理
│   │   │               │   └── touch_handler.h
│   │   │               └── network/      # 网络管理
│   │   │                   └── android_network_manager.h
│   │   └── src/                # 对应的源文件实现
│   │       ├── capture/
│   │       │   ├── screen_capture.cpp
│   │       │   ├── media_projection_wrapper.cpp
│   │       │   └── camera_capture.cpp
│   │       ├── render/
│   │       ├── input/
│   │       ├── network/
│   │       └── platform_adapter.cpp
│   │
│   └── windows/                # Windows 平台实现
│       ├── CMakeLists.txt
│       ├── include/
│       │   └── displayflow/
│       │       └── platform/
│       │           └── windows/
│       │               ├── platform_adapter.h
│       │               ├── virtual_display/  # 虚拟显示器
│       │               │   ├── virtual_display.h
│       │               │   └── iddcx_wrapper.h
│       │               ├── capture/          # 捕获模块
│       │               │   └── camera_capture.h  # 摄像头捕获
│       │               ├── render/           # 渲染引擎
│       │               │   ├── directx_renderer.h
│       │               │   └── d3d11_renderer.h
│       │               ├── input/            # 输入处理
│       │               │   ├── keyboard_handler.h
│       │               │   └── mouse_handler.h
│       │               └── network/          # 网络管理
│       │                   └── windows_network_manager.h
│       └── src/                # 对应的源文件实现
│           ├── virtual_display/
│           ├── capture/
│           │   └── camera_capture.cpp
│           ├── render/
│           ├── input/
│           ├── network/
│           └── platform_adapter.cpp
│
├── docs/                       # 文档目录
│   ├── ARCHITECTURE.md         # 架构设计文档
│   └── API.md                  # API 文档
│
├── prototypes/                 # 原型和测试代码
│   └── README.md
│
└── tools/                      # 开发工具脚本
    └── README.md
```

## 模块说明

### 核心库 (core/)

100% 跨平台的业务逻辑实现，不依赖任何平台特定 API。

- **common/**: 基础类型定义和常量
- **network/**: 网络抽象层，统一管理 RNDIS、Wi-Fi、以太网
  - **nat_traversal/**: NAT 穿透模块（STUN/TURN/ICE）
- **protocol/**: 基于 FlatBuffers 的协议定义和序列化
- **session/**: 会话生命周期管理
- **codec/**: 编解码器抽象接口和管理
- **role/**: 角色（Host/Client/Peer）实现
- **file_transfer/**: 文件传输模块（断点续传、多文件传输）
- **utils/**: 通用工具类（日志、定时器等）

### 平台适配层 (platforms/)

各平台特定功能的薄封装层。

#### Android
- **capture/**: 
  - 屏幕捕获（MediaProjection API 封装）
  - 摄像头捕获（Camera2 API / NDK Camera API）
- **render/**: 渲染引擎（用于 Client 角色）
- **input/**: 触摸输入处理
- **network/**: Android 网络管理（USB RNDIS、Wi-Fi）

#### Windows
- **virtual_display/**: IddCx 驱动框架封装，创建虚拟显示器
- **capture/**: 
  - 摄像头捕获（DirectShow / Media Foundation）
- **render/**: DirectX 渲染引擎
- **input/**: 键盘和鼠标输入处理
- **network/**: Windows 网络管理（USB RNDIS、Wi-Fi、以太网）

## 命名空间

- `displayflow::core` - 核心库
- `displayflow::platform::android` - Android 平台适配
- `displayflow::platform::windows` - Windows 平台适配

## 构建系统

使用 CMake 作为统一构建系统：
- 根目录 `CMakeLists.txt` 负责平台检测和子目录管理
- 各模块有独立的 `CMakeLists.txt`
- 支持条件编译，根据平台自动选择对应的适配层

## 当前状态

所有基础框架文件已创建，包含：
- ✅ 完整的目录结构
- ✅ 所有头文件和源文件占位符
- ✅ CMake 构建配置
- ✅ 基础类型和接口定义

**下一步**：开始实现核心功能模块。

## 新增功能模块

### 文件传输模块 (core/file_transfer/)

支持在设备间传输文件，特性包括：
- 断点续传
- 多文件并发传输
- 传输进度监控
- 文件校验（MD5/SHA256）
- 传输队列管理

### 远程摄像头模块

支持使用对方的摄像头作为视频源，特性包括：
- 摄像头设备枚举和选择
- 视频流捕获和编码
- 与屏幕共享复用相同的传输通道
- 支持多摄像头切换
- 摄像头参数控制（分辨率、帧率等）

### NAT 穿透模块 (core/network/nat_traversal/)

支持通过互联网连接设备，突破局域网限制，特性包括：
- **STUN 客户端**：NAT 类型检测和公网 IP 发现
- **TURN 客户端**：中继服务器支持（当直连失败时）
- **ICE 协议**：自动选择最佳连接路径
- **候选地址收集**：收集本地、STUN、TURN 候选地址
- **连接建立**：自动尝试多种连接方式，选择最优路径

**连接方式优先级：**
1. 局域网直连（最快）
2. 公网直连（通过 STUN 发现）
3. TURN 中继（最慢但最可靠）

**架构优势：**
- 文件传输复用现有的网络抽象层和协议层
- 摄像头捕获复用现有的编码和传输机制
- NAT 穿透完全透明，上层无需关心连接方式
- 完全集成到现有角色模型中
- 保持跨平台兼容性