查询金蝶仓库信息策略实战:从金蝶云星空拉取仓库主数据到轻易云的完整配置
这个策略解决什么问题(场景与价值)
某零售企业的供应链集成项目里,仓库主数据是所有后续单据(销售出库、采购入库、调拨、盘点)流转的基础。我们在客户现场见过太多这样的翻车:金蝶云星空里新增了一个仓库,但聚水潭侧并不知道,发货单推过去对不上组织,仓库编码找不到对应记录,业务侧只能手工补录。
「查询-金蝶仓库信息(正式)」这条策略解决的就是:把金蝶云星空里仓库档案的变化,增量地、可控地同步到轻易云数据集成平台,作为下游所有单据同步的参照底表。它本身不写目标业务系统,只把仓库快照写到平台侧,后续其他策略在写单据时直接引用平台里的仓库主数据。
数据流向与字段映射
数据流向非常清晰:金蝶云星空(源)→ 轻易云集成平台(中间层 / 目标)。源端走的是金蝶的 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都是空数组,意味着这条策略不向任何业务系统落数据,只是把金蝶拉到的仓库快照沉淀到平台侧。 - 响应处理:同样为空,因为源端已经完成数据校验,目标端无需回执。
轻易云客户常见的应对模式是编码映射集中管理——所有跨系统的组织、仓库、客户编码都在平台侧做一张映射表,后续单据策略通过查表完成转换,而不是每个策略各自写一遍映射逻辑。
实施步骤
我们在客户现场一般按三个阶段调度:
- 增量起点:首次跑全量,把金蝶当前所有启用的仓库全部拉到轻易云。这一步通常在凌晨业务低峰期手工触发,跑完之后记录下「最大 FStockId」或「最大修改时间」作为增量起点。
- 全量触发:建议每周一次,放在周日夜里,作为兜底校验。全量触发时,把上一次增量期间漏掉的脏数据、误删数据补齐。
- 调度频率:这条策略的
crontab是3-59/5 7-23 * * *,即每天 7 点到 23 点,每 5 分钟一次,避开凌晨的金蝶备份窗口。轻易云客户里另一种常见做法是「增量与全量双轨」:高频增量保证时效,低频全量保证最终一致。
依赖关系上,这条策略被标记为其他单据同步的前置依赖(比如销售出库、采购入库),所以一旦它失败,下游策略会自动暂停,避免带着错误仓库编码往下推。
踩坑复盘
- 内嵌对象只取内码:很多工程师直接写
FUseOrgId,把金蝶的内码带过来,到下游根本查不到对应组织。稳妥的做法是写FUseOrgId.FNumber。 - 自定义字段漏拉:
F_POKM_JSTSTOCKNUMBER是金蝶侧为对接聚水潭做的扩展字段,看似不重要,但下游对账全靠它。第一次配置时漏掉,3 个月后两边数字对不上,排查起来非常痛苦。 - 幂等键选错:有人图省事把
FNumber同时当作id和number,一旦编码被修改就会重复入库。正确做法是id用FStockId(物理主键不变),number用FNumber(业务编码可变)。 - 调度时间踩在备份窗口:把
crontab写到凌晨 2 点,正好撞上金蝶自动备份,接口超时一片红。务必和客户的运维确认备份时段,避开它。 - 全量和增量互斥:很多现场同时跑全量和增量,造成数据重复或覆盖。稳妥做法是用平台自带的「运行互斥」开关,或干脆错开时间段。
适用场景与不适用场景
适用:金蝶云星空作为 ERP 主数据源,需要把仓库、组织、客户等基础资料以增量方式同步到集成平台,作为后续业务单据的参照底表;部署在私有化环境,无法直接共享数据库。
不适用:源端不是金蝶系;目标不是「写平台」而是直接写业务系统;或者数据量极小、变更极低,手工维护反而更省事。