# SHOPEE_011_AGV出库分拣V1.1

> 来源文件：`C:\work\gitlab\shopee\ttx-project-doc\拣货\SHOPEE_011_AGV出库分拣V1.1.docx`
> 生成说明：由 docx 抽取正文、表格和内嵌图片生成，保留原文结构并补充简要分析。

## 文档分析摘要

- 本文档描述 Shopee WES 客户化场景下的 AGV 分拣出库方案。
- 核心数据调整包含操作员技能表 `operator_skills`，用于控制拣选模式、出库单类型和分拣模式权限。
- 功能重点围绕工作站登录、工作模式控制、集波抓单、绑箱/换箱和 AGV 调度前置校验。

Shopee WES客户化设计

| 文档编号： | Shopee_011 |
| --- | --- |
| 文档内容： | AGV分拣出库 |
| 版本： | 1.1 |
| 项目经理： |  |
| 客户经理： |  |
| 确认人： |  |
| 确认日期： |  |

修改历史：

| 作者 | 时间 | 版本 | 备注 |
| --- | --- | --- | --- |
| 张庆辉 | 2026-05-15 | 1.0 | 方案初版 |
| 王泽港 | 2026-06-06 | 1.1 | 方案更新 |
|  |  |  |  |

## 业务流程

| 主流程 | 流程名称 | 描述 | 应用场景 | 设备类型 |
| --- | --- | --- | --- | --- |

## 业务描述

![image_01](SHOPEE_011_AGV出库分拣V1.1_assets/image_01.png)

![image_02](SHOPEE_011_AGV出库分拣V1.1_assets/image_02.png)

## 修改范围

UI增加AGV分拣出库

## 前提条件

N/A

## 新增表/字段

操作员技能

operator_skills

客户化：用户创建成功需要同步插入该表用户userCode

| 字段名 | 含义 | 类型 | 长度 | 非空 | 备注 |
| --- | --- | --- | --- | --- | --- |
| id | 内部号 | bigint |  | Y |  |
| userCode | 用户编码 | varchar | 50 | Y |  |
| pickMode | 订单拣选模式 | int |  | Y | 整数枚举 |
| shipmentType | 出库单类型 | varchar | 50 | Y | 取出库单类型<br>可多选 |
| sortingMode | 分拣模式 | int |  | Y | 整数枚举 |
| inventoryThreshold | 库存阈值-出库分拣使用 | int |  | Y | 0 |
| 其他base预留字段等 |  |  |  |  |  |

## 实现状态 / TODO

### 第一阶段后端闭环已落地

- 已新增最小 `operator_skills` 表迁移与后端 domain，支持按 `userCode` 查询操作员技能。
- 已在现有 `AgvSortingController` / `AgvSortingService` 上补充后端入口：
  - `start`
  - `exit`
  - `assignShopeeWaveToAcceptedWorkStations`
- 已复用现有 `WcsWorkStationService.updateAcceptStatus` 做暂停/继续接单。
- 已复用现有 `WaveRuleMatchService.findBestMatchedRuleByWorkStationAndOutboundType` 做分拣墙空闲格口的 Shopee 集波分配。
- 已在绑箱/满箱后端校验格口必须已有 `shopeeWaveCode`，避免未分配波次的格口绑定箱号。
- 已在封箱后清理现有真实字段：`containerCode`、`shopeeWaveCode`、`currentWaveRule`、`useStatus`。

### 第一阶段的最小承载策略

- `wcs_work_station` 当前没有独立 `shipmentType/taskType` 字段，开始作业时先复用 `userDef1` 承载操作员选择的出库单类型。
- `operator_skills` 第一阶段按 `userCode` 查询；`pickMode`、`sortingMode` 按整数枚举做后端校验。
- 退出接单时，如果工作站仍存在进行中的 PICK 任务或仍有占用格口，则后端拒绝退出。

### TODO / 缺口说明

- 用户创建成功后自动同步插入 `operator_skills` 的系统钩子暂未接入。
  - 原因：当前未在本轮实现中确认到稳定的用户创建落点，避免硬接错误钩子。
- `wcs_work_station.userDef1` 仅作为第一阶段最小承载字段，若后续产品要求强语义字段，应新增正式字段或扩展配置。
- 绑箱/换箱阶段当前复用 Shopee 集波阶段已完成的 create/bind 结果做闭环校验，未额外新增平行上游接口编排。
- 换箱场景仅补了基础后端限制：
  - `ticketType=5` 的 MTO 任务拒绝换箱
  - Flow Pick 换波次逻辑待确认是否复用现有集波服务，否则需后续补充
- 封箱后的电子标签灭灯仍保留 TODO，待确认现场 PTL 服务接口后接入。
- 任务确认阶段的 `targetContainer` 承载字段本轮未新增。
  - 如后续确认现有任务明细已有合适字段，可优先复用；否则再补迁移。

## 参数设置

| 参数 | 取值范围 | 模块 | 描述 |
| --- | --- | --- | --- |
|  |  |  |  |

## 功能设计

### UI（客户UI界面参考https://www.figma.com/design/h0XKZ4YtrE45BBTAyipsuC/%E3%80%8CWMS-Auto-%E3%80%8D%E8%AE%BE%E8%AE%A1%E6%A0%87%E5%87%86%E6%96%87%E4%BB%B6?node-id=49-5694&p=f）

一、新增UI界面AGV分拣

- 打开界面，选择对应的工作站进行登录；

![image_03](SHOPEE_011_AGV出库分拣V1.1_assets/image_03.png)

- 扫描工作站后，需要检测当前工作站是否在wcs_work_station表存在。

进入管理界面，选择对应订单拣选模式：按单拣选 or 批量拣选，拣选模式必须在登录时选择，且在作业过程中不能更改，选择后如果该用户没有该权限operator_skills.pickMode则不允许登录

A点击开始按钮，弹框选择出库单类型。弹框显示的内容为出库单类型（仅显示操作员具备权限的订单类型operator_skills.shipmentType），点击单选

![image_04](SHOPEE_011_AGV出库分拣V1.1_assets/image_04.png)

![image_05](SHOPEE_011_AGV出库分拣V1.1_assets/image_05.png)

- 选择后判断工作台wcs_work_station的当前模式currentJobMode=‘PICK’或者 为空 并且可作业模式jobMode 包含 ‘PICK’，则提示成功，并将currentJobMode更新为PICK； 将选择的出库单类型更新到当前工作台表的tasktype字段。

- 若此工作台的currentJobMode！=‘PICK’’或者 空，则提示“此工作台正在进行其他工作，不允许开始”；

- 若此工作台的jobMode 不包含‘PICK’，则提示“此工作台不支持该作业类型，不允许开始”；

- 根据选择的拣货模式（按单 or 批量）以及选择单据类型和当前工作站槽口绑定的wave rule，走集波逻辑去抓取对应订单

- B点击退出，该工作站有波次执行一半的则无法退出，如果没有则判断工作台的currentJobMode=‘PICK’，系统提示"未开始的拣选任务将被取消——确认退出？"，确定则提示成功，并将currentJobMode更新为空，剩余未开始拣货的波次取消（可以把波次改为未释放并取消波次，如果波次下有出库单首尾状态>待拣货，且未关闭，则不能退出）；

- 点击暂停，将接单状态acceptStatus更新为‘CLOSED’，暂停后工作站不再继续集波，图表显示为继续

- 点击继续，将接单状态acceptStatus更新为‘OPEN’，继续后工作站恢复继续集波，图表显示为暂停

- 绑箱：点击绑箱，弹框显示

- 货架号：XXXXXXX

- 周转箱号：XXXXXXX

- 扫描货架号，判断必须在wcs_sorting_wall存在，若不存在，则报错

- 另外wcs_sorting_wall_cell的containerCode必须为空为NULL ,否则报错，提醒“当前货架已存在周转箱”

- 将周转箱号更新到wcs_sorting_wall_cell表的containerCode。

- 若返回不可用，则提示“当前周转箱不可用”

- 补充：

- 拣货执行时，如果目标槽口未绑定周转箱（wcs_sorting_wall_cell的containerCode为空或者null）则不允许拣货，提示：请绑定料箱

- 绑箱需要判断槽口是否有分配的波次（wcs_sorting_wall_cell.shopeeWave），否则提示：格口未分配波次，绑定时请求上游实绑拣货任务接口（按出库单类型请求对应实绑接口），上游接口返回成功才允许下发调度任务给agv搬运到工作站，返回失败则界面弹窗报错，按上游返回提示操作直到绑定成功才可继续操作

- 换箱（目标箱放满的情况）

- 点击换箱，弹框显示

- 货架号：XXXXXXX

- 周转箱号：XXXXXXX

- 扫描货架号，判断必须在wcs_sorting_wall存在，若不存在，则报错

- 另外wcs_sorting_wall_cell的containerCode必须为有值，否则报错，提醒“当前货架无箱”

- 扫描周转箱后调用上游WMS的周转箱检查接口，WMS返回成功可用，才可以绑定。将周转箱号更新到wcs_sorting_wall表的LPN。

- 若返回不可用，则提示“当前周转箱不可用”

- 换箱是否换波次号取决是什么wave type，flow pick需要换波次，其他情况不需求（具体逻辑见集波文档）

- 补充：出库单ticketType=5（即MTO下发任务类型）的不允许换箱，如果点换箱时出库单头ticketType=5则提示：MTO非需求池类型不允许换箱

- G.封箱：点击封箱，弹框显示（该波次全部拣完的情况）

- 货架号：XXXXXXX

- 扫描货架号，判断必须在wcs_sorting_wall_cell.containerCode存在，若不存在，则报错

另外wcs_sorting_wall_cell的useStatus使用必须=’ USED’ 绑定状态，且当前槽口绑定的波次必须全部完成（task_detail.cellCode槽口字段，task_detail. shopeeWave波次字段），则将当前格口wcs_sorting_wall_cell.containerCod清空，useStatus更新为‘IDLE’空闲，还需下发当前格口灭灯指令。（之前下发过亮绿灯指令）

G：封箱后面增加缺料按钮

点击按钮，弹框进行二次确认：是否确定短拣并进行重新分配，点击确定更新出库单明细短拣数量shortPickQty，则拿当前周转箱货品+批次的订单需要重新分配（根据短缺数量shortPickQty进行再跑对应波次分配库存，如果分配成功则按集波逻辑进行更新波次号、槽口号等，前端提示分配成功，继续进行下面的作业，如果分配失败则前端提示无可用库存已确认短拣）。

继续判断当前周转箱是否有其他货品需要分拣，若有则显示下一个货品的分拣信息(注意批量和按单)

若当前周转箱无其他货品需要分拣，则下发周转箱回库调度指令

同时也生成缺料的盘点单，盘点类型=缺料。盘点单的具体字段见盘点客户化文档

2.波次任务分配到分拣墙（计划任务）

A.系统用计划任务检测到工作台表存在的currentJobMode=PICK，acceptStatus= OPEN，status=ENABLE启用的工作台，可能会多个工作台，需要轮询。根据工作台对应的分拣墙wcs_sorting_wall.workStationCode=当前工作台，根据当前分拣墙电子标签格口表wcs_sorting_wall_cell判断此工作台所有分拣墙槽口shopeeWave是否有为NULL的槽口,若存在为空或为NULL的货位，则根据槽口绑定的wave rule走《集波客户化进行集波》

B.将任务分配到电子标签格口表wcs_sorting_wall_cell.shopeeWave上，useStatus使用状态更新为‘USED’绑定

C.继续循环执行各工作台各分拣墙槽口分配

3.扫描周转箱分拣

A、周转箱到达工作站agv回调到达，该工作站界面即识别到达的周转箱，根据周转箱找到分拣墙下任务对应的此周转箱status=100的任务明细，

- 若不存在，则提示“无此周转箱任务”

- 若存在，则电脑分拣界面根据人员权限来显示（operator_skills.sortingMode分拣模式：边拣边分pickWhileSort，先拣后分pickThenSort）。

- 若该用户权限是先拣后分，则显示此周转箱第一个货品+批次+库存状态的找到所有分拣墙格口的任务分拣信息(按照每个货品所有格口任务进行分拣，一次性拣货分播)

- 若该用户权限是边拣边分，则显示此周转箱第一个货品+批次+库存状态的找到第一个分拣格口任务的分拣信息(按照每个货品单个格口要拣多少数量进行分拣)

- 若该用户两个权限都有则默认走边拣边分。

- 若该sku是序列号管理的，不管该用户什么权限，只能逐件扫描（扫序列号）。

- 若该sku在该料箱格口总库存数量低于operator_skills.inventoryThreshold数量，则只能走逐渐扫描

![image_06](SHOPEE_011_AGV出库分拣V1.1_assets/image_06.png)

B、显示内容如上图:

- 左边是当前周转箱的信息，需要根据周转箱表的格口数进行动态显示，格口数存在1格口,2格口,4格口,6格口,8格口，当前周转箱分拣货位所在货位格口需要放大蓝色显示

- 中间显示的是当前分拣的数量，下面是货品的图片，货品名称，货品sku编码，UPC货品条码

- 右边显示的分拣墙的示意图，每个工作台有2组货架，1组是4层*5=20个货架，2组是3层*5=15个货架，共35个货架。显示的内容是工作台对应分播墙wcs_sorting_wall_cell表的格口，分拣到的目标格口需要放大黄色显示，下面显示对应格口的分拣数量。

C、扫描货品

扫描周转箱，显示第一个货品的分拣信息。然后扫描货品SKU编码，判断出库单类型=XSCK的需要校验当前周转箱货品SKU+批次库存效期状态location_inventory.shelfLifeSts是否=0正常

- 否，则弹框提醒”当前货品批次已冻结，需要重新分配”，若点击了确认，则当前周转箱货品+批次的订单需要重新分配（按上文2中G点‘封箱后面增加缺料按钮逻辑’进行二次分配）。

- 是，则按上文3中A点的权限模式B点的显示方式进行分拣，分拣后继续判断当前周转箱是否有其他货品需要分拣，若有则显示下一个货品的分拣信息，若当前周转箱无其他货品需要分拣，则下发周转箱回库调度指令。

D、下发电子标签指令

周转箱到达，显示第一个货品的分拣信息。然后扫描货品SKU编码，还需判断分拣货架表在wcs_sorting_wall_cell的containerCode必须都有值。

- 若无值，则提醒“需要绑定订单箱”（详细见上文1中E点的补充说明）

- 若都有值则下发当前周转箱SKU对应分拣墙的电子标签亮红灯。电子标签 id维护在wcs_sorting_wall_cell表的ptlTagId电子标签ID字段，ptlControllerCode电子标签控制器。

E.若货品管控序列号则，扫描SKU后弹框扫描采集序列号，若扫描的UID在系统中未找到或与分配的商品不匹配则报错提示，继续扫描新的UID。

![image_07](SHOPEE_011_AGV出库分拣V1.1_assets/image_07.png)

F．任务确认

UI分拣界面需要监测到电子标签拍灯接口，根据返回对应的格口进行当前货品任务明细的确认。任务确认的时候将当前分拣格口wcs_sorting_wall_cell的目标箱containerCode更新到任务确认的任务明细targetContainer字段。界面刷新按上文3中A点分拣技能继续进行拣货，若当前周转箱全部货品分拣完成，下发当前周转箱回库。

手工确认

为防止电子标签出问题，则保留人工手工任务确认。

在分拣界面点击右下角的完成指令，是将界面上的周转箱、货品、批次对应的任务格口进行确认。任务确认后，逻辑同上。

H、订单分拣完成

任务确认的时候，判断wcs_sorting_wall_cell.shopeeWave分拣墙格口的任务是否完成，若整个任务分拣完成，则下发当前格口电子标签绿灯，useStatus更新‘PENDING_OUT’待离。

UI分拣界面需要监测到电子标签拍灯接口，若报文返回的分拣墙货位wcs_sorting_wall_cell表的useStatus=‘PENDING_OUT’待离，则为封箱，将当前格口shopeeWave，containerCode清空，useStatus更新为‘IDLE’空闲
