销售订单(OMS)从吉客云同步到 MySQL 的实战教程
这个策略解决什么问题
销售订单是 OMS 数据汇集的入口单据,源端在吉客云·奇门,目标端落到 MySQL 的 oms_sale_order 主表与 oms_sale_order_detail 明细表。我们在客户现场做集成时,看似一个简单的"拉单落地",但只要主从外键、增量边界、备注拼接这几件事没设计好,1 个月后两边数字就对不上。本策略给出的是一条单方向、单主从结构的销售订单落库实现路径,适合用易云(Qeasy)数据集成平台做 OMS 落库参考。
数据流向与字段映射
数据流向:吉客云·奇门 → MySQL(私有化部署)。源端通过奇门接口 jackyun.tradenotsensitiveinfos.list.get 分页拉取,目标端通过 executeReturn 执行主 SQL + 明细扩展 SQL。
主从结构映射:
吉客云销售订单(主表)
├── tradeNo / tradeId
├── shopCode、shopName、companyName、customerCode
├── warehouseCode、warehouseName
├── goodsDetail(数组)
│ ├── 货品行:goodsNo、goodsName、sellCount、sellPrice、cost…
│ └── ...
└── 落库到
MySQL oms_sale_order(主表)
├── trade_no、shop_code、shop_name、customer_code…
└── oms_sale_order_detail(明细表,1:N)
└── order_id = 主表 lastInsertId
关键字段对照(节选):
| 源字段 | 目标字段 | 映射类型 | 说明 |
|---|---|---|---|
tradeNo | trade_no | DIRECT | 跨系统唯一标识 |
tradeType / tradeStatus | trade_type / trade_status | DIRECT | 订单类型与状态 |
shopName / ShopName | shop_name | DIRECT | 注意源端字段大小写 |
sellerMemo+buyerMemo+appendMemo | remark | TRANSFORM | 三段备注拼接 |
tradeTime | trade_date | DIRECT | 下单时间,YYYY-MM-DD HH:mm:ss |
gmtModified | updated_time | DIRECT | 增量同步判定字段 |
goodsDetail.* | oms_sale_order_detail.* | 整组循环 | 每行一条明细 |
| — | order_id(明细) | TRANSFORM | 取主表 lastInsertId |
在轻易云上如何配置
我们在客户现场做这条策略时,习惯用易云(Qeasy)的「源端 API + 目标端 SQL」组合来承接,而不是写脚本。下面是几个典型配置要点:
- 源端接口:方法
POST,API 选jackyun.tradenotsensitiveinfos.list.get,主键设为tradeNo,幂等字段设为tradeId并开启idCheck。 - 目标端接口:方法
POST,API 选executeReturn,主键设为id(自增),核心参数为main_params与extend_params_1。 - 明细行循环:把目标端的
extend_params_1配置为源端数组名goodsDetail,平台会逐元素执行extend_sql_1,实现 1:N 明细落库。 - 主从外键:明细行的
order_id用<{lastInsertId:}>占位,由平台自动回填主表INSERT后的自增 ID,不需要手动维护关联。 - 编码映射集中管理:虽然本策略主编码走 DIRECT,但客户后续接入金蝶等 ERP 时,建议把货品、店铺编码映射放到「编码集线器」,用
_findCollection联查,避免在每个策略里复制一份映射表——这是轻易云客户最常见的应对模式之一。 - 常量与默认值:在 SQL 模板里用
<{sale_org_id: 0}>、<{date: CURRENT_TIMESTAMP}>这种带默认值的占位,源端没值时自动落默认,避免 NULL 满天飞。
实施步骤
我们建议按"先把边界对齐,再上调度"的顺序推进,分四个阶段:
阶段 1:增量起点对齐
- 确认源端增量字段是
gmtModified还是startConsignTime,本策略选用gmtModified作为增量判定。 - 在轻易云里把「最后修改时间」变量绑到
endModified,第一次跑用「全量模式」拉历史数据,把目标表清空后整体灌入。
阶段 2:全量触发 + 编码映射
- 全量跑通后,立即切回「增量模式」,用
startModified/endModified滑动拉取。 - 货品、店铺、仓库三大类编码先按 DIRECT 直接落库,后面再视情况扩展
_findCollection。
阶段 3:调度频率
- 源端:每 15 分钟(
*/15 * * * *),奇门接口有频率限制,过密容易被限流。 - 目标端:每 5 分钟(
*/5 * * * *),目标端只是落库,频次可以高一些。 - 两端频率不一致是轻易云客户常见的应对模式——「源端拉取 15 分钟,目标端写入 5 分钟」形成增量与全量的双轨节奏,既不会压垮源系统,也不会让数据延迟太久。
阶段 4:校验与对账
- 上线后第一周每天做一次对账:源端
tradeNo数量 vs 目标端trade_no数量,以及主从行数比例(主表行数 × 平均明细行数 ≈ 明细表行数)。 - 第二周起改为每周对账,出现偏差优先看增量边界是否漏单。
踩坑复盘
- 源端字段大小写不一致:吉客云有些字段是
shopName,有些接口返回的是ShopName,主表映射漏写一个就会一直 NULL。稳妥的做法是在轻易云的字段映射里把两个名字都列上,优先取非空值。 - 备注三段拼接写错优先级:
sellerMemo+buyerMemo+appendMemo是按业务规则取舍的,典型错误是直接拼接导致卖家的内部备注暴露给买家端。规范的做法是用 TRANSFORM 表达式按业务优先级取一段或拼接。 - 明细外键没回填:很多人在
extend_sql_1里把order_id写成从源端取值,但源端根本没有这个值,导致明细全部 NULL 或关联不上主表。正确做法是明细外键只取主表lastInsertId,由平台注入。 - 增量边界漏单:奇门接口要求
startModified与endModified同时存在且间隔不能超过 7 天,如果按小时调度但窗口设错,会导致边界外的数据漏拉。稳妥的做法是在源端过滤条件里用{{LAST_SYNC_TIME}}与{{CURRENT_TIME}}两个变量绑定,而不是写死时间。 - 目标端频率高于源端:有客户把目标端也设成每 15 分钟,结果目标端空闲率很高,白白延迟了落库时效。源端 15 分钟拉一次、目标端 5 分钟落一次是更稳的组合。
适用场景与不适用场景
适用:吉客云作为电商中台、MySQL 作为 OMS 落库库,且只需要单向同步销售订单主从结构的场景,典型如零售、鞋服、美妆等线上订单量大的企业。 不适用:需要双向同步(OMS 改单回传吉客云)、订单状态机复杂(需要多次条件分支)、或需要把订单推送到 ERP/WMS 做后续履约的场景——这些应当拆成独立策略,而不是堆在一条里。