liufumingren 228723e0c3 设备端扫码上报 + 桌面端/Android 正式包发布脚手架
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>
2026-10-21 05:53:27 +08:00

170 lines
8.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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 上报)。
本工程只负责「当一台扫码设备」。