金蝶业务员档案同步实战:从金蝶云星空查询写入轻易云的单一策略深度拆解

这个策略解决什么问题

业务员档案是订单、发货、回款三条主线的「人」的主键,编码一旦错位,下游所有单据关联都会出问题。一次实际项目中,某零售企业把金蝶云星空作为 ERP 主数据源,小满 OKKI CRM 作为前端销售工具,业务员档案只在金蝶里维护,需要每天定时把最新业务员数据同步到中间层,供 CRM 与 BI 消费。这条策略只负责把金蝶里的业务员档案「拉出来」,并不在轻易云上落库,属于典型的 QUERY_ONLY 形态。

数据流向与字段映射

流向是单向的:金蝶云星空 → 轻易云数据集成平台(中间层),再由平台内部按订阅分发给下游。源端使用 executeBillQuery 接口,POST 方式查询业务员单据,目标端是 写入空操作(WebAPI、POST),编号字段为 FNumber,ID 字段为 FEntity_FEntryId,idCheck 默认关闭,autoFillResponse 开启。

关键字段对照(源 → 中间层语义):

注意:目标端 写入空操作 并不真正落库,只是给策略一个落点,真正的写入由下游订阅策略承担。这正是「表头表体分阶段」在平台层的体现。

在轻易云上如何配置

在轻易云数据集成平台里,这条策略的配置要点很轻:

1. 源端:选择金蝶云星空连接器,API 选 executeBillQuery,请求体里把上表字段全部勾选为返回值;
2. 目标端:选择轻易云内置的 写入空操作 适配器,作用是占位、驱动调度流转;
3. 调度:crontab 设为 25 3 * * *,凌晨 3:25 跑,与源系统白天业务高峰错开;
4. 依赖:depends_on 为空,作为独立的「基础资料采集」类策略,不卡其他任务;
5. 响应:autoFillResponse=true,平台自动把源端字段映射到标准响应里,避免手工拼装。

编码映射建议集中放在平台层的「映射中心」统一管理,业务员类型(FOperatorType)的枚举值,例如「内部销售」「兼职」「代理」,放在一处维护,所有下游策略复用,典型的「编码映射集中管理」做法。

实施步骤

分三个阶段推进,稳妥得多:

第一阶段:全量触发,核对基准。第一次上线,关闭调度,手工触发一次,把金蝶里全部业务员档案拉到中间层,与金蝶报表导出的人工台账逐条核对,确认 FNumber 一一对应。这一步重点是「数量对得上、名字对得上」。

第二阶段:开启增量起点。以第一次全量拉取的最大 FModifyDate 作为增量起点,在源端 executeBillQuery 的过滤条件里加上 FModifyDate >= 上次成功时间,之后每天凌晨 3:25 只拉当天变动的业务员;同时把 idCheck 留 false,避免历史数据微小差异导致整批失败。

第三阶段:调度频率与告警。cron 固定在凌晨 3:25,避免和源端结账、备份窗口冲突;在轻易云里配置失败重试 2 次、间隔 5 分钟,并把「拉取条数低于阈值」「接口超时」两类异常接入告警通道。整套流程跑稳后,再让下游 CRM 与 BI 订阅中间层结果,完成「增量与全量双轨」的稳定运行。

踩坑复盘

1. 典型错误是把 QUERY_ONLY 当成「真同步」。很多工程师一看目标端是「写入空操作」就懵,以为配置错了。这里容易翻车,稳妥的做法是理解:它就是平台里专门给「只采集、不落库」策略预留的占位适配器,真正的下游写入由其他策略负责。

2. FModifyDate 时区与格式。金蝶返回的修改时间字符串不带时区,轻易云落中间层时如果不显式按源系统时区解析,会出现「当天没数据」或「重复拉取」的怪现象。我们吃过亏,稳妥的做法是在源端过滤器里显式带上时区转换逻辑。

3. idCheck 开关要谨慎。一旦打开,中间层会以 FEntity_FEntryId 做去重判断,源端如果出现 ID 漂移(常见于金蝶历史数据迁移后),整批会被判为冲突而丢弃。默认关闭更安全,等数据稳定后再分批打开。

4. cron 时间不要和源端备份打架。业务员档案量不大,但金蝶凌晨有索引重建、结账预跑,把 cron 挤在同一窗口很容易超时。我们最终敲定 3:25,是源端最「安静」的时段。

5. 业务员类型枚举散落各策略。第一次没做集中映射,结果 CRM 里把「内部销售」显示成「A 类」、BI 里显示成「Internal」,报表对不上。后来所有枚举都收口到平台的「映射中心」,问题一次解决。

适用场景与不适用场景

适用:金蝶云星空作为 ERP 主数据源,需要把业务员档案(以及类似的轻量基础资料)定时抽取到中间层,供多个下游系统订阅消费,且对实时性要求在「天级」即可。

不适用:需要秒级实时业务员变更推送、对历史 ID 强校验、或者要在中间层直接落库并对外提供查询服务的场景,这些应另起写入型策略,而不是用 QUERY_ONLY 占位。