wms_worker_station/README.md
zm2000 b422bfad08 fix(真机兼容): 退件页间距改用 margin + 订单复核页按钮样式修复
真机 WebView 实测为 com.android.webview 52.0.2743.100(Chromium 52),
flex gap 需 Chrome 84+,因此全站 gap 在真机上一律不生效。

退件页 src/pages/returns/index.vue
- 24 处 gap 全部改用 margin(相邻兄弟 / 子项外距):
  左栏卡片 0.15rem、右栏卡片 0.15rem、扫码指令行 0.1rem、
  正常/破损 0.1rem、提交/删除/清除 0.1rem、字段标签 0.04rem,
  以及明细、对照汇总、备注弹窗、分页等同类间距
- 选择器写成 .容器 > .rp-btn + .rp-btn(0,2,0):.rp-btn 自带 margin:0,
  同权重的 > * + * 会被覆盖,间距失效
- 顺带修「扫码指令被压扁 / 与工作台卡片贴住」:
  .rp-left > .rp-card { flex-shrink: 0 }(高度不足改为左栏滚动)
  .rp-cmd-bc { flex: 0 0 0.36rem }(原 min-height:0 会把条码区压成 0)

订单复核页 src/pages/order/index.vue
- 复核设置分段按钮去掉 gap 改子项 margin-right,补 height/line-height 0.4rem 防真机裁字头
- 工具栏按钮颜色变体改硬编码色值 + 0.02rem 完整 border,并加 !important
  压过 uni-button 内置样式(真机曾出现「橙底白字」变「白底黑字」)

README
- 作废 2026-09-26「gap 真机生效」的结论,改回「Chromium 52 不支持 flex gap,间距一律用 margin」
- 新增「按钮颜色被 uni-button 内置样式覆盖」踩坑说明与 !important 对策

验证:adb 截图 + 像素采样(gap:0.15rem 的两卡片之间实测空隙为 0);npm run build:app 通过
EOF
2026-10-27 18:20:58 +08:00

381 lines
30 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)
## UI 排版规范(全站强约束)
> 一句话:**布局用 rem(1rem = 100px),间距用 5px 网格;控件高度 36px,行高两档,字号 10 档,圆角 3 档,控件内嵌图标取控件高度的 55~60%。**
> 新增页面/组件照此写;改动旧页面时按本节重新排一遍。
> 页面级结构与自查见 **第 14 节**;真机平台注意见 **第 13 节**。
### 1. 尺寸基数:1rem = 100px
- 唯一实现 `src/render-common/rem-base.js`:`html.fontSize = 100 × min(1, 视口宽 / 1280)`
- **宽度 ≥1280 一律 1rem = 100px**(1280 / 1920 / 2560 / 4K 都一样,也不看窗口高度);
- 窄于 1280 等比缩小,下限 50px(640 宽)。
- 口径:**CSS 里的 rem 值 = 设计稿像素 ÷ 100**(写 `0.5rem` 就是 50px)。
- 真机 APP-PLUS 由 `App.vue` 的 `html { font-size: 7.8125vw !important }` 承担;`7.8125vw = 100/1280`,**必须精确,不要取整**。
- **小数位最多 2 位**(2 位 = 1px 精度,误差 ≤0.5px),`0.20` 写成 `0.2`。
- **媒体查询里不要用 rem 写断点**:媒体查询中的 `rem` 按**初始 16px** 解析,与本项目 1rem = 100px 不是一套(例如写 `20.48rem` 实际是 327px,永远不会触发)。
本项目**不需要窄屏断点**:宽度 <1280 时整站按比例缩放(下限 0.5 倍 = 640px 宽);桌面窗口由 `electron/main.js` 的 `minWidth: 1024` / `minHeight: 640` 兜底。
如需新增断点,写**真实 px** 并注明理由。
### 2. 控件高度 / 行高
| 类型 | rem | ≥1280 时 | 用途 |
|---|---|---|---|
| 控件 | `0.36rem` | 36px | **按钮、输入框、下拉、tab、步进按钮全部统一这一档** |
| 表格/列表行 | `0.5rem` 左右 | 50px | 表格行、列表行(订单表格实为 `0.52`/`0.56rem`,以内容为准) |
| 顶栏 | `0.7rem` | 70px | 顶栏高度,内行由 `0.5rem` 的 logo 决定 |
- **控件不要再写 `0.5rem` 高度**(2026-09-25 已全站从 0.5rem 降到 0.36rem);`80px`/`120px` 是移动端口径,PC 上更不要用。
- 图标、图片、头像、缩略图等**非控件**不套这几档,按内容尺寸走。
- **控件内部的图标/徽标/字形**另有比例要求(可见标记 ≈ 控件高度的 55~60%),见第 12 节。
- 按钮**不要写死宽度**:给高度 + 左右 `padding`,宽度跟内容走。
- 给 `button` 设高度时**必须同时设 `line-height`**(uni-app 默认 `line-height: 2.55555556`,不设会文字偏移/被裁)。
- 多行粘贴框(订单页 `.batch-review-input`)例外,按内容给高度。
### 3. 字号:只有 10 档
| token | rem | ≥1280 | 用途 |
|---|---|---|---|
| `--wms-font-xs` | 0.15 | 15px | 标签、角标、辅助提示 |
| `--wms-font-sm` | 0.17 | 17px | 说明文字 |
| `--wms-font-base` | 0.18 | 18px | 正文、表格 |
| `--wms-font-md` | 0.2 | 20px | 正文强调 |
| `--wms-font-lg` | 0.21 | 21px | 卡片标题 |
| `--wms-font-xl` | 0.22 | 22px | 导航菜单、大标题 |
| `--wms-font-title` | 0.25 | 25px | 页面/弹窗标题 |
| `--wms-font-2xl` | 0.3 | 30px | 大号数值(称重输入、数量) |
| `--wms-font-3xl` | 0.35 | 35px | 合计、重点数字 |
| `--wms-font-4xl` | 0.45 | 45px | 强调大字(打包拦截提示等) |
- 全站字号已统一 ×0.85(只降文字、不降布局尺寸);**要调字号只改字号值,别动 rem 基数**。
- 浮层里的 `px` 字号(退件页摄像头浮窗 11/12/13px、`scan-diag-panel.vue`)是有意为之,不参与本刻度。
### 4. 间距:5px 网格
- `padding` / `margin` / `gap` 取 **`0.05rem` 的倍数**(5 / 10 / 15 / 20 / 25 / 30 …px)。
- 紧凑标签、角标的**内部微内边距**可取 **`0.02rem` 的倍数**(2 / 4px),不要再出现第三种写法。
- 行高与控件高度不受本网格限制(走第 2 节的 36 / 50 / 70)。
### 5. 圆角:3 档 + 圆
| 档位 | rem | 用途 |
|---|---|---|
| 角标 | `0.03rem` | 小标签、角标 |
| 控件/小卡片 | `0.07rem` | 按钮、输入框、标签、小色块;列表/信息类小卡片(退件 `.rp-card`、订单左栏卡片) |
| 大容器 | `0.13rem` | 页面级面板/弹窗(`.pack-card`、`.popup-card`、`.update-dialog`、`.container`) |
| 圆形 | `50%` | 头像、圆形图标按钮 |
### 6. 边框:1px
- 常规边框统一 `0.01rem`(≥1280 正好 1px)。
- 例外只有两种:图标描边/装饰虚线 `0.02rem`(2px)、左侧强调条/对齐条 `0.05rem`(5px)。
### 7. 颜色:用 token,不写死高频色值
- 颜色/圆角/字号都集中在 `src/styles/base.css` 的 `:root`,页面里写 `var(--wms-*)`:
`--wms-primary`、`--wms-primary-alt`、`--wms-success`、`--wms-warning`、`--wms-danger`、
`--wms-text` / `-strong` / `-secondary` / `-tertiary` / `-muted` / `-placeholder` / `-disabled`、
`--wms-page-bg`、`--wms-card-bg`、`--wms-bg-subtle`、`--wms-bg-tint`、`--wms-border` / `-alt` / `-light` / `-strong`、`--wms-white`。
- **页面底色全站统一 `--wms-page-bg = #e8eaed`,各页不要自己写底色**(登录页、打包页原先各写 `#f2f2f2` / `#e8eaed`,已统一)。
它比 `#f8f8f8` 深一档:与白卡片对比 **1.21 : 1**(`#f8f8f8` 只有 1.06 : 1),这样白色卡片才「立」得起来。
页面级框架背景在 `pages.json` 的 `globalStyle.backgroundColor`,与 token 保持同值。
- 纯白分两种写法:**底色**用 `var(--wms-card-bg)`,**文字/描边**用 `var(--wms-white)`。
- 一次性特殊色(渐变、遮罩、阴影里的 `rgba()`、品牌图标色)可以直接写。
### 8. 布局:% / flex 负责伸展,rem 负责封顶
- **大屏表现**:宽度 ≥1280 后所有 rem 尺寸封顶,只做布局变化——多余空间给主区(`flex: 1; min-width: 0`),**不要给窄侧栏**。
- 窄侧栏统一 `flex: 0 0 3.8rem`(380px),三页(订单左栏 / 打包右栏 / 退件左栏)保持一致。
- **主体到页边的留白全站统一**:`--wms-page-pad` = `0.25rem`(25px),由基准 `.page-main` 的
`padding: 0.05rem var(--wms-page-pad) var(--wms-page-pad)` 提供;顶栏 `margin-bottom: 0.2rem` + 上 0.05 = 25px,**四边视觉留白一致**。
- 页面内层容器**不要再加内间距**,否则和基准叠加(订单 `.container` 已置 0;打包页没有 `.page-main`,`.mode-main` 直接取同一个 token)。
- 顶栏(`top-nav`)与打包页顶栏(`.mode-topbar`)的水平内边距也用 `var(--wms-page-pad)`,保证 logo/内容左右对齐。
- **主体内左右分栏间距统一 `--wms-panel-gap` = `0.15rem`(15px)**:
订单 `.panel-left { margin-right }`、退件 `.rp-left { margin-right }`、打包 `.pack-right { margin-left }`(三页统一用 `margin`,保持一致)。
> **更正(2026-10-27)**:2026-09-26 记的“`gap` 在真机生效”**是错的**。真机 `webview_provider` = `com.android.webview`,
> `versionName = 52.0.2743.100`(Chromium 52),flex `gap` 要 Chrome 84+ 才有 → **真机上 `gap` 完全失效**
> (退件页曾用 `gap: 0.15rem` 分隔两张卡片,像素级采样量到空隙为 **0**)。
> 结论:**间距一律用 `margin`**;页面里现存的 `gap` 要逐步换成 `margin`(同一处只能留一种)。
- 页面骨架统一用 `.page` / `.page-main`,每页只写差异项。
- **侧栏内容用「灰底 + 白卡片」**:侧栏自己不要铺底色(订单左栏、退件左栏都是透明灰底,与右栏一致);里面的每一块(搜索、列表、底部信息栏)做成独立白卡片,卡片间距 `0.15rem`、卡片内边距 `0.15rem`。
- 滚动方式各页自定:整块滚用 `overflow-y: auto`(订单、称重);面板各自滚用 `overflow: hidden` + 子面板 `auto`(退件)。
### 9. 样式放哪:全局在 base.css,个性化在页面
- 6 个页面都要用的 → `src/styles/base.css`(`App.vue` 的 `<style>` 顶部 `@import` 引入;编译后顺序在所有页面 CSS 之前,页面同权重规则天然覆盖基准)。
- 单页面用、或与基准不同的 → 写在页面 `<style>` 里,只写差异项。
- **不要**把页面骨架类改造成公共类去复用:`.page` / `.page-main` 是跨页共用类名(首页用 `keep-alive` 内嵌其它页),加公共类会把别页的 `padding` / `overflow` 套到自己身上。
- 页面 `<style>` 没有 `lang="scss"`,`uni.scss` 的 scss 变量在页面里不可用 → 基准统一用 **CSS 变量**。
### 10. 提交前自检
```bash
npm run lint:layout # 代码级自检:字号/圆角/间距网格/rem 小数位/颜色 token
```
- [ ] 控件高度是 `0.36rem`(表格/列表行 ≈ `0.5rem`),顶栏 `0.7rem`;按钮没写死宽度,设了高度就设 `line-height`
- [ ] 间距是 `0.05rem` 的倍数(微内边距是 `0.02rem` 的倍数)
- [ ] 字号在 10 档内、圆角在 3 档内、边框 `0.01rem`(例外:图标描边 0.02、强调条 0.05)
- [ ] 颜色用 `var(--wms-*)`,没有写死 `#333` / `#2f7dff` / `#909399` 这类高频色
- [ ] 控件内嵌图标/字形 ≤ `0.22rem`,且点击热区与可见标记分开写(第 12 节)
- [ ] 没新增 flex `gap`;`position: sticky` 带了 `-webkit-` 前缀;没在媒体查询里写 rem(第 13 节)
- [ ] rem 值最多 2 位小数;没有动 `7.8125vw`
- [ ] `npm run build:h5` 通过
> 代码级自检只能盖住可量化的部分(字号/间距/小数位);**尺寸比例、图标大小、真机表现这类“看得见”的问题必须先在 dev 里量尺寸或截图确认**(见第 14 节自查)。
### 11. 本地画图:二维码/条形码一律视图层现画,不走远程出图
- **原因**:远程出图(`.../grcode/build?text=`、`api.qrserver.com` 兜底)在断网、内网隔离、服务不可用时二维码直接出不来,
且真机每次都要联网取图。扫码登录二维码、工作台绑定码已全部改为本地绘制。
- **二维码**:`src/render-common/qr-render.js`(依赖 `qrcode-generator`,devDependency:纯 ES5、零运行时依赖、约 15KB)。
用法固定为「属性传内容 + 视图层画」:
```vue
<view class="scan-image" :data-qr-text="scanQrText"></view>
```
```js
// 页面 renderjs 模块
import { paintQrIn, watchQrIn } from '../../render-common/qr-render.js'
mounted () {
// 视图层副作用(画二维码/条形码、console 转发、视口自愈)直接写在最外层:
// 它们 H5 与真机都要跑,不要包进任何 #ifdef 里
this.paintQrCodes() // 内部:paintQrIn + 80/600/1500ms 兜底 + watchQrIn
// #ifndef APP-PLUS
// 只有 H5/Electron 需要的东西(如 rem 初始化)包在 #ifndef 里,
// ⚠️ 不要用 `#ifdef APP-PLUS + return`(会让 esbuild 报 semicolon-after-return,
// 而且以后补的视图层代码会变成真机永不执行)
// #endif
}
```
- **约定**:`data-qr-text` 存**二维码内容**(不是图片地址);画完打 `data-qr-drawn` 记录已画内容,内容不变不重画
(绑定码轮询每 1.5s 一次,不做这层判断会一直重绘);容器用 `childList` + `attributeFilter` 监听,`v-if` 首次插入也会画。
- **绘制细节**:静区 4 模块(少了真机扫不出)、白底、`shape-rendering: crispEdges`(缩放不抗锯齿)、同色连续模块横向合并成一个 `rect`(节点数约减半)。
- **容器要求**:固定正方形(登录页 `0.36rem` 级控件之外的 `1.47rem` 图),**不要加 `border-radius` / `overflow: hidden` 剪裁**,否则会把码切掉导致扫不出。
- **条形码**同理:退件页 `JsBarcode` → SVG(`data-bc-code`,见该页 renderjs)。
- **验证方式**(改完照着做一遍):① 反推 SVG 矩阵与库矩阵逐格比对(0 差异);② 用独立解码器(如 `jsqr`)回环解码等于原文;③ 真机实扫。
### 12. 控件内嵌元素:图标 / 徽标 / 字形
- **可见标记取控件高度的 55~60%**:36px 控件里放 `0.2rem`~`0.22rem`(20~22px),上下各留 7~8px 白边。
- 输入框清除圆标:`0.22rem` 圆 + `0.01rem` 描边 + `0.15rem` 字形 + `line-height: 0.2rem`(配 `box-sizing: border-box`)
- 密码可见图标 `0.2rem`;下拉箭头 `0.2rem`;搜索框清除字形 `0.18rem`(36px 灰圆本身保留)
- **点击热区与可见标记必须分开写**:热区保持控件尺寸 `0.36rem`(透明、**不加边框**),可见圆标/图标放子元素上。
- 坑:`content-box` 下给 `0.36rem` 的盒子再加 `0.01rem` 边框,实际占位 38px,会比 36px 输入框高出 2px 溢出上下边(登录页清除圆标原来就是这样)。
- 圆形一律 `border-radius: 50%`;描边用 `0.01rem`(`0.02rem` 是装饰虚线档)。
- 图标统一用内联 `<svg>`(`viewBox` + `width/height: 100%`),尺寸由外层盒子控制,不要在 `svg` 上写死 px。
- 反例(2026-09-25 已全改):圆标和输入框同高、眼睛图标 `0.3rem` 顶满输入框、下拉箭头 `0.3rem`、搜索清除字形 `0.25rem`。
- 非控件图形(商品图 59px、头像 42.6px、缩略图 36px、表格行 50px+)按内容尺寸走,不套本节的 55~60%。
### 13. 真机平台注意(WebView 由 Chrome 应用提供)
> **更正(2026-10-27)**:2026-09-26 那条“`gap` 在真机生效 / WebView 由 Chrome 应用提供”的结论**已作废**。
> 实测 `adb shell settings get global webview_provider` = `com.android.webview`,
> `adb shell dumpsys package com.android.webview | findstr versionName` = **52.0.2743.100(Chromium 52)**,
> 所以 **flex `gap`(Chrome 84+)不支持**:退件页 `gap: 0.15rem` 的两张卡片,按列采样像素量到的空隙是 0。
> 验证手法:`adb exec-out screencap -p > shot.png` 后用 `build/measure.ps1`(按列/行采样像素)量真实间距,比肉眼看截图可靠。
**与 WebView 版本无关的硬约束(务必遵守)**
| 约束 | 说明 | 对策 |
|---|---|---|
| 媒体查询里的 `rem` 按初始 16px 解析 | CSS 规范行为,任何版本都一样:写 `20.48rem` 实际是 327px,永不触发 | 断点用真实 px(第 1 节) |
| 新页面早期视口可能是 0×0 | 此时 `vw/vh` 全为 0 → rem 归零 → 白屏(真机实测过) | `viewport-fix.js` 已自愈,见下文「真机坑」 |
| `html { font-size: 7.8125vw }` 不能取整 | 取整会让 1rem 不是整 100px | 保持原值 |
| `content-box` 下加边框会撑大尺寸 | 给 0.36rem 盒子加 0.01rem 边框实际占 38px | 写 `box-sizing: border-box`(第 12 节) |
**新 API / 新语法:先确认再用(不要照抄旧结论)**
- 历史上为“老 WebView”规避过:flex `gap`、`replaceChildren`、`Element.append/prepend/before/after`、CSS `min()/max()/clamp()`、CSS Grid、无前缀 `position: sticky`。
其中 **`gap` 已实测不可用**(Chromium 52),间距必须用 `margin`;其余**没有实测过是否必需**,属于保守写法:
- 视图层 renderjs 保持 ES5 写法(少一层降级不确定性);
- `position: sticky` 同时写 `-webkit-sticky`(老 WebView 只认前缀;新 Chrome 前缀仍有效、无副作用);
- 换 DOM 节点用 `appendChild` / `removeChild` 就够,没必要引入新 API。
- **要用新的 CSS/JS 特性前,先用上面的命令查真机版本或在真机上实测**,别拿本文件的历史结论当限制。
### 14. 页面规范:结构 / 骨架 / 公共类 / 新增页面自查
**页面文件结构(每个 `.vue`)**
- **只能有 2 个 `<script>` 块**:主逻辑 + `<script module="remInject" lang="renderjs">`;多一个 dev 就报
`Single file component can contain only one <script> element`(遮罩 + 页面卡住)。
- `<style>` 不带 `lang="scss"`(`uni.scss` 的变量在页面里不可用)。
- renderjs 的 `mounted()` **不要用 `#ifdef APP-PLUS … return … #endif` 的写法**(2026-09-26 统一改掉):
- 真机 rem 交给 `App.vue` 的 CSS,所以 rem 初始化包在 **`// #ifndef APP-PLUS`** 里(H5/Electron 照常执行,真机整块被抖掉);
- 视图层副作用(画二维码/条形码、`installZeroViewportFix()`、`installConsoleForward()`)H5 与真机都要跑,**直接写在最外层**,不要包进任何 `#ifdef`;
- 旧写法(`#ifdef APP-PLUS` + `return` + 后续代码)会让 esbuild 报 `[semicolon-after-return]`(真机死代码),而且后续新增的视图层代码会变成真机永不执行 —— 6 个页面已全部改为 `#ifndef` 包裹。
- 双 script 页面改 CSS,dev 下 HMR 会失败 → **必须刷新页面**才看到效果(`npm run build:h5` 不受影响)。
**页面骨架(每页只写差异项)**
| 项 | 基准来源 | 页面要不要写 |
|---|---|---|
| 页面底色 | `.page` → `--wms-page-bg` | 不写(要例外时写 token,不要写死色值) |
| 主体留白 25px | `.page-main` → `--wms-page-pad` | 不写;内层容器不要再加内边距 |
| 左右分栏间距 15px | `--wms-panel-gap`(**用 margin**) | 侧栏自己写 `margin-right` / `margin-left` |
| 顶栏 70px | `.top-nav` / `.mode-topbar`:`0.7rem` + 水平 `var(--wms-page-pad)` | 顶栏内 logo `1.33rem × 0.5rem` |
| 滚动方式 | 无基准 | 自己写:整块滚 `overflow-y: auto`;面板各自滚 `overflow: hidden` + 子面板 `auto` |
- **卡片三级**:页面级容器(`.container` / `.pack-card` / `.popup-card`)`0.13rem` 圆角;信息卡片(`.rp-card`、订单左栏卡片)`0.07rem`;**卡片内边距与卡片间距都 `0.15rem`**。
- **列表/表格**:行高 `0.5rem` 档(订单表格 `0.52`/`0.56rem` 以内容为准);表头要吸顶按第 13 节写前缀 `sticky`。
- **空状态**统一 `.empty-panel`(`0.07rem` 圆角),左栏用 `.empty-panel--left`(`margin-top: 0`)。
- **接入首页菜单**:在 `src/router/menuRoutes.js` 的 `menuRouteMap` 里同时注册短路径(`/order`)与完整路径(`/pages/order/index`),否则 URL 跳转解析不到页面。
**公共类清单(都在 `src/styles/base.css`,新增同类需求先看这里)**
- 骨架:`.page` / `.page-main`
- 工具类:`.scan-hidden-input`(隐藏的扫码输入框,四页共用;打包页只覆盖 `top: 0`)
- 按钮去默认边框的 `::after`:目前 12 个类集中写在 base.css 的选择器列表里,
**新增自定义 `uni-button` 按钮必须把类名补进这个列表**,否则会带上框架默认的 `1px solid rgba(0,0,0,.2)` 边框。
- **按钮颜色被框架内置样式覆盖(2026-10-27 踩坑)**:真机 APP-PLUS 的 `<button>` 渲染成 `<uni-button>` 自定义元素,
框架内置 `uni-button[disabled]:not([type]){background:#f7f7f7}`(特异性 (0,3,1))等规则**优先级高于自定义类**(`.tool-btn--orange` 只有 (0,1,0)),
会把按钮颜色覆盖成「灰白底黑字」(典型:面单补打应是橙底白字,真机却白底黑字)。
**给自定义按钮颜色变体的 `background-color` / `border` / `color` 加 `!important` 才能压过内置样式**;
禁用态同理(`.tool-btn[disabled]` 也要 `!important`,否则被 `uni-button[disabled]:not([type])` 抢走)。排查「web 正常、真机按钮颜色不对」时优先怀疑 uni-button 内置样式,而不是 CSS 变量/颜色值本身。
**新增/修改页面的自查(§10 只能盖住可量化部分)**
- [ ] dev 里真看过:用 `getBoundingClientRect()` 量过关键尺寸,或截图对比过
- [ ] 没有新增 flex `gap`;`sticky` 带了 `-webkit-` 前缀;图标符合第 12 节比例
- [ ] 从别的页面复制来的样式,把不属于本页的差异项删掉(内边距、`overflow`、残留 `@media`)
- [ ] 窄屏(H5 缩到 <1280 宽)与真机各看一遍布局没被压坏
## 真机调试热更新(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 由 Chrome 应用提供)上,从登录页 `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 全部失效是这类白屏的典型特征。
### 订单复核页(布局壳)与退出登录白屏(2026-10-25 补充)
同一套 reLaunch 视口问题,还波及两个场景:
1. **登录 → 布局壳 → 订单复核页白屏(偶发)**:订单复核页是布局壳 `pages/index` 里 `:embedded="true"` 的动态组件,没有独立的 onLoad/onShow 生命周期,完全依赖布局壳的 lockLandscape。布局壳(`pages/index`)与订单页(`pages/order`)的 lockLandscape **只保留 `plus.screen.lockOrientation('landscape')` 横屏兜底,禁止调用 `webview.setStyle`**——setStyle 在 WebView 未就绪时触发 `ViewOptions.updateViewData` NPE → 白屏(与上文第 2 条同源)。
2. **退出登录必须用 `plus.runtime.restart()`,禁止 reLaunch**:`top-nav.finishLogout` 若用 reLaunch 回登录页,退出后再登录 reLaunch 到布局壳会白屏;restart 重启进程恢复干净渲染才可靠(代价是闪一下启动图,`manifest.splashscreen.waiting=true` 让启动图持续到登录页渲染完成)。配套:登录页 `onShow` 读取 storage 的 `__logout_msg__` 回显「已退出登录」。
⚠️ 上述修复曾被 HBuilderX / 外部编辑器**整体回退**(finishLogout 改回 reLaunch、`__logout_msg__` 逻辑丢失、页面 lockLandscape 重新加了 setStyle)。改动后务必 grep 确认:`plus.runtime.restart`、`__logout_msg__` 仍在,且各页 lockLandscape 内**没有** `setStyle`。
## ⚠️ 机型注意: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,做常驻服务不稳 |
| **有线网重启后变回静态 IP** | 出厂默认就是 `STATIC 10.10.1.100/24`。本 ROM 的以太网服务把配置存在 **`/system/etc/ipconfig.txt`**(不是常见的 `/data/misc/ethernet/`),该文件在只读 `/system` 上,**在安卓设置里改成 DHCP 不会保存**,重启照旧读回静态。改法:`powershell -ExecutionPolicy Bypass -File scripts\set-eth-dhcp.ps1`(自动备份原文件、写入 DHCP 记录、重启并核对),恢复出场值用 `-Restore` |
### 四、现场排查工具
| 工具 | 用途 |
|---|---|
| 诊断面板 | 打包页标题**3 秒内连点 5 次**(退件页为「拆包工作台」同操作):实时看按键到达 / 丢弃原因 / 门控快照 / 自愈次数,可复制与一键上报 |
| `scripts/scan-forensics.ps1` | 故障**当场**一键取证:内核按键流 + dmesg + App 心跳 + 自动判据(内核有事件而 App `keys=0` → 上层;内核无事件 → 枪/线/供电) |
| `scripts/power-probe.sh`、`scripts/power-load-test.sh` | 电源/负载对比实测(采样 ADC、温度、CPU 频率、扫码枪是否仍在总线) |
| `scripts/set-eth-dhcp.ps1` | 把有线网默认改成 DHCP(重写 `/system/etc/ipconfig.txt` 后重启),带 `-Restore` 回滚;开机后网口要约 20s 才 Link Up,属正常 |
| 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 音响,再复核。