tongtongstudio
d5e66a1777
AGENTS.md 与 README.md 同步更新：根据实际代码结构重写目录树、技术栈、架构分层及编码规范，移除旧版内联示例并补充新的开发约定与代码生成命令。
101 lines
4.2 KiB
Markdown
101 lines
4.2 KiB
Markdown
# 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 凭据。
|