packServer/AndroidStation/.github/copilot-instructions.md
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

103 lines
4.9 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 / 电视盒子上的**扫码设备端**。它扮演网口扫码设备,让 `desktop/` 的扫码服务
自动发现并读取 USB 扫码枪的结果。
## 角色
```
桌面端(发现 + 连接) → UDP 48899 发现 / TCP 8087 读取扫码结果 → 本机
```
- **只做设备端**:不扫描别的设备、不管理通道、不回放、没有手势登录、没有网络设置。
- **不改 IP**:设备地址由现场网络分配;设置页只配置设备名、服务端口、发现端口和启停开关。
- **不要搬回中控业务**:`desktop/` 才是中控/桌面端,相关逻辑不在本工程。
## 关键实现
| 文件 | 职责 |
| --- | --- |
| `App` | 进程启动时拉起 `StationService` |
| `core/service/StationService` | 进程级单例:服务启停、扫码历史、UI 回调 |
| `core/service/DiscoveryResponder` | UDP 发现应答 + JCMD 兼容 |
| `core/service/ScanServer` | TCP 服务端,向桌面端推送扫码结果 |
| `core/StationSettings` | 设备名 / TCP 端口 / UDP 端口 / 开关 |
| `core/StationIdentity` | MAC、IP、型号、版本、Uptime |
| `core/speech/BarcodeSpeaker` | 离线语音种子拼接 + MediaPlayer 播报 + 启动音量最大 |
| `MainActivity` | 状态展示 + USB 扫码枪按键采集 |
| `SettingsActivity` | 服务设置 |
## 协议约定(必须与桌面端保持一致)
桌面端常量在 `desktop/Services/Scan/ScanChannel.cs` 的 `ScanProtocol`:
- UDP 发现端口 **48899**;广播请求 `{"Type":"EP_Tool",...}`。
- TCP 服务端口 **8087**(桌面端参数名为 `TcpPort`)。
- SOCK 条目名 **`packcenter`**。
- 扫码结果按 **UTF-8 + CRLF** 一行一条推送。
- JCMD 只需支持 `10001 / 10003 / 10005 / 10017`;`20003` 只回 `RC=0`,不要重启本机。
- 发现回复字段见 `docs/udp-48899-protocol.md` §6;`HostName` 用 UTF-8。
## 构建
```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File tools\android.ps1 build
```
或:
```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`
## 日志
- 统一用 `com.gztbyc.scancenter.util.L`(静态导入 `log/i/w/e`),**不要直接写 `android.util.Log`**。
- tag 固定 `AndroidStation`;release 包需 `adb shell setprop log.tag.AndroidStation DEBUG` 才输出。
- 不要删 `buildFeatures { buildConfig true }`,`L` 依赖 `BuildConfig.DEBUG`。
## 扫码热路径(必须保持快)
设备大概率长期不接显示器,扫码链路只允许做最少的事:
```
dispatchKeyEvent → StringBuilder → commitScan → StationService.pushBarcode
→ ScanServer 单线程 writer → 桌面端
```
- **禁止**在 `dispatchKeyEvent` / `commitScan` / `pushBarcode` 里同步刷新 UI 或写日志。
界面刷新由 `MainActivity` 的低频任务兜底(5 秒一次)。
- **禁止**在主线程写 socket。所有推送都在 `ScanServer` 的 `station-scan-write` 线程完成。
- **禁止去重**:重复条码也必须上报;连续扫描的重复帧由桌面端判断。
- 扫码枪没有回车/Tab 后缀时,50ms 无输入自动提交;不要再调大。
- 条码清理用首尾字符扫描,不要用正则。
## 语音播报
- 设备只有 `PicoTts` 且没有中文数据,**不要用 `TextToSpeech`**;用 `tools/fetch-voice-seeds.ps1`
抓下来的 `res/raw/voice_*.wav` 离线种子。
- 种子统一为 **44.1kHz / 立体声 / 16-bit PCM**;这台 rk3288 上 `AudioTrack` 初始化会失败,
播放必须走 `MediaPlayer`,且放在 `station-speech` 线程。
- 播报内容 = 条码末尾 4 个字母/数字 + 「开始打包」;同一码 2.5 秒内不重复播报,
换码立即打断上一句。**语音去重不等于上报去重**,上报仍然逐条发。
- 启动时把媒体音量设到最大(`MODIFY_AUDIO_SETTINGS`)。不要在扫码热路径里调音量。
## 代码约定
- Java + XML 布局,不用 Kotlin / Compose。
- 界面文案统一放 `res/values/strings.xml`,不硬编码。
- 主界面以遥控器为主:可点击控件必须方向键可达,并带 `state_focused` 反馈。
- 不要再加「跳系统设置页面」的入口(厂商把部分系统页面从 dex 删了,启动会崩)。
- 权限只需 `INTERNET`、`RECEIVE_BOOT_COMPLETED`、`MODIFY_AUDIO_SETTINGS`;这是普通用户应用,
**不要**引入 Device Owner / 设备管理员 / lock task / 系统应用 / 任何需要 ADB 赋权的功能。
- 开机自启只靠 `BootReceiver` + `RECEIVE_BOOT_COMPLETED`;新装后需手动启动一次。
## 不要做
- 不要恢复 `LoginActivity` / 手势 / 安全设置 / 通道管理 / 扫码回放 / 网络设置 / HTTP 条码上报。
- 不要在本机提供改 IP、掩码、网关的写入口。
- 不要把桌面端的 `DeviceScanner` / `ChannelConnection` / `ScanService` 逻辑复制进来。