# AGENTS.md — 项目全局规则

本仓库是一个 **WebRTC 远程控制系统** 的多端单体仓库（monorepo），包含 Android 被控端、多平台控制端（Android / iOS / Flutter / Web）、Spring Boot 信令服务器及其后台管理前端。

---

## 一、工程总览

| 目录 | 工程类型 | 主语言 | 构建工具 | 角色 |
|---|---|---|---|---|
| `WebRTCSignalServer/` | Spring Boot 后端 | Java 25 | Maven | 信令服务器 + REST API |
| `WebRTCSignalServerWeb/` | Vue3 SPA | TypeScript | Vite | 服务器后台管理前端 |
| `WebRTCControlled/` | Android App | Java | Gradle | **被控端**（投屏 + 接收指令） |
| `WebRTCController/` | Android App | Java | Gradle | **控制端**（观看 + 发送指令） |
| `webrtc_controller_flutter/` | Flutter App | Dart | Flutter CLI | 控制端（Android/iOS 跨平台） |
| `webrtc_controller_ios/` | iOS App | Swift 5 | Xcode + SPM | 控制端（原生 iOS） |
| `WebRTCControllerWeb/` | Vue3 SPA | JavaScript | Vite | 控制端（网页版） |
| `AdbLoopbackController/` | Android App | Java | Gradle | ADB 回环控制工具（独立） |
| `vue-vben-admin-origin/` | 第三方模板 | TypeScript | pnpm | **只读参考**，禁止修改 |

---

## 二、各工程详细规则

### 1. `WebRTCSignalServer/` — 信令服务器

- **类型**：Spring Boot 4.1.0 应用，`spring-boot-starter-parent`
- **语言**：Java 25（`<java.version>25</java.version>`）
- **坐标**：`com.tt:webrtc-signal-server:1.0.0`
- **核心依赖**：`spring-boot-starter-websocket`、`starter-web`、`starter-data-jpa`（MySQL）、`starter-data-redis`、`starter-validation`、`spring-security-crypto`（仅 BCrypt 编码器，**不启用** Security 自动配置）、Jackson
- **测试**：`spring-boot-starter-test` + H2（无外部 MySQL 时上下文可启动）
- **构建**：`mvn clean package` / `mvn spring-boot:run`

**AI 规则**
- 使用 Java 25 语法，可用 record、sealed、switch 模式匹配、文本块。
- 持久化统一走 JPA Repository，不要手写 JDBC。
- Redis 用于：在线状态、频控计数、nonce 去重、踢线广播。新增缓存需说明 key 规范与 TTL。
- 密码只允许 BCrypt 编码，禁止明文或可逆加密存储。
- 请求体参数校验统一使用 `jakarta.validation` 注解，不在 Controller 里手写 if 校验。
- 不要引入 Spring Security 的完整过滤器链（当前设计是刻意只用 crypto 模块）。
- 信令协议改动必须同步更新所有客户端（Android / iOS / Flutter / Web）。

### 2. `WebRTCSignalServerWeb/` — 后台管理前端

- **类型**：Vue 3 SPA，ESM（`"type": "module"`）
- **技术栈**：Vue `^3.5.12` + TypeScript `^5.6.3` + Vite `^5.4.10` + Pinia `^2.2.4` + Vue Router `^4.4.5` + Element Plus `^2.8.4` + ECharts `^5.5.1` + axios `^1.7.7`
- **脚本**：`npm run dev` / `npm run build`（含 `vue-tsc --noEmit`）/ `npm run preview`（端口 5180）

**AI 规则**
- 统一使用 `<script setup lang="ts">` + Composition API，禁止 Options API。
- UI 组件一律用 Element Plus，图标用 `@element-plus/icons-vue`，不引入其他 UI 库。
- 状态管理用 Pinia，禁止 Vuex。
- 所有请求走统一封装的 axios 实例，不在组件内直接 `fetch`。
- 构建前必须通过 `vue-tsc` 类型检查，禁止用 `any` 绕过报错。
- 风格可参考 `vue-vben-admin-origin/`，但**只读参考**，不得拷贝整块代码或改动该目录。

### 3. `WebRTCControlled/` — Android 被控端

- **类型**：Android App，`applicationId` / `namespace` = `com.ttstd.controlled`
- **语言**：**Java**（源码全部为 `.java`；虽启用了 Kotlin/kapt 插件，但仅用于注解处理）
- **SDK**：compileSdk 34 / minSdk 24 / targetSdk 34，Java 兼容 `VERSION_1_8`，`jvmTarget = 1.8`
- **buildFeatures**：`dataBinding`、`buildConfig`、`aidl` 均开启
- **核心依赖**：WebRTC `io.github.webrtc-sdk:android:144.7559.09`、Protobuf 3.25.1、Gson 2.14.0、Retrofit 3.0.0 + OkHttp 5.3.2、RxJava3 + RxAndroid、Room 2.8.4、Lifecycle 2.10.0、`androidx.security:security-crypto:1.1.0`、MMKV 2.4.0、Glide 4.15.1
- **BuildConfig 字段**：`API_BASE`、`DEVICE_PROVISION_SECRET`
- **构建变体**：`debug` / `release` / `zhanRuiDebug` / `zhanRuiRelease` / `CrosshatchDebug` / `CrosshatchRelease`；zhanRui 与 Crosshatch 变体使用 `src/system/AndroidManifest.xml`（系统签名场景）
- **签名**：`keypub` / `crosshatch` / `zhanxun`，配置来自 `rootProject.ext.signingConfigs`（外部 `config.gradle`）

**AI 规则**
- **新代码一律用 Java 编写**，不要擅自引入 Kotlin 源文件。
- 语言级别限制在 Java 8，禁止使用 Java 9+ 的 API（如 `List.of`、`var` 之外的新特性需确认脱糖支持）。
- 异步统一使用 RxJava3 + `rxlifecycle4` 管理生命周期，禁止裸 `Thread` / `AsyncTask`。
- 网络请求走 Retrofit + OkHttp，JSON 用 Gson；**DataChannel 控制指令用 Protobuf 二进制，信令消息用 JSON**，两者不可混用。
- 敏感数据（`deviceSecret` / `deviceUid` / `accessToken`）必须存 `security-crypto` 加密 SharedPreferences，禁止明文 SP 或硬编码。
- `DEVICE_PROVISION_SECRET` 与 `API_BASE` 是开发期占位值，**禁止把真实密钥写入 build.gradle**，应通过 flavor / CI 注入。
- 修改签名配置、变体名或 `src/system/AndroidManifest.xml` 前必须先确认，涉及系统签名固件适配。
- Room 实体/DAO 变更必须提供 Migration，禁止 `fallbackToDestructiveMigration`。

### 4. `WebRTCController/` — Android 控制端

- **类型**：Android App，`applicationId` / `namespace` = `com.ttstd.controller`
- **语言 / SDK / 依赖**：与 `WebRTCControlled` 完全一致（Java、compileSdk 34、minSdk 24、同一套依赖集）
- **BuildConfig 字段**：`API_BASE`、`WS_URL`

**AI 规则**
- 同 `WebRTCControlled` 的全部 Android 规则。
- 该模块与被控端共享协议层代码（Protobuf `.proto`、信令 JSON 结构），**任一端修改协议必须双端同步**，并同步 Flutter / iOS / Web 三端。
- 修复 `appName()` 返回值前请先确认，可能影响既有 CI 产物名。

### 5. `webrtc_controller_flutter/` — Flutter 控制端

- **类型**：Flutter App（Android + iOS），版本 `1.0.0+1`
- **语言**：Dart SDK `^3.12.2`
- **核心依赖**：`flutter_webrtc: ^1.5.2`、`web_socket_channel: ^3.0.3`、`protobuf: ^6.0.0` + `fixnum: ^1.1.1`、`flutter_secure_storage: ^9.0.0`、`device_info_plus: ^11.0.0`、`android_id: ^0.5.2+1`、`http: ^1.2.0`、`uuid: ^4.4.0`、`path_provider: ^2.1.5`
- **Lint**：`flutter_lints: ^6.0.0`
- **入口**：`lib/main.dart` → `MyApp`（CupertinoApp）→ `ControllerHome`
- **关键目录**：`lib/config/ice_servers.dart`、`lib/signaling/`、`lib/webrtc/`、`lib/controller/`、`lib/widgets/`
- **iOS**：已配置 `ios/Podfile` 以支持 `flutter_webrtc`

**AI 规则**
- 遵循 `flutter_lints` 规则，提交前跑 `flutter analyze`，不得有 warning。
- 保持现有分层：`config` / `signaling` / `webrtc` / `controller` / `widgets`，新代码放入对应层，不要在 `main.dart` 堆逻辑。
- UI 使用 Cupertino 风格（项目基调为 `CupertinoApp`），保持一致性。
- 敏感凭据用 `flutter_secure_storage`，禁止 `SharedPreferences` 明文存储。
- 控制指令编码必须与 Android 端 Protobuf schema 保持字段号一致。
- 新增依赖需在 `pubspec.yaml` 锁定 caret 版本，并说明引入理由。
- 改动 iOS 原生依赖后需提示执行 `cd ios && pod install`。

### 6. `webrtc_controller_ios/` — 原生 iOS 控制端

- **类型**：iOS App，Bundle ID `com.ttstd.web-rtc-controller-ios`
- **语言**：Swift 5.0，`IPHONEOS_DEPLOYMENT_TARGET = 15.0`
- **依赖管理**：**Swift Package Manager**（远程包 `WebRTC`），**无 CocoaPods**
- **架构**：UIKit（`AppDelegate` + `SceneDelegate`）+ SwiftUI（`ContentView`）混合
- **代码分组**：`App/`、`Signaling/`、`Control/`、`WebRTC/`、`Views/`、`ViewModel/`、`Utils/`
- **关键文件**：`WebRTCClient.swift`、`SignalingClient.swift`、`ControlMessage.swift`、`ControllerViewModel.swift`、`RemoteTouchView.swift`、`RemoteVideoView.swift`、`VideoRecorder.swift`

**AI 规则**
- 只用 Swift，不引入 Objective-C 文件。
- 依赖统一走 SPM，**禁止添加 Podfile / CocoaPods**。
- 遵循 MVVM：视图逻辑放 `ViewModel/`，网络与 WebRTC 逻辑放 `Signaling/` 与 `WebRTC/`，不要在 View 中直接持有 `RTCPeerConnection`。
- 保持最低支持 iOS 15.0，禁止使用更高版本独占 API（必要时用 `@available` 兜底）。
- 修改 `project.pbxproj` 需谨慎，优先通过 Xcode 操作而非手改文本。
- 控制消息结构（`ControlMessage.swift`）需与其他端协议对齐。

### 7. `WebRTCControllerWeb/` — 网页控制端

- **类型**：Vue 3 SPA，ESM
- **技术栈**：Vue `^3.4.21` + Vite `^5.2.0` + `protobufjs: ^7.3.2`（**纯 JavaScript，无 TypeScript**）
- **脚本**：`npm run dev` / `npm run build` / `npm run preview`

**AI 规则**
- 该工程未启用 TypeScript，**不要擅自引入 `.ts` 或 tsconfig**，除非用户明确要求迁移。
- 使用 `<script setup>` + Composition API。
- WebRTC 直接用浏览器原生 API（`RTCPeerConnection` / `RTCDataChannel`），不要引入 adapter 之外的第三方封装库。
- 控制指令用 `protobufjs` 编解码，`.proto` 定义须与 Android / iOS / Flutter 端一致。
- 保持依赖精简，新增依赖前先确认是否有原生 API 替代方案。

### 8. `AdbLoopbackController/` — ADB 回环控制工具

- **类型**：Android App，`applicationId` / `namespace` = `com.ttstd.adbloopback`
- **语言**：Java（无 Kotlin），Java 兼容 `VERSION_1_8`
- **SDK**：AGP 8.1.4，compileSdk 34 / minSdk 24 / targetSdk 34
- **依赖**：仅 `appcompat:1.6.1`、`material:1.11.0`、`constraintlayout:2.1.4`
- **入口**：`MainActivity`
- **特色**：自实现 ADB 协议栈 —— `adb/AdbConnection`、`AdbPairing`、`AdbStream`、`TlsPskClient`
- **签名**：依赖外部 `config.gradle` 的 `signingConfigs.keypub`

**AI 规则**
- 纯 Java 项目，**不要引入 Kotlin**。
- 依赖保持极简，新增第三方库前必须说明必要性。
- `adb/` 包是手写的 ADB 无线调试协议（含配对与 TLS-PSK 握手）实现，改动需严格对照 ADB 协议规范，任何修改都要说明协议依据。
- 与 WebRTC 系列工程相互独立，不要在两者间引入耦合。

### 9. `vue-vben-admin-origin/` — 第三方模板（只读）

- **类型**：上游开源后台模板 vue-vben-admin，TypeScript + Vue 3 monorepo（pnpm）
- **用途**：仅作为 `WebRTCSignalServerWeb` 的风格与实现参考

**AI 规则**
- **严禁修改该目录下任何文件**，也不要为其安装依赖或执行构建。
- 不要将其纳入代码搜索的改动范围；检索到的匹配结果仅供参考。
- 需要复用其能力时，在 `WebRTCSignalServerWeb` 中重新实现，而非拷贝目录。

---

## 三、跨工程通用规则

### 协议一致性（最高优先级）
本系统有 **1 个被控端 + 5 个控制端**，通信协议改动影响面极大：

- **信令通道**：WebSocket + **JSON**
- **控制指令通道**：WebRTC DataChannel + **Protobuf 二进制**
- 修改 `.proto` 文件或信令 JSON 字段时，**必须同时更新**：`WebRTCControlled`、`WebRTCController`、`webrtc_controller_flutter`、`webrtc_controller_ios`、`WebRTCControllerWeb`、`WebRTCSignalServer`。
- Protobuf 字段号只增不改不删；废弃字段用 `reserved` 标记。
- 指令类型（TOUCH / SWIPE / KEY 等）新增时需在所有端补齐分支处理。

### 安全
- 禁止在源码、`build.gradle`、`pubspec.yaml`、`application.yml` 中硬编码真实密钥、证书口令、生产地址。
- 现有占位值（`dev-device-provision-secret-change-me`、`192.168.5.224:8080`）为开发默认值，不要当作正式配置扩散。
- 签名文件与密码通过 `config.gradle` / CI 环境变量注入，不进版本库。
- 客户端凭据一律加密存储（Android: security-crypto；Flutter: secure_storage；iOS: Keychain）。

### 代码修改
- 优先做**最小化定向修改**，不要对既有大文件做整体重写或重构。
- 修改前先读取文件当前内容，避免基于陈旧上下文编辑。
- 不要主动创建 `*.md` 文档、示例文件或临时脚本；临时产物用完即删。
- 编辑后修复自己引入的 lint / 编译错误。
- 注释与提交说明使用**简体中文**。

### 禁止事项
- 不改动 `vue-vben-admin-origin/`。
- 不删除 `.codebuddy/` 目录。
- 不擅自升级 AGP、Spring Boot、Flutter SDK、Vue 等大版本。
- 不在 Java 工程中混入 Kotlin 源码。
- 不提交构建产物（`build/`、`dist/`、`*.class`、`*.flat`、`*.dex`、`*.dumpstream`）。