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
+
预览不可用
{{ error }}
-