查询金蝶部门：单一策略同步方案实战教程

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

在供应链集成里，部门档案是一切业务单据的「抬头前置条件」：采购订单要带申请部门、报销单要归属成本中心、审批流要根据部门路由负责人。很多项目一开始都低估了它的复杂度——以为一个接口就完事，结果上线后才发现编码带不过来、组织层级对不上、增量与全量混在一起三个月都理不清。

我们这次落地的「查询金蝶部门」策略，就是把源系统 ERP 的部门主数据按计划拉取并落到目标端，为后续采购、销售、审批类策略提供干净、可追溯的部门字典。它本身不写业务数据，是典型的「只读-查询-落地型」基础资料同步。

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

策略的核心流向是：源 ERP(金蝶云星空) → 轻易云数据集成平台 → 目标端。中间层在这里既是查询调度器，也是字段标准化器。

关键字段对照(基于源端 executeBillQuery 接口返回)：

源端使用金蝶云星空的 executeBillQuery(POST)，目标端在本次配置里走的是「写入空操作」(WebAPI,POST,EXECUTE 语义)，目的是先把字典落进轻易云自身的资料库，再由下游策略消费。

在轻易云上如何配置

我们这次用轻易云数据集成平台(Qeasy)承接，配置分三块：

1. 源端连接器：选 Kingdee.Cloud,填好私有化部署的访问地址与账套授权信息；接口选 executeBillQuery,方法 POST,勾选 autoFillResponse,让返回字段自动展开,省得手写映射。
2. 字段映射：在轻易云的「编码映射」里集中维护 FNumber → dept_code 这种对应,后续不管新增多少部门,规则只改一处。这是轻易云客户常见的做法：把编码规则、字段别名、清洗规则集中到一张「映射总表」,避免散落在每条策略里。
3. 目标端写入：这里先用「空操作」落字典,相当于让轻易云先承担「主数据中心」角色；如果后续要直接推钉钉,再加一个 DingTalk 连接器即可,不动源端。

实施步骤

我们把上线节奏拆成三段：

• 第一周·全量初始化：手工触发一次全量,把现有部门一次性拉过来,确认映射无误。建议放在业务低峰期,跑完后抽样比对两边编码。
• 第二周·切换增量：把调度从「手工」切到自动,源端用 */5 * * * * 这种每 5 分钟一次的频率抓增量。这里是「增量与全量双轨」：全量脚本保留但平时不跑,每周做一次对账兜底。
• 第三周及之后·稳定运行：观察告警,关注 idCheck 字段——本次配置里 idCheck=false,意味着目标端不去重,完全靠源端 FNumber 保证唯一。如果将来字典规模上来了,再考虑打开 idCheck 配合 upsert。

踩坑复盘

1. 组织层级被拍平：源端 FUseOrgId 返回的是「使用组织」,不是「上级部门」。如果直接当成父子关系建树,3 个月后审批路由全乱。稳妥的做法是单独维护一张组织层级映射表,别拿使用组织当父节点。
2. 助记码为空导致匹配失败：FHelpCode 在新建部门时往往为空,如果目标端拿它做模糊匹配,会出现「找不到」的假象。建议匹配键优先级：编码 > 名称 > 助记码。
3. 忽略停用部门：源端默认会返回已停用部门,如果无差别同步,目标端审批流可能把单据派给一个空部门。我们会在中间层加一个过滤条件 FForbidStatus='A'。
4. 调度频率过密：*/5 * * * * 对小规模字典够用,但如果源端是按组织隔离,每个组织都跑一遍,数据库压力会叠加。建议按组织拆成多条策略,错峰执行。
5. 空操作目标端的误区：看到 api 写「写入空操作」就以为没写东西,其实轻易云已经把数据落进自己的资料库了——后续策略要消费时,从轻易云读,别再回头打源端。

适用场景与不适用场景

适用：单一 ERP 作为部门唯一来源、目标端需要可消费的部门字典、业务量适中(部门数 < 数千)的私有化项目。不适用：部门频繁跨组织调动且要求实时(分钟级)同步、多源 ERP 合并字典、需要在钉钉侧直接维护部门并回写 ERP 的双向场景。