# WebRTC 控制端 (webrtc_controller_flutter)

将原生 Android 项目 **WebRTCController** 的功能移植到 Flutter，使用**跨平台**依赖，可同时运行于 **Android** 与 **iOS**。

## 功能

对应原 Android 控制端（WebRTCController）的能力：

- 通过 WebSocket 连接信令服务器并注册为 `CONTROLLER` 设备
- 创建 WebRTC 连接（仅接收远端视频 `recvonly` + 一条控制用 DataChannel）
- 显示被控端画面（远端视频流）
- 通过触摸 / 滑动 / 物理按键采集输入，转换为相对坐标（0.0~1.0）经 DataChannel 发送控制指令（TOUCH / SWIPE / KEY / MOTION_EVENT）
- 实时显示连接统计（分辨率、帧率、延迟、解码格式）
- 支持自编码（自建 MediaCodec 解码）与 WebRTC 全托管两种串流模式
- 支持远程视频录制（MP4 保存到 app 专属目录）

## 架构

采用 **特性优先（Feature-First）** + **整洁架构（Clean Architecture）** 分层：

| 层 | 目录 | 职责 |
| --- | --- | --- |
| 全局 | `lib/app/` | 入口、路由（GoRouter）、主题、常量 |
| 共享 | `lib/core/` | 网络（dio）、Protobuf 协议、存储、工具、共享组件 |
| 认证 | `lib/features/auth/` | 登录 / 令牌 / 绑定列表（data / domain / presentation） |
| 连接 | `lib/features/connection/` | 信令、WebRTC、控制面板（data / domain / presentation） |

状态管理使用 **Riverpod**（`@riverpod` 注解 + 代码生成），路由使用 **go_router**，网络使用 **dio**，数据模型使用 **freezed**。

## 运行依赖（跨平台）

| 包 | 用途 |
| --- | --- |
| `flutter_webrtc` | WebRTC（Android + iOS 统一封装） |
| `web_socket_channel` | 信令 WebSocket |
| `dio` | HTTP API（登录 / 刷新 / 绑定列表 / TURN 凭证） |
| `flutter_riverpod` | 状态管理 |
| `go_router` | 路由 |
| `freezed` + `json_serializable` | 不可变数据模型与 JSON 序列化 |
| `flutter_secure_storage` | 令牌安全存储（Keychain / EncryptedSharedPreferences） |

## 目录结构

```
lib/
├── main.dart                       # 入口（ProviderScope + runApp）
├── app/
│   ├── app.dart                    # CupertinoApp.router
│   ├── router/app_router.dart      # GoRouter（/ = 设置页，/control = 控制页）
│   ├── theme/app_theme.dart        # 全局主题
│   └── constants/                  # 全局常量、ICE 配置
├── core/
│   ├── network/                    # dio、ApiException
│   ├── proto/                      # Protobuf 生成代码
│   ├── storage/                    # 令牌安全存储
│   ├── utils/                      # 控制指令、设备工具
│   └── widgets/                    # RemoteTouchView 触摸层
├── features/
│   ├── auth/                       # 登录 / 令牌
│   └── connection/                 # 信令 / WebRTC / 控制面板
└── l10n/                           # 国际化（.arb）
```

## 代码生成

新增或修改 freezed 模型 / Riverpod 控制器后：

```bash
dart run build_runner build --delete-conflicting-outputs
flutter gen-l10n
```

## 运行

```bash
flutter pub get
flutter run          # 默认运行到已连接设备
flutter run -d android
flutter run -d ios   # 需 macOS + Xcode
```

### iOS 注意事项

- 本项目已补齐 `ios/Podfile`（基于当前 Flutter 版本官方模板）。
  在 macOS 上首次构建会自动执行 `pod install` 拉取 `flutter_webrtc`。
- 为支持开发环境的 `ws://` 明文信令，`ios/Runner/Info.plist` 已添加
  `NSAppTransportSecurity -> NSAllowsArbitraryLoads = true`（生产环境建议改用 `wss://`）。

### Android 注意事项

- `android/app/src/main/AndroidManifest.xml` 已添加 `INTERNET` 权限与
  `android:usesCleartextTraffic="true"`（支持 `ws://`）。

## 对接说明

- **信令服务器**：需与 WebRTCControlled 项目共用同一套信令协议
  （REGISTER / OFFER / ANSWER / ICE_CANDIDATE，payload 为 JSON 字符串）。
- **被控端**：使用 WebRTCControlled（Android）接收 OFFER 并回传 ANSWER，
  其 `InputCommandHandler` 解析 TOUCH / SWIPE / KEY 指令。
- **ICE 服务器**：见 `lib/app/constants/ice_servers.dart`，请按需替换为自己的 TURN 凭据。