5.1 KiB

Raw Blame History

StandAPP 智能调度终端 - 开发指南 (AGENTS.md)

本文档为 StandAPP 项目的开发规范与技术参考，旨在帮助开发者快速理解项目架构、构建流程及核心业务逻辑。

1. 项目概况

StandAPP 是一款基于 Kotlin 和 Jetpack Compose 开发的 Android 应用。集成了 AgentWeb（网页交互）、打印服务、自动更新以及核心的 PTT (Push-to-Talk) 对讲模块。

主包名: com.stand.standapp
PTT 包名: com.example.kingway.ptt (严禁修改，与 Native 层硬绑定)
技术栈: Kotlin, Jetpack Compose, Gradle (Kotlin DSL), OkHttp, AgentWeb, NDK (C++).
SDK 版本: Compile SDK 36, Target SDK 34, Min SDK 24.

2. 构建、检查与测试

构建命令

编译 Debug APK: ./gradlew assembleDebug
清理项目: ./gradlew clean
编译 Release APK: ./gradlew assembleRelease

检查与测试

运行 Lint 检查: ./gradlew lint
运行单元测试: ./gradlew test
运行单项测试: ./gradlew :app:testDebugUnitTest --tests "包名.类名"

3. 代码风格与规范

缩进: 4 个空格。
命名: 类名使用 PascalCase；函数和变量使用 camelCase；常量使用 SCREAMING_SNAKE_CASE。
Compose: 优先使用 Material 3 组件；Composable 函数首字母大写；Modifier 必须作为第一个可选参数。
错误处理: 必须使用 try-catch 包裹 IO、网络、JSON 解析等易错操作，并使用 Log.e 记录异常。

4. PTT (对讲) 核心业务逻辑解析

PTT 模块是本项目的通讯核心，依赖底层 libptt.so 原生引擎。其业务流程高度依赖 十六进制 AT 指令 交互。

4.1 核心组件与关键方法

A. 指令发送：`SendAtUtil` (指令工厂)

封装了所有发往 Native 引擎的控制指令。

toLogin(account, pwd, ip, location, tempCall): 登录接口。将账号、密码、服务器 IP、GPS 开启标志及单呼标志拼接为 010000 开头的十六进制指令。
speakPlay(): 开始对讲。发送 0B0000 指令，触发底层 POC 引擎进入发送模式并准备处理语音数据。
speakRelease(): 停止对讲。发送 0C0000 指令通知引擎结束通话，并同步停止本地录音线程。
sendTCP() / sendUDP(): 心跳维持。登录成功后，必须每 40秒 调用一次。570000 为 TCP 心跳，580000 为 UDP 心跳。
getGroupInfo(): 查询群组。发送 0D0000 指令。
getGroupMemberInfo(groupId): 查询成员。发送 0E0000 + 群组 ID。
jumpGroup(groupId): 切换群组。发送 090000 + 群组 ID，用于即时切换监听的群组。

B. 指令解析：`CallBackResolution` (响应处理器)

解析 Native 引擎通过 JNI 异步返回的十六进制数据。

at_OEM_AT_cb(lisHex): 解析入口。识别首字节指令码：
- 82: 登录/离线状态变更。
- 80: 接收群组详细信息（ID、名称、成员数）。
- 81: 接收群成员在线状态及视频能力。
- 83: 语音发起者信息（当前谁在说话）。
- 8b: 播音状态变更（引擎开始或停止播放对方声音）。
- 8d: 经纬度数据通知。
at_Play_TTS_cb(sData): TTS 状态解析。解析中文状态描述。当识别到“已登录”时，需触发心跳定时器。
isLoginConflict(state): 冲突检测。逻辑：1 分钟内若状态在“离线”和“登录中”切换超过 5 次，则判断为登录冲突。

C. 录音管理：`AudioRecordManager` (音频采集)

startRecord(): 启动录音循环。设置优先级为 THREAD_PRIORITY_URGENT_AUDIO。
stopRecord(): 释放 AudioRecord 资源。
技术参数: 采样率 8000Hz, 16bit, 单声道。每读取 320 字节 PCM 原始数据即调用 pttNativeSendRecordCmd 推送至 Native 层。

D. JNI 桥接：`pttNative` (底层交互)

OEM_Play_cb(byte[] bytes): 播放回调。底层接收到的音频流会实时回调此方法，数据需直接写入 AudioTrack 实例进行播放。
pttNativePocTaskStart(): 引擎初始化。

4.2 业务技术流程

初始化: 调用 MyApplication.init(context) -> 加载 SO 库 -> 启动 Native 任务。
认证: 调用 toLogin -> 异步等待 82 回调或 TTS “已登录”提示。
在线维持: 登录成功后启动周期为 40s 的任务发送 TCP/UDP 心跳。
对讲过程:
- 按下 PTT: speakPlay -> 收到成功反馈 -> AudioRecordManager 持续采音并推送。
- 松开 PTT: speakRelease -> 停止录音 -> 发送结束指令。
UI 更新: 引擎回调均在 子线程。所有 UI 操作（Toast、Dialog、TextView 更新）必须切回主线程。

5. 开发约束与安全

包名与类名: com.example.kingway.ptt.pttNative 严禁改名或移动，否则会导致 JNI 方法找不到实现导致崩溃。
权限管理: 必须先通过 XXPermissions 获取 RECORD_AUDIO 权限后再执行对讲。
线程规范: 回调处理严禁阻塞。耗时操作必须异步执行。

本文档由 AI 助手维护，旨在确保业务逻辑的一致性。

5.1 KiB Raw Blame History Unescape Escape