feat: 接入ERP成品发货出库流程

This commit is contained in:
mtf committed 2026-07-18 13:41:54 +08:00
1 parent 66a1f60428
commit 7c2722c88d
25 files changed
+2547 -22

No files matched your search

@@ -0,0 +1,129 @@
# ERP事项二:成品发货接口联动——实施方案
## 1. 设计目标
- 通过按钮按ERP发货通知单号拉取出库单,不做无条件批量同步。
- ERP拉单按整批数据库事务保存;任一明细写入失败时整批回滚,避免留下半张单或孤立主单。
- 人员选择库存并填写计划分配数量;系统不自动替人分配。
- WCS继续整托搬运,一个托盘只生成一个活动任务。
- 到站后人员确认每条分配关系的实际出库数量,再扣库存并回传ERP。
- 余料托盘继续使用原回库流程。
- 复用 `ShipmentHeader`、`ShipmentDetail`、`TaskHeader`、`TaskDetail` 和库存交易表,不新增业务表。
## 2. 最终操作流程
```text
出库单页面点击“获取ERP发货通知单”并输入DLCode
→ WMS保存主单和明细
→ 在明细页面点击“分配/下发”
→ 勾选库存并填写计划数量
→ 同一托盘的多物料/多明细合并为一个待下发任务
→ 选择6个成品出库口之一并一键下发
→ WCS整托搬到出库口,任务状态变为“到站台”
→ 成品出入库页面扫描托盘,只显示已分配关系
→ 人员修改实际数量并点击“确认发货”
→ 一次事务扣库存、更新出库数量、完成任务
→ 按ERP主单调用AddSaleOut;失败进入补传
→ 余料托盘按原流程回库
```
6个允许出库口:`EnterExit_P1001`、`P1004`、`P1007`、`P1008`、`P1009`、`P1010`。原 `StartOut` 入口保留给旧出库单;ERP发货单只显示“分配/下发”,服务端也会拦截旧入口,避免两套流程串用。
## 3. ERP通知单规则
- 请求:`POST LoadDispatch`,参数 `DLCode`。
- `ShipmentHeader.SourceCode = DLCode`。
- `ShipmentDetail.DLsID` 保存ERP表体明细ID并建立唯一索引,保证重复拉取幂等。
- 本地需求数量首次取 `DeliveryQty`。
- `fOutQuantity` 完全不参与WMS计划数量和剩余数量;它在WMS回传后才由ERP更新,不能作为拉取时的已出库依据。
- 已发生分配或出库的明细再次拉取时,不覆盖本地计划数量。
- 只接收 `bReturnFlag=0` 的正常发货数据。
- 同一次拉取在一个数据库事务中完成;`DLsID` 唯一索引负责并发重复拉取的最终防重。
## 4. 分配模型与数量规则
| 字段/实体 | 含义 |
| --- | --- |
| `TaskHeader` | 托盘级活动WCS任务 |
| `TaskDetail.OrderDetailId` | 出库明细ID |
| `TaskDetail.InventoryId` | 人员选择的库存ID |
| `TaskDetail.Qty` | 该明细分配给该库存的计划数量 |
| `ShipmentDetail.DividedQty` | 当前所有活动分配数量合计 |
| `ShipmentDetail.CompletedQty` | 已人工确认的实际出库数量 |
允许一条明细选择多个库存,也允许同一库存由人员分别分配给多个明细。约束为:
```text
同一库存全部活动TaskDetail.Qty之和 <= Inventory.Qty
明细CompletedQty + DividedQty <= 明细Qty
```
库存候选和服务端提交校验都限定 `Inventory.ZoneId=1028`,不会把同一数据库中的模具库库存(`1025`)分配给成品发货单。
选中托盘内任一库存后,物理上锁定整个托盘、库位和托盘内全部库存;业务关系只记录人员实际勾选的库存。数据库使用行锁和 `TaskHeader.ContainerCode` 唯一索引,避免双击、双用户或多实例并发生成重复托盘任务。
## 5. 到站实际数量规则
必须提交当前托盘的全部分配关系。实际数量允许为0,也允许高于原计划分配数量,但必须同时满足:
```text
同一库存本次全部实际数量合计 <= 当前库存数量
当前明细本次实际数量 <= 明细需求 - 已出库 - 其他托盘活动分配
```
确认事务同时锁定任务、库存和出库明细;任一校验失败整次回滚。成功后:
1. 库存只扣实际数量;数量为0不扣库存。
2. `CompletedQty` 增加实际数量。
3. 当前托盘分配全部释放,`DividedQty` 按其他活动任务重新计算。
4. 任务及明细转历史,托盘和剩余库存解锁并留在出库口。
5. 同一ERP主单的有效交易聚合为一次 `AddSaleOut` 请求。
## 6. 取消、失败与补传
- 未下发:可取消单条分配或整托任务;取消最后一条时删除空任务并释放全部锁。单条取消与下发共用任务行锁,避免两个操作并发通过状态校验。
- 已下发:不允许直接取消,防止WMS与WCS不一致;到站后可全部填0确认。
- WCS下发失败:任务保持待下发,可排查后重试。
- WCS重复完成:到站任务直接返回等待确认,不重复迁移库存。
- ERP失败:WMS实物出库不回滚,交易保持 `UploadErpFlag=0`。
- 人工补传/`AddSaleOutJob`:按同一 `BillCode` 整批补传,每次生成新的CK,不再次扣库存。
- 旧出库任务:只有关联带 `DLsID` 的ERP明细才进入新到站确认流程。
## 7. AddSaleOut字段
| ERP字段 | WMS取值 |
| --- | --- |
| `ErpCode` | `003` |
| `OutCode` | 每次首次回传或补传生成新的 `CK` |
| `WhCode` | `cp` |
| `Maker` | 当前确认人姓名/账号 |
| `DLsID` | ERP发货通知单表体明细ID |
| `InvCode` | 实际出库物料号 |
| `OutQty` | 人工确认的实际数量 |
接口文档未给出响应模型,按已确认方案复用 `FinishInResponse`。
## 8. 数据库与发布SQL
执行顺序:
1. 在 `default` 和 `cp` 两库分别执行 [20260717_add_sale_out.sql](../sql/20260717_add_sale_out.sql),只增加共享字段 `ShipmentDetail.DLsID`。
2. 只在 `cp` 成品库执行 [20260717_add_sale_out_cp.sql](../sql/20260717_add_sale_out_cp.sql),先检查重复数据,再创建 `IX_ShipmentDetail_DLsID` 和 `IX_TaskHeader_ContainerCode` 两个唯一索引。
3. 只在 `cp` 成品库执行 [20260717_add_sale_out_job.sql](../sql/20260717_add_sale_out_job.sql),新增默认暂停的 `AddSaleOutJob`。
4. 脚本均可重复执行。唯一索引不在线边库创建,避免事项二扩大到线边库任务规则。
共享模型字段必须两库同步,否则同一套代码访问线边库的原出库明细页面也可能因缺列报错。数据库连接名和生产库名不在本次代码中修改。
## 9. 主要代码影响
- 新增ERP请求/响应模型和 `ShipmentHeaderController.Erp` 业务入口,拉单保存使用整批事务。
- 出库单列表增加拉取、分配/下发入口及两个数量列;ERP和旧出库入口互斥显示并做服务端校验。
- 分配页增加库存选择、取消和下发;确认按钮使用异步 `before-ok`,成功后才关闭弹窗。
- `IWCSController` 识别ERP发货任务并保留到站任务。
- `SimpleReceiptInController` 增加到站发货确认。
- `InventoryVM`、库存交易页面和 `AddSaleOutJob` 增加ERP首次回传及补传。
- 原出库、回库、库存和WCS模型均保留,没有新增业务表。
## 10. 回退
先暂停 `AddSaleOutJob` 并停止新任务下发。确保没有“待下发/已下发/到站台”的ERP发货任务后再回退代码。新增可空字段和成品库索引可保留;如必须删除,应在所有新代码实例停止后进行,且先备份 `DLsID` 和失败补传交易。
@@ -0,0 +1,109 @@
# ERP事项二:成品发货接口联动——测试报告
## 1. 测试信息
- 日期:2026-07-17
- 数据库:本地 `wms_yongfeng_cp`,并检查 `wms_yongfeng_xb` 共享模型兼容
- 外部接口:本机ERP/WCS Mock
- 账号:`admin`、`101001`(并发测试)
- 测试通知单:`CODEX-SHIP-20260717`
ERP Mock返回3条明细:D1物料3000374数量30、D2物料3000374数量40、D3物料3000362数量15;三条 `fOutQuantity` 均故意设为999。测试托盘含I1物料3000374数量50、I2物料3000362数量50。
## 2. 构建和SQL
| 编号 | 场景 | 结果 |
| --- | --- | --- |
| T01 | 最终代码构建 | 通过;0错误,15个现有编译警告(含.NET 6停止支持提示) |
| T02 | 共享字段SQL在两库各连续执行2次 | 通过;两库 `DLsID` 字段各1个,线边库未创建事项二唯一索引 |
| T03 | 成品库约束SQL和Job SQL各连续执行2次 | 通过;成品库两个唯一索引各1个,只有1个 `AddSaleOutJob`,`Status=0` |
| T04 | 线边库出库明细列表和Search | 通过;HTTP 200,无 `DLsID` 缺列错误 |
| T05 | 分配页服务端渲染 | 通过;HTTP 200,确认事件为 `before-ok`,不存在旧 `ok` 绑定 |
## 3. 业务测试
| 编号 | 场景 | 实际结果 |
| --- | --- | --- |
| T06 | 按DLCode拉取 | 通过;生成1张主单、3条明细,`DLsID`正确 |
| T07 | `fOutQuantity=999` | 通过;WMS需求仍为30/40/15,只使用 `DeliveryQty` |
| T08 | 重复拉取同一DLCode | 通过;仍为3条,不重复、不覆盖本地执行量 |
| T09 | 同库存跨明细分配 | 通过;I1给D1分20、给D2分30,分别记录数量 |
| T10 | 同托盘多物料 | 通过;I2给D3分10,仍只有1个托盘任务 |
| T11 | 明细超分 | 通过;D1剩余10时再分11被拒绝 |
| T12 | 库存累计超分 | 通过;I1已累计50时再分1被拒绝 |
| T13 | 取消整托待下发任务 | 通过;任务删除,`DividedQty`清零,托盘/库位/库存解锁 |
| T14 | 两账号同时给同一明细和库存各分20 | 通过;1个成功、1个因剩余不足失败,数据库只有1个任务和20数量 |
| T15 | 一键下发 | 通过;WCS收到 `TaskNo`、托盘、起点和出库口 |
| T16 | 同一任务重复下发 | 通过;第二次返回“任务不存在或已下发” |
| T17 | WCS State=100 | 通过;整托移至 `EnterExit_P1001`,库存未扣,任务状态50等待人工确认 |
| T18 | WCS重复完成回调 | 通过;返回等待人工确认,不重复移动 |
| T19 | 站口扫描 | 通过;只返回3条已选分配,默认实际量20/20/10 |
| T20 | I1实际40+20=60,超过库存50 | 通过;整次返回失败,库存、任务、单据和交易均未变化 |
| T21 | 实际量25/20/10 | 通过;D1允许高于计划20但不超明细30 |
| T22 | 库存扣减 | 通过;I1 50→5,I2 50→40 |
| T23 | 单据和任务 | 通过;CompletedQty=25/20/10,DividedQty=0,活动任务删除并写历史 |
| T24 | ERP首次回传 | 通过;3条按同一主单一次回传,同一CK,状态均为1 |
| T25 | 重复确认发货 | 通过;返回“未找到待确认任务”,不重复扣库存 |
| T26 | 人工补传 | 通过;整批生成新CK,状态恢复1,不再次扣库存 |
| T27 | Job补传 | 通过;再次生成另一个新CK,Job仍保持暂停状态 |
| T28 | 库存交易列表补传按钮 | 通过;临时失败 `AddSaleOut` 行只显示成品补传,未显示领料补传;测试记录已清理为0条 |
## 4. 报文与数据库证据
首次 `AddSaleOut` Mock实际收到:
```text
Main: ErpCode=003, WhCode=cp, OutCode=CK202607170004, Maker=Admin
Details:
DLsID=990000001, InvCode=3000374, OutQty=25
DLsID=990000002, InvCode=3000374, OutQty=20
DLsID=990000003, InvCode=3000362, OutQty=10
```
人工和Job补传分别生成 `CK202607170005`、`CK202607170006`,证明每次补传新建CK。有效确认后的数据库快照:
```text
Inventory.Qty = 5 / 40
ShipmentDetail.CompletedQty = 25 / 20 / 10
ShipmentDetail.DividedQty = 0 / 0 / 0
InventoryTransaction.Qty = 25 / 20 / 10
InventoryTransaction.BillType = AddSaleOut
InventoryTransaction.UploadErpFlag = 1 / 1 / 1
TaskHeader active count = 0
TaskHeaderHistory.Status = 100
```
## 5. 最终修复复核
测试后针对上线风险做了以下最小修复:
1. 分配弹窗从 `ok` 改为 `before-ok`,异步成功后才关闭。
2. 分配、取消、下发和确认增加数据库行锁;确认同时锁任务、库存、出库明细。
3. 只在成品库增加活动任务托盘唯一索引,数据库级阻止同托盘重复活动任务,不改变线边库任务规则。
4. 库存交易列表按交易类型、单据类型和回传状态控制补传按钮,避免普通出入库误操作。
5. 库存选择限定 `ZoneId=1028`,ERP/旧出库入口互斥,并将ERP拉单保存改为整批事务。
修复后的最终代码已重新构建通过,并在完整WTM管理页面完成获取ERP通知单、分配页源码绑定及库存交易补传按钮冒烟验证;未发现新增页面脚本错误。
## 6. 2026-07-18上线前复查
| 编号 | 场景 | 实际结果 |
| --- | --- | --- |
| T29 | 成品库库存库区基线 | 数据库同时存在 `1025=3587` 条、`1028=1635` 条库存,722个物料编码跨库区重叠,证明必须限制库区 |
| T30 | ERP明细查询物料3000053可用库存 | 只返回成品库库存ID 5011;模具库同物料库存ID 238未返回 |
| T31 | 绕过页面提交模具库存ID 238 | 服务端返回“只能选择成品库库存”,未生成任务、未修改库存 |
| T32 | ERP单与旧出库单入口 | ERP行 `CanAllocateErp=true/CanStartLegacyOut=false`;旧单相反;旧单打开分配页被拦截 |
| T33 | 直接调用旧 `StartOut` | ERP单被拦截并提示使用“分配/下发”;普通旧单仍可正常启动 |
| T34 | 待下发单条分配取消 | 返回成功;任务头/明细删除,库存、托盘、库位解锁,`DividedQty`归零 |
| T35 | 调整后的SQL连续执行2次 | 两库共享字段正常;唯一索引仅在成品库;两个Job仍各自在对应数据库且 `Status=0` |
| T36 | 调整后最终构建 | 通过;0错误,未引入新的编译警告 |
本轮使用的 `CODEX-AUDIT-*` 主单、明细、任务、库存、托盘和库位均已精确删除,复查剩余0条。本轮只使用本地数据库和本地WMS实例,未调用真实ERP/WCS。
## 7. 数据清理与结论
- 测试出库单、明细、库存、托盘、库位、交易、活动任务和任务历史均已精确删除,复查剩余0条。
- 两库 `DLsID` 字段、成品库唯一索引和默认暂停的 `AddSaleOutJob` 保留,属于正式变更。
- SO/Out/CK流水号保留正常间隔,不回退序列,避免后续单号冲突。
本地接口、数据库事务、并发保护、WCS流程、ERP首次回传及两种补传均达到发布条件。真实ERP响应模型和真实WCS地址仍需在发布窗口做外部联调;Job应在联调成功后启用。