# AndroidStation(设备端) 面向 Android TV / 电视盒子的**扫码设备端**:把 USB 扫码枪的结果通过局域网推给桌面端 (`desktop/` 的扫码服务),并且在 UDP 48899 上扮演网口扫码设备,让桌面端自动发现。 原「扫描中心(AndroidScanCenter)」的中控业务已整体删除:不再扫描别的设备、不再管理通道、 不再有手势登录 / 网络设置 / 条码 HTTP 上报。 ## 技术栈 - 语言 / UI:**Java + XML 布局**(不使用 Kotlin、不使用 Compose) - 包名:`com.gztbyc.scancenter`(沿用原工程,便于现场覆盖安装) - minSdk 21 / targetSdk 28 / compileSdk 35 - Gradle 8.11.1 + AGP 8.7.3,JDK 17 - 依赖:仅 `androidx.appcompat`(纯 Java,无 native 库 → 与 CPU 架构无关) ## 工作方式 ``` 桌面端(desktop/Services/Scan) AndroidStation │ UDP 48899 广播 {"Type":"EP_Tool",...} → DiscoveryResponder │ ← 自己的 {"MAC","HostName","Type",...} (同一个 socket 回复) │ │ TCP 8087 主动连接 → ScanServer(服务端) │ ← 扫码结果(UTF-8 + CRLF) USB 扫码枪(键盘 HID) ``` - **允许被发现**:`DiscoveryResponder` 绑定 UDP 48899,收到发现广播就按设备固件的字段回复 (协议见 [`docs/udp-48899-protocol.md`](docs/udp-48899-protocol.md))。 - **扫码上报**:`ScanServer` 监听 TCP 8087,桌面端连上后,主界面收到的每一条扫码结果 都会按行推送过去。桌面端下发的扫码枪串口设置指令会被读取并丢弃(本机是 USB HID)。 - **兼容桌面端添加通道**:响应 JCMD `10001 / 10003 / 10005 / 10017`,报出一条 `packcenter / TCP-SERVER / 8087` 的 SOCK 条目;桌面端写 `SYS.HostName` 会更新设备名, 写 `SOCK.LocalPort` 会改本地服务端口。`20003` 只确认,不重启本机。 - **不改 IP**:网络参数只读上报,设置页没有改 IP / 掩码 / 网关的入口。 ## 主界面 - 设备名称 / MAC / IP / 型号版本 / 服务与发现状态 / 累计扫码。 - 最近 8 条扫码记录(**每 5 秒才刷新一次**,不参与扫码热路径)。 - USB 扫码枪是键盘设备:在 Activity 层统一收键,连续可打印字符攒成一条条码, 回车/Tab 立即提交;没有后缀时停手 **50ms** 自动提交。 - 底部「服务设置」「清空记录」两个按钮可用遥控器操作。 - `FLAG_KEEP_SCREEN_ON` 保证长期不接显示器时 Activity 仍保持前台、服务不被挂起。 ### 扫码性能约定(重要) 设备长期不接显示器,扫码路径必须尽量短: ``` 按键 → 追加缓冲 → 提交 → StationService 入队 → 后台写线程 → 桌面端 ``` - **按键/扫码回调里不同步刷新任何 UI、不写日志**;界面由 1 秒的时钟和 5 秒一次的状态刷新兜底。 - socket 写入只在 `station-scan-write` 单线程里做,避免主线程 `NetworkOnMainThreadException`, 同时保证多条扫码按顺序发出。 - **不做任何去重**:同一个条码连续扫到多少次就上报多少次,重复帧由桌面端自己判断。 - 条码校验只做首尾非字母数字清理 + 4~64 位长度检查,不用正则。 ## 语音播报(离线) 设备没有显示器,扫码后要能听到「后四位 + 开始打包」。 - 设备上只有 `PicoTts` 且**没有中文语音数据**,所以运行时**不用 TextToSpeech**。 - 用 `tools/fetch-voice-seeds.ps1` 从现场语音服务(`http://tbdata.gztbyc.com/voice/<文本>`) 一次性抓取 `0-9`、`A-Z`、`开始打包`,统一转成 **44.1kHz / 立体声 / 16-bit PCM**, 放到 `app/src/main/res/raw/voice_*.wav`;运行时只读本地资源,**断网也能播报**。 - 播放用系统 `MediaPlayer` 读临时拼接的 WAV(这台 rk3288 的 `AudioTrack` 初始化会失败), 在 `station-speech` 独立线程完成,不阻塞扫码上报。 - 同一串条码 2.5 秒内不重复播报(连续扫描的重复帧);换了条码立即打断上一句播最新的。 **上报不受影响**:重复条码仍然逐条发送。 - 语音内容:条码末尾 4 个字母/数字(标点跳过)+ 「开始打包」。 - 启动时 `BarcodeSpeaker.maximizeVolume` 把媒体音量设为最大(实测 `11 -> 15`)。 需要 `MODIFY_AUDIO_SETTINGS` 普通权限。 - 重新生成种子: ```powershell powershell -NoProfile -ExecutionPolicy Bypass -File tools\fetch-voice-seeds.ps1 -Force ``` 脚本依赖 `desktop/native/ffmpeg/ffmpeg.exe`;生成的 WAV 需要一起提交。 ## 服务设置 只保留服务参数: | 项 | 默认值 | 说明 | | --- | --- | --- | | 设备名称 | `Build.MODEL` / `工位终端` | 广播里的 `HostName`,桌面端用它显示通道名 | | 扫码服务端口(TCP) | **8087** | 桌面端连上来读扫码结果 | | 设备发现端口(UDP) | **48899** | 桌面端发现广播的目标端口 | | 启用扫码服务 | 开 | 关掉后不监听 TCP | | 允许被桌面端发现 | 开 | 关掉后不应答 UDP 广播 | ⚠️ 修改端口后要和桌面端约定保持一致(桌面端常量见 `desktop/Services/Scan/ScanChannel.cs` 的 `ScanProtocol`)。 ## 常用命令 所有构建/装机/抓日志统一走 `tools/android.ps1`(`.vscode/tasks.json` 只做转发), 脚本内会自动探测 JDK 与 adb: ```powershell powershell -NoProfile -ExecutionPolicy Bypass -File tools\android.ps1 dev ``` 任务:`build` / `install` / `run` / `dev` / `logs` / `clean` / `devices`; 选项:`-Variant` / `-Serial` / `-CleanFirst` / `-NoLaunch` / `-NoLogcat`。 直接用 Gradle 也可以(需自行设置 `JAVA_HOME`,本机 `java` 不在 PATH): ```powershell $env:JAVA_HOME='C:\Users\lfmingren\AppData\Local\Programs\EclipseAdoptium\jdk-17.0.20.1+1' .\gradlew.bat :app:assembleDebug ``` APK 产物:`app\build\outputs\apk\debug\app-debug.apk` ## 正式包(签名 + 发布) release 包用仓库根目录 `keystore/packservice-release.jks` 签名,密码放在 `keystore.properties` (两者都被 `.gitignore` 忽略,**发布机必须自行备份**;丢了就只能换包名重新发)。 ```powershell # 只构建正式包(产物 app\build\outputs\apk\release\app-release.apk) $env:JAVA_HOME='C:\Users\lfmingren\AppData\Local\Programs\EclipseAdoptium\jdk-17.0.20.1+1' .\gradlew.bat :app:assembleRelease -PversionName=1.0.1 -PversionCode=10001 ``` 发布(构建 + 上传到服务器 `download/android_client/`)统一走后端脚手架,配置和桌面端同套路: ```powershell cd ..\backend npm run android:build # 只构建(dry-run),产物在 backend\android_client\out npm run android:publish # 构建 + 上传 + 刷新 nginx ``` 下载地址 `https://<域名>/download/android_client/YuncangScan-<版本>.apk` (版本信息 `.../android_client/version.json`)。 ## 日志 - 统一用 `com.gztbyc.scancenter.util.L`(静态导入后 `log(...)` / `i(...)` / `w(...)` / `e(...)`), **不要直接写 `android.util.Log`**。 - tag 固定为 `AndroidStation`,类名+方法名+行号自动附在消息里;单条超 3000 字符自动分段。 - release 包默认不输出,需 `adb shell setprop log.tag.AndroidStation DEBUG` 才打开。 - **新增代码必须保留日志链路可用**:不要删掉 `buildFeatures { buildConfig true }`, `L` 依赖 `BuildConfig.DEBUG`。 ## 安装与开机启动 - 这是**普通用户应用**:只需要 `INTERNET`、`RECEIVE_BOOT_COMPLETED`、 `MODIFY_AUDIO_SETTINGS` 三个普通权限,`/data` 直接安装即可。 - 不依赖 Device Owner / 设备管理员 / lock task / 系统应用 / 任何 ADB 赋权。 - `BootReceiver` 监听 `BOOT_COMPLETED`,开机后自动拉起 `MainActivity`。 ⚠️ Android 的既定行为:**新装后必须手动启动一次**,应用才脱离 stopped 状态, 之后重启才会收到开机广播。 - 主界面不在后台驻留额外服务;扫码服务随应用进程生命周期运行。 ## 约定 - 依赖仓库走阿里云镜像,Gradle 分发走腾讯云镜像,改动仓库配置时保持国内源优先。 - 主界面以遥控器为主:可点击控件必须方向键可达,并在 `res/drawable/bg_button.xml` 这类 selector 中提供 `state_focused` 视觉反馈。 - 界面文案统一放 `res/values/strings.xml`,不硬编码在 XML / Java 中。 - **不要再加「跳系统设置页面」的入口**:这台盒子的 Settings 清单里声明了一些页面, 但厂商把它们从 dex 里删掉了,用组件名启动会让系统设置当场崩。 - **不要再把中控逻辑搬回来**(设备扫描 / 通道管理 / 回放 / 手势 / 网络设置 / HTTP 上报)。 本工程只负责「当一台扫码设备」。