金蝶云星空客户主数据同步到 MySQL：单策略实战教程

这个策略解决什么问题

一次实际项目中,某零售企业把金蝶云星空作为 ERP 主数据源,下游 BI 和业务中台需要一份扁平的客户主数据表,用于画像标签和门店分析。金蝶的 BD_Customer 接口返回的是「基础资料 ID + 嵌套对象」结构,直接进 BI 几乎没法用。这个策略只做一件事:把金蝶客户按 FModifyDate 增量拉到 MySQL 的 tp_jd_customer,组织隔离为 TP000,并把国家/地区/省份/城市等嵌套对象扁平化。

数据流向与字段映射

流向:金蝶云星空(executeBillQuery,FormId=BD_Customer)→ 轻易云数据集成平台(Qeasy)→ MySQL(tp_jd_customer)。

关键字段对照:

目标字段	源字段	映射类型	说明
FCUSTID	FCUSTID	DIRECT	主键,用于 upsert
FNumber	FNumber	DIRECT	客户编码,业务键
FName	FName	DIRECT	客户名称
FCOUNTRY_FNumber	FCOUNTRY.FNumber	TRANSFORM	源端预提取,扁平化
FCOUNTRY_FName	FCOUNTRY.FDataValue	TRANSFORM	同上
FPROVINCE_FNumber	FPROVINCE.FNumber	TRANSFORM	省份编码
FCITY_FName	FCITY.FDataValue	TRANSFORM	城市名称
FCustType_FName	FCustTypeId.FDataValue	TRANSFORM	客户类别名称
FGroup_FNumber	FGroup.FNumber	TRANSFORM	客户分组编码
FUseOrgId	FUseOrgId.FNumber	TRANSFORM	使用组织,过滤条件
FModifyDate	FModifyDate	DIRECT	增量游标

注意 FCustTypeId 在源端带 Id 后缀,目标端命名为 FCustType_,这里容易对错字段。

在轻易云上如何配置

源端是金蝶云星空的 WebAPI(executeBillQuery),目标端是 MySQL 的 SQL 执行器(batchexecute)。在轻易云数据集成平台里,典型配置点有四个:

源端请求配置里,直接用 {{FCOUNTRY.FNumber}}、{{FCustTypeId.FDataValue}} 这类点路径语法,让金蝶在接口层就把嵌套对象摊平,目标表就不必再写表达式。
过滤条件写成 FModifyDate>='{{LAST_SYNC_TIME|datetime}}' and FUseOrgId.fnumber='TP000',把增量游标和组织隔离放在源端,网络往返最小。
目标端写入用 REPLACE INTO tp_jd_customer (...) VALUES (...),主键 FCUSTID 打开 idCheck,天然 upsert。
单批 200 条封顶,超过就分页。

实施步骤

我们在客户现场通常按四步走,顺序不能乱:

第一步:全量打底。先把 FModifyDate 起点设到一个很早的日期(比如 2000-01-01),手动跑一次,确认目标表行数与金蝶按 TP000 过滤后的客户总数对得上。这一步的产物是一份「全量基线」。
第二步:开启增量。把 LAST_SYNC_TIME 切到平台自动维护,源端按 */7 * * * * 跑(每 7 分钟一次),目标端按 3-59/7 * * * * 跑(每 7 分钟、相对源端偏移 3 分钟)。先拉后写,时序就稳。
第三步:对账与监控。每天早上跑一次金蝶 TP000 客户总数 vs MySQL tp_jd_customer 行数的对账,差异超过阈值就告警。
第四步:异常兜底。如果金蝶端有客户被禁用又启用,FModifyDate 不会刷新,得用「冻结/禁用状态变更」单独补一道,别只押在修改日期上。

踩坑复盘

嵌套对象忘了扁平化。直接把金蝶原始 JSON 灌进 MySQL,下游 BI 解析时一堆 FCOUNTRY.FNumber 拿不到值。稳妥做法是在源端请求配置里就预提取,目标表只收扁平字段。
字段名对错。FCustTypeId(源)对应 FCustType_FName / FCustType_FNumber(目标),差一个 Id、多一条下划线,典型错误是直接照搬源端名,导致整列 NULL。
组织过滤写反。FUseOrgId.fnumber 是使用组织,FCreateOrgId 是创建组织,多组织客户会同时存在两个组织,过滤条件写错就会出现「金蝶有、MySQL 没有」。
增量游标不更新。调度器若使用全局时间戳,跨策略并发会互相覆盖。轻易云这边建议每条策略独立维护自己的 LAST_SYNC_TIME,放在策略元数据里,别共用一个全局变量。
idCheck 与 id 的取值。源端 id 配 FCUSTID 但 idCheck=false(金蝶接口返回里 FCUSTID 可能为 0);目标端 id 配 id、idCheck=true,靠 MySQL 主键约束去重。两侧语义不同,不要混淆。

适用场景与不适用场景

适合:ERP 主数据集中下发到数据仓库/中台,需要扁平结构、增量高频、多组织隔离。

不适合:需要跨系统反查客户扩展信息(此时应在源端补 _findCollection),也不适合跨币别、跨语言的复杂客户模型——那种建议拆成多个策略分别落地。