wms_worker_station/README.md
liufumingren b69acb26d6 docs(readme): 新增 X9R 机型注意 - 供电/USB 口/固件差异(2026-09-25 实测)
现场"扫着扫着就扫不上、重启才好"的实测根因是硬件,写进 README 供装机/巡检执行:

- 电源必须 ≥12V/2.5A(推荐 3A):12V/2.0A(24W) 满载实测出现 2 次 usb 2-1(内部 Hub) +
  usb 2-1.4(扫码枪) 掉线、device not accepting address error -71、4 次总线复位,枪离线 13/120;
  2.5A 与"2A 但撤掉音响"均为 0 掉线、枪 120/120。
- 禁止从平板 USB 口给音响取电:与内部 Hub/扫码枪共用 5V 支路,语音播报峰值触发过流 ->
  先掉 Hub 再掉枪 -> 应用侧 keys=0。给出 dmesg 判据与四种正确接法。
- 其他机型注意:adb 换 USB 口才认设备;该固件 WebView 实现是 Chrome 不可卸载;
  开机自启需先手动启动过一次(stopped/notLaunched 检查命令);扫码枪身份与 event 节点;
  满载 75℃ 散热建议;建议走网线。
- 现场排查工具与排查口诀(keys=0 -> 查 dmesg)。
2026-09-25 17:05:42 +08:00

125 lines
9.0 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.

# WMS 工作台(wms_worker_station)
## 真机调试热更新(dev:adb)
`npm run dev:adb` 一条命令完成真机调试闭环:
1. 自动列出所有 ADB 设备(多台时交互选择,单台自动选中)
2. 进程常驻,监听 `src/` 与原生工程源码(`simpleDemo/src/main/java`、`AndroidManifest.xml`)
3. 保存文件后自动:`build:app` → 离线打包(gradle 增量) → `adb install -r` → 启动应用(约 20 秒/轮)
4. **真机 console 实时打印到终端**(含视图层 renderjs)
可选参数:
- `npm run dev:adb -- --no-launch`:重装后不自动启动应用
- `npm run dev:adb -- --adb=D:\path\to\adb.exe`:自定义 adb 路径(默认自动探测 SDK)
console 转发原理(release 包 console 默认不进 logcat):
- 逻辑层:`src/main.js` 接管 `console.*` 与 uni-app 内部日志 `uni.__log__`(编译后的 console.log 走它),转发到 logcat tag `UniConsole`
- 视图层:`src/render-common/viewport-fix.js` 的 `installConsoleForward()`,各页 renderjs 调用,tag `UniViewConsole`
注意:不要 watch `simpleDemo/src/main/assets` 与 `res`(构建注入产物),否则构建自触发死循环(已在脚本中排除)。
## ⚠️ 真机坑:登录页 reLaunch 到打包模式白屏(切后台回前台才恢复)
### 现象
- 真机(RK3288 工控机 / Android 7.1.2,系统 WebView = Chromium 52)上,从登录页 `uni.reLaunch` 到打包模式页(`/pages/packaging/index`)后**整个页面白屏**;
- 按 Home 退后台再切回前台,页面恢复正常显示;
- 服务层逻辑正常执行(页面 onLoad/onShow/mounted 都跑了,toast/语音也正常),只有渲染层白屏。
### 根因
- reLaunch 创建的新页面 WebView 初始**视口为 0×0**(`window.innerWidth/innerHeight` 都是 0,`document.body` 尺寸 0×0);
- 全局 CSS 的 `html { font-size: min(5.2734375vw, 7.91015625vh) }` 依赖视口,视口为 0 时 fontSize 计算为 **0px**;
- 本项目全站用 rem 布局,fontSize=0 → 所有 rem 尺寸归零 → 白屏;
- 切后台回前台时 Activity resume 触发原生重排,视口恢复(961×640 CSS 像素,dpr=2 对应物理 1920×1280),页面随即正常。
### 诊断方法(重要,后续排查类似问题照此做)
- **renderjs 的 `console.log` 在 release 包里拿不到**(不会输出到 logcat);
- 必须用原生日志:`plus.android.importClass('android.util.Log').i('TAG', msg)`,然后 `adb logcat | grep TAG`;
- 轮询观察视口:`setInterval` 里打印 `window.innerWidth + 'x' + window.innerHeight` 与 `document.documentElement.style.fontSize / getComputedStyle(...).fontSize`。
### 修复(已落地,公共逻辑抽离到 `src/render-common/viewport-fix.js`)
- 在页面 renderjs 的 `mounted` 里 `import { installZeroViewportFix } from '../../render-common/viewport-fix.js'` 并调用一次,检测视口 0×0 时强制原生 Activity 重排自愈;
- 新页面接入示例:
```js
// 页面 .vue 内的 renderjs 模块
<script module="remInject" lang="renderjs">
import { installZeroViewportFix } from '../../render-common/viewport-fix.js'
export default {
mounted() {
// #ifdef APP-PLUS
installZeroViewportFix() // 视口自愈(0×0 → requestLayout+invalidate)
return // 注意:APP 端 renderjs 不覆盖 fontSize,rem 由 App.vue 全局 CSS 承担
// #endif
// H5 端 rem 逻辑...
},
}
</script>
```
### 后续开发注意
1. **不要**在页面 renderjs 的 APP 端覆盖 `html` fontSize(真机 rem 统一由 `App.vue` 全局纯 CSS 承担,renderjs 覆盖会导致字号/布局异常);
2. **不要**在新页面 WebView 创建早期(onLoad)调用 `plus.screen.lockOrientation` / `plus.webview.currentWebview().setStyle` 等 native 操作——实测无效且会触发 `AdaUniWebView` 的 `ViewOptions.updateViewData` NPE。横屏由 `manifest.json` 的全局 `screenOrientation` 配置承担,打包页的 lockLandscape 已因此移除;
3. 若新增页面在真机出现同样白屏,按上面的示例接入 `installZeroViewportFix` 即可;
4. 排查白屏类问题先看**视口尺寸**(renderjs 里打 Log),而不是猜字体/样式——0×0 视口下 CSS 的 vw/vh 全部失效是这类白屏的典型特征。
## ⚠️ 机型注意:X9R 工控机的供电 / USB 口 / 固件差异(2026-09-25 实测)
> 结论先说:这台机器的「扫码突然没反应」**多数不是软件问题**,而是供电不足或 USB 口上挂了耗电外设。
> 装机、巡检、换电源前请先读本节。实测机型:X9R(RK3288 / Android 7.1.2 / 内核 4.4.112)。
### 一、电源:必须 ≥12V/2.5A(推荐 3A)
| 电源 | 满载实测(屏幕最亮 + 4 核满载 60s) | 结果 |
|---|---|---|
| 12V/**2.5A** | USB 掉线 0 次,扫码枪全程在线(120/120) | ✅ 可用 |
| 12V/**2.0A**(24W) | dmesg 出现 **2 次 `usb 2-1: USB disconnect`**(内部 USB Hub 与扫码枪一起掉)、`device not accepting address, error -71`、4 次总线复位;采样中枪离线 13/120(约 6.5s) | ❌ 临界,不可用 |
24W 是**临界值**:屏背光最亮 + WiFi + 内部 USB Hub + 扫码枪 + 喇叭峰值很容易越过它。
### 二、⛔ 绝对不要从平板 USB 口给外设(音响)供电
**现象**:插上 USB 音响后「扫着扫着就扫不上」,重启设备才恢复;**12V/2.5A 电源现场同样复现**。
**根因**:音响与内部 USB Hub、扫码枪共用同一条 5V 支路(USB 口规范每口仅 0.5A,音响常远超)→ 一放音(尤其每次扫码后的**语音播报峰值**)Hub 就过流跳闸 → 先掉 Hub(`usb 2-1`)再掉枪(`usb 2-1.4`)→ 应用侧表现就是 **`keys=0`(一个按键都收不到)**。
**现场判据(不用拆机、不用 root)**:
```bash
adb shell "dmesg | grep -E 'USB disconnect|error -71' | tail -20"
```
- 同时出现 `usb 2-1:`(Hub)与 `usb 2-1.x`(枪)→ **USB 口上挂了耗电外设 / 供电不足**;
- 只有 `usb 2-1.4`(枪)单独掉 → 更可能是枪的线材/接头。
**正确接法**:① 音响自带电源适配器;② 用**带独立供电的 USB Hub**(Hub 自己给音响供电,平板只出信号);③ 蓝牙/自带电池音箱;④ 若必须吃 12V,从 12V 母线单独引一路,不要走平板 USB 口。
### 三、其他机型相关注意
| 项目 | 说明 |
|---|---|
| **adb 认不到设备** | 同一台机器**换个 USB 口可能就认**:实测某个口 Windows 会把 `USB\VID_2207&PID_0006` 绑成通用 WinUSB 驱动,`adb devices` 全空;换口后立刻正常。**先换口/换线,别急着装驱动** |
| **不要卸载 Chrome** | 该固件 WebView 实现就是 Chrome(`adb shell settings get global webview_provider` = `com.android.chrome`),卸了打包页直接白屏;`com.android.webview` 同样必须保留 |
| **开机自启的前提** | 自启靠原生 `BootReceiver`(`BOOT_COMPLETED` / `QUICKBOOT_POWERON`)。**新装机或被 `force-stop` 后必须手动启动一次**(Android 3.1+ 规则);检查:`adb shell dumpsys package com.gztbyc.sandan \| grep 'User 0'` 需为 `stopped=false notLaunched=false` |
| **扫码枪身份** | USB HID 键盘(`Newtologic DW-8200`,VID_060E:PID_0960),挂在 `usb-1.4` → `/dev/input/event4`,供后续排查对照 |
| **散热** | 4 核满载实测 75℃(室温环境、无散热片);7×24 使用建议加散热片/小风扇,否则会热降频 |
| **网络** | 建议走网线(`eth0` 存在但默认无链路,先确认机器有没有 RJ45 口);WiFi 是 Broadcom SDIO,做常驻服务不稳 |
### 四、现场排查工具
| 工具 | 用途 |
|---|---|
| 诊断面板 | 打包页标题**3 秒内连点 5 次**(退件页为「拆包工作台」同操作):实时看按键到达 / 丢弃原因 / 门控快照 / 自愈次数,可复制与一键上报 |
| `scripts/scan-forensics.ps1` | 故障**当场**一键取证:内核按键流 + dmesg + App 心跳 + 自动判据(内核有事件而 App `keys=0` → 上层;内核无事件 → 枪/线/供电) |
| `scripts/power-probe.sh`、`scripts/power-load-test.sh` | 电源/负载对比实测(采样 ADC、温度、CPU 频率、扫码枪是否仍在总线) |
| logcat | `adb logcat -s WMSScan`(扫码链路)、`WMSPage`(页面生命周期)、`UniConsole` / `UniViewConsole`(JS 日志) |
> 日志上行已做降噪(2026-09-25):本地明细全部保留(面板 + logcat + 环形缓存),**只有异常才上报服务端**(主线程卡顿、真自愈、活动突然中断),正常扫码不再产生上行记录。
### 五、排查口诀
1. 先看诊断面板的 `按键到达`:**`keys=0` → 按键根本没到 JS**,转第 2 步;有 `keys` 但业务没生效 → 看 `丢弃统计` 的 reason(属 JS 门控,按 reason 定位)。
2. `keys=0` 时执行上面那条 `dmesg | grep -E 'USB disconnect|error -71'`:**有输出 → 供电 / USB 口外接耗电外设**(见本节一、二);无输出 → 枪 / 线材 / 系统扫码服务。
3. 长跑中「突然扫不上、重启才好」几乎都是第 2 步命中的供电类问题:先换电源、拔掉 USB 音响,再复核。