万里牛调拨单查询策略实战:从源系统拉取到轻易云调度的完整拆解

这个策略解决什么问题

在某零售企业的多仓调拨场景里,门店之间、门店与总仓之间的库存调拨单需要在源系统(万里牛)落地后,尽快被下游财务和供应链系统看到。如果只靠人工导出再导入,不仅慢,而且单据状态经常对不齐。

我们这次要拆解的「查询万里牛调拨单」策略,定位很清晰:把源系统里符合条件的调拨单按时间窗口拉取,作为整个调拨同步链路的起点。它不直接写目标系统,而是把数据推到轻易云数据集成平台(Qeasy)的中间层,由后续策略接力处理。

换句话说,这一策略解决的是「调拨单从哪里取、按什么节奏取」的问题。

整个链路是单向拉取:万里牛 → 轻易云中间层(等待后续策略消费)。

源系统调用的是 POST 接口 /erp/allocation/changebill/query,分页参数 page 从 1 开始,limit 最大 200。关键过滤字段如下:

中间层落地目标在轻易云侧是一个「写入空操作」的执行节点(type=WebAPI,effect=EXECUTE),它本身不写任何业务系统,只是把分页拉到的数据沉淀下来,供后置策略消费。这种「源 → 中间层」的拆分,是轻易云客户常见的应对模式:把拉取与写入解耦,避免任一端抖动影响全局。

字段层面,源端 bill_code 同时承担「单据号」和「唯一 ID」两个角色,这一点在后续做幂等校验时尤其关键。

策略的元数据里有几个一眼就要盯住的开关:

请求体里 create_time 用 {{LAST_SYNC_TIME|datetime}}、create_end_time 用 {{CURRENT_TIME|datetime}},这是轻易云里典型的「滑动窗口」写法,平台会在每次调度前自动把上次同步成功的时间戳填进去。

我们建议分三步走,这也是轻易云客户落地这类查询策略的常见节奏:

第一步:确认增量起点。 先在源系统里找一张历史调拨单,记录它的创建时间,作为 LAST_SYNC_TIME 的初始值。轻易云支持手动回填一次历史时间戳,先把过去一段时间的数据补齐,再切到正常运行。

第二步:触发一次全量回灌。 把 crontab 临时调成一次性的运行(比如手动触发),观察分页是否完整、有没有超时报错。这一步只看「能不能跑通」,不关心数据量。

第三步:切换到日常调度。 策略的 crontab 是 */5 8-23 * * *,也就是每天 8 点到 23 点每 5 分钟跑一次。这个频次覆盖了门店营业时段的调拨节奏,夜里停跑是因为源系统在凌晨做结算,接口稳定性最差。

调度策略上,我们用的是「增量与全量双轨」:日常按 5 分钟滑窗拉增量,出问题或补数据时,再单独触发一次回溯拉取,两轨互不干扰。

1. 窗口别只看「近 3 个月」。 源端接口 create_time 字段明确写「只能查近 3 个月」。一次实际项目里,有同事把 LAST_SYNC_TIME 误填成一年前,接口直接报错,调度反复失败。稳妥的做法是:在轻易云里加一个前置校验,如果窗口超过 90 天,自动截断并告警。

2. 分页一定要封顶到 200。 limit 最大就是 200,超过会被源端截断并静默丢数据,接口不报错。客户现场出现过「看起来跑完了,实际少了一页」的情况,排查半天才发现是分页参数被改小。

3. idCheck 别关。 这一策略的 idCheck 默认就是 true,幂等靠 bill_code 兜底。一旦手动关掉,同一张调拨单会因为分页边界被拉两次,下游写入就会出现重复行,排查起来非常痛苦。

4. 「写入空操作」不是漏配。 看到 api 字段写着「写入空操作」,新手工程师常常以为配置没写完。其实这是设计上的故意:查询策略只负责拉取,真正的目标系统写入交给后置策略。这里容易翻车的地方是「想一步到位把目标系统也配上」,结果破坏了链路的清晰边界。

适用:源系统有明确的时间窗口分页查询接口、下游需要按单据状态或时间区间做增量同步、整体链路需要拉取与写入解耦的库存调拨场景。

不适用:源端不支持时间窗口过滤、必须全量重拉才能拿到数据的场景;以及单据写入要求强实时(秒级)、不适合 5 分钟调度的场景。