packServer/AndroidStation/.github/copilot-instructions.md
liufumingren c07d5c640b fix: 扫码结束键按设备识别、发现列表就地刷新、NVR 唯一性按主体
AndroidStation
- 有的扫码枪(Newtologic DW-8200,T95MAX/Android 12)用 KEYCODE_DPAD_CENTER 当结束键,
  之前只认 ENTER/TAB:结束键会落到当前焦点按钮上(一扫就进「服务设置」,焦点在
  「清空记录」时还会清空记录),而且扫码只能等 50ms 超时才提交。现在按 deviceId 认
  “刚发过条码字符的那台设备”,DPAD_CENTER 也算结束键,遥控器 OK 键不受影响。
- 新增「播报走本机扬声器(AV / 3.5mm)」开关(默认关):个别机型插 HDMI 时 HAL 会把
  媒体声音锁在 HDMI 声卡,需要显式指定内建扬声器。

桌面端
- 发现列表改为按 MAC 就地合并,不再整表 Clear(每 3 秒一次刷新会把 ListView 的选中项
  和滚动位置清掉,现场表现为“设备选不中”)。
- 「添加为通道」从标题行移到列表行内「操作」列,不再依赖选中项。

后端
- NVR 唯一键由全局 (host, port, username) 改为 (subject_id, host, port, username):
  不同仓库的内网地址经常相同,之前会报「已被其他主体添加」。查重也只查本主体。
- 新增迁移 20261116010000-scope-nvr-unique-to-subject 与按主体范围的测试。

构建
- android_client/build.ps1:gradle 把 javac 的 stderr 提示写出来时,PowerShell 的
  $ErrorActionPreference='Stop' 会把它当终止错误,release 包必失败;改为只以退出码判定。

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-11-16 02:43:26 +08:00

106 lines
5.2 KiB
Markdown
Raw Permalink 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 无输入自动提交;不要再调大。
- **结束键要按设备判定**:有的枪(Newtologic DW-8200)发 `KEYCODE_DPAD_CENTER` 而不是回车;
结束键集合包含 DPAD_CENTER,但必须 `event.getDeviceId()` 等于「刚发过条码字符的设备」,
否则遥控器 OK 会被误判,枪的 DPAD_CENTER 还会激活焦点按钮(进设置页/清空记录)。
- 条码清理用首尾字符扫描,不要用正则。
## 语音播报
- 设备只有 `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` 逻辑复制进来。