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

5.2 KiB
Raw Permalink Blame History

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 -NoProfile -ExecutionPolicy Bypass -File tools\android.ps1 build

或:

$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 逻辑复制进来。