组织主数据查询策略实战:从ERP拉取组织树到集成平台的完整路径

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

在做供应链集成时,几乎所有业务单据都要带「组织」字段:发货组织、结算组织、库存组织、门店组织。源 ERP 的组织接口通常返回一棵多级树,而下游业务系统、报表系统、甚至集成平台内部都要消费这份「组织全景」。一次实际项目中,客户希望我们在每次跑物料、销售订单同步之前,先把组织全量拉取一次,作为后续所有单据的「地址簿」。这个策略就是这条链路最前面的「组织地址簿」:用友BIP的 /yonbip/digitalModel/orgunit/querytree 接口被查询,结果落在轻易云数据集成平台供后续策略引用。看似只是「查一次」,但它在 41 条策略里承担的是 A 序列的「基础资料底座」。

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

源端是用友BIP的数字模型组织接口,目标是轻易云集成平台的「空写入」动作——它不是把数据推到某个业务系统,而是把组织快照留在平台内部,作为后续映射的查询字典。

关键字段对照:

角色	字段	说明
源请求	`code`	组织编码,可选,示例如某零售组织的 `yy1`
源请求	`name`	组织名称,可选
源请求	`enable`	启用状态,必填,1=启用、0=未启用、2=停用
源响应	`name`	组织名称
源响应	`tenant`	租户标识
目标写入	—	空操作,不落外部业务系统,仅保留平台侧快照
平台键值	`number=code`、`id=id`	用 `code` 作为业务主键,`id` 作为平台主键

这里有个细节值得强调:number 用 code、id 用 id,意味着组织编码就是唯一键。后续任何依赖组织编码的字段映射,都以这份字典为准。

在轻易云上如何配置

在轻易云数据集成平台里,这条策略的形态是「源元数据 + 目标元数据」一对配置。

源端(用友BIP):

palatom.code 填 YonYon.BIP,平台 ID 与租户绑定;
api 写 /yonbip/digitalModel/orgunit/querytree,method=POST,type=QUERY,effect=QUERY;
request 三项:编码、名称、启用状态,其中 enable 默认填 1,即「只取启用组织」;
number=code、id=id、idCheck=true,开启幂等校验,避免重复写入;
buildModel=false、autoFillResponse=false,表示模型字段需要手工维护,响应不做自动填充。

目标端(轻易云集成平台):

palatom.code 填 datahub(代表平台自身);
api 写「写入空操作」,method=POST,type=EXECUTE;
request/response 均为空,意思就是「数据落库到平台,不去推任何外部系统」。

两次配置合在一起,就是「从 ERP 查 → 平台落地」。

实施步骤

我们在一个客户现场通常按三阶段推进:

阶段一:增量起点先行。先用 enable=1 跑一次启用组织,核对返回的树形结构与客户主数据台账是否一致;code 是否唯一、是否存在「已停用但仍被业务引用」的脏数据,这一步就暴露出来了。

阶段二:全量触发对齐。把 enable 改成空值或不传,跑一次全量(含停用),与启用集做差集,得到「停用组织清单」,人工确认是否要纳入字典。轻易云客户的常见做法是:启用集常驻内存,停用集按月归档,这样既能保证主流程不引用到脏组织,也保留审计痕迹。

阶段三:调度频率与依赖编排。源端 crontab 写的是 49 3 * * *——每天凌晨 3:49 跑一次,放在夜里是为了抢在物料、销售订单策略之前。目标端 crontab 是 23 2 1 1 1,代表「1 月 1 日凌晨 2:23」触发一次年度快照,典型用于年初组织架构重整。

在 41 条策略的编排里,这条策略 sequence=A,且 depends_on=[],说明它是整条链路的「无依赖起点」。我们习惯把它放在「编码映射集中管理」的目录里,所有依赖组织的字段映射统一引用同一份字典,避免出现「A 模块用编码、B 模块用 ID」这种割裂。

踩坑复盘

空操作不是「不需要配」。目标端 api=写入空操作 看起来像占位,但 idCheck=true、number=id 必须和源端对齐,否则平台侧会重复建档,3 个月后字典膨胀一倍。
enable 默认值最容易翻车。源端 enable 默认写 1,好处是干净;但如果客户业务里存在「先建组织再启用」的场景,跑出来会是空集,排查半天才发现字典没建出来。稳妥做法是上线前在轻易云上跑一次「请求预览」,确认返回值非空。
组织编码不是全局唯一。源系统里 code 在租户内唯一,但跨租户会重复。一旦平台侧开了多租户模式,一定要在映射层加 tenant + code 的复合主键。
停用组织被静默过滤。enable=1 跑久了,业务方会来问「为什么某个组织突然查不到」,其实是它被停用了。最好在平台侧把停用组织单独打标,而不是直接丢掉。
crontab 时间窗要错峰。源端 49 3 * * *、目标端 23 2 1 1 1,看似随意,实则错开了物料、销售订单等下游策略的高峰期。多个策略都堆在凌晨 3 点跑,平台侧会出现「字典还没准备好,下游就来引用」的竞态。

适用场景与不适用场景

适用:多组织架构的零售、连锁、制造企业;需要在供应链单据同步前建立统一组织字典;需要按 code 做幂等映射的所有下游策略。

不适用:单组织、不存在多级组织树的小型业务;需要把组织实时推送给第三方业务系统(此策略仅落平台,不外推);对组织变更敏感度要求在分钟级的场景,本策略按天调度不够用。