11 KiB
11 KiB
AGENTS.md — WebRTCController（Android 控制端）
本文件是 WebRTCController/ 工程的 AI 协作规则与开发规范。它是仓库根 AGENTS.md 中 Android 控制端条目的细化与补充，当两者冲突时以本文件为准（但安全与协议一致性约束始终以根文件最高优先级为准）。
一、工程定位
| 项 | 值 |
|---|---|
| 角色 | 控制端（观看被控端投屏 + 通过 DataChannel 下发控制指令） |
| 应用 ID / namespace | com.ttstd.controller |
| 主语言 | Java（全部源码为 .java；Kotlin 插件仅用于注解处理，禁止新增 Kotlin 源文件） |
| 语言级别 | Java 8（sourceCompatibility/targetCompatibility = VERSION_1_8，jvmTarget = 1.8） |
| SDK | compileSdk 34 / minSdk 24 / targetSdk 34 |
| 构建系统 | Gradle + AGP 8.13.2（Kotlin 插件仅作注解处理器） |
| 构建变体 | debug / release / zhanRuiDebug / zhanRuiRelease / CrosshatchDebug / CrosshatchRelease |
| 协议通道 | 信令 = WebSocket + JSON；控制指令 = WebRTC DataChannel + Protobuf 二进制 |
二、技术栈（当前已采用，遵循 Google 推荐与业内标准）
2.1 官方 Jetpack 与 Google 标准库
- 架构组件：
androidx.lifecycle（ViewModel / LiveData / LifecycleService）、androidx.room（本地持久化）、androidx.appcompat+com.google.android.material（Material Design 3 基础组件）。 - 安全存储：
androidx.security:security-crypto:1.1.0，用于加密保存deviceSecret/deviceUid/accessToken。绝不明文 SharedPreferences 或硬编码。 - 并发 / 异步：
io.reactivex.rxjava3（RxJava3 + RxAndroid），配合com.trello.rxlifecycle4做生命周期自动解绑。禁止裸Thread/AsyncTask。 - 图片加载：
com.github.bumptech.glide:4.15.1（含kapt注解处理器）。 - 轻量 KV：
com.tencent:mmkv-static:2.4.0（仅用于非敏感运行态缓存；敏感数据必须用 security-crypto）。
2.2 网络与序列化
- HTTP / REST：
Retrofit 3.0.0+OkHttp 5.3.2（logging-interceptor）+converter-gson+adapter-rxjava3。 - JSON：
Gson 2.14.0（信令消息 JSON 解析）。 - Protobuf：
com.google.protobuf:protobuf-java:3.25.1，由com.google.protobufGradle 插件按*.proto生成 Java 类（DataChannel 控制指令二进制）。 - WebRTC：
io.github.webrtc-sdk:android:144.7559.09。
2.3 构建与代码生成
- DataBinding：
buildFeatures.dataBinding = true（视图绑定统一用 DataBinding 或 ViewBinding，避免findViewById）。 - BuildConfig：
API_BASE（HTTP 基址）、WS_URL（信令 WebSocket 地址），均为开发占位值，部署时由 flavor / CI 注入。 - AIDL：
buildFeatures.aidl = true（如需跨进程通信）。
注：仓库当前使用
moshi依赖但未实际用于信令/指令编解码（信令用 Gson、指令用 Protobuf）。新增 JSON 解析请优先统一到 Gson，避免双序列化栈。
三、推荐目录结构（Google 应用架构指南 + 现代 Android 开发）
采用 单一 Activity + 多 Fragment（Navigation Component） 的应用结构，按 UI / Domain / Data 分层。源码位于 app/src/main/java/com/ttstd/controller/ 下，建议如下布局：
com.ttstd.controller
├── App.java // Application 子类：初始化 MMKV、Room、全局依赖
│
├── ui/ // 表现层 UI （按 Feature 分包）
│ ├── base/ // 基类
│ ├── main/ // 主功能
│ │ ├── MainActivity.java
│ │ ├── MainViewModel.java
│ │ └── MainUiState.java
│ ├── home/ // 首页 / 设备列表
│ │ ├── HomeFragment.java
│ │ └── HomeViewModel.java
│ ├── control/ // 远程控制界面（投屏观看 + 触控下发）
│ │ ├── ControlFragment.java
│ │ └── ControlViewModel.java
│ ├── login/ // 激活 / 登录
│ └── common/ // 共享 UI（BaseFragment、适配器、自定义 View）
│
├── domain/ // 领域层（可选，纯 Java 用例 / 业务规则）
│ ├── model/ // 业务模型（与 data 层实体解耦的纯对象）
│ └── usecase/ // 交互器（封装单一业务动作）
│
├── data/ // 数据层
│ ├── local/ // Room（实体、DAO、Database）、MMKV、security-crypto 封装
│ │ ├── db/ // @Entity / @Dao / @Database
│ │ ├── secure/ // EncryptedSharedPreferences 封装（凭据存储）
│ │ └── pref/ // MMKV 封装（非敏感）
│ ├── remote/ // 网络（Retrofit API 接口、WebSocket 信令客户端）
│ │ ├── api/ // REST 接口定义
│ │ ├── model/
│ │ └── signaling/ // WebSocket 信令连接与消息收发
│ ├── signaling/ // 信令消息（JSON）数据类 / 解析
│ ├── proto/ // 由 app/src/main/proto/*.proto 生成的指令类 + 编解码封装
│ └── repository/ // 仓储：向 UI 暴露单一数据源（组合 local + remote）
│
├── webrtc/ // WebRTC 封装
│ ├── PeerConnectionClient.java // RTCPeerConnection / SDP / ICE 管理
│ ├── DataChannelManager.java // 控制指令收发（Protobuf 编码）
│ ├── WebSocketSignalingClient.java// 信令（JSON）
│ └── IceServerProvider.java // ICE 服务器配置
│
├── controller/ // 远端控制指令业务逻辑
│ ├── CommandDispatcher.java // 指令分发（TOUCH / SWIPE / KEY 等）
│ └── ControlCommandFactory.java // 构造 Protobuf 控制指令
│
├── service/ // 前台 / 后台 Service（如保活、长连接）
│ └── SignalingService.java
│
├── receiver/ # 全局 BroadcastReceiver（系统级广播）
│ ├── BootCompletedReceiver.java # 开机启动
│ └── NetworkChangeReceiver.java # 网络变化
│
└── utils/ // 工具类（线程、日志、权限、网络状态）
资源目录（已存在 app/src/main/res/）：
layout/：Fragment/Activity 布局（DataBinding 布局以fragment_xxx.xml/activity_xxx.xml命名）。navigation/：NavGraph（nav_graph.xml，单一 Activity 路由）。values/、drawable/、mipmap-*、xml/（网络/备份配置）等按 Android 规范组织。
Proto 目录：app/src/main/proto/*.proto（与 WebRTCControlled 及 Flutter / iOS / Web 端字段号一致）。
分层约束（Google 架构基线）
- 单向数据流：UI 不直接访问
remote/local，统一经repository。 - ViewModel 持有状态：用
LiveData/RxJava暴露可观察数据；UI 只负责渲染与事件上报。 - 依赖方向：
ui → domain → data，data不反向依赖ui。 - 不要在
Activity/Fragment中直接持有RTCPeerConnection；WebRTC 逻辑收敛到webrtc/包。
四、编码规范（Google Java Style + Android 实践）
- Java 8 限制：禁止
List.of、var、switch 表达式等 Java 9+ API（除非确认脱糖支持）。 - 架构模式：UI 用 MVVM（ViewModel + LiveData / RxJava）；单 Activity + Navigation。
- 视图绑定：使用 DataBinding / ViewBinding，禁止
findViewById裸用。 - 异步：所有后台任务走 RxJava3，
.compose(rxlifecycle)绑定生命周期，避免内存泄漏。 - 网络请求：统一走 Retrofit 接口 + OkHttp 拦截器；JSON 用 Gson，DataChannel 指令用 Protobuf。
- 敏感数据：
deviceSecret/deviceUid/accessToken一律存security-crypto加密 SP，禁止明文。 - 线程：主线程只做 UI；IO / 网络 / 编解码放
Schedulers.io()/ 子线程。 - 日志：使用统一日志工具（带 TAG），发版变体关闭敏感信息输出。
五、协议一致性（最高优先级，跨端约束）
本系统为 1 被控端 + 5 控制端，协议改动影响面极大：
- 信令通道：WebSocket + JSON；控制指令通道：WebRTC DataChannel + Protobuf 二进制。两者不可混用。
- 修改
*.proto或信令 JSON 字段，必须同步：WebRTCControlled、WebRTCController、webrtc_controller_flutter、webrtc_controller_ios、WebRTCControllerWeb、WebRTCSignalServer。 - Protobuf 字段号只增不改不删；废弃字段用
reserved标记。 - 指令类型（TOUCH / SWIPE / KEY 等）新增时，在所有端补齐分支处理（
CommandDispatcher与各端解析处）。
六、安全与配置
- 禁止在源码、
build.gradle、config.gradle、local.properties中硬编码真实密钥、证书口令、生产地址。 - 现有占位值（
http://192.168.5.224:8080、ws://192.168.5.224:8080/ws/signal、签名密码123456/Fan1996）为开发默认值，不要当作正式配置扩散。 - 签名文件与密码通过
config.gradle（外部）注入，不进版本库；config.gradle已含keypub/crosshatch/zhanxun三套签名。 - 客户端凭据一律加密存储（本工程：
androidx.security.crypto）。
七、构建与变体
- 构建：
gradle assembleDebug/gradle assembleRelease；产物名由appName()（WebRTCController）+ 版本 + 日期生成。 - 变体说明：
debug/release：公开签名keypub。zhanRui*：展锐平台，使用zhanxun签名（系统签名场景）。Crosshatch*：Crosshatch 设备，使用crosshatch签名（系统签名场景）。
- 修改
appName()返回值会影响既有 CI 产物名，先确认。 - 修改签名配置、变体名或系统签名相关（
src/system/AndroidManifest.xml等）前必须先确认，涉及系统签名固件适配。
八、代码修改通用规则
- 优先做最小化定向修改，不对既有大文件整体重写或重构。
- 修改前先
read_file当前内容，避免基于陈旧上下文编辑。 - 不主动创建
*.md文档、示例文件或临时脚本；临时产物用完即删。 - Room 实体/DAO 变更必须提供 Migration，禁止
fallbackToDestructiveMigration。 - 编辑后修复自己引入的 lint / 编译错误。
- 注释与提交说明使用简体中文。
- 新增第三方依赖前说明必要性，并锁定版本；不擅自升级 AGP / Gradle / 大版本库。
- 不在 Java 工程中混入 Kotlin 源码（Kotlin 插件仅用于注解处理）。
九、禁止事项
- 不改动根目录
AGENTS.md与vue-vben-admin-origin/。 - 不删除
.codebuddy/目录。 - 不提交构建产物（
build/、*.class、*.dex、*.flat、*.dumpstream等）。 - 不引入 CocoaPods / 其他平台专属工具链到 Android 工程。