金蝶销售订单查询策略实战:从金蝶云·星空旗舰版拉到轻易云数据集成平台

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

在某零售企业的供应链集成里,旺店通是前端电商履约系统,金蝶云·星空旗舰版是后端 ERP,两套系统共用一份销售订单。我们经常碰到一个真实诉求:在某些时点(例如月末对账、活动复盘、第三方 BI 拉数)只需要把金蝶侧的销售订单原样取出来,交给 BI 或下游数仓,而不立刻回写旺店通。

这个策略只做一件事:按时间窗从金蝶云·星空旗舰版分页查询销售订单,落到轻易云数据集成平台作为中转落点,由后续策略再按需分发。它最大的价值是把"查询"和"写回"解耦,先把数据稳定地"拿到手",再讨论怎么用。

源端是金蝶云·星空旗舰版的开放接口,目标端在轻易云平台当前节点是一次"写入空操作"(EXECUTE),实际扮演的是落点/中转角色,后续可被其他策略消费。

关键字段对照(节选):

编码层面有两个细节要留意:billno 作为业务单据号,id 作为系统记录号,二者不要混用——做幂等去重时优先用 id,做业务追溯时再用 billno。

我们在客户现场通常这样配:把源端的金蝶资源、目标端的"写入空操作"分别注册成两个数据源节点,中间用一个查询策略串起来。

要点:

源端:平台选 Kingdee.QJB(金蝶云·星空旗舰版),接口填 /kapi/v2/dtog/sm/sm_salorder/query,方法 POST,effect 选 QUERY,主键字段 billno,幂等字段 id 并启用 idCheck。
请求体:pageSize 写 500,pageNo 由分页器自动维护,初次运行从 1 开始;查询条件放在 data 对象里,通常按最后修改时间区间过滤。
目标端:平台选 datahub(轻易云集成平台),api 用"写入空操作",method POST,effect EXECUTE,这一步的作用是把抓回来的数据落到中转层供下游消费。
构建模型:两边都保持 buildModel=false、autoFillResponse=true,字段由平台根据响应样本自动补齐,降低首次接入成本。

上线一般分三步走,先把骨架立稳,再调频率和增量起点。

全量触发(冷启动):把 crontab 临时改成一次性时间点,例如 1 1 1 1 1(仅作触发器),先跑一遍全量,把历史订单一次性拉齐,作为基线。冷启动阶段建议把 pageSize 调到接口允许的最大值,缩短首跑时间。
切到增量起点:全量完成后,把请求条件 data 里加上"最后修改时间 > 上次成功截止时间"的过滤,确保后续只拉增量。增量起点要刻意晚于全量完成的真实时间点几分钟,避免边界单据被漏拉或重复拉。
调度频率切到日常:正式调度写成 0-59/3 7-23 * * *,即每天 7:00–23:59 每 3 分钟一次,覆盖营业时段。凌晨窗口留给对账和物料同步等重型任务,不与本策略抢资源。

典型错误一:增量起点设错。这里容易翻车的点是"用全量开始时间当增量起点",结果中间几分钟的单据可能既被全量抓到又被增量抓到,产生重复行。稳妥的做法是记下全量任务实际结束的时刻,再加上 1–2 分钟偏移。
典型错误二:分页中途接口抖动。我们见过 pageNo 跑到 200 多次时偶然超时,如果不带断点续跑,会导致后续页整体漏数据。配置上要打开分页器自动重试,并把每页处理的中间状态持久化,异常后能从中断页继续。
典型错误三:把 billno 当幂等键。金蝶的 billno 在业务上是单据号,但接口层唯一标识是 id;在轻易云上做幂等去重时,务必用 idCheck=true 走 id,而不是 billno。
典型错误四:一次拉太多撑爆内存。pageSize 给到 500 已经是偏大值,若单据行项目非常多,建议先在测试环境压一下,再决定是否降到 200 或 100。
典型错误五:忽略编码映射集中管理。哪怕这一策略本身是"查询",下游一旦接进来,客户、仓库、商品编码不一致就会立刻显形。建议在轻易云上把编码映射集中放在一张映射表,后续策略共用,不要每条策略各写一份。

适用:作为整条供应链集成的"取数起点",把金蝶销售订单稳定拉到中转层,再由其他策略分发给旺店通、BI 或数仓;或者用于月末对账、临时数据抽取。不适用:需要立刻在旺店通侧看到订单变更、做强一致写回的场景——那种应另起一条"金蝶 → 旺店通推送"策略,而不要复用纯查询策略加逻辑补丁。