基础资料同步实战：从金蝶云星辰查询部门并落地到集成平台的完整策略

这个策略解决什么问题

基础资料不同步，业务单据就是空中楼阁。一次实际项目里，某零售企业的供应链集成要把旺店通与金蝶云星辰打通，第一步不是同步销售订单，而是先把金蝶云星辰里的部门主数据按增量方式拉到集成平台作为后续单据写入时的“参照系”。本策略只做一件事：以增量方式从金蝶云星辰 V2 接口拉取部门数据，落到轻易云数据集成平台（即 Qeasy）内部，供后续物料、客户、订单等下游策略按编号引用。

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

源端是金蝶云星辰 V2 的 /jdy/v2/bd/department 接口，类型为 QUERY，HTTP 方法 GET；目标端是轻易云集成平台的“写入空操作”WebAPI（内部登记用途，POST）。

关键请求参数（源端筛选条件）：

返回体识别字段：number（部门编码）、id（部门内码）。目标端由于是平台内部的登记写入，不绑定具体业务字段，重点是把 number 与 id 这两个“身份证”持久化下来，供下游策略引用。

在轻易云上如何配置

我们用轻易云（Qeasy）做承接时，这条策略的本质是一条 QUERY_ONLY（只查询入库） 的内部策略，源端按修改时间增量拉，目标端只是把数据落到平台自身的中间存储里。

配置要点：

• 源平台：选择金蝶云星辰 V2 适配器，接口填 /jdy/v2/bd/department，方法 GET，type=QUERY、effect=QUERY。
• 增量时间窗：把 modify_start_time、modify_end_time 配成平台变量函数（{{LAST_SYNC_TIME}} 与 {{CURRENT_TIME}}），由轻易云自动维护游标，免人工更新时间。
• 分页处理：开启分页循环，page 从 1 起按返回结果递增，直到空页或 has_more 为止。
• 去重键：idCheck=true，以部门 id 为唯一键，避免重复写入。
• 目标端：源系统实例配“轻易云集成平台”，api 选“写入空操作”（即平台内部登记）。
• 编码映射集中管理：部门编码字段 number 提前在轻易云的“编码映射”模块登记，后续物料、客户策略统一引用，杜绝下游各自重复维护。

实施步骤（增量起点 / 全量触发 / 调度频率）

1. 首次全量回灌：把 modify_start_time 置为一个很早的时间戳（例如 0 或业务上线日），modify_end_time 取当前时间，先跑一次全量，把存量部门一次性拉到集成平台。
2. 建立时间游标：轻易云在第一次成功执行后自动记录 LAST_SYNC_TIME，之后每次按毫秒级增量推进。
3. 调度频率：源策略 cron 设为 0 8 5,15,28 * *（每月 5/15/28 日 08:00），适合部门这种低频变更的基础资料；如果客户组织变动频繁，可改成每天一次。目标端 cron 配 23 2 * * * 作为平台内部的对账窗口。
4. 校验与对账：轻易云提供运行日志与影响行数，可在“策略监控”里核对本次新增、修改条数。
5. 依赖编排：这条策略被下游物料同步、销售订单等策略 depends_on，由轻易云的依赖调度器自动保证上游先于下游触发。

踩坑复盘

• 时间戳单位不统一：金蝶 V2 接口要的是毫秒，但平台变量默认是秒。这里的稳妥做法是源参数里直接用 _function {{LAST_SYNC_TIME}}*1000 做单位换算，否则一开始会拉不到任何数据。
• 首次没跑全量：典型错误是上线后直接进入增量模式，结果发现某些历史部门缺失。一定要先做一次全量回灌，再切增量。
• id 与 number 混用：客户现场常见问题是用 number（编码）做去重键，但编码允许被修改，导致同一部门被当成两条记录。建议固定以 id（内码）为主键，number 作为业务展示字段。
• 跨页漏数：分页参数没循环，跑一次只取第一页，结果月度对账时数据明显偏少。轻易云默认会按 page_size 自动翻页，但要确认接口是否支持以及返回结构里是否有 total/has_more。
• 下游引用时机过早：物料同步策略没有 depends_on 这条部门查询，导致新建物料时找不到合法部门。基础资料类策略一律建议作为下游的依赖项编排进去。

适用场景与不适用场景

适用：组织架构稳定或月度变更的零售/制造企业，需要把 ERP 中的部门主数据统一汇聚到集成平台作为下游业务单据的参照；多系统共享同一套部门编码。不适用：组织架构频繁调整、要求实时同步（分钟级以内）的场景，此时应改为事件驱动或流式接口；也不适用于没有部门概念的小型业务系统。