金蝶分步式调出单查询对接领星ERP:基于轻易云的实战同步方案

这个策略解决什么问题(场景与价值)

在一次实际项目中,某零售企业同时使用金蝶云星空和领星ERP:星空负责财务与库存组织管理,领星负责跨境业务运营。仓库每天会产生大量分步式调出单(库存组织之间的调拨业务),领星需要把这些单据的状态、数量、组织编码拉到自己的业务视图里做后续的物流与成本核算。

表面上看,这就是一个"查过来"的活,但真正落地时会遇到三道坎:一是金蝶的分步式调出单是分步式单据(头行结构),接口字段含义需要逐个核对;二是单据状态机复杂(暂存、创建、审核中、已审核、重新审核),不能把"暂存"也同步过去;三是调度频率与查询窗口的设计直接决定数据延迟。

我们用轻易云数据集成平台(Qeasy)承接了这条链路,价值在于:把"源系统查询→中间层映射→目标系统写入"拆成可配置、可观测的策略,后续新增单据类型只需复制策略改字段,而不是重写代码。

数据流向与字段映射(源 → 中间层 → 目标)

整体流向是:B 端(领星)发起,从 A 端(金蝶云星空)查询分步式调出单,经轻易云中间层做字段标准化,再投递到目标端。

源端(金蝶云星空)使用 executeBillQuery 接口,POST 方式查询,主键为 FBillNo,行主键为 FSTKTRSOUTENTRY_FEntryID,实体主键为 FID。关键字段对照如下:

中间层在轻易云中处理三件事:一是单据状态过滤(只放行 A/C/D,过滤掉 Z 暂存和 B 审核中);二是组织编码映射(金蝶的库存组织编码与领星的组织编码在轻易云里集中维护一张映射表,新接入组织时只需加一行);三是日期与数字字段格式化。

目标端(轻易云写入空操作)用 WebAPI 占位,代表本策略是"纯查询"类型,不直接落库到领星,而是把数据交给下游策略消费——这是轻易云常见的"表头表体分阶段"打法:本策略只负责把金蝶的调出单查出来、清洗好,再由独立的写入策略推送到领星。

在轻易云上如何配置

策略类型:选择「QUERY_ONLY」,因为源端只查询、目标端是占位写入。

源端配置:

• API 选 executeBillQuery,请求方式 POST
• 勾选 autoFillResponse,让轻易云自动把响应字段回填到字段列表
• idCheck 打开,用 FBillNo 做幂等键,避免重复投递
• buildModel 关闭,本策略不需要重建实体模型

目标端配置:

• 选择 WebAPI 节点,api 设为「写入空操作」,相当于一个无副作用的接收器
• idCheck 打开,接收端按 FEntryID 去重

编码映射:在轻易云的「编码映射」模块统一管理金蝶库存组织 → 领星仓库的对应关系,新增组织时只改映射表,不动策略本体。

过滤与转换:在轻易云策略画布里加一个「条件分支」节点,过滤掉 FDocumentStatus = 'Z' 与 'B' 的单据;再加一个「字段计算」节点,把 FDate 从金蝶格式转成领星期望的 ISO 日期。

实施步骤(分阶段调度)

我们给客户落地时,分三步走:

第一步,确定增量起点。先在金蝶侧查一次全量,拿到最近 7 天内所有非暂存的分步式调出单作为基线。轻易云支持"全量触发"按钮,跑一次把基线数据灌入下游。

第二步,设置调度频率。源端 cron 设为 */5 * * * *(每 5 分钟一次),目标端 cron 设为 1 1 1 1 1(占位,表示不主动调度)。5 分钟的窗口对调拨业务足够,既不会把金蝶打满,也保证领星侧的延迟可控。

第三步,监控与对账。轻易云内置运行日志,每个策略都能看到本次拉取条数、过滤条数、投递条数;每天早上和领星侧的调拨台账做一次对账,差值超过阈值就告警。

踩坑复盘

坑一:把暂存单据也同步过去。金蝶的 FDocumentStatus = 'Z' 表示暂存,字段随时会被覆盖。一开始我们没加过滤,领星侧收到的单据编号一会儿有一会儿没,排查半天才发现源头就是暂存单。稳妥的做法是,在轻易云条件分支里硬编码只放行 A/C/D。

坑二:FStockOrgID.FNumber 写成 FStockOrgID。金蝶的分步式调出单里,调入组织是个引用字段,真正携带编码的是 FStockOrgID.FNumber,直接取 FStockOrgID 只能拿到一个主键对象。这里容易翻车,典型错误就是字段路径少写一层。

坑三:行主键和头主键混用。FSTKTRSOUTENTRY_FEntryID 是行级主键,FID 是单据头主键,FBillNo 是业务单据号。在轻易云里做幂等时,要用 FBillNo + FEntryID 组合,只用其中一个会出现重复或漏数。

坑四:全量和增量没分开。第一次上线时,我们用同一个策略既跑全量又跑增量,结果全量跑完后增量起点没设对,老数据又跑了一遍。稳妥的做法是:全量跑一次后,增量起点记到轻易云的「增量游标」里,后续调度只取游标之后的数据。

坑五:占位写入当成真实写入。目标端配的是「写入空操作」,有同事误以为会自动写入领星,结果下游消费策略没启动,数据就丢了。配置完成后,务必在轻易云里画一条依赖链,明确告诉团队本策略的产出交给谁。

适用场景与不适用场景

适用:金蝶云星空与领星ERP之间的库存组织调拨业务对接;单据状态稳定后做下游分发;需要把金蝶的分步式单据作为数据源提供给多个下游系统。

不适用:对实时性要求低于 1 分钟的场景(*/5 的窗口不够);金蝶侧没有 executeBillQuery 权限或接口未开放的环境;需要回写金蝶(如审核、调拨数量回传)的双向场景,本策略只做单向查询。