178 lines
11 KiB
Markdown
178 lines
11 KiB
Markdown
# 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.protobuf` Gradle 插件按 `*.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、全局依赖
|
||
├── MainActivity.java // 唯一入口 Activity，承载 NavHost
|
||
│
|
||
├── ui/ // 表现层（UI）
|
||
│ ├── home/ // 首页 / 设备列表
|
||
│ │ ├── HomeFragment.java
|
||
│ │ ├── HomeViewModel.java
|
||
│ │ └── fragment_home.xml
|
||
│ ├── control/ // 远程控制界面（投屏观看 + 触控下发）
|
||
│ │ ├── ControlFragment.java
|
||
│ │ ├── ControlViewModel.java
|
||
│ │ └── fragment_control.xml
|
||
│ ├── 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 接口定义
|
||
│ │ └── 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
|
||
│
|
||
└── 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 实践）
|
||
|
||
1. **Java 8 限制**：禁止 `List.of`、`var`、switch 表达式等 Java 9+ API（除非确认脱糖支持）。
|
||
2. **架构模式**：UI 用 MVVM（ViewModel + LiveData / RxJava）；单 Activity + Navigation。
|
||
3. **视图绑定**：使用 DataBinding / ViewBinding，禁止 `findViewById` 裸用。
|
||
4. **异步**：所有后台任务走 RxJava3，`.compose(rxlifecycle)` 绑定生命周期，避免内存泄漏。
|
||
5. **网络请求**：统一走 Retrofit 接口 + OkHttp 拦截器；JSON 用 Gson，DataChannel 指令用 Protobuf。
|
||
6. **敏感数据**：`deviceSecret` / `deviceUid` / `accessToken` 一律存 `security-crypto` 加密 SP，禁止明文。
|
||
7. **线程**：主线程只做 UI；IO / 网络 / 编解码放 `Schedulers.io()` / 子线程。
|
||
8. **日志**：使用统一日志工具（带 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 工程。
|