UDI主数据查询回写：国药WMS到轻易云集成平台的单一策略实战
这个策略解决什么问题(场景与价值)
某医药流通企业在国药WMS与金蝶云星空之间做供应链集成时,碰到一个具体而琐碎的问题:UDI(医疗器械唯一标识)码段返回结果分散在WMS侧的WebService接口里,下游金蝶云星空按单据触发时拿不到完整字段,需要在集成层做一次"轻查询、轻落库"。这条策略就是为这个场景准备的——从国药WMS的GetUdiRstErp接口主动拉取UDI返回数据,经过中间层清洗,再以一次"空操作写入"回写到轻易云集成平台(Qeasy)自身,作为后续金蝶云星空侧策略的数据来源。它的价值不在于搬运数据本身,而在于把UDI的归属信息(ERP货主、ERP仓库、单据号、ASN类型)沉淀成下游可消费的"准主数据",避免在每张下游单据里重复去WMS端拉取。
数据流向与字段映射
整条链路的流向很清晰:国药WMS → 轻易云集成平台(中间层)→ 轻易云集成平台(目标写入)。源端是WebService查询接口,目标端是一个POST类型的"空操作"写入,数据最终停留在平台内部的中间表里供下游消费。
关键字段对照关系如下:
| 源端字段(WMS返回) | 中间层字段 | 目标端落地 | 说明 |
|---|---|---|---|
| ERP_OWNERID | erp_owner_id | 中间表 erp_owner_id | ERP货主编码 |
| ERP_WHSE_CODE | erp_whse_code | 中间表 erp_whse_code | ERP仓库编码 |
| LORDERID | l_order_id | 中间表 l_order_id | 上层单据号 |
| ASN_TYPE | asn_type | 中间表 asn_type | ASN类型(P收货/R退货等) |
| GRPNO | grp_no | 中间表 grp_no | 分组号,作为查询入参 |
| BARCODE | barcode | 中间表 barcode | 条码,拼接为接口id |
源端接口的id由{{GRPNO}}{{BARCODE}}拼接而成,idCheck关闭,autoFillResponse关闭,意思是返回值要按返回体原样取,不要让平台自作主张回填。我们在中间层做了一次轻量标准化:统一转大写、去前后空格、把数值型仓库编码保留为字符串——这一步是为了避免下游金蝶云星空那边因为类型不一致反复报错。
在轻易云上如何配置
在轻易云(Qeasy)集成平台里,这条策略的源端选国药WMS、目标端选轻易云集成平台本体(datahub)。几个非默认的配置点要单独说一下:
- 请求体组装:源端只有一个入参
GrpNo,固定值1,可以直接写在请求参数的value里;若后续要做多分组扩展,把它改成{{grp_no}}变量更稳妥。 - id拼接策略:
id字段设为{{GRPNO}}{{BARCODE}},关掉idCheck,否则平台会按返回的id做去重,丢数据。 - 响应解析:开启字段自动映射,源端
ERP_OWNERID等几个字段一一映射到中间表的同名字段,标签(label)和描述(describe)直接复用,减少维护成本。 - 目标端空操作:
写入空操作这个API(method=POST、effect=EXECUTE)的request和response都是空,它的意义在于触发一次"持久化落库"事件,让轻易云集成平台内部把这份数据登记为下游可消费的资产,而不是真的往某个外部系统写。 - 调度表达式:crontab写成
1 1 1 1 1,这是占位表达式,意思是"不靠定时触发,而是由前序策略驱动"。
实施步骤
我们把这套策略上线分成了三个阶段,踩过几次坑之后才稳定下来:
第一阶段:增量起点确认。 先确认UDI数据的产生源在WMS侧,新数据以单据过账为节点进入分发表。我们在轻易云里订阅WMS的过账事件,事件触发时把GRPNO和BARCODE写进一张轻量级的"待查询队列"。这一步是整条策略的起点,没它后面全是空转。
第二阶段:全量补偿触发。 增量只能覆盖当天新数据,历史UDI必须靠全量补偿。我们用一个一次性触发的策略,以分组号GrpNo=1为入参全量拉取一次,落库后切回增量。全量策略的buildModel设为true,让平台先按样例数据建表结构,避免字段缺失。
第三阶段:调度频率与重试。 增量策略每5分钟轮询一次"待查询队列",队列空就跳过。WebService接口偶发超时,我们设了3次重试,间隔30秒。重试仍失败的条码写入"待人工处理表",第二天早上由值班同事统一排查。
踩坑复盘
坑1:id拼接顺序写反。 早期版本把id写成{{BARCODE}}{{GRPNO}},源端WMS的接口对id顺序敏感,反了就返回空值。稳妥做法是和WMS侧的接口文档逐字符核对,不要凭直觉。
坑2:目标端"空操作"被误删。 升级平台版本时,有人觉得写入空操作这个API没业务含义就清理掉了,结果下游策略找不到数据源。空操作不是冗余,它是触发平台内部持久化的事件钩子,删除前必须确认没有下游消费者。
坑3:autoFillResponse默认开启导致脏数据。 默认开启时,平台会用请求字段去补齐响应字段,让所有返回字段看起来都有值,实际是假的。UDI这类需要精确匹配的字段必须关闭它。
坑4:全量与增量混跑。 全量补偿跑的时候,增量策略没停,造成同一条UDI被写入多次,下游去重逻辑压力大。稳妥做法是全量窗口期间增量策略挂起,落库完成后再放行。
坑5:数值字段被强转。 ERP_WHSE_CODE在WMS端是字符串531,金蝶云星空那边是数值型,平台默认做了一次强制转换,把0531这种带前导零的仓库编码丢掉了。稳妥的做法是中间层统一保留字符串,只在金蝶侧落库前做一次显式转换。
适用场景与不适用场景
适用:WMS侧只能提供WebService查询接口、无法推送变更事件;需要把零散返回值沉淀为准主数据供下游多个策略复用;数据量在单次接口容忍范围内(本案例单分组千级)。 不适用:实时性要求秒级、UDI数据量在万级以上、需要双写强一致的链路——这类场景应当用实时消息中间件而非查询回写。