渠道信息从吉客云对账系统同步到 MySQL：轻易云实战教程

这个策略解决什么问题

渠道信息属于典型的「基础资料」。它本身不直接产生交易流水，却是订单、对账、结算的共同前提。我们做过的实际项目里，客户痛点很朴素：吉客云里维护的渠道档案，对账侧要按渠道汇总，但下游 MySQL SRM 库里的渠道表要么缺字段、要么滞后一周，财务月结时两边渠道名录对不上，追责追到 IT。这条策略的目标就是：让 MySQL 中的渠道表与吉客云对账系统的渠道档案保持准实时一致，以 gmtModified 为增量游标，按小时窗口轮询拉取并写入。

数据流向与字段映射

源端是吉客云的 erp.sales.get 查询接口（POST，分页+增量时间窗），目标端是 MySQL 私有化 SRM 库的 channel 表（INSERT 写入）。中间层由轻易云承担，负责分页拼装、增量游标维护、字段映射与落库。

关键字段对照如下（截取核心列）：

源字段（吉客云）	目标字段（MySQL `channel`）	说明
`channelCode`（业务编号）	`channelCode`	唯一业务键
`channelId`（系统主键）	`channelId` + `source_Id`	双写，便于追溯
`channelName`	`channelName`	渠道名称
`name` / `code`（查询入参）	—	仅用于过滤
`gmtModifiedStart`	—	取上次同步时间
`pageIndex` / `pageSize`	—	分页，默认 0/50

地理区划类字段（countryId/Name、provinceId/Name、cityId/Name、townId/Name、streetId/Name）一并在目标表中保留冗余名称，方便报表层直接读取，避免连表。

在轻易云上如何配置

我们在客户现场一般按「先源后目标、中间再串映射」的顺序配：

源平台：选择吉客云，接口 erp.sales.get（POST，QUERY 类型）。请求体里把 pageIndex、pageSize 固定成 0、50，把 gmtModifiedStart 绑定到轻易云内置变量 {{LAST_SYNC_TIME|datetime}}，gmtModifiedEnd 留空或同样取当前时间，code/name 置空走全量筛选。
分页与去重：开启轻易云自动分页，把 channelCode 配置为 number（业务编号）、channelId 配置为 id（主键），并把 idCheck 设为 true。这一步决定了去重粒度——务必用业务稳定字段，不要用名称。
目标平台：选择该企业私有化部署的 MySQL，接口选 execute（POST，EXECUTE 类型），把上方那段 INSERT INTO lhhy_srm.channel ... 完整 SQL 放进 main_sql。
编码映射集中管理：轻易云客户里常见的应对模式之一——把所有「吉客云编码 → MySQL 编码」的字典（渠道类型、平台类型、仓库编码等）抽到映射表统一维护，源字段经过映射后再写 SQL 占位符。这里 channelTypeId、onlinePlatTypeCode、warehouseCode 都建议走映射，否则后期改值要改 SQL。
落库策略：建议默认走 INSERT + 业务键幂等。如果客户后续要做变更追踪，再加 UPDATE 分支。一次性双写（INSERT/UPDATE）容易把 create_time 冲掉，稳妥做法是分开两阶段。

实施步骤

分阶段调度是轻易云另一个常见应对模式——增量与全量双轨：

首次全量：把 gmtModifiedStart 固定写死为 1970-01-01 00:00:00，手动触发一次，把历史渠道档案一次性落到 MySQL。完成后立刻把增量游标切回 {{LAST_SYNC_TIME|datetime}}。
增量起点：源端策略调度 20 1-8 * * *（凌晨 1 点到 8 点，每小时第 20 分），目标端策略调度 55 1-8 * * *（同窗口，每小时第 55 分），目标比源晚 35 分钟，留出源端抓取和分页合并的余量。
调度频率：基础资料变更频次不高，按小时足够；如果客户在白天有大量渠道新建动作，可以把窗口扩到 0-23，但建议别短于 30 分钟，避免对源接口造成压力。
依赖与顺序：本策略在客户的整张集成链路里属于 B 序列（基础资料），下游销售订单同步（A 序列）会消费渠道编码，所以一定要确认这条策略在 OMS 之前稳定跑通。

踩坑复盘

典型错误是用渠道名称做去重键。渠道名称在源端允许重名也不报警，一旦用它做 number，轻易云会把后到的覆盖先到的，造成静默丢数据。这里要稳：用 channelCode 做 number、channelId 做 id，双保险。
gmtModified 时区踩坑。吉客云返回的时间戳不带时区，MySQL 端如果按本地时区入库，跨天后增量窗口会漏数据。稳妥的做法是在轻易云映射层显式格式化为 UTC，再让 MySQL 端统一按 UTC 存储和比较。
地理区划字段为空时 SQL 报错。源端某些老渠道没有填写省市区，但 SQL 占位符是 <{xxx: }>，空值会被写成空字符串，能过；如果客户后续改成 NOT NULL 约束就会爆。这里要提前在映射层把空值规范成 NULL。
source_Id 别和 channelId 混用。我们见过客户把源系统主键直接当目标主键 id 用，结果某天源系统主键策略调整，整张表需要重建。source_Id 单独存一份，是回溯和重跑的救命稻草。
首次全量忘了切回增量游标。上线后第一周数据准确，第二周突然停摆，排查发现 gmtModifiedStart 仍然是固定的历史时间戳，后面全量跑不动了。这种「忘了切回去」是典型翻车点，建议在轻易云的策略备注里写红字提醒。

适用场景与不适用场景

适用：基础资料从 SaaS ERP 同步到私有化业务库，需要按时间窗增量落库，下游有订单、对账等链路消费这份资料。不适用：需要双向同步、实时性要求秒级（建议走变更通知或 CDC）、或者源端没有可靠修改时间字段的场景——后者只能走全量定时覆盖。