袁伟杰：V2.0.003 采购入库扫码

2026-05-14 16:48:09 +08:00
parent 7f84bbca79
commit 7859af83b2
24 changed files with 3479 additions and 62 deletions
--- a/docs/superpowers/specs/2026-05-14-purchase-in-pda-scan-design.md
+++ b/docs/superpowers/specs/2026-05-14-purchase-in-pda-scan-design.md
@@ -0,0 +1,367 @@
+# 采购入库 PDA 扫码页重构设计
+
+## 背景
+
+当前“扫码采购入库”页面更接近通用表单页，而非工厂仓库现场的扫码作业页。页面在未锁定采购单前就暴露了商品扫码、批次号、库位码、提交等动作，导致流程噪音大、操作节奏不稳定、误操作风险高。
+
+本次重构面向工厂仓库出入库场景，明确主使用设备与操作方式：
+
+- 90% 使用 PDA / 手持终端物理扫码枪
+- 10% 使用手机摄像头扫码
+- 商品扫码主路径为“一枪一件”，每次扫码自动累计 `+1`
+
+因此页面设计必须优先服务高频、连续、站立式作业，而不是低频表单录入。
+
+## 目标
+
+重构采购入库扫码页，使其满足以下目标：
+
+- 先锁采购单，再进入连续扫码作业
+- 商品扫码成功时不打断操作节奏
+- 异常时给出明确、可恢复的处理反馈
+- 始终让操作员看到当前单据、当前仓库、扫码进度、异常数量
+- 降低危险操作误触概率，避免“清空全部”成为高频可见动作
+- 保持与现有 ERP 扫码页代码风格一致，优先复用现有扫描输入、明细列表、提交逻辑能力
+
+## 非目标
+
+本次设计不包含以下范围：
+
+- 不重做采购入库后端接口协议
+- 不新增复杂的离线同步机制
+- 不引入多步骤向导页或跨页长流程
+- 不为手机摄像头场景单独做一套交互，只保留备用入口
+
+## 设计方向
+
+页面采用“作业台式”方案。锁单是进入作业态的前置动作，作业态才是页面主体。
+
+相比“单页折叠式”或“全表单式”，作业台式更适合 PDA 连续扫码场景，原因是：
+
+- 核心视线始终集中在当前单据、扫码输入、最近结果
+- 可以让商品扫码输入框常驻焦点，适应物理扫码枪回车行为
+- 订单上下文与作业进度持续可见，减少扫错单、扫过量、扫混仓的风险
+
+## 页面状态
+
+页面只允许存在两个一等状态：`锁单态` 与 `作业态`。
+
+### 锁单态
+
+页面目标只有一件事：确定当前采购单。
+
+展示内容：
+
+- 页面标题：`扫码采购入库`
+- 主动作：`扫描采购订单号`
+- 次动作：`手动选单`
+- 可选辅助文案：说明供应商、仓库、结算账户将在锁单后自动带出
+
+锁单态不展示以下内容：
+
+- 商品扫码输入框
+- 批次号输入框
+- 库位码输入框
+- 入库明细列表
+- 提交采购入库按钮
+
+设计理由：未锁单前，商品扫码与提交都不可执行。提前展示只会制造误导。
+
+### 作业态
+
+选定采购单后进入作业态，页面主体切换为扫码作业台。
+
+展示内容：
+
+- 顶部固定订单信息条
+- 商品扫码输入区
+- 批次号、库位码辅助区
+- 最近扫描记录区
+- 底部主提交区
+
+作业态的默认焦点必须回到商品扫码输入框，以适应 PDA 连续扫码。
+
+## 页面结构
+
+### 1. 顶部固定订单信息条
+
+用于持续回答两个问题：当前在扫哪张单，以及还差多少。
+
+固定展示字段：
+
+- `采购单号`：最醒目的主字段，例如 `CG2025001`
+- `供应商`
+- `仓库`
+- `进度`：格式为 `已扫 X / Y`
+- `异常数`：格式为 `异常 N`
+
+规则：
+
+- 当异常数大于 0 时，使用警示色强调
+- 顶部信息条在明细滚动时仍保持可见
+- 标题可显示为 `采购入库 / CG2025001`，帮助快速确认当前上下文
+
+### 2. 商品扫码输入区
+
+这是作业态的主操作区。
+
+字段与控件：
+
+- 商品条码输入框：主输入，常驻焦点
+- 批次号输入框：可选
+- 库位码输入框：可选
+- 相机按钮：仅手机摄像头备用
+
+规则：
+
+- 商品扫码成功后自动累计 `+1`
+- 默认不依赖手动点击“确认”按钮完成正常扫码
+- 若保留“确认”能力，也仅作为手机手输备用，不应成为 PDA 主路径
+- 商品扫码完成后，焦点自动回到商品条码输入框
+
+### 3. 最近扫描记录区
+
+该区域不是传统表单明细，而是作业回显区。
+
+默认展示：
+
+- 最近 5 条扫描记录
+- 最新一条置顶
+- 最新成功记录高亮约 2 秒
+
+每条记录显示：
+
+- 商品名称
+- 商品条码
+- 批次号
+- 库位码
+- 当前明细累计数量
+- 当前订单该商品剩余可入库数量
+
+合并规则：
+
+- 同商品、同批次、同库位的重复扫码：合并到同一条明细并数量 `+1`
+- 同商品但批次不同：分成新行
+- 同商品但库位不同：分成新行
+
+操作规则：
+
+- 每条记录提供 `撤销` 或 `删除本条` 能力
+- 不提供高频可见的 `清空全部`
+
+### 4. 底部主提交区
+
+底部只保留一个强主动作：`提交采购入库`
+
+规则：
+
+- 仅当存在有效明细时可点击
+- 点击后进入 loading，防止重复提交
+- 不将 `清空全部` 与 `提交` 并列摆放
+
+## 扫码交互规则
+
+### 正常路径
+
+锁单后，PDA 连续扫码主路径如下：
+
+1. 扫描商品条码
+2. 系统匹配当前采购单中的订单行
+3. 若匹配成功，则新增或累计对应明细
+4. 数量自动 `+1`
+5. 顶部进度同步刷新
+6. 页面显示成功反馈，例如：`西兰花 +1，已扫 12 / 30`
+7. 焦点返回商品扫码输入框，等待下一枪
+
+正常路径要求：
+
+- 不弹窗
+- 不要求人工再次确认
+- 不打断扫码节奏
+
+### PDA 行为适配
+
+考虑物理扫码枪通常自带输入结束与回车行为，页面需满足：
+
+- 商品条码输入框支持快速连续触发提交
+- 回车后自动执行匹配与累计
+- 成功后无需额外点击
+- 扫码完成后尽快恢复待扫状态
+
+### 手机摄像头备用路径
+
+手机端仍保留相机按钮，但定位是备用入口：
+
+- 适用于无 PDA 或临时补录
+- 交互与 PDA 一致，扫码成功后同样走自动累计逻辑
+- 不单独扩展额外的手机专属页面流程
+
+## 异常处理
+
+异常处理分为三类。
+
+### 1. 不中断型反馈
+
+适用于成功扫码。
+
+表现：
+
+- 使用绿色反馈条或高可见状态条
+- 文案直接描述结果，例如：`西兰花 +1，已扫 12 / 30`
+- 持续约 0.8 到 1.2 秒后消失
+- 焦点自动回到商品扫码输入框
+
+### 2. 中断型异常
+
+适用于以下场景：
+
+- 商品不在当前采购单内
+- 商品剩余可入库数量为 0
+- 扫码后将超出剩余可入库数量
+- 条码命中多个待入库订单行
+- 当前采购单未锁定
+
+表现：
+
+- 使用红色错误条或常驻错误提示
+- 错误文案必须明确原因，不能只写“操作失败”
+- 焦点不应伪装成成功回跳
+- 必要时进入人工处理分支
+
+推荐错误文案：
+
+- `商品不在当前采购单内`
+- `该商品剩余可入库 0 件`
+- `该商品本次扫码后将超出剩余数量`
+- `条码命中多个订单行，请人工选择`
+- `请先扫描采购订单号`
+
+### 3. 可恢复型提示
+
+适用于非强拦截场景，例如：
+
+- 批次号为空
+- 库位码为空
+
+处理原则：
+
+- 若业务允许为空，则不拦截扫码
+- 可在记录中标记为空，或在提交前统一提醒
+- 不应影响正常扫码节奏
+
+## 危险操作策略
+
+仓库扫码场景下，危险操作必须降级。
+
+优先提供：
+
+- `撤销上一笔`
+- `删除单条`
+
+降级隐藏：
+
+- `清空全部`
+
+规则：
+
+- `清空全部` 放入右上角更多菜单或二级操作区
+- 执行前必须二次确认
+- 不能与 `提交采购入库` 同层并列
+
+原因：现场最常见修正动作是撤销刚才那一枪，而不是整单清空。
+
+## 提交流程
+
+### 提交前条件
+
+`提交采购入库` 按钮仅在满足以下条件时启用：
+
+- 已锁定采购单
+- 至少存在 1 条有效明细
+
+### 提交前校验
+
+提交前统一执行轻校验，检查：
+
+- 是否已锁单
+- 是否存在有效明细
+- 是否存在未处理异常
+- 是否存在超量或冲突记录
+- 若业务要求，可额外检查是否存在空库位记录
+
+### 提交中行为
+
+- 提交按钮进入 loading
+- 页面避免重复触发提交
+- 不清空当前上下文，直到接口明确成功
+
+### 提交成功后
+
+成功反馈不能只有“成功”提示，而应给用户明确后续动作：
+
+- `继续当前单据扫码`
+- `返回列表`
+
+若业务允许同一采购单分批入库，则继续当前单据是高价值动作。
+
+### 提交失败后
+
+提交失败时必须保留现场：
+
+- 当前采购单
+- 已扫明细
+- 当前批次号 / 库位码上下文
+- 当前异常状态
+
+不能因为接口失败而丢失现场数据，否则会造成重复作业和人工补录。
+
+## 数据与组件边界
+
+建议将页面逻辑拆分为以下职责单元：
+
+- `锁单上下文`：负责采购单选择、锁定、切换、上下文字段映射
+- `扫码作业上下文`：负责商品扫码、累计、异常判断、反馈文案
+- `最近扫描记录列表`：负责最近记录展示、合并、撤销
+- `提交控制器`：负责校验、提交、成功/失败收尾
+
+实现时应优先复用现有能力：
+
+- 扫码输入组件
+- ERP 明细展示组件
+- 采购入库现有数据结构与接口
+
+避免将全部状态与条件判断继续堆在单个页面文件中。
+
+## 错误处理与恢复策略
+
+- 切换采购单前，如已有明细，需明确提示并确认
+- 删除或撤销明细后，顶部进度立即回算
+- 发生条码歧义时，进入人工选择而不是静默失败
+- 明细为空时不得允许提交
+- 页面刷新或重新进入时，若未设计暂存机制，则明确回到锁单态
+
+## 测试关注点
+
+测试应覆盖以下高风险路径：
+
+- 未锁单时误扫商品
+- 连续多枪同商品累计
+- 同商品不同批次 / 库位分行
+- 超量扫码拦截
+- 条码命中多个订单行
+- 撤销上一笔后进度与剩余数量回算
+- 提交失败后现场状态保留
+- PDA 回车触发下焦点能持续回到主扫码框
+
+## 设计结论
+
+采购入库扫码页应从“表单页”重构为“PDA 作业台页”：
+
+- 先锁单，再作业
+- 一枪一件，自动累计
+- 正常路径绝不打断
+- 异常路径明确、可恢复
+- 明细区服务作业反馈，不服务传统录单表单
+- 危险操作降级，提交操作集中
+
+该方案优先满足工厂仓库高频扫码场景，同时保留手机摄像头作为备用输入方式。
--- a/env/.env
+++ b/env/.env
@@ -10,8 +10,8 @@ VITE_WX_APPID = 'wx1a832d51073d3a35'
 VITE_APP_PUBLIC_BASE=/

 # 后台请求地址
-VITE_SERVER_BASEURL = 'http://119.96.62.56:7004/admin-api'
-VITE_UPLOAD_BASEURL = 'http://localhost:48080/upload'
+VITE_SERVER_BASEURL = 'http://192.168.1.20:48080/admin-api'
+VITE_UPLOAD_BASEURL = 'http://192.168.1.20:48080/upload'
 # 备注：如果后台带统一前缀，则也要加到后面，eg: https://ukw0y1.laf.run/api

 # 注意，如果是微信小程序，还有一套请求地址的配置，根据 develop、trial、release 分别设置上传地址，见 `src/utils/index.ts`。
--- a/package.json
+++ b/package.json
@@ -180,6 +180,9 @@
  "pnpm": {
    "overrides": {
      "unconfig": "7.3.2"
+    },
+    "patchedDependencies": {
+      "wot-design-uni@1.13.0": "patches/wot-design-uni@1.13.0.patch"
    }
  },
  "overrides": {
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -8,6 +8,11 @@ overrides:
  bin-wrapper: npm:bin-wrapper-china
  unconfig: 7.3.2

+patchedDependencies:
+  wot-design-uni@1.13.0:
+    hash: 29ab7840a74d54969d4cbe5b840208d3d4911a82be189ac8581d462190fb5210
+    path: patches/wot-design-uni@1.13.0.patch
+
 importers:

  .:
@@ -89,7 +94,7 @@ importers:
        version: 4.5.1(vue@3.4.21(typescript@5.8.3))
      wot-design-uni:
        specifier: ^1.13.0
-        version: 1.13.0(vue@3.4.21(typescript@5.8.3))
+        version: 1.13.0(patch_hash=29ab7840a74d54969d4cbe5b840208d3d4911a82be189ac8581d462190fb5210)(vue@3.4.21(typescript@5.8.3))
      z-paging:
        specifier: 2.8.7
        version: 2.8.7
@@ -13316,7 +13321,7 @@ snapshots:

  word-wrap@1.2.5: {}

-  wot-design-uni@1.13.0(vue@3.4.21(typescript@5.8.3)):
+  wot-design-uni@1.13.0(patch_hash=29ab7840a74d54969d4cbe5b840208d3d4911a82be189ac8581d462190fb5210)(vue@3.4.21(typescript@5.8.3)):
    dependencies:
      vue: 3.4.21(typescript@5.8.3)

--- a/src/api/erp/purchase-in/index.ts
+++ b/src/api/erp/purchase-in/index.ts
@@ -13,6 +13,8 @@ export interface PurchaseInItem {
  remark?: string
  warehouseId?: number
  warehouseName?: string
+  batchNo?: string
+  locationCode?: string
  productName?: string
  productBarCode?: string
  productUnitName?: string
--- a/src/api/erp/stock-in/index.ts
+++ b/src/api/erp/stock-in/index.ts
@@ -7,9 +7,11 @@ export interface StockInItem {
  stockInId?: number
  warehouseId?: number
  warehouseName?: string
+  locationCode?: string
  productId?: number
  productName?: string
  productUnitName?: string
+  batchNo?: string
  count?: number
  productPrice?: number
  totalPrice?: number
--- a/src/api/erp/stock-out/index.ts
+++ b/src/api/erp/stock-out/index.ts
@@ -7,9 +7,11 @@ export interface StockOutItem {
  stockOutId?: number
  warehouseId?: number
  warehouseName?: string
+  locationCode?: string
  productId?: number
  productName?: string
  productUnitName?: string
+  batchNo?: string
  count?: number
  productPrice?: number
  totalPrice?: number
--- a/src/components/erp-scan/item-list.vue
+++ b/src/components/erp-scan/item-list.vue
@@ -6,7 +6,7 @@
    <view v-for="(item, index) in items" :key="`${item.warehouseId}-${item.productId}-${index}`" class="item-card">
      <view class="item-card__header">
        <text class="item-card__name">{{ item.productName }}</text>
-        <text class="item-card__remove" @tap="emit('remove', index)">删除</text>
+        <text class="item-card__remove" @tap="emit('remove', index)">{{ removeText }}</text>
      </view>
      <view class="item-card__meta">
        <text>仓库：{{ item.warehouseName || '-' }}</text>
@@ -20,6 +20,14 @@
        <text>单价：{{ formatNumber(item.productPrice) }}</text>
        <text v-if="showStock">库存：{{ formatNumber(item.stockCount) }}</text>
      </view>
+      <view v-if="item.targetCount !== undefined" class="item-card__meta">
+        <text>目标：{{ formatNumber(item.targetCount) }}</text>
+      </view>
+      <view v-if="item.remainCount !== undefined || item.batchNo || item.locationCode" class="item-card__meta">
+        <text v-if="item.remainCount !== undefined">剩余：{{ formatNumber(item.remainCount) }}</text>
+        <text>批次：{{ item.batchNo || '-' }}</text>
+        <text>库位：{{ item.locationCode || '-' }}</text>
+      </view>
      <view class="item-card__footer">
        <view class="counter">
          <text class="counter__button" @tap="emit('decrease', index)">-</text>
@@ -42,6 +50,10 @@ export interface ItemCardValue {
  productUnitName?: string
  productPrice?: number
  stockCount?: number
+  batchNo?: string
+  locationCode?: string
+  remainCount?: number
+  targetCount?: number
  count: number
 }

@@ -49,9 +61,11 @@ withDefaults(
  defineProps<{
    items: ItemCardValue[]
    showStock?: boolean
+    removeText?: string
  }>(),
  {
    showStock: false,
+    removeText: '删除',
  },
 )

--- a/src/components/erp-scan/scan-input.vue
+++ b/src/components/erp-scan/scan-input.vue
@@ -10,11 +10,18 @@
      @input="handleInput"
      @confirm="handleSubmit"
    >
-    <button class="scan-input__button scan-input__button--primary" size="mini" :disabled="disabled || loading" @tap="handleSubmit">
+    <!-- 通过属性控制确认按钮是否渲染，兼容不同交互模式下的输入提交流程 -->
+    <button
+      v-if="showConfirmButton"
+      class="scan-input__button scan-input__button--primary"
+      size="mini"
+      :disabled="disabled || loading"
+      @tap="handleSubmit"
+    >
      {{ loading ? '处理中' : '确认' }}
    </button>
    <button class="scan-input__button scan-input__button--camera" size="mini" :disabled="disabled || loading" @tap="handleCameraScan">
-      相机
+      {{ cameraText }}
    </button>
  </view>
 </template>
@@ -27,12 +34,16 @@ const props = withDefaults(
    disabled?: boolean
    loading?: boolean
    autoFocus?: boolean
+    showConfirmButton?: boolean
+    cameraText?: string
  }>(),
  {
    placeholder: '请扫描条码',
    disabled: false,
    loading: false,
    autoFocus: true,
+    showConfirmButton: true,
+    cameraText: '相机',
  },
 )

@@ -98,10 +109,12 @@ function handleCameraScan() {
  }

  &__button {
-    width: 128rpx;
+    min-width: 128rpx;
    height: 84rpx;
+    padding: 0 24rpx;
    line-height: 84rpx;
    border-radius: 12rpx;
+    box-sizing: border-box;

    &--primary {
      background: #1677ff;
--- a/src/pages-erp/purchase-in/scan/components/order-context-bar.vue
+++ b/src/pages-erp/purchase-in/scan/components/order-context-bar.vue
@@ -0,0 +1,85 @@
+<template>
+  <view class="order-context-bar">
+    <view class="order-context-bar__main">
+      <view class="order-context-bar__order">
+        <text class="order-context-bar__label">单号</text>
+        <text class="order-context-bar__value">{{ orderNo || '-' }}</text>
+      </view>
+      <view class="order-context-bar__progress">
+        已扫 {{ scannedCount }} / {{ targetCount }}
+      </view>
+    </view>
+
+    <view class="order-context-bar__meta">
+      <text>供应商：{{ supplierName || '-' }}</text>
+      <text>仓库：{{ warehouseName || '-' }}</text>
+      <text class="order-context-bar__exception">异常：{{ exceptionCount }}</text>
+    </view>
+  </view>
+</template>
+
+<script setup lang="ts">
+defineProps<{
+  orderNo: string
+  supplierName?: string
+  warehouseName?: string
+  scannedCount: number
+  targetCount: number
+  exceptionCount: number
+}>()
+</script>
+
+<style lang="scss" scoped>
+.order-context-bar {
+  padding: 20rpx 24rpx;
+  border-bottom: 2rpx solid #e5e6eb;
+  background: rgba(255, 255, 255, 0.96);
+
+  &__main,
+  &__meta {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 16rpx;
+  }
+
+  &__order {
+    display: flex;
+    align-items: center;
+    gap: 12rpx;
+    min-width: 0;
+    flex: 1;
+  }
+
+  &__label {
+    flex-shrink: 0;
+    color: #86909c;
+    font-size: 24rpx;
+  }
+
+  &__value {
+    min-width: 0;
+    color: #1f2329;
+    font-size: 30rpx;
+    font-weight: 600;
+  }
+
+  &__progress {
+    flex-shrink: 0;
+    color: #1677ff;
+    font-size: 24rpx;
+    font-weight: 600;
+  }
+
+  &__meta {
+    margin-top: 12rpx;
+    color: #4e5969;
+    font-size: 22rpx;
+    flex-wrap: wrap;
+  }
+
+  &__exception {
+    color: #d4380d;
+  }
+}
+</style>
--- a/src/pages-erp/purchase-in/scan/components/recent-scan-list.vue
+++ b/src/pages-erp/purchase-in/scan/components/recent-scan-list.vue
@@ -0,0 +1,187 @@
+<template>
+  <view class="recent-scan-list">
+    <view v-if="items.length === 0" class="recent-scan-list__empty">
+      暂无最近扫码记录
+    </view>
+
+    <view
+      v-for="(item, index) in items"
+      :key="buildItemKey(item)"
+      class="scan-card"
+      :class="{ 'scan-card--latest': latestIndex === index }"
+    >
+      <view class="scan-card__header">
+        <text class="scan-card__name">{{ item.productName || '-' }}</text>
+        <text class="scan-card__undo" @tap="emit('undo', index, item)">撤销</text>
+      </view>
+
+      <view class="scan-card__meta">
+        <text>条码：{{ item.productBarCode || '-' }}</text>
+        <view class="scan-card__quantity">
+          <text class="scan-card__step" @tap="emit('decrease', index, item)">-</text>
+          <input
+            class="scan-card__count-input"
+            type="number"
+            :value="formatCount(item.count)"
+            @blur="handleCountBlur($event, index, item)"
+            @confirm="handleCountBlur($event, index, item)"
+          >
+          <text class="scan-card__step" @tap="emit('increase', index, item)">+</text>
+        </view>
+      </view>
+      <view class="scan-card__meta">
+        <text>批次：{{ item.batchNo || '-' }}</text>
+        <text>剩余：{{ formatCount(item.remainCount) }}</text>
+      </view>
+      <view class="scan-card__meta">
+        <text>库位：{{ item.locationCode || '-' }}</text>
+      </view>
+    </view>
+  </view>
+</template>
+
+<script setup lang="ts">
+import type { PurchaseScanItem } from '@/utils/purchase-scan'
+
+defineProps<{
+  items: PurchaseScanItem[]
+  latestIndex?: number
+}>()
+
+const emit = defineEmits<{
+  (event: 'undo', index: number, item: PurchaseScanItem): void
+  (event: 'increase', index: number, item: PurchaseScanItem): void
+  (event: 'decrease', index: number, item: PurchaseScanItem): void
+  (event: 'change-count', index: number, nextCount: number, item: PurchaseScanItem): void
+}>()
+
+/**
+ * 功能说明：生成最近扫码卡片的稳定 key，复用采购扫码的聚合维度。
+ * 适用场景：最近扫码列表渲染时为每条记录提供唯一标识。
+ * @param item 当前扫码记录
+ * @return 组合后的字符串 key
+ * 注意事项：采购扫码项已按订单行、批次和库位聚合，这里直接使用相同维度生成稳定 key，避免列表重排时节点误复用。
+ */
+function buildItemKey(item: PurchaseScanItem) {
+  return [
+    item.orderItemId || item.productId || 'unknown',
+    item.batchNo || 'no-batch',
+    item.locationCode || 'no-location',
+  ].join('-')
+}
+
+/**
+ * 功能说明：格式化数量展示，避免空值直接透出到工作台。
+ * 适用场景：最近扫码卡片展示扫码数量和剩余数量。
+ * @param value 原始数量
+ * @return 格式化后的数量文案
+ * 注意事项：采购扫码数量可能来自接口或本地累加，这里统一转数值后再按整数/小数展示。
+ */
+function formatCount(value?: number) {
+  if (value === undefined || value === null) {
+    return '-'
+  }
+
+  const normalizedValue = Number(value)
+  return normalizedValue.toFixed(Number.isInteger(normalizedValue) ? 0 : 4)
+}
+
+/**
+ * 功能说明：处理扫码卡片中的手动数量录入。
+ * 适用场景：操作员直接输入目标数量后离焦或回车确认。
+ * @param event 输入框事件
+ * @param index 当前记录索引
+ * @param item 当前扫码记录
+ * @return 无
+ * 注意事项：这里只负责把输入值抛给页面层，实际数量校验与上限判断统一由页面业务逻辑处理。
+ */
+function handleCountBlur(event: Record<string, any>, index: number, item: PurchaseScanItem) {
+  const rawValue = event?.detail?.value
+  emit('change-count', index, Number(rawValue), item)
+}
+</script>
+
+<style lang="scss" scoped>
+.recent-scan-list {
+  &__empty {
+    padding: 28rpx;
+    border-radius: 16rpx;
+    background: #fff;
+    color: #86909c;
+    text-align: center;
+  }
+}
+
+.scan-card {
+  margin-bottom: 16rpx;
+  padding: 24rpx;
+  border: 2rpx solid transparent;
+  border-radius: 16rpx;
+  background: #fff;
+
+  &--latest {
+    border-color: #1677ff;
+    box-shadow: 0 8rpx 20rpx rgba(22, 119, 255, 0.12);
+  }
+
+  &__header,
+  &__meta {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 16rpx;
+  }
+
+  &__header {
+    margin-bottom: 12rpx;
+  }
+
+  &__name {
+    color: #1f2329;
+    font-size: 28rpx;
+    font-weight: 600;
+  }
+
+  &__undo {
+    flex-shrink: 0;
+    color: #f53f3f;
+    font-size: 24rpx;
+  }
+
+  &__meta {
+    margin-top: 8rpx;
+    color: #4e5969;
+    font-size: 24rpx;
+    flex-wrap: wrap;
+  }
+
+  &__quantity {
+    display: flex;
+    align-items: center;
+    gap: 12rpx;
+  }
+
+  &__step {
+    width: 44rpx;
+    height: 44rpx;
+    line-height: 44rpx;
+    border-radius: 8rpx;
+    background: #f2f3f5;
+    color: #1f2329;
+    text-align: center;
+    font-size: 30rpx;
+  }
+
+  &__count-input {
+    width: 104rpx;
+    height: 44rpx;
+    line-height: 44rpx;
+    border: 2rpx solid #d9dce3;
+    border-radius: 8rpx;
+    background: #fff;
+    color: #1f2329;
+    text-align: center;
+    box-sizing: border-box;
+  }
+}
+</style>
--- a/src/pages-erp/purchase-in/scan/components/scan-feedback-bar.vue
+++ b/src/pages-erp/purchase-in/scan/components/scan-feedback-bar.vue
@@ -0,0 +1,43 @@
+<template>
+  <view v-if="message" class="feedback-bar" :class="`feedback-bar--${tone}`">
+    {{ message }}
+  </view>
+</template>
+
+<script setup lang="ts">
+withDefaults(
+  defineProps<{
+    tone?: 'success' | 'error' | 'idle'
+    message?: string
+  }>(),
+  {
+    tone: 'idle',
+    message: '',
+  },
+)
+</script>
+
+<style lang="scss" scoped>
+.feedback-bar {
+  min-height: 76rpx;
+  padding: 18rpx 24rpx;
+  border-radius: 14rpx;
+  font-size: 24rpx;
+  line-height: 40rpx;
+
+  &--idle {
+    background: #f2f3f5;
+    color: #4e5969;
+  }
+
+  &--success {
+    background: #f6ffed;
+    color: #389e0d;
+  }
+
+  &--error {
+    background: #fff2f0;
+    color: #cf1322;
+  }
+}
+</style>
--- a/src/pages-erp/purchase-in/scan/index.vue
+++ b/src/pages-erp/purchase-in/scan/index.vue
--- a/src/pages-erp/purchase-order/detail/index.vue
+++ b/src/pages-erp/purchase-order/detail/index.vue
@@ -12,6 +12,7 @@
      <!-- 基本信息 -->
      <wd-cell-group title="基本信息" border>
        <wd-cell title="采购单编号" :value="formData.no" />
+        <wd-cell title="扫码识别值" :value="formData.no || '-'" />
        <wd-cell title="采购状态">
          <view
            class="rounded-8rpx px-16rpx py-4rpx text-24rpx"
--- a/src/pages-erp/stock-in/scan/index.vue
+++ b/src/pages-erp/stock-in/scan/index.vue
@@ -31,6 +31,8 @@
        <view class="scan-section__title">
          扫码录入
        </view>
+        <input v-model="batchNo" class="scan-field" placeholder="请输入或扫描批次号（可选）">
+        <input v-model="locationCode" class="scan-field" placeholder="请输入或扫描库位码（可选）">
        <ScanInput
          v-model="scanCode"
          placeholder="请先选择仓库，再扫描产品条码"
@@ -55,7 +57,6 @@
 <script setup lang="ts">
 import type { ProductByBarCode } from '@/api/erp/product'
 import type { StockIn, StockInItem } from '@/api/erp/stock-in'
-import type { SupplierSimple } from '@/api/erp/supplier'
 import type { Warehouse } from '@/api/erp/warehouse'
 import type { ItemCardValue } from '@/components/erp-scan/item-list.vue'

@@ -82,21 +83,33 @@ interface StockInScanItem extends ItemCardValue {
  remark?: string
 }

+interface OptionalSupplierOption {
+  id?: number
+  name: string
+}
+
 const toast = useToast()
 const scanCode = ref('')
 const scanLoading = ref(false)
 const submitting = ref(false)
 const remark = ref('')
 const warehouses = ref<Warehouse[]>([])
-const suppliers = ref<SupplierSimple[]>([])
+const suppliers = ref<OptionalSupplierOption[]>([])
 const selectedWarehouseId = ref<number>()
 const selectedSupplierId = ref<number>()
 const items = ref<StockInScanItem[]>([])
+const batchNo = ref('')
+const locationCode = ref('')
+
+const EMPTY_SUPPLIER_OPTION: OptionalSupplierOption = {
+  id: undefined,
+  name: '不选择供应商（可选）',
+}

 const currentWarehouse = computed(() =>
  warehouses.value.find(item => item.id === selectedWarehouseId.value),
 )
-const currentSupplierName = computed(() => suppliers.value.find(item => item.id === selectedSupplierId.value)?.name || '请选择供应商（可选）')
+const currentSupplierName = computed(() => suppliers.value.find(item => item.id === selectedSupplierId.value)?.name || EMPTY_SUPPLIER_OPTION.name)
 const selectedWarehouseIndex = computed(() => Math.max(warehouses.value.findIndex(item => item.id === selectedWarehouseId.value), 0))
 const selectedSupplierIndex = computed(() => {
  const index = suppliers.value.findIndex(item => item.id === selectedSupplierId.value)
@@ -126,7 +139,7 @@ async function loadInitialData() {
  ])

  warehouses.value = warehouseList
-  suppliers.value = supplierList
+  suppliers.value = [EMPTY_SUPPLIER_OPTION, ...supplierList]
  selectedWarehouseId.value = warehouseList.find(item => item.defaultStatus)?.id || warehouseList[0]?.id
 }

@@ -163,12 +176,22 @@ function handleSupplierChange(event: Record<string, any>) {
 */
 function appendScannedProduct(product: ProductByBarCode) {
  const warehouseId = selectedWarehouseId.value as number
-  const targetKey = buildScanMergeKey({ warehouseId, productId: product.id, count: 1 })
+  const currentBatchNo = batchNo.value.trim()
+  const currentLocationCode = locationCode.value.trim()
+  const targetKey = buildScanMergeKey({
+    warehouseId,
+    productId: product.id,
+    count: 1,
+    batchNo: currentBatchNo,
+    locationCode: currentLocationCode,
+  }, true)
  const existedIndex = items.value.findIndex(item => buildScanMergeKey({
    warehouseId: item.warehouseId,
    productId: item.productId,
    count: item.count,
-  }) === targetKey)
+    batchNo: item.batchNo,
+    locationCode: item.locationCode,
+  }, true) === targetKey)

  if (existedIndex >= 0) {
    items.value[existedIndex].count += 1
@@ -184,6 +207,8 @@ function appendScannedProduct(product: ProductByBarCode) {
    productSpec: product.standard,
    productUnitName: product.unitName,
    productPrice: Number(product.minPrice || 0),
+    batchNo: currentBatchNo,
+    locationCode: currentLocationCode,
    count: 1,
  })
 }
@@ -315,8 +340,10 @@ function clearItems() {
 function buildSubmitItems(): StockInItem[] {
  return items.value.map(item => ({
    warehouseId: item.warehouseId,
+    locationCode: item.locationCode,
    productId: item.productId,
    productPrice: item.productPrice,
+    batchNo: item.batchNo,
    count: item.count,
    remark: item.remark,
  }))
@@ -341,16 +368,20 @@ async function handleSubmit() {
  submitting.value = true
  try {
    const payload: StockIn = {
-      supplierId: selectedSupplierId.value,
      inTime: new Date().toISOString(),
      remark: remark.value,
      items: buildSubmitItems(),
    }
+    if (selectedSupplierId.value !== undefined) {
+      payload.supplierId = selectedSupplierId.value
+    }

    await createStockIn(payload)
    toast.success('入库成功')
    clearItems()
    remark.value = ''
+    batchNo.value = ''
+    locationCode.value = ''
  } finally {
    submitting.value = false
  }
--- a/src/pages-erp/stock-out/detail/index.vue
+++ b/src/pages-erp/stock-out/detail/index.vue
@@ -12,6 +12,7 @@
      <!-- 基本信息 -->
      <wd-cell-group title="基本信息" border>
        <wd-cell title="出库单号" :value="detail.no || '-'" />
+        <wd-cell title="扫码识别值" :value="detail.no || '-'" />
        <wd-cell title="出库时间" :value="formatDate(detail.outTime)" />
        <wd-cell title="客户" :value="detail.customerName || '-'" />
        <wd-cell title="审核状态">
@@ -78,6 +79,14 @@

    <!-- 底部操作按钮 -->
    <view class="yd-detail-footer">
+      <wd-button
+        v-if="hasAccessByCodes(['erp:stock-out:query']) && detail.status !== 20"
+        type="primary"
+        plain
+        @click="handleTaskScan"
+      >
+        去扫码
+      </wd-button>
      <wd-button
        v-if="hasAccessByCodes(['erp:stock-out:update']) && detail.status !== 20"
        type="primary"
@@ -135,19 +144,25 @@ const detail = ref<StockOut>({})

 /** 格式化数量 */
 function formatCount(count?: number) {
-  if (count === undefined || count === null) return '-'
+  if (count === undefined || count === null) {
+    return '-'
+  }
  return count.toFixed(2)
 }

 /** 格式化金额 */
 function formatPrice(price?: number) {
-  if (price === undefined || price === null) return '-'
+  if (price === undefined || price === null) {
+    return '-'
+  }
  return `¥${price.toFixed(2)}`
 }

 /** 格式化日期 */
 function formatDate(dateStr?: string) {
-  if (!dateStr) return '-'
+  if (!dateStr) {
+    return '-'
+  }
  return dateStr.substring(0, 10)
 }

@@ -158,7 +173,9 @@ function handleBack() {

 /** 加载详情 */
 async function getDetail() {
-  if (!props.id) return
+  if (!props.id) {
+    return
+  }
  try {
    toast.loading('加载中...')
    detail.value = await getStockOut(props.id)
@@ -172,13 +189,20 @@ function handleEdit() {
  uni.navigateTo({ url: `/pages-erp/stock-out/form/index?id=${props.id}` })
 }

+/** 去扫码执行 */
+function handleTaskScan() {
+  uni.navigateTo({ url: `/pages-erp/stock-out/task-scan/index?id=${props.id}` })
+}
+
 /** 审批 */
 function handleApprove() {
  uni.showModal({
    title: '提示',
    content: '确定要审批该出库单吗？',
    success: async (res) => {
-      if (!res.confirm) return
+      if (!res.confirm) {
+        return
+      }
      try {
        await updateStockOutStatus(props.id, 20)
        toast.success('审批成功')
@@ -196,7 +220,9 @@ function handleReverseApprove() {
    title: '提示',
    content: '确定要反审批该出库单吗？',
    success: async (res) => {
-      if (!res.confirm) return
+      if (!res.confirm) {
+        return
+      }
      try {
        await updateStockOutStatus(props.id, 10)
        toast.success('反审批成功')
@@ -214,7 +240,9 @@ function handleDelete() {
    title: '提示',
    content: '确定要删除该出库单吗？',
    success: async (res) => {
-      if (!res.confirm) return
+      if (!res.confirm) {
+        return
+      }
      try {
        await deleteStockOut([props.id])
        toast.success('删除成功')
--- a/src/pages-erp/stock-out/index.vue
+++ b/src/pages-erp/stock-out/index.vue
@@ -13,18 +13,18 @@
    </view>

    <!-- 快捷筛选标签 -->
-    <view class="flex items-center overflow-hidden rounded-12rpx bg-white mx-24rpx mb-16rpx shadow-sm">
+    <view class="mx-24rpx mb-16rpx flex items-center overflow-hidden rounded-12rpx bg-white shadow-sm">
      <view
        v-for="tab in statusTabs"
        :key="tab.value"
-        class="flex-1 py-20rpx text-center text-26rpx relative"
+        class="relative flex-1 py-20rpx text-center text-26rpx"
        :class="queryParams.status === tab.value ? 'text-[#1890ff] font-semibold' : 'text-[#666]'"
        @click="onTabChange(tab.value)"
      >
        {{ tab.label }}
        <view
          v-if="queryParams.status === tab.value"
-          class="absolute bottom-0 left-1/4 w-1/2 h-4rpx rounded-2rpx bg-[#1890ff]"
+          class="absolute bottom-0 left-1/4 h-4rpx w-1/2 rounded-2rpx bg-[#1890ff]"
        />
      </view>
    </view>
@@ -58,7 +58,7 @@
          <!-- 产品 -->
          <view class="mb-8rpx flex items-center justify-between text-26rpx text-[#666]">
            <text class="text-[#999]">产品</text>
-            <text class="ml-16rpx line-clamp-1 text-right" style="max-width: 400rpx;">{{ item.productNames || '-' }}</text>
+            <text class="line-clamp-1 ml-16rpx text-right" style="max-width: 400rpx;">{{ item.productNames || '-' }}</text>
          </view>
          <!-- 出库时间 -->
          <view class="mb-8rpx flex items-center justify-between text-26rpx text-[#666]">
@@ -71,19 +71,33 @@
            <text>{{ item.creatorName || '-' }}</text>
          </view>
          <!-- 数量金额区域 -->
-          <view class="flex items-center justify-around mt-12rpx pt-16rpx border-t border-[#f0f0f0]">
+          <view class="mt-12rpx flex items-center justify-around border-t border-[#f0f0f0] pt-16rpx">
            <view class="text-center">
-              <view class="text-32rpx text-[#333] font-semibold">{{ formatCount(item.totalCount) }}</view>
-              <view class="text-22rpx text-[#999] mt-4rpx">数量</view>
+              <view class="text-32rpx text-[#333] font-semibold">
+                {{ formatCount(item.totalCount) }}
+              </view>
+              <view class="mt-4rpx text-22rpx text-[#999]">
+                数量
+              </view>
            </view>
            <view class="text-center">
-              <view class="text-32rpx text-[#f5222d] font-semibold">{{ formatPrice(item.totalPrice) }}</view>
-              <view class="text-22rpx text-[#999] mt-4rpx">金额</view>
+              <view class="text-32rpx text-[#f5222d] font-semibold">
+                {{ formatPrice(item.totalPrice) }}
+              </view>
+              <view class="mt-4rpx text-22rpx text-[#999]">
+                金额
+              </view>
            </view>
          </view>
        </view>
        <!-- 操作按钮 -->
        <view class="flex flex-wrap gap-12rpx px-24rpx pb-20rpx" @click.stop>
+          <wd-button
+            v-if="hasAccessByCodes(['erp:stock-out:query']) && item.status !== 20"
+            size="small" type="primary" plain @click="handleTaskScan(item)"
+          >
+            去扫码
+          </wd-button>
          <wd-button
            v-if="hasAccessByCodes(['erp:stock-out:update']) && item.status !== 20"
            size="small" type="primary" plain @click="handleEdit(item)"
@@ -135,11 +149,15 @@
    <wd-popup v-model="searchVisible" position="top" @close="searchVisible = false">
      <view class="yd-search-form-container" :style="{ paddingTop: `${getNavbarHeight()}px` }">
        <view class="yd-search-form-item">
-          <view class="yd-search-form-label">出库单号</view>
+          <view class="yd-search-form-label">
+            出库单号
+          </view>
          <wd-input v-model="searchForm.no" placeholder="请输入出库单号" clearable />
        </view>
        <view class="yd-search-form-item">
-          <view class="yd-search-form-label">审核状态</view>
+          <view class="yd-search-form-label">
+            审核状态
+          </view>
          <view class="yd-search-form-radio-group">
            <view
              v-for="opt in statusOptions"
@@ -153,8 +171,12 @@
          </view>
        </view>
        <view class="yd-search-form-actions">
-          <wd-button class="flex-1" plain @click="handleReset">重置</wd-button>
-          <wd-button class="flex-1" type="primary" @click="handleSearch">搜索</wd-button>
+          <wd-button class="flex-1" plain @click="handleReset">
+            重置
+          </wd-button>
+          <wd-button class="flex-1" type="primary" @click="handleSearch">
+            搜索
+          </wd-button>
        </view>
      </view>
    </wd-popup>
@@ -213,29 +235,34 @@ const statusOptions = [
 /** 搜索条件 placeholder */
 const searchPlaceholder = computed(() => {
  const conditions: string[] = []
-  if (searchForm.no) conditions.push(`单号:${searchForm.no}`)
+  if (searchForm.no)
+    conditions.push(`单号:${searchForm.no}`)
  if (searchForm.status !== undefined) {
    const statusLabel = statusOptions.find(o => o.value === searchForm.status)?.label
-    if (statusLabel && statusLabel !== '全部') conditions.push(`状态:${statusLabel}`)
+    if (statusLabel && statusLabel !== '全部')
+      conditions.push(`状态:${statusLabel}`)
  }
  return conditions.length > 0 ? conditions.join(' | ') : '搜索出库单'
 })

 /** 格式化数量 */
 function formatCount(count?: number) {
-  if (count === undefined || count === null) return '-'
+  if (count === undefined || count === null)
+    return '-'
  return count.toFixed(2)
 }

 /** 格式化金额 */
 function formatPrice(price?: number) {
-  if (price === undefined || price === null) return '-'
+  if (price === undefined || price === null)
+    return '-'
  return `¥${price.toFixed(2)}`
 }

 /** 格式化日期 */
 function formatDate(dateStr?: string) {
-  if (!dateStr) return '-'
+  if (!dateStr)
+    return '-'
  return dateStr.substring(0, 10)
 }

@@ -257,7 +284,8 @@ async function getList() {
  loadMoreState.value = 'loading'
  try {
    const params = { ...queryParams.value }
-    if (searchForm.no) params.no = searchForm.no
+    if (searchForm.no)
+      params.no = searchForm.no
    const data = await getStockOutPage(params)
    list.value = [...list.value, ...data.list]
    total.value = data.total
@@ -292,7 +320,8 @@ function handleReset() {

 /** 加载更多 */
 function loadMore() {
-  if (loadMoreState.value === 'finished') return
+  if (loadMoreState.value === 'finished')
+    return
  queryParams.value.pageNo++
  getList()
 }
@@ -307,6 +336,11 @@ function handleEdit(item: StockOut) {
  uni.navigateTo({ url: `/pages-erp/stock-out/form/index?id=${item.id}` })
 }

+/** 去扫码执行 */
+function handleTaskScan(item: StockOut) {
+  uni.navigateTo({ url: `/pages-erp/stock-out/task-scan/index?id=${item.id}` })
+}
+
 /** 详情 */
 function handleDetail(item: StockOut) {
  uni.navigateTo({ url: `/pages-erp/stock-out/detail/index?id=${item.id}` })
@@ -318,7 +352,8 @@ function handleApprove(id: number) {
    title: '提示',
    content: '确定要审批该出库单吗？',
    success: async (res) => {
-      if (!res.confirm) return
+      if (!res.confirm)
+        return
      try {
        await updateStockOutStatus(id, 20)
        toast.success('审批成功')
@@ -336,7 +371,8 @@ function handleReverseApprove(id: number) {
    title: '提示',
    content: '确定要反审批该出库单吗？',
    success: async (res) => {
-      if (!res.confirm) return
+      if (!res.confirm)
+        return
      try {
        await updateStockOutStatus(id, 10)
        toast.success('反审批成功')
@@ -354,7 +390,8 @@ function handleDelete(id: number) {
    title: '提示',
    content: '确定要删除该出库单吗？',
    success: async (res) => {
-      if (!res.confirm) return
+      if (!res.confirm)
+        return
      try {
        await deleteStockOut([id])
        toast.success('删除成功')
--- a/src/pages-erp/stock-out/scan/index.vue
+++ b/src/pages-erp/stock-out/scan/index.vue
@@ -31,6 +31,8 @@
        <view class="scan-section__title">
          扫码录入
        </view>
+        <input v-model="batchNo" class="scan-field" placeholder="请输入或扫描批次号（可选）">
+        <input v-model="locationCode" class="scan-field" placeholder="请输入或扫描库位码（可选）">
        <ScanInput
          v-model="scanCode"
          placeholder="请先选择仓库，再扫描产品条码"
@@ -53,7 +55,6 @@
 </template>

 <script setup lang="ts">
-import type { CustomerSimple } from '@/api/erp/customer'
 import type { ProductByBarCode } from '@/api/erp/product'
 import type { Stock } from '@/api/erp/stock'
 import type { StockOut, StockOutItem } from '@/api/erp/stock-out'
@@ -84,21 +85,33 @@ interface StockOutScanItem extends ItemCardValue {
  remark?: string
 }

+interface OptionalCustomerOption {
+  id?: number
+  name: string
+}
+
 const toast = useToast()
 const scanCode = ref('')
 const scanLoading = ref(false)
 const submitting = ref(false)
 const remark = ref('')
 const warehouses = ref<Warehouse[]>([])
-const customers = ref<CustomerSimple[]>([])
+const customers = ref<OptionalCustomerOption[]>([])
 const selectedWarehouseId = ref<number>()
 const selectedCustomerId = ref<number>()
 const items = ref<StockOutScanItem[]>([])
+const batchNo = ref('')
+const locationCode = ref('')
+
+const EMPTY_CUSTOMER_OPTION: OptionalCustomerOption = {
+  id: undefined,
+  name: '不选择客户（可选）',
+}

 const currentWarehouse = computed(() =>
  warehouses.value.find(item => item.id === selectedWarehouseId.value),
 )
-const currentCustomerName = computed(() => customers.value.find(item => item.id === selectedCustomerId.value)?.name || '请选择客户（可选）')
+const currentCustomerName = computed(() => customers.value.find(item => item.id === selectedCustomerId.value)?.name || EMPTY_CUSTOMER_OPTION.name)
 const selectedWarehouseIndex = computed(() => Math.max(warehouses.value.findIndex(item => item.id === selectedWarehouseId.value), 0))
 const selectedCustomerIndex = computed(() => {
  const index = customers.value.findIndex(item => item.id === selectedCustomerId.value)
@@ -128,7 +141,7 @@ async function loadInitialData() {
  ])

  warehouses.value = warehouseList
-  customers.value = customerList
+  customers.value = [EMPTY_CUSTOMER_OPTION, ...customerList]
  selectedWarehouseId.value = warehouseList.find(item => item.defaultStatus)?.id || warehouseList[0]?.id
 }

@@ -194,12 +207,22 @@ function validateStock(stockCount: number, nextCount: number, productName: strin
 */
 async function appendScannedProduct(product: ProductByBarCode) {
  const warehouseId = selectedWarehouseId.value as number
-  const targetKey = buildScanMergeKey({ warehouseId, productId: product.id, count: 1 })
+  const currentBatchNo = batchNo.value.trim()
+  const currentLocationCode = locationCode.value.trim()
+  const targetKey = buildScanMergeKey({
+    warehouseId,
+    productId: product.id,
+    count: 1,
+    batchNo: currentBatchNo,
+    locationCode: currentLocationCode,
+  }, true)
  const existedIndex = items.value.findIndex(item => buildScanMergeKey({
    warehouseId: item.warehouseId,
    productId: item.productId,
    count: item.count,
-  }) === targetKey)
+    batchNo: item.batchNo,
+    locationCode: item.locationCode,
+  }, true) === targetKey)
  const stockInfo = await loadStockInfo(product.id)
  const stockCount = Number(stockInfo?.count || 0)

@@ -211,6 +234,7 @@ async function appendScannedProduct(product: ProductByBarCode) {

    items.value[existedIndex].count = nextCount
    items.value[existedIndex].stockCount = stockCount
+    items.value[existedIndex].remainCount = Math.max(stockCount - nextCount, 0)
    return
  }

@@ -228,6 +252,9 @@ async function appendScannedProduct(product: ProductByBarCode) {
    productUnitName: product.unitName,
    productPrice: Number(stockInfo?.unitPrice ?? product.minPrice ?? 0),
    stockCount,
+    remainCount: Math.max(stockCount - 1, 0),
+    batchNo: currentBatchNo,
+    locationCode: currentLocationCode,
    count: 1,
  })
 }
@@ -319,6 +346,7 @@ async function increaseCount(index: number) {
  }

  item.stockCount = Number(stockInfo?.count || 0)
+  item.remainCount = Math.max(Number(stockInfo?.count || 0) - nextCount, 0)
  item.count = nextCount
 }

@@ -367,8 +395,10 @@ function clearItems() {
 function buildSubmitItems(): StockOutItem[] {
  return items.value.map(item => ({
    warehouseId: item.warehouseId,
+    locationCode: item.locationCode,
    productId: item.productId,
    productPrice: item.productPrice,
+    batchNo: item.batchNo,
    count: item.count,
    remark: item.remark,
  }))
@@ -393,16 +423,20 @@ async function handleSubmit() {
  submitting.value = true
  try {
    const payload: StockOut = {
-      customerId: selectedCustomerId.value,
      outTime: new Date().toISOString(),
      remark: remark.value,
      items: buildSubmitItems(),
    }
+    if (selectedCustomerId.value !== undefined) {
+      payload.customerId = selectedCustomerId.value
+    }

    await createStockOut(payload)
    toast.success('出库成功')
    clearItems()
    remark.value = ''
+    batchNo.value = ''
+    locationCode.value = ''
  } finally {
    submitting.value = false
  }
--- a/src/pages/index/index.ts
+++ b/src/pages/index/index.ts
@@ -138,6 +138,14 @@ const menuGroupsData: MenuGroup[] = [
        iconColor: '#722ed1',
        permission: 'erp:stock-record:query',
      },
+      {
+        key: 'purchaseInScan',
+        name: '扫码采购入库',
+        icon: 'scan',
+        url: '/pages-erp/purchase-in/scan/index',
+        iconColor: '#2f54eb',
+        permission: 'erp:purchase-in:query',
+      },
      {
        key: 'stockIn',
        name: '其他入库',
@@ -170,6 +178,14 @@ const menuGroupsData: MenuGroup[] = [
        iconColor: '#ff7a45',
        permission: 'erp:stock-out:query',
      },
+      {
+        key: 'stockOutTaskScan',
+        name: '扫码销售出库',
+        icon: 'scan',
+        url: '/pages-erp/stock-out/task-scan/index',
+        iconColor: '#cf1322',
+        permission: 'erp:stock-out:query',
+      },
      {
        key: 'stockGain',
        name: '库存报溢',
--- a/src/utils/tests/purchase-scan.spec.ts
+++ b/src/utils/tests/purchase-scan.spec.ts
@@ -0,0 +1,616 @@
+import { describe, expect, it } from 'vitest'
+import {
+  appendPurchaseBatchLocationItem,
+  appendPurchaseScanItem,
+  buildPurchasePendingGuideItems,
+  buildPurchasePendingItems,
+  buildPurchaseScanFeedback,
+  buildPurchaseSubmitGuard,
+  findPendingOrderItemByBarCode,
+  findPendingOrderItemForBatchFlow,
+  findPurchaseOrderByScanCode,
+  removePurchaseScanItemAt,
+  updatePurchaseScanItemCount,
+} from '../purchase-scan'
+
+function createOrderItem(overrides: Record<string, any> = {}) {
+  return {
+    id: 1,
+    productId: 101,
+    productBarCode: 'BC-001',
+    productName: '测试产品',
+    productUnitId: 11,
+    productUnitName: '件',
+    productPrice: 12.5,
+    productSpec: '10kg',
+    count: 10,
+    inCount: 2,
+    taxPercent: 13,
+    remark: '订单备注',
+    ...overrides,
+  }
+}
+
+function createPurchaseOrder(overrides: Record<string, any> = {}) {
+  return {
+    id: 1,
+    no: 'CG2025001',
+    supplierName: '供应商A',
+    ...overrides,
+  }
+}
+
+function createPurchaseScanItem(overrides: Record<string, any> = {}) {
+  return {
+    orderItemId: 1,
+    warehouseId: 9,
+    warehouseName: '默认仓',
+    productId: 101,
+    productName: '测试产品',
+    productBarCode: 'BC-001',
+    productSpec: '10kg',
+    productUnitId: 11,
+    productUnitName: '件',
+    productPrice: 12.5,
+    taxPercent: 13,
+    totalCount: 10,
+    inCount: 2,
+    remainCount: 7,
+    batchNo: 'B-01',
+    locationCode: 'A-01',
+    count: 1,
+    remark: '订单备注',
+    ...overrides,
+  }
+}
+
+describe('buildPurchasePendingItems', () => {
+  it('应只保留仍可入库的订单行', () => {
+    const items = buildPurchasePendingItems([
+      createOrderItem({ id: 1, count: 10, inCount: 8 }),
+      createOrderItem({ id: 2, count: 5, inCount: 5 }),
+    ], { id: 9, name: '默认仓' })
+
+    expect(items).toHaveLength(1)
+    expect(items[0].orderItemId).toBe(1)
+    expect(items[0].count).toBe(2)
+    expect(items[0].remainCount).toBe(2)
+    expect(items[0].warehouseId).toBe(9)
+  })
+})
+
+describe('buildPurchasePendingGuideItems', () => {
+  it('应只输出仍需提示扫码的商品，并保留核心展示字段', () => {
+    const result = buildPurchasePendingGuideItems([
+      createPurchaseScanItem({ productName: '苹果', productBarCode: 'BC-001', productSpec: '大果', productUnitName: '箱', remainCount: 3 }),
+      createPurchaseScanItem({ productName: '香蕉', productBarCode: 'BC-002', productSpec: '散装', productUnitName: '件', remainCount: 0 }),
+    ])
+
+    expect(result).toEqual([
+      {
+        orderItemId: 1,
+        productName: '苹果',
+        productBarCode: 'BC-001',
+        productSpec: '大果',
+        productUnitName: '箱',
+        remainCount: 3,
+      },
+    ])
+  })
+})
+
+describe('findPendingOrderItemByBarCode', () => {
+  it('应命中唯一待入库条码行', () => {
+    const result = findPendingOrderItemByBarCode([
+      createOrderItem({ id: 1, productBarCode: 'BC-001', count: 5, inCount: 1 }),
+    ], 'BC-001')
+
+    expect(result.type).toBe('matched')
+    if (result.type === 'matched') {
+      expect(result.item.id).toBe(1)
+      expect(result.remainCount).toBe(4)
+    }
+  })
+
+  it('同条码命中多个待入库订单行时应返回冲突', () => {
+    const result = findPendingOrderItemByBarCode([
+      createOrderItem({ id: 1, productBarCode: 'BC-001' }),
+      createOrderItem({ id: 2, productBarCode: 'BC-001' }),
+    ], 'BC-001')
+
+    expect(result.type).toBe('ambiguous')
+  })
+
+  it('没有可入库命中时应返回未找到', () => {
+    const result = findPendingOrderItemByBarCode([
+      createOrderItem({ id: 1, productBarCode: 'BC-001', count: 5, inCount: 5 }),
+    ], 'BC-001')
+
+    expect(result.type).toBe('not_found')
+  })
+})
+
+describe('findPendingOrderItemForBatchFlow', () => {
+  it('仅剩一个待入库物料时应允许直接进入批次库位流程', () => {
+    const result = findPendingOrderItemForBatchFlow([
+      createOrderItem({ id: 1, count: 8, inCount: 3 }),
+    ])
+
+    expect(result.type).toBe('matched')
+    if (result.type === 'matched') {
+      expect(result.item.id).toBe(1)
+      expect(result.remainCount).toBe(5)
+    }
+  })
+
+  it('存在多个待入库物料时应返回冲突', () => {
+    const result = findPendingOrderItemForBatchFlow([
+      createOrderItem({ id: 1, count: 8, inCount: 3 }),
+      createOrderItem({ id: 2, count: 6, inCount: 1 }),
+    ])
+
+    expect(result.type).toBe('ambiguous')
+  })
+})
+
+describe('findPurchaseOrderByScanCode', () => {
+  it('应按标准化后的订单编号精确命中', () => {
+    const result = findPurchaseOrderByScanCode([
+      createPurchaseOrder({ id: 1, no: 'CG-2025-001' }),
+      createPurchaseOrder({ id: 2, no: 'CG-2025-002' }),
+    ], ' cg2025001 ')
+
+    expect(result?.id).toBe(1)
+  })
+
+  it('未命中时应返回 undefined', () => {
+    const result = findPurchaseOrderByScanCode([
+      createPurchaseOrder({ id: 1, no: 'CG-2025-001' }),
+    ], 'CG2025999')
+
+    expect(result).toBeUndefined()
+  })
+})
+
+describe('appendPurchaseScanItem', () => {
+  it('首次扫码应新增一条采购入库明细', () => {
+    const result = appendPurchaseScanItem([], {
+      orderItem: createOrderItem({ id: 1 }),
+      warehouseId: 9,
+      warehouseName: '默认仓',
+      batchNo: 'B-01',
+      locationCode: 'A-01',
+    })
+
+    expect(result.ok).toBe(true)
+    if (result.ok) {
+      expect(result.items).toHaveLength(1)
+      expect(result.items[0].count).toBe(1)
+      expect(result.items[0].remainCount).toBe(7)
+    }
+  })
+
+  it('相同订单行且相同批次库位重复扫码应累计数量', () => {
+    const result = appendPurchaseScanItem([{
+      orderItemId: 1,
+      warehouseId: 9,
+      warehouseName: '默认仓',
+      productId: 101,
+      productName: '测试产品',
+      productBarCode: 'BC-001',
+      productSpec: '10kg',
+      productUnitId: 11,
+      productUnitName: '件',
+      productPrice: 12.5,
+      taxPercent: 13,
+      totalCount: 10,
+      inCount: 2,
+      remainCount: 8,
+      batchNo: 'B-01',
+      locationCode: 'A-01',
+      count: 1,
+    }], {
+      orderItem: createOrderItem({ id: 1 }),
+      warehouseId: 9,
+      warehouseName: '默认仓',
+      batchNo: 'B-01',
+      locationCode: 'A-01',
+    })
+
+    expect(result.ok).toBe(true)
+    if (result.ok) {
+      expect(result.items).toHaveLength(1)
+      expect(result.items[0].count).toBe(2)
+      expect(result.items[0].remainCount).toBe(6)
+    }
+  })
+
+  it('不同批次不应错误合并', () => {
+    const result = appendPurchaseScanItem([{
+      orderItemId: 1,
+      warehouseId: 9,
+      warehouseName: '默认仓',
+      productId: 101,
+      productName: '测试产品',
+      productBarCode: 'BC-001',
+      productSpec: '10kg',
+      productUnitId: 11,
+      productUnitName: '件',
+      productPrice: 12.5,
+      taxPercent: 13,
+      totalCount: 10,
+      inCount: 2,
+      remainCount: 8,
+      batchNo: 'B-01',
+      locationCode: 'A-01',
+      count: 1,
+    }], {
+      orderItem: createOrderItem({ id: 1 }),
+      warehouseId: 9,
+      warehouseName: '默认仓',
+      batchNo: 'B-02',
+      locationCode: 'A-01',
+    })
+
+    expect(result.ok).toBe(true)
+    if (result.ok) {
+      expect(result.items).toHaveLength(2)
+    }
+  })
+
+  it('相同批次但不同库位时不应错误合并', () => {
+    const result = appendPurchaseScanItem([{
+      orderItemId: 1,
+      warehouseId: 9,
+      warehouseName: '默认仓',
+      productId: 101,
+      productName: '测试产品',
+      productBarCode: 'BC-001',
+      productSpec: '10kg',
+      productUnitId: 11,
+      productUnitName: '件',
+      productPrice: 12.5,
+      taxPercent: 13,
+      totalCount: 10,
+      inCount: 2,
+      remainCount: 8,
+      batchNo: 'B-01',
+      locationCode: 'A-01',
+      count: 1,
+    }], {
+      orderItem: createOrderItem({ id: 1 }),
+      warehouseId: 9,
+      warehouseName: '默认仓',
+      batchNo: 'B-01',
+      locationCode: 'A-02',
+    })
+
+    expect(result.ok).toBe(true)
+    if (result.ok) {
+      expect(result.items).toHaveLength(2)
+      expect(result.items[0].locationCode).toBe('A-02')
+      expect(result.items[1].locationCode).toBe('A-01')
+    }
+  })
+
+  it('累计数量超过订单剩余数时应拦截', () => {
+    const result = appendPurchaseScanItem([{
+      orderItemId: 1,
+      warehouseId: 9,
+      warehouseName: '默认仓',
+      productId: 101,
+      productName: '测试产品',
+      productBarCode: 'BC-001',
+      productSpec: '10kg',
+      productUnitId: 11,
+      productUnitName: '件',
+      productPrice: 12.5,
+      taxPercent: 13,
+      totalCount: 3,
+      inCount: 2,
+      remainCount: 1,
+      batchNo: 'B-01',
+      locationCode: 'A-01',
+      count: 1,
+    }], {
+      orderItem: createOrderItem({ id: 1, count: 3, inCount: 2 }),
+      warehouseId: 9,
+      warehouseName: '默认仓',
+      batchNo: 'B-01',
+      locationCode: 'A-01',
+    })
+
+    expect(result.ok).toBe(false)
+    expect(result).toMatchObject({ ok: false, reason: 'exceed_remaining' })
+  })
+
+  it('同一订单行跨批次累计超过剩余数时也应拦截', () => {
+    const result = appendPurchaseScanItem([
+      {
+        orderItemId: 1,
+        warehouseId: 9,
+        warehouseName: '默认仓',
+        productId: 101,
+        productName: '测试产品',
+        productBarCode: 'BC-001',
+        productSpec: '10kg',
+        productUnitId: 11,
+        productUnitName: '件',
+        productPrice: 12.5,
+        taxPercent: 13,
+        totalCount: 4,
+        inCount: 2,
+        remainCount: 1,
+        batchNo: 'B-01',
+        locationCode: 'A-01',
+        count: 1,
+      },
+      {
+        orderItemId: 1,
+        warehouseId: 9,
+        warehouseName: '默认仓',
+        productId: 101,
+        productName: '测试产品',
+        productBarCode: 'BC-001',
+        productSpec: '10kg',
+        productUnitId: 11,
+        productUnitName: '件',
+        productPrice: 12.5,
+        taxPercent: 13,
+        totalCount: 4,
+        inCount: 2,
+        remainCount: 1,
+        batchNo: 'B-02',
+        locationCode: 'A-01',
+        count: 1,
+      },
+    ], {
+      orderItem: createOrderItem({ id: 1, count: 4, inCount: 2 }),
+      warehouseId: 9,
+      warehouseName: '默认仓',
+      batchNo: 'B-03',
+      locationCode: 'A-01',
+    })
+
+    expect(result.ok).toBe(false)
+    expect(result).toMatchObject({ ok: false, reason: 'exceed_remaining' })
+  })
+})
+
+describe('appendPurchaseBatchLocationItem', () => {
+  it('首次按批次库位确认时应按剩余数量创建记录', () => {
+    const result = appendPurchaseBatchLocationItem([], {
+      orderItem: createOrderItem({ id: 1, count: 10, inCount: 2 }),
+      warehouseId: 9,
+      warehouseName: '默认仓',
+      batchNo: 'B-01',
+      locationCode: 'A-01',
+    })
+
+    expect(result.ok).toBe(true)
+    if (result.ok) {
+      expect(result.items).toHaveLength(1)
+      expect(result.items[0].count).toBe(8)
+      expect(result.items[0].remainCount).toBe(0)
+    }
+  })
+
+  it('同订单行同批次同库位重复确认时不应超出剩余上限', () => {
+    const result = appendPurchaseBatchLocationItem([
+      createPurchaseScanItem({
+        orderItemId: 1,
+        totalCount: 10,
+        inCount: 2,
+        remainCount: 0,
+        count: 8,
+        batchNo: 'B-01',
+        locationCode: 'A-01',
+      }),
+    ], {
+      orderItem: createOrderItem({ id: 1, count: 10, inCount: 2 }),
+      warehouseId: 9,
+      warehouseName: '默认仓',
+      batchNo: 'B-01',
+      locationCode: 'A-01',
+    })
+
+    expect(result.ok).toBe(false)
+    expect(result).toMatchObject({ ok: false, reason: 'exceed_remaining' })
+  })
+})
+
+describe('appendPurchaseScanItem recent-first behavior', () => {
+  it('新增不同批次时应把最新记录放在最前面', () => {
+    const result = appendPurchaseScanItem([{
+      orderItemId: 1,
+      warehouseId: 9,
+      warehouseName: '默认仓',
+      productId: 101,
+      productName: '测试产品',
+      productBarCode: 'BC-001',
+      productUnitId: 11,
+      productUnitName: '件',
+      productPrice: 12.5,
+      totalCount: 10,
+      inCount: 2,
+      remainCount: 7,
+      batchNo: 'B-01',
+      locationCode: 'A-01',
+      count: 1,
+    }], {
+      orderItem: createOrderItem({ id: 1 }),
+      warehouseId: 9,
+      warehouseName: '默认仓',
+      batchNo: 'B-02',
+      locationCode: 'A-01',
+    })
+
+    expect(result.ok).toBe(true)
+    if (result.ok) {
+      expect(result.items[0].batchNo).toBe('B-02')
+      expect(result.items[1].batchNo).toBe('B-01')
+    }
+  })
+})
+
+describe('buildPurchaseSubmitGuard', () => {
+  it('缺少采购订单时不允许提交', () => {
+    expect(buildPurchaseSubmitGuard({
+      hasOrder: false,
+      hasAccount: true,
+      itemCount: 2,
+      exceptionCount: 0,
+    })).toEqual({
+      ok: false,
+      reason: '请先选择采购订单',
+    })
+  })
+
+  it('缺少结算账户时不允许提交', () => {
+    expect(buildPurchaseSubmitGuard({
+      hasOrder: true,
+      hasAccount: false,
+      itemCount: 2,
+      exceptionCount: 0,
+    })).toEqual({
+      ok: false,
+      reason: '请选择结算账户',
+    })
+  })
+
+  it('没有扫码明细时不允许提交', () => {
+    expect(buildPurchaseSubmitGuard({
+      hasOrder: true,
+      hasAccount: true,
+      itemCount: 0,
+      exceptionCount: 0,
+    })).toEqual({
+      ok: false,
+      reason: '请先扫描入库明细',
+    })
+  })
+
+  it('存在异常时不允许提交', () => {
+    expect(buildPurchaseSubmitGuard({
+      hasOrder: true,
+      hasAccount: true,
+      itemCount: 2,
+      exceptionCount: 1,
+    })).toEqual({
+      ok: false,
+      reason: '存在未处理异常，请先处理后再提交',
+    })
+  })
+
+  it('前置条件全部满足时允许提交', () => {
+    expect(buildPurchaseSubmitGuard({
+      hasOrder: true,
+      hasAccount: true,
+      itemCount: 2,
+      exceptionCount: 0,
+    })).toEqual({ ok: true })
+  })
+})
+
+describe('buildPurchaseScanFeedback', () => {
+  it('成功扫码时应返回 success 状态文案', () => {
+    expect(buildPurchaseScanFeedback({
+      type: 'success',
+      productName: '西兰花',
+      delta: 1,
+      scannedCount: 12,
+      targetCount: 30,
+    })).toMatchObject({
+      tone: 'success',
+      message: '西兰花 +1，已扫 12 / 30',
+    })
+  })
+
+  it('数量减少时应返回负向调整文案', () => {
+    expect(buildPurchaseScanFeedback({
+      type: 'success',
+      productName: '西兰花',
+      delta: -1,
+      scannedCount: 11,
+      targetCount: 30,
+    })).toMatchObject({
+      tone: 'success',
+      message: '西兰花 -1，已扫 11 / 30',
+    })
+  })
+
+  it('失败扫码时应优先返回指定错误文案', () => {
+    expect(buildPurchaseScanFeedback({
+      type: 'error',
+      message: '商品条码未匹配到采购订单',
+    })).toMatchObject({
+      tone: 'error',
+      message: '商品条码未匹配到采购订单',
+    })
+  })
+
+  it('失败扫码未传文案时应返回默认兜底提示', () => {
+    expect(buildPurchaseScanFeedback({
+      type: 'error',
+    })).toMatchObject({
+      tone: 'error',
+      message: '扫码失败，请重试',
+    })
+  })
+})
+
+describe('removePurchaseScanItemAt', () => {
+  it('撤销首条记录后应删除该项并保留其他记录', () => {
+    const result = removePurchaseScanItemAt([
+      { ...createPurchaseScanItem({ batchNo: 'B-01', count: 1 }) },
+      { ...createPurchaseScanItem({ batchNo: 'B-02', count: 2 }) },
+    ], 0)
+
+    expect(result).toHaveLength(1)
+    expect(result[0].batchNo).toBe('B-02')
+  })
+})
+
+describe('updatePurchaseScanItemCount', () => {
+  it('应更新目标行数量并回写该行剩余数量', () => {
+    const result = updatePurchaseScanItemCount([
+      createPurchaseScanItem({ orderItemId: 1, count: 2, remainCount: 6, batchNo: 'B-01' }),
+      createPurchaseScanItem({ orderItemId: 1, count: 1, remainCount: 7, batchNo: 'B-02' }),
+    ], 0, 3)
+
+    expect(result.ok).toBe(true)
+    if (result.ok) {
+      expect(result.items[0].count).toBe(3)
+      expect(result.items[0].remainCount).toBe(4)
+      expect(result.items[1].count).toBe(1)
+    }
+  })
+
+  it('同一订单行累计超出剩余上限时应拦截', () => {
+    const result = updatePurchaseScanItemCount([
+      createPurchaseScanItem({ orderItemId: 1, totalCount: 10, inCount: 2, count: 5, remainCount: 3, batchNo: 'B-01' }),
+      createPurchaseScanItem({ orderItemId: 1, totalCount: 10, inCount: 2, count: 2, remainCount: 6, batchNo: 'B-02' }),
+    ], 0, 7)
+
+    expect(result.ok).toBe(false)
+    expect(result).toMatchObject({ ok: false, reason: 'exceed_remaining' })
+  })
+
+  it('数量小于 1 时应拦截', () => {
+    const result = updatePurchaseScanItemCount([
+      createPurchaseScanItem({ count: 2 }),
+    ], 0, 0)
+
+    expect(result.ok).toBe(false)
+    expect(result).toMatchObject({ ok: false, reason: 'invalid_count' })
+  })
+
+  it('索引不存在时应返回 not_found', () => {
+    const result = updatePurchaseScanItemCount([
+      createPurchaseScanItem({ count: 2 }),
+    ], 9, 3)
+
+    expect(result.ok).toBe(false)
+    expect(result).toMatchObject({ ok: false, reason: 'not_found' })
+  })
+})
--- a/src/utils/tests/scan.spec.ts
+++ b/src/utils/tests/scan.spec.ts
@@ -21,6 +21,8 @@ function createItem(overrides: Partial<ScanItem> = {}): ScanItem {
    productId: 1001,
    count: 1,
    orderItemId: undefined,
+    batchNo: undefined,
+    locationCode: undefined,
    ...overrides,
  }
 }
@@ -51,7 +53,15 @@ describe('buildScanMergeKey', () => {
  })

  it('订单约束模式应额外带上订单明细编号', () => {
-    expect(buildScanMergeKey(createItem({ orderItemId: 5001 }), true)).toBe('1:1001:5001')
+    expect(buildScanMergeKey(createItem({ orderItemId: 5001 }), true)).toBe('1:1001:5001::')
+  })
+
+  it('订单约束模式应带上批次号和库位码', () => {
+    expect(buildScanMergeKey(createItem({
+      orderItemId: 5001,
+      batchNo: 'BATCH-01',
+      locationCode: 'A-01-02',
+    }), true)).toBe('1:1001:5001:BATCH-01:A-01-02')
  })
 })

@@ -78,4 +88,24 @@ describe('mergeScannedItem', () => {

    expect(merged).toHaveLength(2)
  })
+
+  it('订单约束模式下不同批次不应合并', () => {
+    const merged = mergeScannedItem(
+      [createItem({ orderItemId: 9001, batchNo: 'BATCH-01', locationCode: 'A-01' })],
+      createItem({ orderItemId: 9001, batchNo: 'BATCH-02', locationCode: 'A-01' }),
+      true,
+    )
+
+    expect(merged).toHaveLength(2)
+  })
+
+  it('订单约束模式下不同库位不应合并', () => {
+    const merged = mergeScannedItem(
+      [createItem({ orderItemId: 9001, batchNo: 'BATCH-01', locationCode: 'A-01' })],
+      createItem({ orderItemId: 9001, batchNo: 'BATCH-01', locationCode: 'A-02' }),
+      true,
+    )
+
+    expect(merged).toHaveLength(2)
+  })
 })
--- a/src/utils/purchase-scan.ts
+++ b/src/utils/purchase-scan.ts
@@ -0,0 +1,498 @@
+import type { PurchaseInItem } from '@/api/erp/purchase-in'
+import type { PurchaseOrder, PurchaseOrderItem } from '@/api/erp/purchase-order'
+
+export interface PurchaseScanItem extends PurchaseInItem {
+  productBarCode?: string
+  productSpec?: string
+  totalCount?: number
+  inCount?: number
+  remainCount?: number
+  batchNo?: string
+  locationCode?: string
+}
+
+export interface PurchaseWarehouseOption {
+  id?: number
+  name?: string
+}
+
+export interface PurchasePendingGuideItem {
+  orderItemId?: number
+  productName?: string
+  productBarCode?: string
+  productSpec?: string
+  productUnitName?: string
+  remainCount?: number
+}
+
+interface PendingLookupMatched {
+  type: 'matched'
+  item: PurchaseOrderItem
+  remainCount: number
+}
+
+interface PendingLookupAmbiguous {
+  type: 'ambiguous'
+}
+
+interface PendingLookupNotFound {
+  type: 'not_found'
+}
+
+type PendingLookupResult = PendingLookupMatched | PendingLookupAmbiguous | PendingLookupNotFound
+
+interface AppendPurchaseScanSuccess {
+  ok: true
+  items: PurchaseScanItem[]
+}
+
+interface AppendPurchaseScanFailure {
+  ok: false
+  reason: 'exceed_remaining'
+}
+
+interface UpdatePurchaseScanFailure {
+  ok: false
+  reason: 'exceed_remaining' | 'invalid_count' | 'not_found'
+}
+
+export interface PurchaseScanFeedback {
+  tone: 'success' | 'error'
+  message: string
+}
+
+/**
+ * 功能说明：判断两条采购扫码记录是否允许合并
+ * 适用场景：采购扫码时识别是否命中同一订单行、同一仓库、同一批次和同一库位
+ * @param current 已存在的扫码记录
+ * @param payload 本次扫码载荷
+ * @return 字段完全匹配时返回 true，否则返回 false
+ * 注意事项：这里使用本地字段比较，避免依赖其他扫描域的通用 merge key 逻辑导致采购批次/库位约束失效
+ */
+function isSamePurchaseScanTarget(
+  current: PurchaseScanItem,
+  payload: {
+    orderItem: PurchaseOrderItem
+    warehouseId?: number
+    batchNo?: string
+    locationCode?: string
+  },
+): boolean {
+  // 批次号和库位编码统一转成字符串兜底，避免 undefined 与空字符串比较不一致导致误合并
+  const currentBatchNo = String(current.batchNo || '')
+  const targetBatchNo = String(payload.batchNo || '')
+  const currentLocationCode = String(current.locationCode || '')
+  const targetLocationCode = String(payload.locationCode || '')
+
+  return Number(current.orderItemId || 0) === Number(payload.orderItem.id || 0)
+    && Number(current.warehouseId || 0) === Number(payload.warehouseId || 0)
+    && Number(current.productId || 0) === Number(payload.orderItem.productId || 0)
+    && currentBatchNo === targetBatchNo
+    && currentLocationCode === targetLocationCode
+}
+
+/**
+ * 功能说明：构建采购扫码台待入库明细列表
+ * 适用场景：采购订单选定后，生成仍可入库的候选明细
+ * @param orderItems 采购订单明细列表
+ * @param warehouse 当前选中的仓库信息
+ * @return 仅包含仍可入库数量的扫码明细列表
+ * 注意事项：会过滤掉剩余数量小于等于 0 的订单行，避免无效扫码
+ */
+export function buildPurchasePendingItems(
+  orderItems: PurchaseOrderItem[],
+  warehouse?: PurchaseWarehouseOption,
+): PurchaseScanItem[] {
+  return orderItems
+    .filter(item => Number(item.count || 0) - Number(item.inCount || 0) > 0)
+    .map((item) => {
+      const remainCount = Number(item.count || 0) - Number(item.inCount || 0)
+      return {
+        orderItemId: item.id,
+        warehouseId: warehouse?.id,
+        warehouseName: warehouse?.name,
+        productId: item.productId,
+        productName: item.productName,
+        productBarCode: item.productBarCode,
+        productUnitId: item.productUnitId,
+        productUnitName: item.productUnitName,
+        productPrice: item.productPrice,
+        productSpec: item.productSpec,
+        taxPercent: item.taxPercent,
+        totalCount: item.count,
+        inCount: item.inCount,
+        remainCount,
+        count: remainCount,
+        remark: item.remark,
+      }
+    })
+}
+
+/**
+ * 功能说明：构建采购扫码工作台的待扫码提示清单。
+ * 适用场景：采购单锁定成功后，向操作员展示当前还需要扫码入库的商品。
+ * @param items 当前仍待入库的采购扫码明细
+ * @return 仅包含提示展示所需字段的轻量列表
+ * 注意事项：只保留剩余数量大于 0 的记录，避免把已完成项继续展示在待扫码提示区。
+ */
+export function buildPurchasePendingGuideItems(items: PurchaseScanItem[]): PurchasePendingGuideItem[] {
+  return items
+    .filter(item => Number(item.remainCount || 0) > 0)
+    .map(item => ({
+      orderItemId: item.orderItemId,
+      productName: item.productName,
+      productBarCode: item.productBarCode,
+      productSpec: item.productSpec,
+      productUnitName: item.productUnitName,
+      remainCount: item.remainCount,
+    }))
+}
+
+/**
+ * 功能说明：根据条码查找唯一可扫码的采购订单行
+ * 适用场景：PDA 扫码商品条码后定位待入库订单明细
+ * @param orderItems 采购订单明细列表
+ * @param barCode 扫描得到的商品条码
+ * @return 唯一命中、冲突或未命中的查找结果
+ * 注意事项：只会匹配剩余可入库数量大于 0 的订单行
+ */
+export function findPendingOrderItemByBarCode(
+  orderItems: PurchaseOrderItem[],
+  barCode: string,
+): PendingLookupResult {
+  const matchedItems = orderItems.filter((item) => {
+    const remainCount = Number(item.count || 0) - Number(item.inCount || 0)
+    return remainCount > 0 && item.productBarCode === barCode
+  })
+
+  if (matchedItems.length === 0) {
+    return { type: 'not_found' }
+  }
+
+  if (matchedItems.length > 1) {
+    return { type: 'ambiguous' }
+  }
+
+  const item = matchedItems[0]
+  return {
+    type: 'matched',
+    item,
+    remainCount: Number(item.count || 0) - Number(item.inCount || 0),
+  }
+}
+
+/**
+ * 功能说明：在不扫描商品码的采购入库场景下，判断当前采购单是否能直接进入批次/库位流程。
+ * 适用场景：原辅料采购入库锁单后，仅当待入库物料唯一时允许继续扫描批次和库位。
+ * @param orderItems 采购订单明细列表
+ * @return 唯一命中、冲突或未命中的查找结果
+ * 注意事项：多个待入库订单行时前端不应擅自猜测目标物料，否则会把整批原辅料记到错误订单行。
+ */
+export function findPendingOrderItemForBatchFlow(
+  orderItems: PurchaseOrderItem[],
+): PendingLookupResult {
+  const pendingItems = orderItems.filter((item) => {
+    const remainCount = Number(item.count || 0) - Number(item.inCount || 0)
+    return remainCount > 0
+  })
+
+  if (pendingItems.length === 0) {
+    return { type: 'not_found' }
+  }
+
+  if (pendingItems.length > 1) {
+    return { type: 'ambiguous' }
+  }
+
+  const item = pendingItems[0]
+  return {
+    type: 'matched',
+    item,
+    remainCount: Number(item.count || 0) - Number(item.inCount || 0),
+  }
+}
+
+/**
+ * 功能说明：根据扫码内容匹配采购订单
+ * 适用场景：扫描采购单号后在已加载订单列表中定位目标订单
+ * @param orders 采购订单列表
+ * @param scanCode 扫描得到的订单编码
+ * @return 匹配到的采购订单，未命中时返回 undefined
+ * 注意事项：会先做去空格、去分隔符和大写标准化，兼容扫码枪格式差异
+ */
+export function findPurchaseOrderByScanCode(
+  orders: PurchaseOrder[],
+  scanCode: string,
+): PurchaseOrder | undefined {
+  const normalizedCode = scanCode.trim().replace(/[^a-z0-9]/gi, '').toUpperCase()
+  if (!normalizedCode) {
+    return undefined
+  }
+
+  return orders.find((item) => {
+    const normalizedNo = String(item.no || '').trim().replace(/[^a-z0-9]/gi, '').toUpperCase()
+    return normalizedNo === normalizedCode
+  })
+}
+
+/**
+ * 功能说明：追加一条采购扫码记录，并在可合并时累加数量
+ * 适用场景：PDA 每次成功扫码后更新本地入库明细列表
+ * @param items 当前已扫码的采购入库明细
+ * @param payload 本次扫码匹配到的订单行及批次库位信息
+ * @return 追加成功时返回最新明细列表，超出剩余数量时返回失败原因
+ * 注意事项：不同批次或库位不能合并；新增记录需要放在最前面，保证最近扫码优先展示
+ */
+export function appendPurchaseScanItem(
+  items: PurchaseScanItem[],
+  payload: {
+    orderItem: PurchaseOrderItem
+    warehouseId?: number
+    warehouseName?: string
+    batchNo?: string
+    locationCode?: string
+  },
+): AppendPurchaseScanSuccess | AppendPurchaseScanFailure {
+  const remainCount = Number(payload.orderItem.count || 0) - Number(payload.orderItem.inCount || 0)
+  const scannedTotal = items
+    .filter(item => item.orderItemId === payload.orderItem.id)
+    .reduce((sum, item) => sum + Number(item.count || 0), 0)
+  // 采购扫码的合并约束必须在本域内自包含，防止共享扫描工具变更后破坏批次/库位隔离语义
+  const existedIndex = items.findIndex(item => isSamePurchaseScanTarget(item, payload))
+
+  if (existedIndex >= 0) {
+    const nextCount = Number(items[existedIndex].count || 0) + 1
+    // 这里按订单行累计校验，避免跨批次累计后超出采购订单剩余可入库数量
+    if (scannedTotal + 1 > remainCount) {
+      return { ok: false, reason: 'exceed_remaining' }
+    }
+
+    return {
+      ok: true,
+      items: items.map((item, index) => (
+        index === existedIndex
+          ? {
+              ...item,
+              count: nextCount,
+              remainCount: remainCount - nextCount,
+            }
+          : item
+      )),
+    }
+  }
+
+  // 新批次新增时同样需要校验总扫码数，避免不同批次拆分后绕过剩余数量限制
+  if (scannedTotal + 1 > remainCount) {
+    return { ok: false, reason: 'exceed_remaining' }
+  }
+
+  return {
+    ok: true,
+    // 最近一次扫码的记录放在最前面，便于 PDA 工作台优先展示最新操作结果
+    items: [{
+      orderItemId: payload.orderItem.id,
+      warehouseId: payload.warehouseId,
+      warehouseName: payload.warehouseName,
+      productId: payload.orderItem.productId,
+      productName: payload.orderItem.productName,
+      productBarCode: payload.orderItem.productBarCode,
+      productUnitId: payload.orderItem.productUnitId,
+      productUnitName: payload.orderItem.productUnitName,
+      productPrice: payload.orderItem.productPrice,
+      productSpec: payload.orderItem.productSpec,
+      taxPercent: payload.orderItem.taxPercent,
+      totalCount: payload.orderItem.count,
+      inCount: payload.orderItem.inCount,
+      remainCount: remainCount - 1,
+      batchNo: payload.batchNo,
+      locationCode: payload.locationCode,
+      count: 1,
+      remark: payload.orderItem.remark,
+    }, ...items],
+  }
+}
+
+/**
+ * 功能说明：按批次和库位确认一条采购入库记录，不依赖商品条码扫描。
+ * 适用场景：原辅料采购入库锁单后，扫描批次号和库位码完成上架确认。
+ * @param items 当前已确认的采购入库明细
+ * @param payload 本次确认对应的订单行及批次库位信息
+ * @return 新增成功时返回最新明细列表，超出剩余数量时返回失败原因
+ * 注意事项：默认按当前订单行剩余数量整行确认；若后续存在部分入库，再由工作台手动调整数量。
+ */
+export function appendPurchaseBatchLocationItem(
+  items: PurchaseScanItem[],
+  payload: {
+    orderItem: PurchaseOrderItem
+    warehouseId?: number
+    warehouseName?: string
+    batchNo?: string
+    locationCode?: string
+  },
+): AppendPurchaseScanSuccess | AppendPurchaseScanFailure {
+  const remainCount = Number(payload.orderItem.count || 0) - Number(payload.orderItem.inCount || 0)
+  const existedIndex = items.findIndex(item => isSamePurchaseScanTarget(item, payload))
+
+  if (remainCount < 1) {
+    return { ok: false, reason: 'exceed_remaining' }
+  }
+
+  if (existedIndex >= 0) {
+    return { ok: false, reason: 'exceed_remaining' }
+  }
+
+  return {
+    ok: true,
+    items: [{
+      orderItemId: payload.orderItem.id,
+      warehouseId: payload.warehouseId,
+      warehouseName: payload.warehouseName,
+      productId: payload.orderItem.productId,
+      productName: payload.orderItem.productName,
+      productBarCode: payload.orderItem.productBarCode,
+      productUnitId: payload.orderItem.productUnitId,
+      productUnitName: payload.orderItem.productUnitName,
+      productPrice: payload.orderItem.productPrice,
+      productSpec: payload.orderItem.productSpec,
+      taxPercent: payload.orderItem.taxPercent,
+      totalCount: payload.orderItem.count,
+      inCount: payload.orderItem.inCount,
+      remainCount: 0,
+      batchNo: payload.batchNo,
+      locationCode: payload.locationCode,
+      count: remainCount,
+      remark: payload.orderItem.remark,
+    }, ...items],
+  }
+}
+
+/**
+ * 功能说明：构建采购扫码后的前端反馈文案
+ * 适用场景：扫码成功或失败后，统一生成工作台提示消息
+ * @param payload 扫码结果及相关上下文
+ * @return 标准化的反馈状态和提示文案
+ * 注意事项：成功场景会对商品名、增量和进度做默认值兜底，避免提示文案缺失
+ */
+export function buildPurchaseScanFeedback(payload: {
+  type: 'success' | 'error'
+  productName?: string
+  delta?: number
+  scannedCount?: number
+  targetCount?: number
+  message?: string
+}): PurchaseScanFeedback {
+  if (payload.type === 'error') {
+    return {
+      tone: 'error',
+      message: payload.message || '扫码失败，请重试',
+    }
+  }
+
+  const delta = Number(payload.delta ?? 1)
+  const deltaText = delta >= 0 ? `+${delta}` : String(delta)
+
+  return {
+    tone: 'success',
+    message: `${payload.productName || '商品'} ${deltaText}，已扫 ${payload.scannedCount || 0} / ${payload.targetCount || 0}`,
+  }
+}
+
+/**
+ * 功能说明：按索引移除一条采购扫码记录
+ * 适用场景：用户撤销最近或指定一条扫码明细
+ * @param items 当前已扫码明细列表
+ * @param index 需要删除的目标索引
+ * @return 删除目标索引后的新列表
+ * 注意事项：保持其他记录原有顺序不变，便于工作台撤销后稳定渲染
+ */
+export function removePurchaseScanItemAt(
+  items: PurchaseScanItem[],
+  index: number,
+): PurchaseScanItem[] {
+  return items.filter((_, currentIndex) => currentIndex !== index)
+}
+
+/**
+ * 功能说明：更新指定采购扫码记录的数量，并校验整条订单行累计数量上限。
+ * 适用场景：PDA 工作台手动加减数量，或直接录入目标数量。
+ * @param items 当前已扫码明细列表
+ * @param index 需要更新的目标索引
+ * @param nextCount 调整后的目标数量
+ * @return 更新成功时返回新列表，非法数量或超上限时返回失败原因
+ * 注意事项：校验维度按订单行累计执行，避免多批次/多库位拆分后绕过采购剩余数量约束。
+ */
+export function updatePurchaseScanItemCount(
+  items: PurchaseScanItem[],
+  index: number,
+  nextCount: number,
+): AppendPurchaseScanSuccess | UpdatePurchaseScanFailure {
+  const targetItem = items[index]
+  if (!targetItem) {
+    return { ok: false, reason: 'not_found' }
+  }
+
+  const normalizedNextCount = Number(nextCount)
+  if (!Number.isFinite(normalizedNextCount) || normalizedNextCount < 1) {
+    return { ok: false, reason: 'invalid_count' }
+  }
+
+  const remainCount = Number(targetItem.totalCount || 0) - Number(targetItem.inCount || 0)
+  const nextScannedTotal = items.reduce((sum, item, currentIndex) => {
+    if (item.orderItemId !== targetItem.orderItemId) {
+      return sum
+    }
+
+    return sum + Number(currentIndex === index ? normalizedNextCount : item.count || 0)
+  }, 0)
+
+  if (nextScannedTotal > remainCount) {
+    return { ok: false, reason: 'exceed_remaining' }
+  }
+
+  return {
+    ok: true,
+    items: items.map((item, currentIndex) => {
+      if (item.orderItemId !== targetItem.orderItemId) {
+        return item
+      }
+
+      return {
+        ...item,
+        count: currentIndex === index ? normalizedNextCount : item.count,
+        remainCount: remainCount - nextScannedTotal,
+      }
+    }),
+  }
+}
+
+/**
+ * 功能说明：构建采购入库提交前的门禁校验结果
+ * 适用场景：提交采购入库单前统一检查前置条件和异常状态
+ * @param payload 提交所需的订单、账户、明细和异常统计信息
+ * @return 校验通过返回 ok=true，否则返回不可提交原因
+ * 注意事项：校验顺序按业务前置条件执行，优先给出最直接的阻断原因
+ */
+export function buildPurchaseSubmitGuard(payload: {
+  hasOrder: boolean
+  hasAccount: boolean
+  itemCount: number
+  exceptionCount: number
+}): { ok: true } | { ok: false, reason: string } {
+  // 未选采购订单时直接阻断，避免后续明细和账户校验失去业务上下文
+  if (!payload.hasOrder) {
+    return { ok: false, reason: '请先选择采购订单' }
+  }
+  // 结算账户是提交单据的必要字段，缺失时不能继续提交
+  if (!payload.hasAccount) {
+    return { ok: false, reason: '请选择结算账户' }
+  }
+  // 没有扫码明细时提交没有业务意义，需要明确拦截
+  if (payload.itemCount <= 0) {
+    return { ok: false, reason: '请先扫描入库明细' }
+  }
+  // 存在未处理异常时阻断提交，避免异常数据直接进入正式入库流程
+  if (payload.exceptionCount > 0) {
+    return { ok: false, reason: '存在未处理异常，请先处理后再提交' }
+  }
+  return { ok: true }
+}
--- a/src/utils/scan.ts
+++ b/src/utils/scan.ts
@@ -7,6 +7,8 @@ export interface ScanItem {
  productId: number
  count: number
  orderItemId?: number
+  batchNo?: string
+  locationCode?: string
 }

 /**
@@ -40,11 +42,13 @@ export function normalizeCameraScanResult(result?: { result?: string } | null):
 * 注意事项：订单约束场景若不带订单行编号，会把不同订单行的同一产品错误合并。
 */
 export function buildScanMergeKey(item: ScanItem, withOrderConstraint = false): string {
-  const segments = [item.warehouseId, item.productId]
+  const segments = [String(item.warehouseId), String(item.productId)]

  // 订单约束扫码时需要把订单明细编号带入合并键，避免不同订单行误合并。
  if (withOrderConstraint) {
-    segments.push(item.orderItemId || 0)
+    segments.push(String(item.orderItemId || 0))
+    segments.push(item.batchNo || '')
+    segments.push(item.locationCode || '')
  }

  return segments.join(':')
--- a/vite.config.ts
+++ b/vite.config.ts
@@ -101,6 +101,7 @@ export default defineConfig(({ command, mode }) => {
      }),
      // Components 需要在 Uni 之前引入
      Components({
+        resolvers: [WotResolver()],
        extensions: ['vue'],
        deep: true, // 是否递归扫描子目录，
        directoryAsNamespace: false, // 是否把目录名作为命名空间前缀，true 时组件名为 目录名+组件名，
@@ -154,13 +155,6 @@ export default defineConfig(({ command, mode }) => {
        },
      ),
      syncManifestPlugin(),
-      Components({
-        resolvers: [WotResolver()],
-        extensions: ['vue'],
-        deep: true, // 是否递归扫描子目录，
-        directoryAsNamespace: false, // 是否把目录名作为命名空间前缀，true 时组件名为 目录名+组件名，
-        dts: 'src/types/components.d.ts', // 自动生成的组件类型声明文件路径（用于 TypeScript 支持）
-      }),
      // 自动打开开发者工具插件 (必须修改 .env 文件中的 VITE_WX_APPID)
      openDevTools(),
    ],