AndroidStation(原中控改造为纯设备端) - 只做三件事:UDP 48899 被桌面端发现、TCP 8087 推送 USB 扫码结果、离线语音播报 - 扫码不再经过 UI:去掉逐键重绘,50ms 自动提交,同一码重复扫码也一律上报 - 离线语音种子(数字/字母/“开始打包”/欢迎语)随包安装,MediaPlayer 播放,启动把音量拉满 - 启动播报「欢迎使用溯源系统,初始化已经完成,扫码即可开始打包」 - 移除 Device Owner / 设备管理员 / lock task / 网络与 IP 设置等非普通应用能力(仅保留开机自启) - 正式签名 keystore + release 签名配置,versionName/versionCode 可由打包脚本覆盖 发布脚手架 - backend/android_client:Android 正式包构建(build.ps1 + package.config.json) - backend/scripts/deploy/publish-android.cjs + npm run android:build / android:publish - 桌面端安装包改为 download/desktop,Android 为 download/android_client; version.json 仍走 /download/version.json(老客户端写死),新增 /download/android_client/version.json - 谷歌插件随桌面端 MSI 安装到 <安装目录>\extension,工具菜单新增「复制谷歌插件地址」 - git-safety-check 增加仓库级禁区(keystore.properties / *.jks / local.properties) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
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)。 - 扫码上报:
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 -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 -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):
$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 忽略,发布机必须自行备份;丢了就只能换包名重新发)。
# 只构建正式包(产物 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/)统一走后端脚手架,配置和桌面端同套路:
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 上报)。 本工程只负责「当一台扫码设备」。