销售出库单运输单号回写金蝶云星空：基于增量触发的单策略同步实战

这个策略解决什么问题

销售出库之后,MES 这一侧会把运输单号写到自己的属性表里;金蝶云星空的销售出库单上必须同步出现这个号,否则下游开票、对账、物流对碰都会卡住。这条策略只做一件事:把 MySQL 里已经产生运输单号、且还没回写过金蝶的记录,推到金蝶的销售出库单上,触发保存。属于典型的「字段级回写」,不是整单重建。

数据流向与字段映射

数据从 MySQL 出发,经过轻易云数据集成平台(Qeasy)的中间层,落到金蝶云星空。

源端(MySQL,WebAPI 查询)从三张表拼出结果:mt_so_delivery_not_label_approve 取单据编号,mt_instruction_doc 取内部 ID,mt_instruction_doc_attr 取运输单号与更新时间。关键过滤条件是 attr_name = 'TRACKING_NUMBER'、运输单号非空、单据编号不以 XSCK 开头,以及「同步标志位」为空或者 last_update_date >= 上次同步时间,确保只拿增量。

目标端(金蝶云星空,BatchSave)只写三个字段:FID 用源端的内部 ID,F_FSYNCMOM 写 true 作为同步标志,FCarriageNO 写入运输单号。FormId 固定为 SAL_OUTSTOCK,Operation 为 BatchSave。

在轻易云上如何配置

源端用一个 WebAPI 类型的查询节点,api=select,请求体里塞 main_params 占位,SQL 用 :limit :offset 动态分页。注意 :limit 不是字符串拼接,是参数绑定,轻易云会按占位符顺序注入,否则分页到后期会越界。

目标端用 batchSave 类型的执行节点,api=batchSave,FormId=SAL_OUTSTOCK,Operation=BatchSave。请求里只放三个字段,轻装上阵。

轻易云的「编码映射集中管理」在这种场景特别顺手:运输单号本身不需要做编码转换,但「同步标志位」的语义最好在平台里集中维护一个常量字典,而不是散落在每条策略里——后面再加几条类似回写时,改一处就够。

实施步骤

第一步,确认增量起点。 第一次上线不能用全量,先用 last_update_date >= 上次同步时间 把历史已写入的记录过滤掉,只回写真正新增的运输单号。如果一开始就把全量灌进去,会把金蝶侧已经存在的 F_FSYNCMOM=true 的记录又写一遍,徒增日志。

第二步,源端调度设成 */7 * * * *,目标端设成 */3 * * * *。 源端拉得慢一些没关系,目标端保存频次更高,确保运输单号能在分钟级落库。

第三步,先在金蝶里挑 2~3 条历史单据手工跑一遍保存接口,确认 BatchSave 在 SAL_OUTSTOCK 上的权限与字段必填项。 典型错误是金蝶侧对自定义字段有「启用」开关,没启用直接写会被静默丢弃。

第四步,小流量灰度。 把源端 SQL 里的 site_id 范围先限制到一个工厂,跑半天观察金蝶侧的 FCarriageNO 是否回写成功、F_FSYNCMOM 是否置位。

第五步,放开范围,正式调度。

踩坑复盘

坑一,同步标志位不是万能防重。 源 SQL 里写的是「t4.attr_value is null or t4.attr_value <> 1」,意思是没置位或没置为 1 都当增量。但如果同一运输单号在 MES 侧被改过,last_update_date 会更新,会再次被当增量推到金蝶——这是设计如此,但要心里有数。

坑二,sd_code not like 'XSCK%' 这条过滤很关键。 MES 里某些单据编号前缀和金蝶的销售出库前缀冲突,如果不剔除,会把 MES 内部单据推到金蝶,直接报错。稳妥的做法是所有回写类策略都把「来源标识」过滤写死。

坑三,金蝶 BatchSave 对空值不友好。 FCarriageNO 如果为空字符串,部分版本会拒绝保存。源 SQL 里 attr_value <> '' 已经做了过滤,但轻易云中间层如果误把空值透传,会在保存阶段才报错,排查链路较长。

坑四,:limit :offset 在 MySQL 大结果集下会越界。 当运输单号历史数据累计很大时,offset 越往后越慢。稳妥做法是分页用 last_update_date + id 双键游标,而不是纯 offset。

坑五,调度频率不一致导致顺序错乱。 源端 7 分钟一次、目标端 3 分钟一次,如果同一批数据被源端拉到两次,目标端会写两次,触发金蝶侧的并发保存校验。建议把目标端也设成与源端同步节拍,或者在轻易云里加一个「同 sourceid 串行化」的轻量锁。

适用场景与不适用场景

适用:销售出库后字段级回写、运输单号/批次号/物流单号等单字段回写、私有化环境增量同步。不适用:整单重建、需要行级事务强一致的场景,以及跨组织的批量反写。