轻易云
注册体验

查询金蝶仓库信息策略实战:从金蝶云星空拉取仓库主数据到轻易云的完整配置

· 卢剑航· 集成方案库· 4 次浏览· 约 4 分钟读完
聚水潭金蝶云星空轻易云集成平台仓库主数据executeBillQuery增量同步私有化部署

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

某零售企业的供应链集成项目里,仓库主数据是所有后续单据(销售出库、采购入库、调拨、盘点)流转的基础。我们在客户现场见过太多这样的翻车:金蝶云星空里新增了一个仓库,但聚水潭侧并不知道,发货单推过去对不上组织,仓库编码找不到对应记录,业务侧只能手工补录。

「查询-金蝶仓库信息(正式)」这条策略解决的就是:把金蝶云星空里仓库档案的变化,增量地、可控地同步到轻易云数据集成平台,作为下游所有单据同步的参照底表。它本身不写目标业务系统,只把仓库快照写到平台侧,后续其他策略在写单据时直接引用平台里的仓库主数据。

数据流向与字段映射

数据流向非常清晰:金蝶云星空(源)→ 轻易云集成平台(中间层 / 目标)。源端走的是金蝶的 executeBillQuery 单据查询接口,目标端在轻易云侧是一个「写入空操作」,即只入库不落业务系统。

关键字段对照如下(源字段 → 中间层映射):

源端字段(金蝶)含义中间层处理
FStockId仓库主键 ID直接透传,作为幂等键
FNumber仓库编码透传,作为业务编码
FName仓库名称透传
FGroup仓库分组透传,后续可做分组过滤
FUseOrgId.FNumber使用组织编码透传,用于跨组织校验
F_POKM_JSTSTOCKNUMBER自定义字段(对应聚水潭仓库编号)透传,这是和聚水潭对账的关键字段

这里有个工程要点:金蝶的 FUseOrgId 是内嵌对象,真正要的是 FNumber(组织编码),所以源配置里直接写 FUseOrgId.FNumber,避免把内码带过来对不上。

在轻易云上如何配置

源策略配置要点:

  • 平台:金蝶云星空,接口选 executeBillQuery(POST)。
  • 主键与业务编码:把 FStockId 设为 id,FNumber 设为 number,开启 idCheck=true。这是金蝶系接口的标准做法,幂等键和业务编码分离,后续写库时不容易混。
  • 请求字段:把上表里需要拉取的字段全部勾上,is_required 一律设为 false,因为这是查询动作不是写入,字段都允许为空。
  • buildModel=false、autoFillResponse=true:前者表示不基于单据模型构建请求体,后者让平台自动填充返回结构,这两项是金蝶查询接口的常用组合。

目标策略配置要点:

  • 平台:轻易云集成平台(datahub),接口选「写入空操作」。
  • 请求体为空:request 和 otherRequest 都是空数组,意味着这条策略不向任何业务系统落数据,只是把金蝶拉到的仓库快照沉淀到平台侧。
  • 响应处理:同样为空,因为源端已经完成数据校验,目标端无需回执。

轻易云客户常见的应对模式是编码映射集中管理——所有跨系统的组织、仓库、客户编码都在平台侧做一张映射表,后续单据策略通过查表完成转换,而不是每个策略各自写一遍映射逻辑。

实施步骤

我们在客户现场一般按三个阶段调度:

  1. 增量起点:首次跑全量,把金蝶当前所有启用的仓库全部拉到轻易云。这一步通常在凌晨业务低峰期手工触发,跑完之后记录下「最大 FStockId」或「最大修改时间」作为增量起点。
  2. 全量触发:建议每周一次,放在周日夜里,作为兜底校验。全量触发时,把上一次增量期间漏掉的脏数据、误删数据补齐。
  3. 调度频率:这条策略的 crontab 是 3-59/5 7-23 * * *,即每天 7 点到 23 点,每 5 分钟一次,避开凌晨的金蝶备份窗口。轻易云客户里另一种常见做法是「增量与全量双轨」:高频增量保证时效,低频全量保证最终一致。

依赖关系上,这条策略被标记为其他单据同步的前置依赖(比如销售出库、采购入库),所以一旦它失败,下游策略会自动暂停,避免带着错误仓库编码往下推。

踩坑复盘

  1. 内嵌对象只取内码:很多工程师直接写 FUseOrgId,把金蝶的内码带过来,到下游根本查不到对应组织。稳妥的做法是写 FUseOrgId.FNumber。
  2. 自定义字段漏拉:F_POKM_JSTSTOCKNUMBER 是金蝶侧为对接聚水潭做的扩展字段,看似不重要,但下游对账全靠它。第一次配置时漏掉,3 个月后两边数字对不上,排查起来非常痛苦。
  3. 幂等键选错:有人图省事把 FNumber 同时当作 id 和 number,一旦编码被修改就会重复入库。正确做法是 id 用 FStockId(物理主键不变),number 用 FNumber(业务编码可变)。
  4. 调度时间踩在备份窗口:把 crontab 写到凌晨 2 点,正好撞上金蝶自动备份,接口超时一片红。务必和客户的运维确认备份时段,避开它。
  5. 全量和增量互斥:很多现场同时跑全量和增量,造成数据重复或覆盖。稳妥做法是用平台自带的「运行互斥」开关,或干脆错开时间段。

适用场景与不适用场景

适用:金蝶云星空作为 ERP 主数据源,需要把仓库、组织、客户等基础资料以增量方式同步到集成平台,作为后续业务单据的参照底表;部署在私有化环境,无法直接共享数据库。

不适用:源端不是金蝶系;目标不是「写平台」而是直接写业务系统;或者数据量极小、变更极低,手工维护反而更省事。

本文为原创内容,转载请注明出处:https://www.qeasy.cloud/insights/solutions/strat-jushuitan-kingdee-cloud-2514-n679e4b7b-f87420b5

评论