简介本资源为WMS与WCS系统对接的通信代码示例聚焦仓储管理系统中WMS向WCS下发任务的JSON报文格式与字段定义面向自动化立体库、智能仓储方向的开发人员与集成工程师。资源以cmd指令区分入库、出库、移库三类业务并完整给出task_id、起终点站台、排/列/层坐标、重量与条码等字段的注释说明便于快速理解任务调度接口的数据结构。压缩包共约2000个文件以dll动态库、cshtml页面、js脚本、cs源码、css样式及xml、config配置为主另有png、jpg等图片资源整体约367MB可支撑一套完整WCS项目的运行与二次开发。目前已有2355人学习下载适合需要参考任务下发协议、排查字段含义或搭建WMS-WCS联调环境的读者。1. WMS 到 WCS 的任务下发一条指令如何穿过系统边界电商仓、图书仓、制造业线边仓里最常见的画面是WMS 里一个出库单审核通过几秒后堆垛机或 AGV 开始动。中间那几秒发生了什么很多人说不清。WMS 负责“账”WCS 负责“动”两者之间靠一条任务报文连接。这条报文发错了轻则任务卡在中间态重则设备撞库。我见过最典型的一次翻车WMS 把同一个出库任务重复下发了三次WCS 老老实实执行了三遍最后盘点差了整整一托货。问题不在 WCS也不在设备而在 WMS 到 WCS 的发送任务环节缺少幂等控制。这篇笔记就围绕“WMS 向 WCS 发送任务”这件事把报文结构、接口选型、发送时机、状态回传和踩坑点讲透。适合正在做 WMS/WCS 对接的开发和实施也适合想搞清楚仓储系统边界的运维。2. 先搞清楚 WMS 和 WCS 的任务边界在哪2.1 为什么任务下发不能由 WMS 直接驱动设备WMS 管的是库存、订单、批次、效期它的数据模型是“账”。WCS 管的是设备调度、路径规划、任务排队它的数据模型是“动作”。如果让 WMS 直接给 PLC 发指令会出两个问题一是 WMS 的事务周期太长一个出库单可能涉及拣选、复核、打包多个环节设备等不起二是设备状态变化太快WMS 的数据库事务扛不住每秒几十次的状态写入。所以中间必须有一个 WCS 做缓冲和翻译。WMS 只负责说“把 A 货位的 10 个图书搬到出库口”WCS 负责决定用哪台堆垛机、走哪条路径、什么时候启动。这个边界划清楚了发送任务这件事才有讨论的基础。常见做法是 WMS 生成任务号WCS 接收后返回确认后续状态由 WCS 主动回传。任务号是两边唯一的关联键格式通常是“仓库编码 日期 序列号”比如WH01-20240520-0001。这个号在 WMS 里是出库单明细的行号在 WCS 里是任务主键。两边必须约定好长度和字符集我一般要求纯 ASCII、不超过 32 位避免不同数据库排序规则带来的玄学问题。2.2 任务报文的字段设计哪些必须传哪些不能传一个最小可用的 WMS 到 WCS 任务报文至少包含这些字段字段名类型必填说明taskIdstring是全局唯一任务号WMS 生成taskTypestring是INBOUND / OUTBOUND / MOVE / COUNTfromLocationstring是起始货位编码需与 WCS 货位表一致toLocationstring是目标货位或站台编码skuCodestring是物料编码quantitynumber是数量整数prioritynumber否优先级默认 5数字越小越优先timestampstring是ISO8601 格式用于超时判断不能传的字段WMS 的内部主键、数据库自增 ID、未经脱敏的客户信息。我见过有人把订单号直接当任务号传结果 WCS 日志里全是客户手机号审计过不了。另外数量字段一定要用整数图书仓里按“册”管理不要出现小数否则 WCS 换算托盘数时会除不尽。2.3 接口选型REST、消息队列还是中间表三种方式我都用过各有适用场景。REST 接口最直观WMS 调 WCS 的 HTTP 接口同步返回接收结果。优点是调试方便缺点是 WMS 和 WCS 耦合紧WCS 重启时 WMS 会报错。消息队列常见的是 RabbitMQ 或 Kafka适合任务量大的场景WMS 往队列里投消息WCS 消费。优点是削峰填谷缺点是消息顺序和重复消费要自己处理。中间表是传统做法WMS 写一张wcs_task表WCS 轮询读取。优点是事务可控缺点是实时性差轮询间隔一般 500ms 到 2s。我的选择逻辑是日均任务量低于 5 万、实时性要求秒级用 REST高于 5 万或者有多个 WCS 实例用消息队列老系统改造、数据库同构用中间表。图书 WMS 因为 SKU 多、订单行多但单仓任务量通常不超过 3 万REST 足够。下面给一个 REST 方式的发送代码示例。import requests import json from datetime import datetime def send_task_to_wcs(task): task: dict包含 taskId, taskType, fromLocation, toLocation, skuCode, quantity, priority url http://wcs-host:8080/api/v1/task headers {Content-Type: application/json} # 补全时间戳统一用 UTC 避免时区问题 task[timestamp] datetime.utcnow().isoformat() Z # 设置超时避免 WMS 线程被卡死 try: resp requests.post(url, headersheaders, datajson.dumps(task), timeout3) resp.raise_for_status() result resp.json() # WCS 返回 code0 表示接收成功非 0 要记录并告警 if result.get(code) ! 0: raise Exception(fWCS rejected: {result.get(msg)}) return result.get(data, {}).get(wcsTaskId) except requests.exceptions.Timeout: # 超时不等于失败需要后续用 taskId 查询确认 raise Exception(WCS timeout, need idempotent check)这段代码的关键点有三个一是timeout3WMS 的线程不能无限等 WCS二是时间戳用 UTC避免跨时区仓库对不上三是超时后不能直接判定失败因为 WCS 可能已经收到并执行了必须用taskId去查一次。这就是幂等控制的起点。3. 发送任务的完整实现从 WMS 出库单到 WCS 任务队列3.1 触发时机审核后发还是分配后发WMS 里出库单的状态流转一般是创建 → 审核 → 分配库存 → 生成拣货任务 → 下发 WCS。触发点选在“分配库存之后、生成拣货任务之前”最稳妥。原因是如果审核后就发库存还没锁定WCS 可能把货搬走了但 WMS 账上还没扣造成超卖如果拣货任务生成后再发WMS 内部已经占用了拣货位WCS 再改目标货位就会冲突。我一般会在分配库存的事务提交后发一个领域事件由独立的发送服务消费这个事件再调 WCS。这样即使 WCS 挂了WMS 的主流程也不回滚任务可以重试。具体到代码WMS 侧通常有一个OutboundOrderService在allocateInventory方法成功后发布事件# WMS 侧分配库存后发布事件不直接调 WCS from django.db import transaction from .events import TaskDispatchEvent transaction.atomic def allocate_inventory(order_id): order OutboundOrder.objects.select_for_update().get(idorder_id) # ... 分配逻辑锁定库存 ... order.status ALLOCATED order.save() # 事务提交后再发事件避免 WCS 收到任务但 WMS 回滚 transaction.on_commit(lambda: TaskDispatchEvent.publish(order_id))transaction.on_commit是 Django 的写法其他框架也有类似机制。核心是保证 WMS 本地事务成功后再对外发任务否则会出现 WCS 已经动了、WMS 却回滚的“黑匣子”状态。3.2 任务拆分一个出库单拆成几条 WCS 任务一个出库单可能包含多个 SKU、多个货位。WCS 的任务粒度通常是“一次搬运动作”所以需要拆分。拆分规则同一个起始货位、同一个目标站台、同一个 SKU 的明细合并为一条任务不同货位必须拆开。比如订单里有 A01 货位的 5 本图书和 A02 货位的 3 本图书都发往出库口那就是两条任务。拆分的数量单位要和 WCS 的搬运单位一致如果 WCS 按托盘搬运而 WMS 按册管理就需要在 WMS 侧先做“整托换算”把零散数量合并成托盘任务。拆分逻辑我一般放在发送服务里不放在 WMS 主流程def split_order_to_tasks(order): tasks [] # 按 fromLocation toLocation skuCode 分组 grouped {} for line in order.lines.all(): key (line.from_location, line.to_location, line.sku_code) grouped.setdefault(key, 0) grouped[key] line.quantity seq 1 for (from_loc, to_loc, sku), qty in grouped.items(): task_id f{order.warehouse_code}-{order.order_no}-{seq:04d} tasks.append({ taskId: task_id, taskType: OUTBOUND, fromLocation: from_loc, toLocation: to_loc, skuCode: sku, quantity: qty, priority: order.priority or 5 }) seq 1 return tasks注意taskId的生成规则里带了order_no和序号这样即使重试也不会生成重复的任务号。如果 WMS 重启后重新拆分只要订单号不变任务号就不变WCS 侧可以用任务号做去重。3.3 发送后的状态回传WCS 怎么告诉 WMS 任务完成了任务发出去只是开始WCS 执行过程中要回传状态。常见状态有RECEIVED已接收、EXECUTING执行中、COMPLETED完成、FAILED失败。回传方式一般也是 REST 或消息队列方向反过来WCS 调 WMS 的接口。WMS 收到 COMPLETED 后才扣减库存、更新订单状态。这里有个坑WCS 的 COMPLETED 只代表“搬运完成”不代表“库存已扣”。如果 WMS 扣库存失败任务状态和库存状态就不一致。我的做法是 WMS 收到 COMPLETED 后先落一张wcs_task_log表再用异步任务去扣库存扣减成功才把任务标记为最终完成。回传接口的字段至少要有taskId、status、timestamp、errorMsg失败时。WMS 侧要做幂等同一个taskId的 COMPLETED 重复收到只处理一次。可以用数据库唯一索引兜底CREATE TABLE wcs_task_log ( id BIGINT PRIMARY KEY AUTO_INCREMENT, task_id VARCHAR(64) NOT NULL, status VARCHAR(20) NOT NULL, error_msg VARCHAR(255), created_at DATETIME DEFAULT CURRENT_TIMESTAMP, UNIQUE KEY uk_task_status (task_id, status) );uk_task_status保证同一个任务同一个状态只插入一次重复回传会触发唯一键冲突WMS 捕获后直接忽略即可。4. 避坑与排查WMS 到 WCS 发送任务的 5 个血泪教训4.1 任务重复下发导致设备重复动作现象WCS 日志里同一个taskId出现多次堆垛机执行了多次搬运库存对不上。原因WMS 发送超时后重试但 WCS 第一次其实已经收到并执行了。解决WCS 侧必须用taskId做幂等收到重复任务直接返回已接收不重复执行。WMS 侧超时后不要盲目重发先用taskId查询 WCS 的任务状态。我一般会在 WMS 发送前先查一次本地wcs_task_log如果已经有 RECEIVED 记录就不再发。4.2 货位编码不一致导致任务被拒现象WCS 返回“货位不存在”任务卡在 WMS 的待发送队列。原因WMS 的货位编码是A-01-01-01WCS 的是A010101两边没对齐。解决上线前做一次全量货位映射校验用 SQL 比对两边货位表的差集。日常运维中新增货位必须同时更新两边最好由 WCS 提供货位主数据接口WMS 定时同步。4.3 优先级字段被忽略导致紧急订单排最后现象紧急出库单的任务在 WCS 队列里排在普通任务后面导致发货延迟。原因WMS 发送时priority传了 1但 WCS 的任务排序逻辑只按创建时间没读priority。解决接口联调时必须验证优先级生效构造两条任务一条 priority1一条 priority5看 WCS 是否先执行 priority1。如果 WCS 不支持优先级WMS 侧就要控制发送顺序紧急任务单独走一个队列。4.4 时间戳时区不一致导致任务超时误判现象WMS 认为任务发出 5 分钟未完成触发告警但 WCS 显示任务才执行 2 分钟。原因WMS 用本地时间WCS 用 UTC两边差 8 小时。解决所有跨系统的时间戳统一用 UTC 或带时区偏移的 ISO8601 格式比如2024-05-20T10:00:0008:00。WMS 和 WCS 的服务器时间必须用 NTP 同步偏差超过 1 秒就要告警。4.5 大批量任务同时下发压垮 WCS现象WMS 一次性下发 5000 条任务WCS 接口响应变慢任务队列积压设备空闲。原因WMS 没有做流量控制WCS 的线程池被打满。解决WMS 侧加令牌桶限流比如每秒最多发 50 条或者改用消息队列WCS 按自己的消费能力拉取。我一般会在发送服务里加一个RateLimiter同时监控 WCS 的队列深度超过阈值就暂停发送并告警。5. 进阶技巧用对账和重放保证任务不丢不重任务发送最怕的是“丢”和“重”。丢了对不上账重了设备乱动。我一般会在 WMS 侧加一张wcs_task_outbox表发送前先写 outbox发送成功后更新状态。这样即使发送服务崩溃重启后也能从 outbox 里找到未发送的任务继续发。outbox 表的结构和wcs_task_log类似但多一个send_status字段取值 PENDING / SENT / CONFIRMED。对账逻辑每天跑一次查 WMS 的 outbox 里所有 SENT 但未 CONFIRMED 的任务用taskId去 WCS 查实际状态。如果 WCS 显示已完成WMS 补记 CONFIRMED如果 WCS 没有这个任务WMS 重新发送。这个对账脚本我用 Python 写过核心就是两个查询加一个比对def reconcile_tasks(): # WMS 侧已发送但未确认的任务 pending Outbox.objects.filter(send_statusSENT, created_at__gtedatetime.now() - timedelta(days1)) for task in pending: # 调 WCS 查询接口 wcs_status query_wcs_task(task.task_id) if wcs_status COMPLETED: task.send_status CONFIRMED task.save() elif wcs_status NOT_FOUND: # WCS 没收到重发 resend_task(task) else: # 执行中继续等 pass重放的时候要注意重发前必须确认 WCS 确实没有这个任务否则就是重复下发。查询接口和发送接口都要用同一个taskId这是唯一的后悔药。还有一个技巧是给任务加版本号。WMS 每次修改任务比如改数量、改目标货位都递增版本号WCS 只接受版本号大于当前记录的任务。这样即使旧消息延迟到达也不会覆盖新任务。版本号可以放在报文的version字段里WMS 侧用乐观锁控制。最后说一个我自己的习惯每次上线新的 WMS-WCS 对接先跑 100 条测试任务覆盖正常、超时、重复、货位不存在四种情况确认对账脚本能正确处理后再放量。这个习惯帮我省过至少三次半夜被叫起来处理设备停机的麻烦。希望帮到你。本文还有配套的精品资源点击获取