ttx-project-doc/拣货/SHOPEE_011_AGV出库分拣V1.1.md

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	方案更新

业务流程

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

业务描述

修改范围

UI增加AGV分拣出库

前提条件

N/A

新增表/字段

操作员技能

operator_skills

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

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

Shopee 波次释放标记

在 shopee_wave 新增 deviceReleaseSts，与 3.1.9 三段式回传字段 completeTaskUploadSts 分开维护。

字段名	含义	类型	非空	默认值	状态说明
deviceReleaseSts	格口/设备释放状态	int	Y	0	0 待释放、1 已释放、-1 释放失败

• completeTaskUploadSts 仅表示 3.1.9 回传状态，不直接代表格口/设备已经释放。
• uploadStatus 回写 3.1.9 成功后执行格口/设备释放；释放成功写 deviceReleaseSts=1，失败写 deviceReleaseSts=-1 并进入释放重试。
• 释放任务必须同时满足 completeTaskUploadSts=SUCCESS 和 deviceReleaseSts in (0, -1)，不能只按释放标记查询。

实现状态 / TODO

第一阶段后端闭环已落地

• 已新增最小 operator_skills 表迁移与后端 domain，支持按 userCode 查询操作员技能。
• 已在现有 AgvSortingController / AgvSortingService 上补充后端入口：
  • start
  • exit
  • assignShopeeWaveToAcceptedWorkStations
• 已复用现有 WcsWorkStationService.updateAcceptStatus 做暂停/继续接单。
• 自动集波通过 WaveRuleMatchService.matchByStation 完成分拣墙空闲格口的 Shopee 集波分配。
• 已在绑箱/满箱后端校验格口必须已有 shopeeWaveCode，避免未分配波次的格口绑定箱号。
• 工作站登录及 AGV 分拣页面不提供独立封箱按钮；完成拣货统一进入参考接口 3.1.9 的三段式回传流程。

第一阶段的最小承载策略

• 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分拣

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

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

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

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

• 选择后判断工作台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.完成拣货回传：删除工作站登录及 AGV 分拣页面的封箱按钮、封箱弹框和扫描货架号逻辑，不再提供独立封箱接口。

完成拣货参考接口 3.1.9，采用 confirm -> get -> uploadStatus 三段式回传：

1. confirm：按仓库查询待回传任务，锁定本批任务并返回任务 ID 列表。
2. get：按任务 ID 返回本任务完整拣货明细，重试时必须保持报文一致。
3. uploadStatus：回写本次回传成功或失败；失败进入回传重试，成功后再处理 deviceReleaseSts，释放对应格口/设备并执行灭灯。

缺料按钮保留在分拣操作区：

点击按钮，弹框进行二次确认：是否确定短拣并进行重新分配，点击确定更新出库单明细短拣数量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数量，则只能走逐渐扫描

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。

F．任务确认

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

手工确认

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

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

H、订单分拣完成

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

UI 不再通过封箱按钮释放格口。任务完成后等待 3.1.9 三段式回传结果；uploadStatus 成功后处理 deviceReleaseSts，释放成功时清空当前格口 shopeeWaveCode、containerCode，将 useStatus 更新为 IDLE 并写 deviceReleaseSts=1；释放失败时保留现场绑定并写 deviceReleaseSts=-1，供释放任务重试。