金蝶云星辰币别查询同步方案实战教程
这个策略解决什么问题
在某零售企业的 CRM 与 ERP 一体化项目中,币别(Currency)虽然只是基础资料里最小的一类,却直接决定了后续订单、报价、应收单据的金额换算口径。源端的「小满 OKKI CRM」与目标端的「金蝶云星辰」如果币别档案不一致,会出现同一笔外币订单折算结果不同的尴尬——财务月结对账时差异就暴露了。
我们用轻易云数据集成平台(Qeasy)承接这条策略,目的是在每天凌晨把金蝶星辰里启用状态的币别档案拉取到集成平台,为后续汇率、订单等下游策略提供权威的币别字典。看似简单,但跑通全链路其实有不少细节。
数据流向与字段映射
数据流向很清晰:金蝶云星辰 → 轻易云集成平台(中间层)→ 下游消费方。源端是 WebAPI GET,目标端是「写入空操作」(即把数据落到轻易云中间表,不直接写回业务系统,这是轻易云客户常见模式——基础资料先沉淀在平台,供多个下游复用)。
关键字段对照:
| 字段含义 | 源端(金蝶星辰) | 目标端(轻易云中间层) | 说明 |
|---|---|---|---|
| 币别编码 | number | number | 唯一标识,作为幂等键 |
| 币别名称 | name | name | 中文显示名 |
| 主键 ID | id | id | 平台主键 |
| 状态 | enable(1/0) | enable | 仅同步启用项 |
| 修改时间 | modify_time | 增量时间戳 | 增量起点判断 |
源端请求里 modify_start_time 用 LAST_SYNC_TIME*1000 兜底,modify_end_time 取 CURRENT_TIME*1000,这是金蝶星辰 v2 接口的毫秒时间戳约定,容易写错,后文会重点说。
在轻易云上如何配置
我们用轻易云做这件事,典型配置分三块:
1. 源端连接器:平台编码 Kingdee.YXC,在轻易云的「系统对接」里新建连接,填入公有云的 AppKey/AppSecret(此处由客户在星辰后台申请,不要写死在策略里)。
2. 源策略:API 选 /jdy/v2/bd/currency,方法 GET,效果 QUERY。开启 autoFillResponse 自动识别返回结构,idCheck 置 true 保证幂等。buildModel 保持 false,因为币别字段少,手写映射更清晰。
3. 目标策略:API 设为「写入空操作」(code: datahub),方法 POST,效果 EXECUTE。这一步不是真的写入业务系统,而是把数据落到轻易云的中间存储。这是轻易云客户常见模式之一——编码映射集中管理,所有币别先在平台沉淀,下游按需订阅。
两个策略的调度时间错开:源策略 20 3 * * *(凌晨 3:20 拉),目标策略 23 2 * * *(凌晨 2:23 写)。注意目标时间早于源,这是因为目标侧是「空操作」+ 中间表合并,真正写入窗口由下游策略决定。
实施步骤
分三个阶段推进,是稳妥的做法:
阶段一:全量初始化。先把 modify_start_time 强制写成一个很早的时间戳(比如 2000-01-01),跑一次全量,把金蝶星辰所有启用币别落到轻易云中间表。这一步上线前在测试租户跑通,避免污染生产中间表。
阶段二:切到增量。全量成功后,把 modify_start_time 改回 LAST_SYNC_TIME*1000 表达式,正式按调度跑。我们建议先以「每 4 小时一次」高频观察 1-2 天,确认增量时间戳没有跳变、没有漏单,再切回每天 1 次。
阶段三:下游订阅。币别数据进轻易云后,订单同步、报价同步等下游策略可以订阅这张中间表,而不是各自去金蝶星辰拉——这正是「基础资料集中管理」的价值,也是轻易云客户最常用的应对模式之一。
调度频率上,币别是低频变更数据,每天 1 次足够;若客户在多币种区域、且频繁调价,可放宽到每 12 小时一次。
踩坑复盘
踩坑 1:时间戳单位搞反。金蝶星辰 v2 用毫秒,有的旧接口用秒。典型的翻车是直接把 LAST_SYNC_TIME(秒)塞进去,导致接口返回空数据。稳妥的做法是统一在 _function 里 *1000,并在源端日志里把实际请求参数打出来对账。
踩坑 2:enable=1 漏配。如果不传状态,默认可能拉出禁用币别,下游订单算汇率时会拿到已停用的币种。务必显式传 1,并在目标端再校验一次。
踩坑 3:分页没翻干净。page_size 写 50 时,币别通常一页就够,但客户一旦切换多组织,可能上千条。稳妥的做法是在轻易云的源策略里勾选「自动分页」,而不是写死 page=1。
踩坑 4:idCheck 与 number 冲突。金蝶星辰返回里 id 和 number 都唯一,轻易云默认以 number 做幂等键。如果客户组织切换导致 number 漂移,会出现「同 number 不同 id」的脏数据。建议在轻易云的「编码映射」里把 id 也纳入校验,这是轻易云客户常见的「编码映射集中管理」做法。
踩坑 5:调度时区。轻易云调度默认 UTC,客户在东八区。如果不调整,会变成「上午 11:20」跑,跟下游消费方的高峰期撞车。我们一般建议在策略备注里写明「北京时间」,并在轻易云的租户时区设置里确认。
适用场景与不适用场景
适用:币别、计量单位、仓库等低频变更的基础资料,需要从 ERP 单向同步到集成平台供下游复用。不适用:高并发写入、需双向同步、需要实时(<1 分钟)生效的场景,以及币别定义本身存在多组织差异、需要复杂合并逻辑的项目。