店铺-客户主数据同步实战:管易云→金蝶云星辰的增量落地方案
这个策略解决什么问题
电商企业里，店铺是销售渠道的最小颗粒度,但金蝶云星辰的供应链与财务核算需要的是「客户」主数据。我们做集成时,经常遇到这样的场景:店铺在源系统加了一家家门店或线上店铺,财务第二天对账却发现缺客户档案,或者编码对不上导致后续销售订单无法落库。把管易云的店铺直接映射为金蝶的客户对象,就能让后续的订单、库存、对账流程顺畅跑起来。
数据流向与字段映射
整体流向是 管易云 → 轻易云数据集成平台(Qeasy) → 金蝶云星辰 V2,采用单层中转。增量窗口通过源端接口 gy.erp.shop.get 的修改时间区间过滤,目标端接口 /jdy/v2/bd/customer 做写入。
| 目标字段(金蝶) | 源字段(管易云) | 映射类型 | 说明 |
|---|---|---|---|
| name(客户名称) | name(店铺名称) | DIRECT | 直接取值 |
| number(客户编码) | code(店铺代码) | DIRECT | 店铺代码直接作为客户编码 |
主键设计上,源端 number=code、id=id;目标端当前 number=1、id=1(占位)。目标端开启 idCheck=true,意味着写入前需要校验主键。
源端还有 nick(店铺昵称)、note(备注)、type_name(店铺类型)、create_date/modify_date 等可扩展字段,本方案暂未映射,后续可以用 COLLECTION 或 TRANSFORM 扩展。
在轻易云上如何配置
源端(Source)选择 WebAPI 类型,effect=QUERY,method=POST,接口填 gy.erp.shop.get。主键绑定 code→number、id→id,开启 idCheck=true,关闭 buildModel。增量参数 modify_start_date 取 {{LAST_SYNC_TIME|datetime}},modify_end_date 取 {{CURRENT_TIME|datetime}},分页参数 page_no=1、page_size=10。
目标端(Target)同样是 WebAPI,effect=EXECUTE,接口填 /jdy/v2/bd/customer,请求体里 name 写 {{name}},number 写 {{code}},number 必传是因为金蝶「有编码规则且更新时必传」,不传后台会拒绝更新。
轻易云上常见的应对模式是把编码映射集中到平台里管理:这一类基础资料同步,通常只用到 DIRECT,后面要扩展店铺类型 → 客户分类时,直接在映射编辑里加 COLLECTION 即可,不必改接口结构。
实施步骤
阶段一:增量起点。首次上线前,在轻易云里手动跑一次全量,把历史店铺一次性拉过来,作为后续增量的起点基准。之后调度就用 modify_start_date ~ modify_end_date 滚动窗口拉增量。
阶段二:调度频率。源端 crontab 配置 */20 7-21 * * *(7:00–21:00 每 20 分钟一次),覆盖电商主要营业时段。目标端用 6-59/27 7-21 * * *,与源端错峰 27 分钟,避免两边同时启动造成瞬时压力叠加。
阶段三:投产与监控。第一次跑通后,观察轻易云运行日志里的请求体与响应体,确认 number 始终带着 code。如果金蝶侧出现「编码已存在」之类的报错,说明源端存在重复 code,要从管易云主数据治理入手,而非改集成策略。
踩坑复盘
-
首次上线没跑全量。直接拿当前时间做增量起点,历史店铺全部漏掉。这是典型错误,稳妥的做法是上线前做一次一次性补数,把 LAST_SYNC_TIME 初始化到合理起点。
-
目标端 number 漏传。金蝶的「有编码规则且更新时必须传 number」是个隐藏规则,容易翻车。我们坚持 number=
{{code}},哪怕不依赖编码规则,也始终把店铺代码带过去,保证可追溯。 -
idCheck 配成 true 却没配 id 查询。当前目标端 id、number 都写的是占位 1,idCheck 开了但没有真正的联查去取目标端的 id。稳妥的做法是后续引入物料同步方案里那套「先查后写」的
_mongoQuery联查,按 number 查出目标端 id 再做更新。 -
源端和目标端调度对齐,瞬时打满。如果两边都设
*/20,容易在某分钟同时发起请求,压垮两边。源端 20 分钟一档、目标端 27 分钟一档的错峰,是为了把压力摊开。 -
可扩展字段一开始就贪多。nick、note、type_name 一股脑全部同步,反而让首次上线的映射变得难调试。我们建议先把 name、number 这两个核心字段跑稳,再按业务节奏扩展。
适用场景与不适用场景
适用:电商零售企业的店铺数量可控(几十到几千家)、修改频率稳定、需要把店铺作为客户维度进入财务核算的场景。
不适用:店铺存在跨系统多源写入(例如既有管易云也有自建 ERP 同时改)、或者目标端需要按「客户分类 + 客户层级 + 多组织」维度进行复杂映射的场景,本方案的 DIRECT 直接映射撑不住,需要升级到编码映射集中管理 + TRANSFORM 表达式。