销售订单价格回写：从金蝶云星空到 MySQL 的实战同步方案

这个策略解决什么问题

某制造企业的销售订单从 CRM/电商前台进入 MySQL 业务库后，会再以标准单据的形式同步到金蝶云星空做财务与库存结算。结算完成后，财务最终确认的含税单价往往会与下单时略有差异，需要按销售订单 + 物料维度回写到 MySQL 的订单明细表，供前台、营销、BI 报表继续使用。如果靠人工导出会很慢，靠触发器又容易漏单。我们用轻易云数据集成平台承接这件事，把「价格回写」做成一个独立、可重跑、可监控的同步策略。

数据流向与字段映射

整体流向是：金蝶云星空 → 轻易云 → MySQL。源端通过 executeBillQuery 把销售订单（含表头 + 表体）查询出来，目标端通过 execute 把税价更新到一张业务明细表上。

关键字段对照表（源端金蝶云星空 → 目标 MySQL）：

目标端的 SQL 长这样（脱敏后）：

update mbs_order_bom
   set kingdee_tax_price = :FTaxPrice
 where bom_uuid = :F_bomUuid

注意原素材里 crontab 是 1 1 1 1 1，明显不是正常调度值，正式上线必须改成业务可接受的频率。

在轻易云上如何配置

我们在轻易云里把这个策略按「源策略 + 目标策略」配成一对。几个要点：

1. 源端：单据查询式拉取。接口选 executeBillQuery，方法 POST，效果 QUERY；分页参数用金蝶默认的 Limit/StartRow 即可。请求体里把 FBillNo、FMaterialId.Fnumber、FTaxPrice、FID、FSaleOrderEntry_FEntryID、FDocumentStatus 都声明出来，便于后续在轻易云里做字段映射和分支判断。
2. 目标端：写库式更新。接口选 execute，方法 POST，效果 EXECUTE。main_params 走参数化绑定，避免 SQL 注入；真正要执行的更新语句放在 main_sql 里，强烈建议用唯一业务键（如 bom_uuid）做 where 条件，避免因关联错位导致批量错改。
3. 编码映射集中管理。金蝶的物料编码是 Fnumber，MySQL 这边往往是自有的 UUID，我们在轻易云的「编码映射」里维护一张物料对照表，源端拉到的 FMaterialId.Fnumber 先过一次映射，再去匹配 mbs_order_bom.bom_uuid。这一步是后期排查问题的关键，不放在轻易云里就会散落在各处脚本里。
4. 幂等与回放。源端把 FID 和 FSaleOrderEntry_FEntryID 都带回轻易云，目标端更新时先按这两个键做一次「存在性检查」，避免重复回写把价格覆盖错。

实施步骤

把上线拆成三个阶段，节奏更稳：

• 阶段一：增量起点。先以「单据状态 = 已审核」且「最近修改时间 ≥ 上次成功时间」作为增量条件，跑 1~2 天观察数据量、报错率和回写准确性。轻易云里建议把这个过滤条件直接写在源端请求体里，而不是事后过滤。
• 阶段二：全量触发。在双方系统低峰期（例如凌晨），把过滤条件放开，做一次全量回写；这一步的目的是核对历史数据对得上预期差异，例如金蝶做过调价单的部分。
• 阶段三：调度频率。稳态后改成准实时调度（例如每 5~15 分钟一次），并配轻易云的告警通道：失败重试 N 次、连续 N 次失败通知到企业微信/钉钉。crontab 字段一定要从占位符改成实际 cron 表达式，别留在 1 1 1 1 1 这种无效值上线。

踩坑复盘

1. 典型错误是把单价直接当「不含税价」回写。金蝶字段名里有 Tax，但同名同义的字段在不同单据上含义不同，回写前必须和销售、财务各确认一次口径。
2. 关联键一定要订单+物料双键。只看单据号会重复覆盖整单价格；只看物料会串单。这里稳妥的做法是 FBillNo + FMaterialId.Fnumber 联合匹配。
3. 更新语句别忘带业务库名和分片键。原素材示例只写了 update mbs_order_bom，上线时一定要补全库名/分片键，否则一执行就可能打到错误节点。
4. 回写后前端没刷新缓存。MySQL 价格变了，但 Redis 或 CDN 的报价页缓存还在，客户看到的是老价格。建议在轻易云里加一个「回写完成后触发缓存清理」的小动作，或者约定缓存 TTL。
5. 财务调价单的处理。金蝶里调价不一定会改原销售订单的 FTaxPrice，可能挂在调价单上。如果业务上要求「取最终结算价」，单看 FTaxPrice 不够，需要在源端做关联查询或在目标端追加逻辑。

适用场景与不适用场景

适用：销售订单从外部前台进入 MySQL、再落到金蝶云星空做财务结算，且最终含税单价需要在 MySQL 端被读取和展示的业务，例如零售、制造、电商。不适用：单价完全在金蝶云星空里维护、MySQL 端不需要价格的场景；以及单价在源系统（MySQL 端）才最终确定、不需要回写的场景，那种应该改成「MySQL → 金蝶」单向推送。