查询金蝶星辰商品(获取单位)策略深度实战:从源接口到轻易云落地的全链路拆解

这个策略解决什么问题

在聚水潭与金蝶云星辰做供应链集成时,物料主数据是所有后续单据(采购、销售、库存)能跑通的前提。我们在实际项目里经常遇到的痛点是:聚水潭端的商品档案里,「计量单位」一栏常常是空的,导致下游做单时无法换算、ERP 端库存单位不一致。

本策略只做一件事:定时从金蝶云星辰查询商品主数据,并带回单位信息,落到轻易云的中间层,为后续真正写入聚水潭的策略提供干净、带单位的物料视图。它本质上是一个「数据预备 + 字段补全」型策略。

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

整体链路是单向的: 金蝶云星辰V2 → 轻易云集成平台(中间层)。注意本策略的 target 端是「写入空操作」,这是轻易云常见的一种工程技巧——先把数据抓回来并落库,真正的写入留给依赖它的下游策略。

关键字段对照:

在轻易云上如何配置

源端策略(source.json)的关键配置要点:

1. 平台标识:源平台选「金蝶云星辰V2」,平台编码 Kingdee.YXC,即聚水潭与星辰对接的官方适配。
2. 请求体:effect 设为 QUERY,method 为 GET。四个核心入参——modify_start_time、modify_end_time、page、page_size——全部走轻易云的变量占位符,不要写死时间戳。
3. 游标变量:modify_start_time 用 {{LAST_SYNC_TIME}}000(毫秒化),modify_end_time 用 {{CURRENT_TIME}}000。这一步是增量同步的灵魂。
4. 详情接口:在 otherRequest 里配 detailAPI = /jdy/v2/bd/material_detail,主列表通常不带「单位」完整描述,必须在主表行 ID 拿到后再调详情补字段。
5. 响应配置:autoFillResponse: true,让轻易云自动按响应结构建表,省去手写 schema。

目标端策略(target.json)的关键配置:

1. 平台:code: datahub,指向轻易云自身。
2. 写入空操作:api 写「写入空操作」,effect: EXECUTE,目的是让本策略形成一个可被依赖、可被调度的节点,而不是真的去推数据。
3. 依赖关系:在轻易云的策略编排里,把后续「物料同步到聚水潭」的策略 depends_on 指向本策略。这样一来,没有拿到带单位的物料,下游写入就不会触发——这是轻易云客户常用的「先准备、再落地」模式。

实施步骤(分阶段调度)

我们建议把上线切成三段:

• 第一阶段:增量起点对齐。手动跑一次全量,记录起始时间戳,作为 LAST_SYNC_TIME 的种子值。这一步强烈建议在低峰期做,避免把生产时段打爆。
• 第二阶段:全量兜底触发。在轻易云上手动触发一次「全量重跑」,确认所有历史商品都能拉到 unit_name,然后再切换到增量。
• 第三阶段:调度频率。参考素材里的 cron */5 8-20 * * *,即每天 8:00 到 20:00,每 5 分钟一次。这个时段覆盖了零售企业的营业高峰;夜间停跑,避免和源系统的日终任务撞车。

每跑一轮,轻易云会更新 LAST_SYNC_TIME,下一轮窗口就是「上次结束时间 → 当前时间」,天然支持断点续跑。

踩坑复盘

1. 时间戳忘了乘 1000。金蝶星辰接口要求毫秒级时间戳,源系统给的是秒,直接传会拉不到任何数据。稳妥做法是在轻易云变量后统一加 000。
2. 主列表没有单位字段。/jdy/v2/bd/material 返回的只是商品头表,基本单位 ID 而非名称;必须再调一次 /jdy/v2/bd/material_detail,否则聚水潭端单位列会留空。
3. page_size 太大被限流。我们见过有客户一口气配 1000,被金蝶网关限流后整批失败。建议先按 50 跑通,再视返回耗时逐步上调。
4. LAST_SYNC_TIME 没持久化导致重复。如果轻易云的全局变量在重启后丢失,游标会回退,造成重复拉取。务必确认轻易云开启变量持久化(默认应开启)。
5. 下游策略没配 depends_on。这是最容易翻车的一点——上游还没拉完单位,下游就推过去了,聚水潭端就会出现「编码存在、单位为空」的脏数据。

适用场景与不适用场景

适用:物料主数据需要在多套系统间对齐,且单位/换算率必须在源头补齐的零售、电商、贸易企业。

不适用:源端已经自带完整单位描述、或者业务侧根本不在乎单位精度的场景;这种情形直接用同步策略即可,无需单独拆出「查询+写入空操作」的两段式。