ttx-project-doc/SHOPEE_011_AGV出库分拣_开发计划.md

# SHOPEE_011 AGV出库分拣开发计划

> 依据 `C:/Users/zoe/Downloads/SHOPEE_011_AGV出库分拣(2).docx` 整理。本文档用于维护开发计划和当前完成状态。

## 1. 目标

实现 Shopee AGV 出库分拣：工作站登录 AGV 分拣模式后，系统把已释放的 AGV 区域拣货任务分配到分拣墙，按工作站 AGV 并发量下发周转箱搬运任务；周转箱到站后，操作员按批量或按单首选项扫描分拣，通过电子标签或手工确认完成格口任务，支持绑箱、满箱、缺料重分配、三段式完成回传和回库调度。

## 2. 总体模块拆分

| 阶段 | 模块 | 主要内容 | 状态 |
| --- | --- | --- | --- |
| P0 | 数据模型与配置 | `agv_preference`、`wcs_sorting_wall` AGV 分拣字段、工作站 AGV 并发量、菜单/字典配置 | 部分完成：`agv_preference` 建表/domain/table JSON/bill JSON 已落地 |
| P1 | 工作站 AGV 分拣入口 | 登录工作站、开始/退出/暂停/继续、出库单类型选择 | 部分完成：已存在 `AgvSortingService` 统一服务骨架 |
| P1 | 分拣墙箱绑定 | 绑箱、满箱、缺料按钮；删除独立封箱按钮 | 待实现 |
| P1 | 任务分配计划任务 | 拣货任务分配到分拣墙，绑定上游波次号和分拣墙 | 待实现 |
| P1 | AGV 下发计划任务 | 控制工作站未完成 AGV 数量，生成/下发 `wcs_dispatch_task` | 待实现 |
| P1 | 扫箱分拣服务 | 扫周转箱、按首选项展示批量/按单分拣信息 | 待实现 |
| P1 | 电子标签与确认 | 亮红灯、拍灯确认、手工确认、完成后亮绿灯 | 待实现 |
| P2 | 异常闭环 | SKU 批次冻结、缺料重分配、缺料盘点单、周转箱回库 | 待实现 |
| P2 | UI | AGV 分拣首选项维护、AGV 分拣工作台页面 | 部分完成：工作站出库菜单已增加 `AGV拣货`，`AGV_PICK.vue` 页面已按参考图绘制 |

## 2.1 流程图补充口径

用户补充的两张流程图将 AGV 出库分拣拆成两条入口：

| 流程 | UI 入口 | 核心差异 | 交付差异 |
| --- | --- | --- | --- |
| 按单拣货 | 选择“按单拣货” | 订单准备后选择订单类型并点确认，分配任务到工作站；扫 SKU 后按分配货位逐个指引拣货 | 增加“交付”阶段：停止拣货订单、机器人搬运待交付料箱至分播位、人员离开、PTL 绿灯闪烁、PTL 关闭分播口 |
| 批量拣货 | 选择“批量拣货” | 订单准备后选择订单类型并点确认，按 SKU/UID 统计数量，PTL 开始拣货对应分配货位 | 无独立交付泳道，完成分配订单后可继续找新的潜在货位或停止分配返回工作站 |

共同主流程：
- Shopee-WMS 向 HAIQ 下发拣货任务，HAIQ 接收任务并创建订单。
- HAIQ 预分配库存。
- HAIQ UI 登录工作站并选择拣货模式。
- 若存在进行中任务，需先换人/结束并清除当前任务，或继续执行可操作员执行的其它任务。
- HAIQ 基于订单波次、优先级、释放规则动态生成波次，并将任务分配到工作站。
- 生成料箱取用任务并分配给机器人，机器人接收任务。
- 拣货任务收集后同步到 WMS 仓储系统。
- 操作员绑定订单箱或料箱，系统确认绑定成功后进入扫码拣货。
- SKU 扫描后判断 UID 是否受库存管理：受管理则逐件扫描 UID 后计数，不受管理则直接统计 SKU 数量。
- HAIQ 根据分配货位指引拣货，PTL 按货位亮灯/分播。
- 若需要更换料箱或继续拣货，系统查找新的潜在货位；否则标记本批次/本订单完成。

计划影响：
- `agv_preference.initDocType` 需要明确支持 `SINGLE_ORDER`（按单）和 `BATCH`（批量）两种值。
- UI 工作台入口需按模式切换文案、后续按钮和完成逻辑。
- 后端查询/确认接口需要带 `pickMode`，不能只依赖默认首选项。
- 按单模式需要新增“交付”服务或状态流，批量模式可以先不实现交付泳道。

## 3. 数据库与领域对象

### 3.1 新增表 `agv_preference`（部分完成）

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `id` | bigint | 主键 |
| `code` | varchar(50) | 编码，必填 |
| `name` | varchar(50) | 名称 |
| `warehouseCode` | varchar(50) | 仓库，必填 |
| `initDocType` | varchar(500) | 分拣方式：`BATCH` 批量、`SINGLE_ORDER` 按单 |
| `allUsers` | int | 所有用户可用，默认 0 |
| `useAsDefault` | int | 是否默认，默认 0 |

落地状态：
- 已完成：建表 SQL 已合并到 `wes-loghub/src/main/resources/db/migration/mysql/V3_1_2_3__shopee_outbound_wave_create.sql`。
- 已完成：领域对象 `wes-loghub/wms-automation/src/main/groovy/com/ittx/wms/automation/domain/hairo/AgvPreference.groovy`。
- 已完成：表配置 `wes-loghub/src/main/resources/config/wes/table/agv_preference.json`。
- 已完成：单据配置 `wes-loghub/src/main/resources/config/wes/bill/agv_preference.json`。
- 已完成：维护页面配置 `wes-loghub/src/main/resources/config/wes/view/ttx.wso.TabbedBill/agv_preference.json`。
- 已完成：出库配置菜单 `agv_preference_config` 已挂载到 `wes-loghub/src/main/resources/config/wes/navigator/admin.json`。
- 已完成：服务 `wes-loghub/wms-automation/src/main/groovy/com/ittx/wms/automation/service/hairo/AgvPreferenceService.groovy`，承接平台通用 CRUD。

### 3.2 扩展 `wcs_sorting_wall`

docx 将分拣墙货架作为 AGV 分拣任务载体，现有 `WcsSortingWall.groovy` 仅有基础字段，需要补齐以下字段：

| 字段 | 建议字段名 | 说明 |
| --- | --- | --- |
| 周转箱 | `lpn` | 订单箱/周转箱号 |
| 当前任务 | `taskId` 或 `agvTaskId` | docx 的 `Task_ID`，绑定上游波次号或任务标识需最终确认 |
| 分拣状态 | `syStatus` | 0 空闲、2 已分配、4 分拣中、6 任务完成 |
| 电子标签 | `lamp` | 电子标签 ID |
| 分拣周转箱 | `fjLpn` | 当前正在分拣的周转箱 |
| 分拣 SKU | `fjSku` | 当前正在分拣的 SKU |
| 分拣批次 | `fjBatch` | 当前正在分拣批次 |
| 出库类型范围 | `ckType` | 可绑定的出库任务类型，多值 |
| 组号 | `groupIndex` | UI 显示分拣墙组 |
| AGV 并发量 | `zdAgv` | 当前工作站最多未完成周转箱数，docx 写在 workStationCode 表，需确认是放工作站还是分拣墙 |

计划文件：
- 修改迁移：`wes-loghub/src/main/resources/db/migration/mysql/V3_1_2_x__agv_sorting_wall_fields.sql`
- 修改领域对象：`wes-loghub/wms-automation/src/main/groovy/com/ittx/wms/automation/domain/WcsSortingWall.groovy`
- 如 `zdAgv` 放工作站，修改：`wes-loghub/wms-automation/src/main/groovy/com/ittx/wms/automation/domain/WcsWorkStation.groovy`

### 3.3 任务头/明细字段映射

docx 多次提到任务头自定义字段：
- 自定义1：出库任务类型
- 自定义2：任务分配到分拣墙时间
- 自定义3：电子标签货架货位号
- 自定义4：上游波次号

当前 `TaskHeader.groovy` 没有这些显式字段，计划采用两种方案之一：

| 方案 | 做法 | 优点 | 风险 |
| --- | --- | --- | --- |
| 推荐 A | 新增明确字段：`shipmentType/agvAssignedAt/agvSortingWallCode/upstreamWaveCode` | 语义清楚，后续维护稳定 | 需要迁移和上游字段映射 |
| 备选 B | 使用现有 `EntityUserDef` 自定义字段 | 改动小 | 字段语义隐性，后续易混淆 |

建议先确认任务头“自定义1-4”在当前数据库实际列名，再决定字段落点。

### 3.4 扩展 `shopee_wave` 格口/设备释放标记

新增字段 `deviceReleaseSts int not null default 0`，用于记录 3.1.9 回传完成后的格口/设备释放结果：

| 值 | 状态 | 处理规则 |
| ---: | --- | --- |
| `0` | 待释放 | 3.1.9 尚未成功，或成功后等待执行释放 |
| `1` | 已释放 | 格口/设备释放和灭灯均处理成功 |
| `-1` | 释放失败 | 保留现场绑定，由释放任务重试 |

`completeTaskUploadSts` 继续只表示 3.1.9 的 `confirm/get/uploadStatus` 回传状态，不与 `deviceReleaseSts` 合并。`uploadStatus` 成功后触发释放；释放结果单独写入 `deviceReleaseSts`，避免上游回传成功但现场释放失败时丢失重试依据。

计划文件：
- 修改数据库迁移，给 `shopee_wave` 增加 `deviceReleaseSts`。
- 修改 `ShopeeWave.groovy` 和 `shopee_wave.json`，补充字段及状态说明。
- 三段式回传成功后的释放处理必须同时满足 `completeTaskUploadSts=SUCCESS` 和 `deviceReleaseSts in (0, -1)`，避免默认值为 `0` 的未完成波次被提前释放。

## 4. 后端服务计划

### 4.1 AGV 分拣工作站服务（部分完成）

当前落点：`com.ittx.wms.wave.service.hairo.AgvSortingService`

状态：已创建 AGV 出库分拣统一服务骨架，具体登录、开始、退出、暂停、继续逻辑仍待补齐。

原计划服务：`com.ittx.wms.automation.service.hairo.AgvSortingStationService`

职责：
- `loginStation(session, warehouseCode, workStationCode)`：校验 `wcs_work_station` 存在且启用。
- `startSorting(session, workStationId, shipmentType)`：校验 `currentJobMode` 为 0 或 2，更新为 2，写入当前出库单类型。
- `exitSorting(session, workStationId)`：`currentJobMode=2` 时更新为 0。
- `pauseAccept(session, workStationId)`：`acceptStatus=0`。
- `resumeAccept(session, workStationId)`：`acceptStatus=1`。

注意：
- 现有 `WcsWorkStation.acceptStatus` 是 String，docx 写 0/1，需要确认字典值。计划中先按现有常量或字典，不硬编码数字。
- `currentJobMode=2` 表示 AGV 出库分拣模式，需要补常量注释。

### 4.2 分拣墙箱绑定服务

新增服务：`com.ittx.wms.automation.service.hairo.AgvSortingWallBoxService`

接口：
- `bindBox(session, warehouseCode, sortingWallCode, lpn)`：校验分拣墙存在、`lpn` 为空、调用 WMS 周转箱检查接口、回写 `wcs_sorting_wall.lpn`。
- `replaceFullBox(session, warehouseCode, sortingWallCode, oldLpn, newLpn)`：满箱换箱并更新 LPN，不调用独立封箱接口。
- `shortage(session, warehouseCode, sortingWallCode)`：二次确认后触发缺料重分配、缺料盘点单、继续显示下一货品或回库。

删除 `sealBox/sealDevice` 独立封箱入口。完成拣货改为参考接口 3.1.9 的 `confirm -> get -> uploadStatus` 三段式回传；仅在 `uploadStatus` 成功后释放格口/设备并下发灭灯，释放结果写入 `shopee_wave.deviceReleaseSts`，失败时保留原绑定等待重试。

依赖待确认：
- 上游 WMS 周转箱检查接口。
- 电子标签灭灯接口。
- 缺料盘点单创建接口/字段。

### 4.3 波次任务分配计划任务

新增服务：`com.ittx.wms.automation.service.hairo.AgvWaveTaskAssignService`

入口：
- 建议先不加 `@Scheduled`，提供 `assignOnce()`；计划任务开关确认后再接调度入口。

筛选工作站：
- `wcs_work_station.currentJobMode=2`
- `acceptStatus=1`
- `status=1`

筛选分拣墙：
- `wcs_sorting_wall.workStationCode = 当前工作站`
- 存在 `taskId is null`
- 若分拣墙已有 `taskId`，该货架不再下发任务。

筛选任务头：
- 仓库 = 当前仓库
- 拣货任务头已释放
- 任务从货位区域 = AGV 区域
- 任务头状态 = 100
- AGV 分拣分配时间为空
- 任务头出库任务类型包含在分拣墙 `ckType`
- 任务头上游波次号关联上游波次号段表，且号段未分配

分配动作：
- `wcs_sorting_wall.taskId = task_header.上游波次号`
- `wcs_sorting_wall.syStatus = 2`
- `task_header.agvAssignedAt = now`
- `task_header.agvSortingWallCode = wcs_sorting_wall.code`
- 上游波次号段表标记已分配

需要复用/衔接：
- Shopee 集波里已有 `shopee_wave` 号段逻辑，需确认 “上游波次号段表” 是否就是 `shopee_wave`。

### 4.4 AGV 下发计划任务

新增服务：`com.ittx.wms.automation.service.hairo.AgvDispatchService`

可复用现有：
- `wes-loghub/wms-automation/src/main/groovy/com/ittx/wms/automation/service/WcsDispatchTaskService.groovy`
- `AgvTaskCreateWcsCmd.groovy`
- `AgvTaskCancelWcsCmd.groovy`

流程：
- 轮询 AGV 分拣工作站。
- 查询当前工作站 `wcs_dispatch_task.processStatus` 未完成数量 Y。
- 比较工作站 AGV 并发量 Z，`Y < Z` 才继续。
- 查询当前分拣墙 `taskId` 下的拣货明细：
  - 从区域 = AGV 库区
  - 任务头已释放
  - 明细状态 = 100
  - 明细 `fromLPN` 关联 `wcs_container`
  - `wcs_container.onHandStatus = 10`
- 按货品排序，最多取 `Z - Y` 个周转箱。
- 每个周转箱创建一条 `wcs_dispatch_task`，并下发 AGV 搬运任务。

待确认：
- AGV 库区标识来自系统参数、库区配置还是任务明细字段。
- `wcs_container.onHandStatus=10` 是否已有常量。
- `processStatus` 未完成状态集合是否复用现有 `WcsDispatchTaskService` 常量。

### 4.5 AGV 到站与扫箱分拣服务

新增服务：`com.ittx.wms.automation.service.hairo.AgvOutboundSortingService`

接口：
- `scanContainer(session, workStationCode, containerCode, preferenceCode, pickMode)`：扫周转箱，读取首个待分拣货品。
- `scanSku(session, containerCode, skuCode, pickMode)`：校验 SKU、冻结状态、订单箱是否绑定齐全，返回分拣指引。
- `scanUid(session, containerCode, skuCode, uid)`：UID 受库存管理时逐件扫描并累计 SKU 数量。
- `confirmByLamp(session, lampCallback)`：电子标签拍灯确认。
- `manualConfirm(session, currentSortingContext)`：手工确认。
- `nextSortingItem(session, containerCode, mode)`：批量/按单切换下一任务。

批量模式：
- 同一周转箱第一个 `SKU + 批次 + 库存状态` 下，展示所有分拣墙格口任务。

按单模式：
- 同一周转箱第一个 `SKU + 批次 + 库存状态` 下，只展示第一个格口任务；完成后切下一个格口。

确认动作：
- 任务明细确认。
- 将 `wcs_sorting_wall.lpn` 回写到任务明细自定义1字段。
- 清空 `wcs_sorting_wall.fjLpn/fjSku/fjBatch`。
- `syStatus` 回到 2。
- 若整个格口任务完成，亮绿灯并 `syStatus=6`。
- 若当前周转箱全部完成，下发周转箱回库。

### 4.7 按单拣货交付服务

流程图中“按单拣货”比批量拣货多一个交付阶段，建议新增服务：`com.ittx.wms.automation.service.hairo.AgvSingleOrderDeliveryService`

接口：
- `stopPickingOrder(session, workStationCode, taskCode)`：点击“停止拣货订单”。
- `bindNewBoxToSortPosition(session, workStationCode, sortingLocationCode, lpn)`：继续拣货时绑定新料箱至分播位。
- `finishAssignedTaskToStation(session, workStationCode)`：没有继续拣货时，将未分配完的拣货任务返回本工作站。
- `handoverToPtl(session, workStationCode, sortingLocationCode)`：机器人搬运待交付料箱至分播位，人员离开后触发 PTL 进行确认。
- `ptlConfirmDelivery(session, ptlCallback)`：PTL 绿灯闪烁、完成分播、关闭分播口后同步状态。

状态同步：
- HAIQ 接收拣货任务状态。
- 同步拣货任务状态至 Shopee WMS。
- 更新拣货任务/订单状态。

待确认：
- PTL 分播口编码与 `wcs_sorting_wall`、`wcs_sorting_wall_cell` 还是其它表关联。
- “机器人搬运待交付料箱至分播位”是否复用 `wcs_dispatch_task`，还是需要新任务类型。
- “人员离开，无待搬运料箱”由 UI 点击确认、机器人回调还是 PTL 回调触发。

可参考：
- `wms-shipping/src/main/groovy/com/ittx/wms/shipping/service/RebinService.groovy`
- `wms-task/src/main/groovy/com/ittx/wms/task/service/TaskHeaderService.groovy`
- `wms-task/src/main/groovy/com/ittx/wms/task/service/TaskDetailService.groovy`

### 4.6 电子标签接口

新增/复用 WCS 接口命令：
- 亮红灯：按 `wcs_sorting_wall.lamp` 下发当前 SKU 对应格口分拣数量。
- 灭灯：封箱时下发。
- 亮绿灯：格口整个任务完成。
- 拍灯回调：根据 `lamp` 找 `wcs_sorting_wall`，按 `syStatus` 判断是任务确认还是封箱确认。

待确认：
- 电子标签接口路径、报文结构、回调结构。
- `lamp` 是否唯一绑定到 `wcs_sorting_wall`。

## 5. UI 计划

### 5.1 AGV 分拣首选项维护（部分完成）

新增菜单：AGV 分拣首选项。

功能：
- 编码、名称、仓库。
- 分拣方式：批量/按单。
- 所有用户。
- 是否默认。
- 用户权限配置，参考“包装复合首选项”。

已完成：
- `agv_preference` table/bill/TabbedBill JSON 已新增。
- 出库配置菜单已增加 `AGV分拣首选项`。

待实现/待确认：
- 用户权限配置。

### 5.2 AGV 分拣工作台（部分完成）

入口：
- 打开页面后扫描/选择工作站。
- 校验工作站存在。
- 进入管理界面。

操作区：
- 开始：弹框选择出库单类型。
- 退出：退出 AGV 分拣模式。
- 暂停/继续：切换 `acceptStatus`。
- 绑箱：扫货架号 + 周转箱号。
- 满箱：扫货架号 + 周转箱号。
- 缺料：二次确认后触发缺料流程。
- 不显示封箱按钮，不提供封箱弹框或扫描货架号操作。

分拣区：
- 左侧：当前周转箱格口示意，支持 1/2/4/6/8 格，当前格口放大蓝色显示。
- 中间：分拣数量、商品图片、商品名称、SKU/UPC。
- 右侧：当前工作站两组分拣墙，共 35 个货架：
  - 第 1 组：4 层 * 5 = 20
  - 第 2 组：3 层 * 5 = 15
- 分拣墙当前货位放大蓝色显示，并显示对应格口分拣数量。

已完成：
- `cbt-ui/src/views/wes/workStation/utils.ts` 出库菜单已增加 `AGV拣货`。
- `cbt-ui/src/views/wes/workStation/home.vue` 已接入 `AGV_PICK` 同级页面，后端作业模式映射为 `PICK`。
- `cbt-ui/src/views/wes/workStation/mode/AGV_PICK.vue` 已按参考图绘制页面，并增加自适应防覆盖样式。

待实现：
- 页面真实数据绑定。
- AGV 首选项弹窗/选择逻辑。
- 开始/退出/暂停/绑箱/满箱/任务确认按钮接口联动；删除封箱按钮逻辑。

## 6. 接口清单

| 接口 | 方向 | 状态 |
| --- | --- | --- |
| 周转箱检查 | WES -> 上游 WMS | 待接口 |
| AGV 任务创建 | WES -> WCS/AGV | 可复用现有 `AgvTaskCreateWcsCmd`，需补出库分拣参数 |
| AGV 任务完成回调 | WCS/AGV -> WES | 现有回调需确认是否覆盖 |
| 完成拣货 confirm | EDI -> WES | 参考 3.1.9，返回待回传任务 ID 列表并锁定批次 |
| 完成拣货 get | EDI -> WES | 参考 3.1.9，按任务 ID 返回完整拣货明细 |
| 完成拣货 uploadStatus | EDI -> WES | 参考 3.1.9，回写成功/失败；成功后触发释放并更新 `deviceReleaseSts` |
| AGV 任务取消/回库 | WES -> WCS/AGV | 可复用 `AgvTaskCancelWcsCmd`，回库任务需确认 |
| 电子标签亮红灯 | WES -> WCS | 待接口 |
| 电子标签灭灯 | WES -> WCS | 待接口 |
| 电子标签亮绿灯 | WES -> WCS | 待接口 |
| 电子标签拍灯回调 | WCS -> WES | 待接口 |
| PTL 分播口开始分播 | WES/HAIQ -> PTL | 按单交付阶段待接口 |
| PTL 完成分播 | PTL -> WES/HAIQ | 按单交付阶段待接口 |
| PTL 关闭分播口 | PTL -> WES/HAIQ | 按单交付阶段待接口 |
| PTL 绿灯闪烁/确认 | PTL -> WES/HAIQ | 按单交付阶段待接口 |
| 缺料盘点单创建 | WES -> 盘点模块/上游 | 待字段与接口 |

## 7. 实施任务拆分

### Task 1：数据模型与配置落地（部分完成）

- 已完成：新增 `agv_preference` 建表 SQL。
- 已完成：新增 `AgvPreference` domain 和 `AgvPreferenceService` 通用 CRUD 服务。
- 扩展 `wcs_sorting_wall` AGV 分拣字段。
- 视确认结果扩展 `wcs_work_station` 或系统参数保存 AGV 并发量。
- 增加常量：AGV 分拣模式、分拣墙状态、首选项模式。
- 已完成：增加 `agv_preference` UI 表/单配置。

### Task 2：工作站 AGV 分拣入口（部分完成）

- 部分完成：已新增 `AgvSortingService` 统一服务骨架。
- 新增 controller endpoint。
- 实现登录、开始、退出、暂停、继续。
- 记录系统处理日志。
- 验证 currentJobMode/acceptStatus 状态切换。

### Task 3：AGV 分拣首选项（部分完成）

- 实现首选项 CRUD。
- 实现用户权限过滤和默认首选项选择。
- 已完成：`agv_preference` table/bill/TabbedBill JSON 和出库配置菜单入口。
- 已完成：`AgvPreferenceService` 通用 CRUD 服务。
- 待实现：用户权限过滤和默认首选项选择业务逻辑。

### Task 4：分拣墙绑箱/满箱/缺料

- 新增 `AgvSortingWallBoxService`。
- 实现货架校验、LPN 校验、周转箱检查接口占位。
- 删除封箱按钮及独立封箱接口，格口清理和灭灯由三段式完成回传成功状态触发。
- 实现缺料入口：先记录待重分配和待盘点，等接口确认后补全。

### Task 5：波次任务分配到分拣墙

- 新增 `AgvWaveTaskAssignService.assignOnce()`。
- 查询 AGV 分拣工作站。
- 查询空闲分拣墙。
- 查询符合条件任务头。
- 绑定任务头、分拣墙、上游波次号段。
- 增加 Redis 锁，避免多工作站/多计划任务重复分配。

### Task 6：AGV 任务下发

- 新增 `AgvDispatchService.dispatchOnce()`。
- 控制未完成 AGV 任务数量。
- 查询待搬运周转箱。
- 创建 `wcs_dispatch_task`。
- 调用现有 WCS API 下发 AGV 搬运。
- 失败记录系统处理日志。

### Task 7：扫箱与分拣展示

- 新增 `AgvOutboundSortingService.scanContainer()`。
- 实现批量/按单两种模式的数据查询，接口显式传 `pickMode`。
- 返回周转箱格口示意、商品信息、分拣墙示意和分拣数量。
- SKU 扫描时校验冻结状态和订单箱绑定状态。
- UID 受库存管理时，支持逐件扫描 UID 并累计 SKU 数量。

### Task 8：电子标签与任务确认

- 实现亮红灯、亮绿灯、灭灯命令。
- 实现拍灯回调确认。
- 实现手工确认。
- 确认后更新任务明细、分拣墙状态、当前分拣字段。
- 当前周转箱完成后触发回库调度。

### Task 9：按单交付阶段

- 新增 `AgvSingleOrderDeliveryService`。
- 实现“停止拣货订单”。
- 实现“继续拣货？”判断。
- 继续拣货时查找并绑定新的潜在货位。
- 不继续拣货时将未分配完任务返回本工作站。
- 触发机器人搬运待交付料箱至分播位。
- 对接 PTL 分播口开始分播、完成分播、关闭分播口、绿灯闪烁。
- 同步拣货任务状态至 Shopee WMS，并更新本地任务/订单状态。

### Task 10：异常与缺料闭环

- SKU 批次冻结时触发重分配。
- 缺料按钮触发重分配。
- 生成缺料盘点单。
- 判断当前周转箱是否还有其它货品，若无则回库。

### Task 11：UI 页面（部分完成）

- AGV 分拣首选项页面。
- 已完成：AGV 分拣工作台静态页面和自适应样式。
- 工作站登录/开始/暂停/退出操作。
- 绑箱/满箱/缺料弹框；不提供封箱按钮和弹框。
- 分拣动态图和电子标签/手工确认交互。
- 按单模式增加交付阶段按钮和 PTL 分播口状态展示。

## 8. 工时预估拆分

> 预估单位为人日，按 1 名熟悉当前 WES/WMS 代码的开发人员口径估算。外部接口报文未确认、现场 AGV/PTL 联调等待、真实设备排期不计入纯开发人日；若接口或设备行为与计划差异较大，需要另行追加。

### 8.1 总体预估

| 范围 | 后端 | 前端 | 联调/验证 | 合计 |
| --- | ---: | ---: | ---: | ---: |
| P0 数据模型与配置 | 2 - 3 | 1 - 2 | 1 | 4 - 6 |
| P1 核心出库分拣闭环 | 13 - 19 | 6 - 10 | 3 - 5 | 22 - 34 |
| P2 异常、交付与设备闭环 | 8 - 13 | 3 - 5 | 6 - 8 | 17 - 24 |
| 合计 | 23 - 35 | 10 - 17 | 10 - 14 | 43 - 64 |

建议排期：
- 最小可用版本：先完成 P0 + P1，约 `26 - 40` 人日，可覆盖工作站入口、任务分配、AGV 下发、扫箱分拣、确认闭环。
- 完整版本：完成 P0 + P1 + P2，约 `43 - 64` 人日，覆盖按单交付、缺料、冻结、PTL 和现场设备闭环。
- 若上游 WMS、WCS/AGV、PTL 接口可提前提供稳定 mock，联调人日可压缩约 `20% - 30%`。

### 8.2 按任务拆分

| Task | 内容 | 后端 | 前端 | 联调/验证 | 合计 | 备注 |
| --- | --- | ---: | ---: | ---: | ---: | --- |
| Task 1 | 数据模型与配置落地 | 2 - 3 | 1 | 0 - 1 | 3 - 5 | 包含迁移、domain/service、表单配置和常量 |
| Task 2 | 工作站 AGV 分拣入口 | 1 - 2 | 1 | 0 - 1 | 2 - 4 | currentJobMode、acceptStatus、系统日志 |
| Task 3 | AGV 分拣首选项 | 1 - 2 | 1 - 2 | 0 - 1 | 2 - 5 | CRUD、默认首选项、权限过滤 |
| Task 4 | 分拣墙绑箱/满箱/缺料入口 | 2 - 3 | 1 - 2 | 1 | 4 - 6 | 删除封箱入口，周转箱检查、灭灯接口先可占位 |
| Task 5 | 波次任务分配到分拣墙 | 3 - 4 | 0 | 1 | 4 - 5 | 包含 Redis 锁、任务头/分拣墙回写 |
| Task 6 | AGV 任务下发 | 2 - 3 | 0 | 1 - 2 | 3 - 5 | 复用现有 dispatch task，需确认 AGV 参数 |
| Task 7 | 扫箱与分拣展示 | 3 - 5 | 2 - 3 | 1 - 2 | 6 - 10 | 批量/按单查询差异、SKU/UID 扫描 |
| Task 8 | 电子标签与任务确认 | 3 - 4 | 1 - 2 | 2 - 3 | 6 - 9 | 红灯/绿灯/灭灯、拍灯回调、手工确认 |
| Task 9 | 按单交付阶段 | 3 - 5 | 1 - 2 | 2 - 3 | 6 - 10 | PTL 分播口与机器人搬运接口风险较高 |
| Task 10 | 异常与缺料闭环 | 3 - 4 | 1 | 1 - 2 | 5 - 7 | 冻结、缺料、盘点单、回库调度 |
| Task 11 | UI 页面整合 | 1 | 3 - 5 | 1 - 2 | 5 - 8 | 工作台主界面、动态图、按钮与状态展示 |

### 8.3 外部依赖风险工时

| 依赖项 | 风险 | 可能追加 |
| --- | --- | ---: |
| 上游 WMS 周转箱检查接口 | 报文和校验规则未定，可能影响绑箱/满箱 | 1 - 2 人日 |
| WCS/AGV 任务创建与回库接口 | 现有接口可复用程度待确认，可能需要新任务类型 | 1 - 3 人日 |
| 电子标签接口与拍灯回调 | 灯号映射、回调幂等、异常补偿需现场验证 | 1 - 3 人日 |
| PTL 分播口接口 | 按单交付阶段依赖强，接口未确认时无法闭环 | 2 - 4 人日 |
| 缺料盘点单接口 | 字段和生成入口未确认 | 1 - 2 人日 |
| 真实 AGV/PTL 现场联调 | 设备排队、网络、回调时序和异常重试不可控 | 3 - 6 人日 |

### 8.4 里程碑建议

| 里程碑 | 范围 | 验收口径 | 预估 |
| --- | --- | --- | ---: |
| M1 基础配置可用 | Task 1 - 3 | 可维护 AGV 首选项，工作站可进入/退出 AGV 分拣模式 | 7 - 12 人日 |
| M2 核心分拣可跑 | Task 4 - 7 | 任务可分配到分拣墙，AGV 可下发，扫箱可返回批量/按单分拣指引 | 17 - 26 人日 |
| M3 确认闭环可跑 | Task 8 + Task 11 基础界面 | 支持电子标签/手工确认，分拣墙与任务状态可闭环 | 10 - 14 人日 |
| M4 异常与交付闭环 | Task 9 - 10 + Task 11 完整界面 | 按单交付、缺料、冻结、回库、PTL 状态完成闭环 | 14 - 22 人日 |

## 9. 验证计划

| 验证项 | 方法 |
| --- | --- |
| 编译 | `:wms-automation:compileGroovy`、涉及 shipping/task 时分别编译对应模块 |
| 数据迁移 | 本地 MySQL 执行迁移脚本，确认字段/表存在 |
| 工作站状态 | 手工调用接口验证 `currentJobMode/acceptStatus/taskType` |
| 任务分配 | 构造已释放 AGV 区任务，执行 `assignOnce()` 验证分拣墙和任务头回写 |
| AGV 下发 | 使用模拟 WCS API 验证 `wcs_dispatch_task` 创建和报文 |
| 扫箱分拣 | 构造周转箱和任务明细，验证批量/按单返回差异 |
| UID 扫描 | 构造受 UID 管理的 SKU，验证逐件扫描和数量统计 |
| 确认闭环 | 模拟拍灯/手工确认，验证任务明细、分拣墙状态和回库触发 |
| 按单交付 | 模拟停止拣货、继续拣货、绑定新货位、PTL 完成分播 |
| 异常流程 | 冻结、缺料、无箱、无任务、AGV 超并发 |

## 10. 待确认事项

1. `wcs_sorting_wall.Task_ID` 存“上游波次号”还是“任务头 ID/任务号”。
2. `task_header` 自定义1-4在当前数据库中的实际列名。
3. `wcs_work_station.acceptStatus` 取值是 `0/1` 还是现有字符串字典。
4. AGV 并发量 `ZDagv` 放在工作站表、分拣墙表还是系统参数。
5. AGV 区域判断使用库区编码、库区类型还是系统参数。
6. 上游波次号段表是否复用 `shopee_wave`。
7. 周转箱检查接口报文和返回结构。
8. 电子标签接口和拍灯回调报文。
9. 缺料盘点单字段和创建入口。
10. SKU 批次冻结判断使用库存状态、冻结标识还是库存 holdCode。
11. UID 受库存管理的判断字段和 UID 扫描校验接口。
12. PTL 分播口、分播位、分拣墙/格口之间的表关系。
13. 按单交付阶段是否必须同步 Shopee WMS，接口报文是什么。
14. “换人拣货/结束并清除当前任务”的状态清理范围。