客户主数据从金蝶云星辰拉取到轻易云：单策略增量同步实战

这个策略解决什么问题

客户主数据是供应链一切后续单据的「根」。在一次零售企业的实施里，我们经常碰到这样的场景：金蝶云星辰里维护着几千家经销商门店，营销云侧也在维护一套，3 个月后两边对账发现 200 多家编码对不上，要么是某一方改了名称没同步，要么是新建了客户另一方完全不知道。

这个策略就是用轻易云数据集成平台（Qeasy）做单一职责的同步：把金蝶云星辰的客户档案按修改时间增量拉到 Qeasy 中间层，作为下游分发与对账的唯一权威数据源。看似简单，但编码映射、时间窗口、增量起点三个地方没设计好，后期排查极其痛苦。

数据流向与字段映射

数据流向是单向的：金蝶云星辰（源） → 轻易云 datahub 中间层 → 下游目标。

源端调用的是 /jdy/v2/bd/customer 这个客户档案查询接口，分页参数 page 与 page_size 控制拉取节奏。增量识别的两个核心字段是 modify_start_time 与 modify_end_time，都是毫秒级时间戳。

关键字段对照如下（中间层为 Qeasy datahub）：

目标端的 datahub 节点配置的是「写入空操作」，这一步不是真的落库，而是把客户数据先沉淀在 Qeasy 中间层，由其它分发策略按需消费——这是轻易云典型的**「表头表体分阶段」**应对模式。

在轻易云上如何配置

源端平台选 Kingdee.YXC，API 选 /jdy/v2/bd/customer，effect 设为 QUERY，method 为 GET。idCheck 打开，buildModel 与 autoFillResponse 关闭，这样响应结构由后续处理阶段动态构造。

中间层平台选 datahub，effect 设为 EXECUTE，method 设为 POST，先做「写入空操作」——它的作用是触发 Qeasy 中间层的接收事件，让客户档案进入统一的数据池，供下游分发策略订阅。这是轻易云客户最常用的**「编码映射集中管理」**模式：所有客户档案先汇聚到 datahub，编码映射只在这里维护一份，下游各业务线（订单、库存、对账）按统一编码取数。

请求参数里四个字段是固定的：modify_end_time 取 {{CURRENT_TIME}}*1000，modify_start_time 取 {{LAST_SYNC_TIME}}*1000，page 默认 1，page_size 设 50。这个组合决定了增量同步的窗口大小与每次拉取的体量。

实施步骤

第一步：确定增量起点。第一次运行时 LAST_SYNC_TIME 通常为空或 0，此时必须用一次全量触发把所有客户拉一遍，建立初始基准时间戳。稳妥的做法是手动指定一个历史时间点，比如「2024-01-01 00:00:00」对应的毫秒值，作为首跑窗口的起点。

第二步：配置源端定时。源端 crontab 设为 */16 8-22 * * *，即每天 8 点到 22 点之间每 16 分钟执行一次。这个频次的设计思路是：金蝶云星辰的客户档案修改集中在白天营业时段，高频轮询保证数据延迟不超过 16 分钟；夜间进入低频期，避免无效轮询触发限流。

第三步：配置中间层定时。中间层 crontab 设为 23 2 * * *，即每天凌晨 2 点 23 分执行。源端高频轮询把数据写进 datahub 的暂存区，中间层低频批量消费，避免下游被高频事件冲垮。

第四步：建立编码映射表。在 Qeasy 中间层维护一张 customer_mapping 表，键是金蝶 number，值是下游系统统一编码。新建客户走「金蝶 → 映射表 → 下游」链路；编码变更走「金蝶修改 → 映射表更新版本号 → 下游同步」。

第五步：试运行与对账。先跑 3 天，观察每天拉取的客户数量、修改时间分布、是否有分页未翻完的情况。典型经验是前两天会发现一些 modify_time 为空的历史脏数据，需要在清洗阶段过滤掉。

踩坑复盘

1. 增量起点的毫秒转换最容易翻车。金蝶返回的 modify_time 是字符串时间戳，但 modify_start_time 期望的是「毫秒」级，{{LAST_SYNC_TIME}}*1000 这步千万不能漏，否则拉到的永远是空集。

2. 分页终止条件没判。脚本只判断 page 是否为空，没判断 page_size 是否小于请求值，结果最后一页不满 50 条时会陷入死循环。稳妥的做法是：当返回条数 < page_size 时，跳出循环并刷新 LAST_SYNC_TIME。

3. LAST_SYNC_TIME 更新时机不对。典型错误是边拉边更新——拉到一半失败后，时间戳已经推进，下次重启会丢数据。正确做法是全部翻页完成、全部写入 datahub 后，才更新 LAST_SYNC_TIME。

4. 修改时间字段缺失的脏数据。金蝶有些早期客户档案 modify_time 为空，这种数据既不会出现在增量窗口内，也不会出现在全量里。稳妥的做法是在清洗阶段强制给空 modify_time 赋一个兜底值（比如创建时间），否则这批客户永远同步不到下游。

5. 高频轮询触发金蝶限流。*/16 的频次在客户档案量小的时候没问题，但当档案量过万时，叠加下游分发事件可能触发金蝶侧的 QPS 限流。建议监控源端调用的响应码，遇到 429 时自动降频。

适用场景与不适用场景

适用：客户档案变更频次中等（每天几十到几百次修改）、编码体系相对稳定、需要为多个下游系统分发统一客户主数据的场景。不适用：客户档案全量导入一次性场景（直接用 ETL 工具更省事）、需要双向同步且冲突合并规则复杂的场景（建议引入 MDM 主数据管理平台）。