feat: 支持ERP主动下发成品发货通知单并复用导入逻辑
This commit is contained in:
1 parent
80d1b201b0
commit
ede6d32608
9 files changed
+555
-103
No files matched your search
@@ -0,0 +1,118 @@
|
||||
# ERP发货通知单主动下发接口
|
||||
|
||||
## 两种接单方式
|
||||
|
||||
1. 原有“获取ERP发货通知单”按钮:输入DLCode,WMS按ErpCode=003、BReturnFlag=0分页调用ERP的LoadDispatch。未取完整或返回其他单号时不保存。
|
||||
2. ERP主动下发:调用下面的POST接口,WMS直接接收明细,不再回查ERP。单张通知单的全部明细放在data中;批量下发时混合多个DLCode,WMS按DLCode分组。
|
||||
|
||||
两个入口共用DispatchImportService保存规则,仅创建/更新出库单;分配库存、下发WCS和人工确认发货仍走现有流程。
|
||||
|
||||
## 部署和数据库
|
||||
|
||||
接口地址:`POST https://成品库WMS地址/api/erp/dispatch-notices`
|
||||
|
||||
接口在成品库和线边库实例均可直接访问,无启用开关,无API密钥校验,也不需要网页登录Cookie。程序使用当前部署实例的数据库连接,不根据请求的ErpCode、WhCode或单号切换数据库;ERP向成品库下发时调用成品库WMS地址。
|
||||
|
||||
保存服务按成品库区编码ZoneCode=C查询并加锁,以防止并发导入重复单据,不依赖库区ID;不存在编码C则拒绝导入。明细保存为C,不要求ZoneCode=cp。ERP接口的cp仓库标识与WMS库区编码是不同概念。若线边库也存在编码C的库区且报文通过业务校验,会按现有规则保存,不会自动忽略请求。
|
||||
|
||||
沿用现有DLsID字段和成品库索引,无新增字段。尚未实施之前ERP成品发货功能的环境,须先应用既有 `sql/20260717_add_sale_out.sql` 和成品库专用 `sql/20260717_add_sale_out_cp.sql`,不要在线边库执行成品库专用索引脚本。
|
||||
|
||||
请求头:
|
||||
|
||||
```http
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
接口沿用项目Public API入口,ERP直接提交JSON即可。
|
||||
|
||||
## 单张通知单示例
|
||||
|
||||
```json
|
||||
{
|
||||
"data": [
|
||||
{
|
||||
"ErpCode": "003",
|
||||
"bReturnFlag": false,
|
||||
"DLCode": "202609161279",
|
||||
"DLsID": 1000003782,
|
||||
"CusCode": "SSPB",
|
||||
"CusName": "上海史派博实业有限公司",
|
||||
"InvCode": "3002057",
|
||||
"InvName": "018带边同步轮",
|
||||
"InvDefine1": "QG0409",
|
||||
"DeliveryQty": 100
|
||||
},
|
||||
{
|
||||
"ErpCode": "003",
|
||||
"bReturnFlag": false,
|
||||
"DLCode": "202609161279",
|
||||
"DLsID": 1000003783,
|
||||
"CusCode": "SSPB",
|
||||
"CusName": "上海史派博实业有限公司",
|
||||
"InvCode": "3002057",
|
||||
"InvName": "018带边同步轮",
|
||||
"InvDefine1": "QG0409",
|
||||
"DeliveryQty": 100
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
仅一条明细时data只放一个对象。批量时继续放入其他DLCode的明细,DLsID不能重复。相同物料的两条ERP明细不会合并。
|
||||
|
||||
兼容实际LoadDispatch响应中的data结构,可携带count、code和其他多余字段;推送不使用分页count/code,也不会补拉其他页。ERP必须主动发送需要下发的所有明细。CreateDate支持案例的 `yyyy-MM-dd HH:mm:ss` 格式(沿用WTM JSON配置)。按钮查询参数中的BReturnFlag=0是ERP查询约定;推送明细使用JSON布尔值false。
|
||||
|
||||
| 字段 | 规则 / 用途 |
|
||||
| --- | --- |
|
||||
| ErpCode | 必填,003 |
|
||||
| DLCode | 必填,最多50字符,无首尾空格,保存为SourceCode |
|
||||
| DLsID | 必填,大于0的整数,ERP明细唯一标识 |
|
||||
| InvCode | 必填,最多50字符,物料编码 |
|
||||
| DeliveryQty | 必填,大于0,最多4位小数,最大99999999.9999 |
|
||||
| bReturnFlag | false;true拒绝 |
|
||||
| CusCode / CusName | 客户编码/名称,同单据内须一致;编码最多50字符 |
|
||||
| InvName / InvDefine1 | 物料名称/类型,最多50字符 |
|
||||
| fOutQuantity | 不覆盖WMS已出库数量 |
|
||||
|
||||
零数、负数、退货单均不接收。用户已确认负数单据拒绝接收;案例中的DLsID=1000003443、DeliveryQty=-2500会导致整批失败,不静默过滤。
|
||||
|
||||
## 响应及重试
|
||||
|
||||
成功返回HTTP 200,沿用WMS响应格式(字段名保留项目默认大小写):
|
||||
|
||||
```json
|
||||
{
|
||||
"Status": true,
|
||||
"Success": true,
|
||||
"Msg": "发货通知单接收成功",
|
||||
"Data": {
|
||||
"BillCount": "1",
|
||||
"DetailCount": "2",
|
||||
"DLCodes": ["202609161279"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
WTM默认将数字序列化为字符串,因此BillCount、DetailCount按字符串返回。
|
||||
|
||||
业务校验失败返回HTTP 200、Success=false、Status=false、Msg为具体原因,Data=null。HTTP 400表示报文绑定错误,500表示保存异常。请求体上限10 MiB;超过上限可能由服务器返回413。ERP必须同时检查HTTP状态和Success,不能只判断HTTP 200。
|
||||
|
||||
- 整批事务:任意一条失败,整批回滚。超时或500后允许重试原报文;校验失败须修正数据后重试。
|
||||
- DLCode定位单头、DLsID定位明细;重复推送更新现有记录,不增加重复行。同一请求内重复DLsID直接拒绝。
|
||||
- 同一DLsID不能迁移到另一张通知单;不能覆盖同SourceCode的非ERP单据。归档单据拒绝重新导入。
|
||||
- 未执行的明细允许修改数量/物料;已有分配量或完成量时,数量/物料变更整批拒绝。相同数据重试保留本地执行量。
|
||||
- 增量提交不会删除本地未出现在报文中的明细;取消明细/删除通知单不在此接口范围。
|
||||
- 保存按成品库区行锁串行执行,并对现有明细加锁,与原有分配流程协调。单头数量、行数及状态按保存后的所有明细汇总。
|
||||
- 接收结果写应用日志;新增/修改记录保留ERP审计身份。按钮仍使用当前登录用户。
|
||||
|
||||
## 本地验证
|
||||
|
||||
构建:`dotnet build WMS.sln --no-restore`
|
||||
|
||||
验证程序:`dotnet run --project tools/dispatch-tests/DispatchTests.csproj -- 样例JSON文件路径`
|
||||
|
||||
不提供样例路径时跳过真实样例校验。不设置WMS_DISPATCH_TEST_CONNECTION时,仅运行报文校验测试。设置该环境变量为本地MySQL测试库连接后,会创建随机命名的临时数据库、只复制所需表结构,测试完成自动删除临时库;不修改来源数据库业务数据。
|
||||
|
||||
2026-09-16已验证:真实样例反序列化、正数明细、负数拒绝、单条/批量、重复推送、并发推送、跨单明细冲突、整批回滚、已分配/已完成明细保护、未执行数量更新、增量行汇总与状态、审计人、编码C使用其他ID时正常导入、存在ID=1028但编码不是C时拒绝导入、无配置、无密钥请求成功接收。
|
||||
|
||||
测试直接调用实际控制器方法和共用服务,并连接临时MySQL库;未启动完整WMS现场服务,也未进行ERP网络联调或设备联动。部署后由ERP验证实际HTTP链路,无需额外接口配置。
|
||||
Reference in new issue
Block a user