轻易云
注册体验

销售订单(OMS)从吉客云同步到 MySQL 的实战教程

· 吕修远· 集成方案库· 3 次浏览· 约 4 分钟读完

这个策略解决什么问题

销售订单是 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

关键字段对照(节选):

源字段目标字段映射类型说明
tradeNotrade_noDIRECT跨系统唯一标识
tradeType / tradeStatustrade_type / trade_statusDIRECT订单类型与状态
shopName / ShopNameshop_nameDIRECT注意源端字段大小写
sellerMemo+buyerMemo+appendMemoremarkTRANSFORM三段备注拼接
tradeTimetrade_dateDIRECT下单时间,YYYY-MM-DD HH:mm:ss
gmtModifiedupdated_timeDIRECT增量同步判定字段
goodsDetail.*oms_sale_order_detail.*整组循环每行一条明细
—order_id(明细)TRANSFORM取主表 lastInsertId
轻易云数据对账平台 - 官方宣传图

在轻易云上如何配置

我们在客户现场做这条策略时,习惯用易云(Qeasy)的「源端 API + 目标端 SQL」组合来承接,而不是写脚本。下面是几个典型配置要点:

  1. 源端接口:方法 POST,API 选 jackyun.tradenotsensitiveinfos.list.get,主键设为 tradeNo,幂等字段设为 tradeId 并开启 idCheck。
  2. 目标端接口:方法 POST,API 选 executeReturn,主键设为 id(自增),核心参数为 main_params 与 extend_params_1。
  3. 明细行循环:把目标端的 extend_params_1 配置为源端数组名 goodsDetail,平台会逐元素执行 extend_sql_1,实现 1:N 明细落库。
  4. 主从外键:明细行的 order_id 用 <{lastInsertId:}> 占位,由平台自动回填主表 INSERT 后的自增 ID,不需要手动维护关联。
  5. 编码映射集中管理:虽然本策略主编码走 DIRECT,但客户后续接入金蝶等 ERP 时,建议把货品、店铺编码映射放到「编码集线器」,用 _findCollection 联查,避免在每个策略里复制一份映射表——这是轻易云客户最常见的应对模式之一。
  6. 常量与默认值:在 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 数量,以及主从行数比例(主表行数 × 平均明细行数 ≈ 明细表行数)。
  • 第二周起改为每周对账,出现偏差优先看增量边界是否漏单。

踩坑复盘

  1. 源端字段大小写不一致:吉客云有些字段是 shopName,有些接口返回的是 ShopName,主表映射漏写一个就会一直 NULL。稳妥的做法是在轻易云的字段映射里把两个名字都列上,优先取非空值。
  2. 备注三段拼接写错优先级:sellerMemo + buyerMemo + appendMemo 是按业务规则取舍的,典型错误是直接拼接导致卖家的内部备注暴露给买家端。规范的做法是用 TRANSFORM 表达式按业务优先级取一段或拼接。
  3. 明细外键没回填:很多人在 extend_sql_1 里把 order_id 写成从源端取值,但源端根本没有这个值,导致明细全部 NULL 或关联不上主表。正确做法是明细外键只取主表 lastInsertId,由平台注入。
  4. 增量边界漏单:奇门接口要求 startModified 与 endModified 同时存在且间隔不能超过 7 天,如果按小时调度但窗口设错,会导致边界外的数据漏拉。稳妥的做法是在源端过滤条件里用 {{LAST_SYNC_TIME}} 与 {{CURRENT_TIME}} 两个变量绑定,而不是写死时间。
  5. 目标端频率高于源端:有客户把目标端也设成每 15 分钟,结果目标端空闲率很高,白白延迟了落库时效。源端 15 分钟拉一次、目标端 5 分钟落一次是更稳的组合。

适用场景与不适用场景

适用:吉客云作为电商中台、MySQL 作为 OMS 落库库,且只需要单向同步销售订单主从结构的场景,典型如零售、鞋服、美妆等线上订单量大的企业。 不适用:需要双向同步(OMS 改单回传吉客云)、订单状态机复杂(需要多次条件分支)、或需要把订单推送到 ERP/WMS 做后续履约的场景——这些应当拆成独立策略,而不是堆在一条里。

本文为原创内容,转载请注明出处:https://www.qeasy.cloud/insights/solutions/strat-mysql-p2ea595-5916-oms-e891c8c4

评论