Files

tongtongstudio d5e66a1777 docs(webrtc_controller_flutter): 更新项目文档以反映重构后的架构

AGENTS.md 与 README.md 同步更新：根据实际代码结构重写目录树、技术栈、架构分层及编码规范，移除旧版内联示例并补充新的开发约定与代码生成命令。

2026-08-03 16:12:44 +08:00

4.2 KiB

Raw Blame History

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 控制器后：

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

运行

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 凭据。

4.2 KiB Raw Blame History Unescape Escape