销售订单表头拉取实战:从金蝶云星空到自有 OMS 的同步策略
这个策略解决什么问题(场景与价值)
某零售企业在私有化环境里同时跑着金蝶云星空 ERP 和自建的 OMS(订单管理系统,数据落在 MySQL)。销售订单一旦在 ERP 端创建,OMS 必须尽快拉到头信息,才能驱动后续的配货、发货与对账。
这个策略只做一件事:把金蝶云星空的销售订单表头按 */4 分钟的节奏拉过来,落到 MySQL 的 oms_order 表,先不碰表体。它不解决「单据体行项目同步」「状态回写」「冲销处理」,也不替代主数据治理。它的价值在于:把表头这一最容易被忽略、又最影响下游链路的一层,稳定、低延迟、可重跑地拉通。
数据流向与字段映射(源 → 中间层 → 目标)
源端是金蝶云星空,通过 Kingdee Cloud 平台的 executeBillQuery 查询接口拉取销售订单表头;中间层是轻易云数据集成平台(Qeasy)的策略运行时,负责调度、字段映射与写入;目标端是 MySQL 数据库的 oms_order 表,通过 execute WebAPI 执行一条 INSERT 语句。
关键字段对照如下(只列表头常用的部分):
| 业务含义 | 源端字段(金蝶云星空) | 目标字段(MySQL oms_order) | 说明 |
|---|---|---|---|
| 单据编号 | FBillNo | order_no | 唯一键,OMS 端据此去重 |
| 单据内码 | FID | kingdee_FID | 用于后续关联表体与状态回写 |
| 日期 | FDate | order_date | 字符串按目标格式入库 |
| 单据状态 | FDocumentStatus | order_status | 业务侧自行映射 A/B/C |
| 销售组织 | FSaleOrgId.FNumber | kingdee_salseORG | 编码,建议集中管理 |
| 客户编码 | FCustId.FNumber | customer_uuid | 需在 OMS 侧做主数据对照 |
| 需求日期 | FDemandDate | order_delivery_date | 表头承诺交货日 |
| 客户订单号 | 视业务追加 | customer_order_no | 客户外部参考号 |
在轻易云上如何配置
进入轻易云数据集成平台的策略编辑页,按以下要点配置即可:
- 源端连接器:平台选 Kingdee.Cloud,接口选
executeBillQuery,方法 POST。 - 拉取字段:把 FBillNo、FID、FDocumentStatus、FSaleOrgId.FNumber、FDate、FCustId.FNumber、FDemandDate 等加入请求字段列表。
- 目标端连接器:平台选 MySQL,接口类型 WebAPI
execute,把INSERT INTO oms_order (...) VALUES (...)放进main_sql。 - 参数绑定:
main_params里把源字段映射到目标字段;冒号前缀的命名参数必须和 SQL 中的占位符一一对应。 - 编码映射:客户编码、销售组织这类「编码字段」,强烈建议放在轻易云的统一映射表里集中维护,不要散落在每条策略的脚本里——这是轻易云客户常见的应对模式。
- 去重与幂等:目标
order_no上加唯一键;策略开启idCheck,避免重复拉取时炸出主键冲突。 - 响应自动填充:源端
autoFillResponse保持开启,让平台自动把返回行投影到下游参数。
实施步骤
我们习惯把这类拉取策略分成三个阶段上线,一次跑通再细化。
第一步:确定增量起点。 先用 FDate 作为初筛,把「起点日期之前的所有单据」当成历史数据,由一次性任务补齐;起点之后的数据进入增量通道。增量起点一旦确定,轻易云侧就以 FBillNo + FDate 组合去重,避免历史回灌。
第二步:全量触发与验证。
全量阶段我们通常手动触发一次,先在小范围(比如单一销售组织)跑通,对 oms_order 的行数、状态分布、kingdee_FID 非空率做一轮核对。典型错误是「全量跑完不验数,直接开调度」——一旦字段映射错位,增量阶段会持续写脏。
第三步:调度频率与监控。
源策略 crontab 写的是 */4 * * * *,也就是每 4 分钟跑一次。目标端 MySQL 的执行计划 */5 * * * *,间隔略大是为了给源端留出查询结束时间窗,避免两边在同一秒集中写。轻易云侧建议同时挂上「失败重试 + 告警通道」,任何一条 SQL 报错立刻推送到运维群。
后续如果要把「表头 + 表体」合并,可以再做一条子策略,顺序执行;先头表体是轻易云客户另一种常见的「分阶段」应对模式,出问题时至少能定位是头错还是体错。
踩坑复盘
-
编码映射分散在脚本里。 早期我们直接在策略脚本里写
if FSaleOrgId == 'X' then 'Y',三个月后销售组织一变,十几条策略都要改。稳妥做法是用轻易云的集中映射表,改一处生效全局。 -
全量与增量混跑导致重复行。 历史补数没去重就开始调度,
oms_order里同一条单据出现两行,后续对账怎么也平不了。必须先全量验数 + 清理,再开增量。 -
字符串日期直接入库。 源端 FDate 是
2024-05-21 00:00:00这种带时分秒的字符串,目标order_date如果是 DATE 类型会报错或被截断。建议在轻易云侧显式做一次格式转换,再写参数绑定。 -
FKingdee_FID 字段名拼写不一致。 源端是
FSaleOrgId.FNumber,目标端字段名历史上被写成kingdee_salseORG(少了一个 e),看起来是小事,但下游 BI 报表已经按错名引用,改名要连带改 5 张报表。配置时把命名当作合同项来对待。 -
调度频率过密,源端接口慢。 */4 对单组织没问题,多组织并发后金蝶侧
executeBillQuery排队,我们改成「错峰拉取」才稳下来。
适用场景与不适用场景
适用:金蝶云星空 → 自建 OMS 类的头信息初始同步;ERP 作为订单唯一入口、OMS 只做下游执行与展示;私有化、弱网、低频批量场景。
不适用:需要行项目同步、需要把 OMS 的变更回写到 ERP、需要实时(亚秒级)推送;这些场景应另立「表体同步」「状态回写」策略,与本策略解耦。