From e46feaaa0127e451935f296f5f2b3bc61935211c Mon Sep 17 00:00:00 2001 From: yin <3313488199@qq.com> Date: Sat, 22 Aug 2026 20:20:47 +0800 Subject: [PATCH] 1 --- docs/returnUnpackwork-扫码指令功能设计.md | 351 +++++++++ .../returnUnpackwork/CameraLivePreview.vue | 102 ++- src/views/express/returnUnpackwork/index.vue | 745 ++++++++++++++++-- .../express/returnUnpackwork/scan-commands.ts | 46 ++ 4 files changed, 1129 insertions(+), 115 deletions(-) create mode 100644 docs/returnUnpackwork-扫码指令功能设计.md create mode 100644 src/views/express/returnUnpackwork/scan-commands.ts diff --git a/docs/returnUnpackwork-扫码指令功能设计.md b/docs/returnUnpackwork-扫码指令功能设计.md new file mode 100644 index 00000000..f4357312 --- /dev/null +++ b/docs/returnUnpackwork-扫码指令功能设计.md @@ -0,0 +1,351 @@ +# returnUnpackwork 扫码指令条码功能设计 + +> 状态:设计稿(待评审) +> 涉及页面:`src/views/express/returnUnpackwork/index.vue` +> 目标:用扫码枪扫描「指令条码 / 运单号 / 商品条码」,**不依赖输入框焦点**自动路由并执行对应操作。 + +--- + +## 1. 需求概述 + +在拆包工作台引入「扫码枪全流程操作」,实现: + +| # | 需求 | 确认结论 | +|---|------|---------| +| 1 | 扫描「提交确认」条码 → 自动执行提交确认 | **单次直接执行**(条码即确认,跳过二次弹窗) | +| 2 | 扫描「切换产品状态」条码 → 切换产品状态 | **语义 A**:设置默认状态(先扫状态条码,再扫商品条码入库),纯前端、无需后端 | +| 3 | 未创建拆包时,**无论焦点是否在「运单号」输入框**,扫条码即输入运单号并创建拆包 | 焦点无关 | +| 4 | 已创建拆包后,**无论焦点是否在「商品条码」输入框**,扫条码即搜索并添加商品 | 焦点无关 | + +核心诉求:**扫码枪扫描结果不再依赖当前输入框焦点,统一由全局扫码路由接管。** + +--- + +## 2. 现状与问题 + +现有实现(`src/views/express/returnUnpackwork/index.vue`): + +- 运单号输入框 `@keyup.enter="handleCreate"`:仅焦点在运单号输入框时才触发创建。 +- 商品条码输入框 `@keyup.enter`/`@change="handleBarcodeQuickAdd"`:仅焦点在商品条码输入框时才触发快速添加。 +- 已有全局 `window keydown` 监听 `handleKeydown`(负责 ←/→ 切换焦点、Enter 提交确认、Esc 取消/清除)。 +- 产品状态由下拉 `defaultProductStatus` 控制,仅影响**后续快速添加**的明细;明细表产品状态列为只读 tag。 +- `returnUnpack.updateDetail` **不支持修改 `product_status`**(仅 quantity/remark)——这正是选择「语义 A」的原因。 + +**问题**:扫码枪是"键盘设备",当前行为完全依赖焦点所在输入框: +- 焦点不在对应输入框时,扫的条码会打乱到当前聚焦元素,动作不触发。 +- 需求 3/4 要求彻底解决该问题。 + +--- + +## 3. 目标行为定义 + +统一入口后,无论焦点在哪,一次扫码按**业务状态**路由: + +``` +未创建拆包单 + └─ 任何条码 → 当作「运单号」→ 创建拆包单 + +已创建拆包单(status = unpacking) + ├─ 指令条码 SUBMIT → 提交确认(单次直接执行) + ├─ 指令条码 NORMAL/DAMAGED → 切换默认产品状态(语义 A) + └─ 其他条码 → 当作「商品条码」→ 查询并快速添加 +``` + +--- + +## 4. 总体架构 + +在页面内新增一层 **扫码输入路由**,置于现有事件链之前: + +```mermaid +flowchart LR + A[扫码枪 / 键盘] --> B[全局 keydown 扫码缓冲
识别连续快速输入] + B --> C{判定为扫码输入?} + C -- 是 --> D[routeScan 业务路由] + C -- 否手工输入 --> E[现有输入框回车
/ 现有快捷键] + D --> F[创建拆包 / 指令动作 / 商品快速添加] +``` + +要点: + +1. 全局 `keydown` 收集**扫码缓冲**,用"字符输入间隔"区分扫码枪与手工键盘。 +2. 判定为扫码输入的字符**一律 `preventDefault()`**,不写入任何输入框 → 从根源避免脏数据与双触发。 +3. 扫码 Enter 触发 `routeScan(barcode)` 路由。 +4. 手工输入回车(焦点在输入框)仍走原输入框逻辑,与扫码互不干扰。 + +--- + +## 5. 指令条码定义 + +统一前缀 `UNPACK.`(与商品条码零冲突),识别时 `trim()` + 忽略大小写: + +| 指令 | 条码内容 | 动作 | +|------|---------|------| +| 提交确认 | `UNPACK.SUBMIT` | 调用 `returnUnpackSubmit({ id })`,成功即重置工作台 | +| 设为正常 | `UNPACK.NORMAL` | `defaultProductStatus = 'normal'` | +| 设为破损 | `UNPACK.DAMAGED` | `defaultProductStatus = 'damaged'` | + +> 集中管理:新增 `src/views/express/returnUnpackwork/scan-commands.ts`,导出指令常量与 `resolveScanCommand()` 解析函数。 + +### 5.1 条码制式(推荐 Code 128) + +指令条码贴纸用 **Code 128** 制式生成: + +| 维度 | Code 128 ✅ | EAN-13 | QR Code | +|------|-------------|--------|---------| +| 免费/专利 | 免费无专利 | 内部可用(零售厂商码需申请) | 免费 | +| 开销(贴纸尺寸) | **高密度**,短文本最紧凑 | 密度低且仅支持数字 | 点阵,占面积大 | +| 扫描性能 | **一维快速扫、识别率高** | 快速 | 需近距/对准,稍慢 | +| 字符支持 | 全 ASCII(字母+符号) | 仅数字 | 任意 | + +结论:**Code 128 免费、高密度、支持全 ASCII、一维快速扫,最适合指令条码**。`UNPACK.SUBMIT / NORMAL / DAMAGED` 均为 ASCII 文本,直接 Code 128 编码即可,无需改动指令内容。 + +--- + +## 6. 扫码输入识别(全局缓冲) + +在现有 `handleKeydown` 内新增扫码缓冲逻辑: + +``` +常量: + SCAN_INTERVAL_MS = 50 // 判定同一段扫码的最大字符间隔(可配置) + SCAN_MIN_LEN = 2 // 至少 2 个字符才判定为扫码(排除单字符回车) + +状态: + scanBuffer = '' + lastScanCharTime = 0 + +keydown 处理(在每个分支前先执行): + if (e.key 是单个可打印字符 && 非功能键/非组合键) { + const now = Date.now() + if (now - lastScanCharTime > SCAN_INTERVAL_MS) scanBuffer = '' // 新一段输入 + scanBuffer += e.key + lastScanCharTime = now + e.preventDefault() // 阻止写入输入框,杜绝脏数据 + return + } + if (e.key === 'Enter' && scanBuffer.length >= SCAN_MIN_LEN + && Date.now() - lastScanCharTime <= SCAN_INTERVAL_MS) { + const barcode = scanBuffer + scanBuffer = '' + lastScanCharTime = 0 + e.preventDefault() // 阻止输入框 @keyup.enter 双触发 + routeScan(barcode) + return + } +``` + +设计说明: + +- **时间间隔判定**:人类手工打字字符间隔普遍 > 100ms,扫码枪连续输入 < 50ms,阈值 50ms 可可靠区分。 +- **`preventDefault()` 阻止字符进输入框**:扫码结果只存在 `scanBuffer`,路由成功后由代码决定回填输入框还是直接执行动作。这是实现"焦点无关"的关键。 +- **排除项**:功能键(F1–F12)、方向键、Enter/Esc/组合键(Ctrl/Alt 等)不进入缓冲。 +- **`SCAN_MIN_LEN = 2`**:手工在输入框按单字符回车不会被误判为扫码。 + +--- + +## 7. 扫码路由 `routeScan(barcode)` + +``` +function routeScan(barcode) { + const id = createResult.value?.id + const record = createResult.value?.record + + // 1) 未创建拆包单 → 当作运单号创建 + if (!id) { handleCreate(barcode); return } + + // 2) 已创建但非拆包中(completed/cancelled)→ 提示,不路由 + if (record?.status !== 'unpacking') { ElMessage.warning('当前拆包单已终态'); return } + + // 3) 指令条码 + const cmd = resolveScanCommand(barcode) + if (cmd) { + if (cmd === 'submit') doSubmit() // 单次直接执行 + else if (cmd === 'normal') setDefaultStatus('normal') + else if (cmd === 'damaged') setDefaultStatus('damaged') + return + } + + // 4) 商品条码 → 复用现有快速添加 + detailBarcode.value = barcode // 回填输入框做视觉反馈 + handleBarcodeQuickAdd() +} +``` + +### 7.1 创建拆包(`handleCreate(barcode?)`) + +- 改造 `handleCreate` 支持传入条码:`const code = (barcode ?? waybillCode.value).trim()`。 +- 扫码路径:直接传入条码创建;创建成功后沿用现有逻辑自动 `focus` 商品条码输入框。 +- 手工路径:仍读输入框 `waybillCode.value`。 + +### 7.2 提交确认(`doSubmit()`) + +- 抽出现有 `confirmSubmit` 成功分支为 `doSubmit()`:调 `returnUnpackSubmit({ id })` → 成功 → `resetWorkState()` + `loadUnpackList()` + `focusWaybill()`。 +- **扫码直接调用 `doSubmit()`,不弹二次确认**(条码即确认)。 +- `submitLoading` 防重入;无拆包单/非 unpacking 时提示不执行。 + +### 7.3 切换默认状态(`setDefaultStatus(status)`) + +- 纯前端:`defaultProductStatus.value = status` + `ElMessage` 反馈(正常=绿 / 破损=红)。 +- 联动:左侧下拉框回显当前状态(与明细表 tag 配色一致)。 +- 未创建拆包单时也允许设置(作为纯前端状态,为后续快速添加做准备)。 + +--- + +## 8. 手工回车与现有快捷键的协同 + +为避免破坏现有交互,`handleKeydown` 内分支编排顺序(自上而下): + +``` +1. 扫码缓冲收集 / 扫码路由(见 §6) ← 新增,最先 +2. 弹窗打开时(stockPicker/quickAdd/detailForm)→ return(弹窗自处理) +3. ←/→ 切换焦点(现有逻辑,不变) +4. Enter: + a. 受控确认弹窗 → 各确认动作(现有,不变) + b. 其他弹窗 → return + c. 焦点在「运单号」输入框且未创建 → handleCreate()(现有 @keyup.enter 保留或并入) + d. 焦点在「商品条码」输入框且已创建 → handleBarcodeQuickAdd() + e. 无输入框焦点 → 提交确认(现有,不变) +5. Esc:取消/清除(现有,不变) +``` + +**双触发防护**(关键): +- 扫码字符已 `preventDefault` 不写入输入框,因此扫码 Enter 时输入框 `@keyup.enter` 若触发,其读取的 `v-model` 为空 → 直接 `return`,不会重复执行。 +- 为稳妥,输入框 `@keyup.enter` 的 handler 开头可加守卫:`if (Date.now() - lastScanAt < 100) return`(`lastScanAt` 为扫码路由完成时刻),彻底杜绝双触发。 + +--- + +## 9. UI 改动:扫码指令展示区块 + +在 `express/returnUnpackwork` 页面新增「扫码指令」展示区块,让工人一眼看到可扫的指令条码、含义与当前激活状态。 + +### 9.1 位置与结构 + +左侧面板「键盘快捷键」(`.shortcut-tips`) **下方**新增独立区块 `.scan-commands-tips`,与快捷键区块同风格、以条形码图标区分: + +``` +┌──────────────────────────────────────────┐ +│ 📟 扫码指令 [打印贴纸] │ +│ 直接用扫码枪扫描下方条形码(无需聚焦输入框) │ +│ │ +│ ▓▓▓▓▓▓▓▓▓▓ UNPACK.SUBMIT [提交确认] │ ← 可扫条形码图(jsbarcode Code 128) +│ ▓▓▓▓▓▓▓▓▓▓ UNPACK.NORMAL [设为正常] │ ← 激活时高亮(绿) +│ ▓▓▓▓▓▓▓▓▓▓ UNPACK.DAMAGED [设为破损] │ ← 激活时高亮(红) +└──────────────────────────────────────────┘ +``` + +### 9.2 每行结构(模板草案) + +```html +
+ + +
+
+ {{ CMD[cmd] }} + 复制 +
+ {{ CMD_LABEL[cmd] }} +
+
+``` + +### 9.3 视觉样式(对齐现有 shortcut-tips) + +| 元素 | 设计 | +|------|------| +| 区块 `.scan-commands-tips` | `border-top: 1px dashed #e8eef7` 与快捷键区块分隔;`padding-top: 12px` | +| 标题 `.scan-commands-title` | `📟 扫码指令`,13px / 600 / `#303133`(与 `.shortcut-tips-title` 一致) | +| 副标题 `.scan-commands-sub` | "直接用扫码枪扫描下方条形码即可(无需聚焦输入框)",12px / `#909399` | +| 条形码图 `.scan-command-barcode-img` | jsbarcode 生成 **Code 128 SVG**(`height:36`),白底圆角,**可直接被扫码枪扫描屏幕**;`onMounted → renderBarcodes()` 渲染 | +| 条码文本 `.scan-command-code` | 辅助文本:等宽字体、深底浅字,便于人工对照(非可扫对象) | +| 动作标签 | `el-tag`:提交=warning / 正常=success / 破损=danger,与明细表状态列配色一致 | +| 激活态 `.is-active` | 当前默认状态对应行加高亮边框 + 浅色背景(正常=绿浅、破损=红浅),**扫码切换时实时更新** | +| 行间距 `.scan-command-row` | `margin-bottom: 10px`,行间留足空隙,**条码不挨太近**;`align-items: center` | +| 复制按钮 `.scan-copy-btn` | `el-button link size=small`,hover 显示,点击复制条码文本(用于打印贴纸) | + +### 9.4 数据源与联动 + +- 条码文本统一从 `scan-commands.ts` 常量读取(`CMD.SUBMIT / CMD.NORMAL / CMD.DAMAGED`),与 `resolveScanCommand()` **同源**,避免硬编码漂移。 +- 激活高亮绑定 `defaultProductStatus`:扫码或下拉切换状态时实时联动。 +- `copyScanCommand(code)`:`navigator.clipboard.writeText(code)` 复制条码文本,便于工人用条码打印机生成贴纸。 +- 页面条形码图形:`renderBarcodes()` 用 jsbarcode 按 `CMD[cmd]` 生成 **Code 128 SVG** 到对应 `svg`(`barcodeRefs` 收集),`onMounted` 后渲染 → 工人可直接扫屏幕。 + +### 9.5 打印条码贴纸(确认实现) + +- **「打印条码贴纸」按钮**:位于扫码指令区块标题栏右侧,点击调起浏览器打印包含三条码的排版页,直接产出贴纸。 +- **排版**:每条码一行 = Code 128 条码图 + 下方文字(内容 + 动作含义),A4 多行排列供裁剪。 +- **条码生成**:轻量免费库 `jsbarcode` 前端生成 Code 128 SVG,无后端依赖。 +- **无折叠开关**:面板空间通过精简快捷键提示释放(见 §9.7)。 + +### 9.6 其他 UI 改动 + +1. 产品状态下拉旁展示当前激活状态高亮(与 tag 配色一致)。 +2. 保留运单号 / 商品条码输入框(扫码自动回填,兼顾手工输入)。 + +### 9.7 键盘快捷键提示精简(给扫码指令区块腾空间) + +精简左侧「键盘快捷键」区低频提示,释放高度给「扫码指令」区块: + +**保留**(高频/核心): +- `Enter` 运单号:创建拆包单(创建后锁定置灰) +- `Enter` 商品条码:查询并添加 +- `Enter` 无表单时:提交确认 +- `Esc`:取消拆包 / 清除信息 + +**删除**(低频/扫码工作流下少用): +- `←/→` 切换焦点(页面 + 商品选择弹窗内) +- `↑/↓` 切换商品、`Enter` 确定选中商品(弹窗内鼠标可替代) +- 整体删除「表单(商品选择弹窗内生效)」小节 + +--- + +## 10. 边界与异常 + +| 场景 | 处理 | +|------|------| +| 未创建拆包单时扫「提交/状态」指令 | 提交→提示无进行中单据;状态→仍可设置默认状态 | +| 已 completed/cancelled 时扫商品条码 | 提示"当前拆包单已终态",不添加 | +| 扫的条码非指令且查不到商品 | 走现有"未找到匹配的商品"提示 | +| 扫码枪快速连扫 | `submitLoading`/`quickAddLoading` 防重入 | +| 弹窗打开时扫码 | 弹窗打开时路由不生效,条码不收集(避免干扰表单) | +| 手工在输入框按单字符回车 | 不被误判为扫码(`SCAN_MIN_LEN=2`) | +| 条码含空格/小写 | `trim()` + 大小写不敏感解析 | + +--- + +## 11. 落地清单(文件级) + +1. 新建 `src/views/express/returnUnpackwork/scan-commands.ts` + - 指令常量 + `resolveScanCommand(barcode): 'submit' | 'normal' | 'damaged' | null` +2. 修改 `src/views/express/returnUnpackwork/index.vue` + - `handleKeydown` 增加扫码缓冲收集 + 路由(§6/§7) + - `handleCreate` 支持传入条码参数 + - 抽出 `doSubmit()`、`setDefaultStatus()`(复用 `confirmSubmit` 成功分支) + - 输入框 `@keyup.enter` 加双触发守卫 + - 新增「扫码指令」展示区块(§9:模板 + 样式 + 激活高亮 + `copyScanCommand()`) + - 「打印条码贴纸」:引入 `jsbarcode` 生成 Code 128 SVG 打印(§9.5) + - 精简「键盘快捷键」提示,删除低频项(§9.7) +3. 无需后端改动(语义 A,纯前端) + +--- + +## 12. 决策记录与待确认项 + +### 已确认 +- [x] 条码制式:**Code 128**(免费、高密度、全 ASCII、一维快速扫) +- [x] 指令内容:`UNPACK.SUBMIT / UNPACK.NORMAL / UNPACK.DAMAGED` +- [x] 「打印条码贴纸」:确认实现(`jsbarcode` 生成 Code 128 SVG) +- [x] 折叠开关:不需要(用快捷键提示精简释放空间,§9.7) +- [x] 条码间距:行间距加大(`margin-bottom: 10px`),条码不挨太近 + +### 待确认 +- [ ] 扫码间隔阈值 50ms 是否合适(可调) diff --git a/src/views/express/returnUnpackwork/CameraLivePreview.vue b/src/views/express/returnUnpackwork/CameraLivePreview.vue index 73bf0124..fb0478c2 100644 --- a/src/views/express/returnUnpackwork/CameraLivePreview.vue +++ b/src/views/express/returnUnpackwork/CameraLivePreview.vue @@ -4,7 +4,13 @@

预览不可用

{{ error }}

- +
{{ loading ? '正在连接录像机…' : '无信号' }}
@@ -13,7 +19,7 @@