金蝶发货通知单查询策略：轻易云上的轻量同步落地实践

这个策略解决什么问题

在某零售企业的供应链集成场景里,客户经常遇到一种尴尬:金蝶云·星空旗舰版里发货通知单已经审核,但下游仓配、WMS、TMS 系统的状态没有跟上。问题往往不是数据没传,而是没有一个稳定的"轮询位"——也就是一个按节奏把金蝶里的发货单数据拉出来、留在中间层、供其他策略订阅的入口。这条"仅查询"策略正是扮演这个角色:它不直接写入业务系统,只负责把金蝶的发货通知单按时拉到轻易云数据集成平台,作为后续对账、推送、触发的数据源。

数据流向与字段映射

数据流向非常清晰:

金蝶云·星空旗舰版 (源)  →  轻易云中间层 (落地)  →  写入空操作 (占位触发位)

源端是金蝶云·星空旗舰版的 /kapi/v2/sm/sm_delivernotice/batchQuery 接口,RESTful 风格、POST 方法,效果为 QUERY(仅查询)。目标端是轻易云内置的"写入空操作",作用是把这次拉取动作本身登记成一个可被订阅的事件位。

关键字段对照如下:

维度	源端(金蝶)	中间层(轻易云)	目标(空操作)
主键字段	`billno`(单据编号)	`billno`	不落字段,仅触发
内部 ID	`id`	`id`	不落字段,仅触发
请求体	`data`(过滤条件)、`pageNo`、`pageSize`	由轻易云根据页码规则拼装	无
默认页码	`1`	按调度自动递增	无
默认页大小	`1000`	透传	无
去重依据	`billno` + `id` 双重校验	`idCheck=true`	无

number 字段映射到 billno,id 字段映射到 id,配合 idCheck=true,可以有效避免同一张单据在分钟级高频轮询下被重复登记。

在轻易云上如何配置

配置这条策略时,核心是"源端的查询能力 + 目标端的占位触发"两个动作的串联。

源端配置要点

选择金蝶云·星空旗舰版适配器,接口路径 /kapi/v2/sm/sm_delivernotice/batchQuery,请求方法 POST。
请求体里 data 留空,依赖金蝶默认返回近期待审核与已审核的发货通知单;若需要更精细的过滤,例如只拉某仓库、某时间窗的数据,可以在 data 里塞入业务条件。
分页参数 pageNo、pageSize 不要写死为单一值,留给轻易云自动翻页;pageSize=1000 在金蝶侧是常见上限,过大会触发限流。
主键映射 number= billno、id= id,并打开 idCheck,这样调度器会按单据编号去重,避免重复登记。

目标端配置要点

选择轻易云内置的"写入空操作"目标。
这种目标不落库、不写字段,只产生一条执行记录,用来给下游订阅方提供触发信号。
在轻易云的策略编排里,你可以把这条策略作为"上游数据准备"挂在前置位置,把真正写业务表的策略挂在 depends_on 上,实现表头先到位、表体再触发的分阶段调度。

策略编排与编码治理

轻易云客户常见的应对模式之一是编码映射集中管理:把金蝶的仓库、客户、品类编码在轻易云的映射中心统一维护,其他策略都引用同一份映射表,避免各策略各自维护导致 3 个月后两边数字对不上。

实施步骤

把这套策略从零跑起来,通常分四步走。

第一步:增量起点 首次执行时,采用"按时间窗拉取 + 断点续跑"。在轻易云调度配置里,把源端请求体的过滤条件设为"更新时间 > 上次执行时间戳",这样第一次只拉近 7 天的发货通知单,避免一上来就跑全量把接口打挂。

第二步:全量触发 仅在补数或新接入仓库时执行。手动触发一次全量拉取,确认金蝶侧的 data 过滤条件是"近 N 个月"或"指定单据号段",分批跑完。轻易云会按 pageNo 自动翻页,直到返回结果为空。

第三步:调度频率 源端的 crontab 写的是 0-59/5 7-22 * * *,含义是每天 7 点到 22 点之间每 5 分钟一次。这个节奏适合零售门店白天密集发货、夜间低峰的场景。如果客户是 24 小时仓配,可以缩短到每 2 分钟一次,但要在金蝶侧确认 API 限流阈值。

第四步:目标端空跑的真正用途 目标端的 crontab 是 1 1 1 1 1,这是一个一次性占位配置,实际不会被调度器主动执行——它只在被上游策略显式调用时触发。这样设计的好处是,目标端的执行时间和频率完全由源端决定,不会出现"两边各跑各的"的时钟漂移问题。

踩坑复盘

坑一:把"仅查询"写成"带写入" 客户现场最常见的错误是,实施工程师看到目标端是"写入空操作"就以为这是占位,顺手把它改成真正的目标系统,结果拉到的发货通知单直接冲进了下游系统,覆盖了真实业务数据。稳妥的做法是:仅查询策略就只做查询,真正写入下游的动作交给下一条专用策略,中间通过轻易云的策略依赖 depends_on 串起来。

坑二:pageSize 过大触发限流 金蝶侧对批量查询接口通常有 QPS 限制。某次项目中,工程师把 pageSize 调成 5000,第一次跑就直接被金蝶网关拒掉。稳妥的做法是保持 pageSize=1000,并把调度间隔拉到 5 分钟以上,给上游留出恢复窗口。

坑三:idCheck 关闭导致重复触发 如果源端配置里 idCheck=false,同一张发货单在 5 分钟一次的高频轮询下会被登记多次,下游策略会被反复唤醒。打开 idCheck=true,用 billno 做去重主键,这个问题就消失了。

坑四:crontab 跨天不衔接 0-59/5 7-22 * * * 只覆盖白天 15 小时。如果客户晚上也有发货,需要把表达式扩展到 0-59/5 0-23 * * *,否则夜间的发货通知单会积压到第二天早上才被拉取。

坑五:空操作目标被误以为"漏配" 审计检查时,reviewer 看到目标端是"写入空操作"、没有任何字段映射,容易误以为这条策略没配完。实际上,这是设计上故意为之——它的价值在于"按时把数据拉过来",而不是"把数据写到哪里"。

适用场景与不适用场景

适用场景:供应链集成中,需要把上游 ERP 的发货通知单作为下游仓配、WMS、TMS、对账系统的统一数据源;需要给其他同步策略提供稳定、按时、按单据编号去重的数据准备位。

不适用场景:需要直接把发货通知单写入业务数据库的场景;需要实时(秒级)响应的场景——5 分钟级别的轮询无法满足;金蝶侧没有开启对应 API 权限或接口限流极严的场景。