反写小满同步状态：一条把同步结果闭环回 CRM 的策略实战

这个策略解决什么问题

在一次实际客户现场，订单从 CRM 推到订单系统之后，销售人员每天打开 CRM 看到的还是「未同步」，需要切到另一个后台去比对，效率很低。我们要做的事很朴素：把订单系统侧已经确认同步成功的订单，把「已同步」这个状态回写到 CRM 上对应的销售订单里，让业务员在 CRM 内一眼看到闭环结果。

数据流向与字段映射

这条策略的数据流是「订单系统 → 轻易云中间层 → CRM」，本质上是一个状态反写动作，不是主数据下发。

源端（订单系统）通过 WebAPI sales.RawTrade.searchSelfOrder 拉取「自营订单」列表，分页参数和业务参数走 params 对象体，返回里重点用到的字段是 tid（订单号）和 rec_id（记录主键），二者构成幂等键。

目标端（CRM）的执行接口是 /v1/invoices/order/push，请求体里有两条关键字段：order_id 和一个代表「ERP 同步状态」的自定义字段。order_id 不是直接传源系统的 tid，而是通过 _findCollection 在上一条「销售订单同步」策略产出的中间表里，按 tid 反查到 CRM 侧的订单主键；状态字段直接写常量字符串「已同步」。

在轻易云上如何配置

我们用轻易云数据集成平台（Qeasy）来承接这种轻量闭环，配置上有几个要点值得展开。

第一，把这条策略挂在「上一条主同步策略」的产出下游，明确 depends_on 关系，避免出现主订单还没落库就先反写状态的竞态。

第二，源端 metadata.number 选 tid，id 选 rec_id，开启 idCheck 防止同一订单被反复写状态。autoFillResponse 保持开启，让轻易云自动把分页和参数拼好。

第三，目标端的 order_id 字段值不写死，而是用 _findCollection find order_id from <上一策略id> where order_no={{tid}} 的写法，把订单号到 CRM 主键的映射集中管理。这是轻易云客户常用的「编码映射集中管理」模式，避免在策略里硬编码 ID。

第四，状态字段值直接写常量「已同步」。如果后续要区分「同步成功 / 部分成功 / 失败」，建议把这一列升级成表达式而不是硬编码字符串。

第五，调度时间上，源端拉取配 1-59/10 6-23 * * *（每 10 分钟一次的非整点偏移），目标端回写配 8-59/10 6-23 * * *（错开几分钟），用「错峰 + 偏移」避免两端在同一秒同时打接口。

实施步骤

第一步，先把上一条「销售订单同步」策略跑稳，确保中间表里有 order_no → id 的映射数据。第二步，在轻易云里新建策略，源端选订单系统的 searchSelfOrder，目标端选 CRM 的 /v1/invoices/order/push，明确标 strategy_type=EXECUTE，这不是 SYNC，是单边执行。第三步，先做一次全量回写（手动触发），把历史已同步订单的状态补齐，建立基线。第四步，把全量结果对照 CRM 抽查 20-30 单，确认无误后切换到增量。第五步，增量起点选「源端返回数据的时间戳 > 上次成功时间」，调度频率设 10 分钟一次，错峰偏移。第六步，观察一周日志，重点看 idCheck 命中的条数和反写失败的明细。

踩坑复盘

第一，order_id 直接传源系统的 tid 是典型错误。CRM 的订单主键和订单系统的订单号是两套体系，必须通过中间映射表反查，否则会出现「CRM 找不到这条订单」或者写错对象的情况。

第二，没设 depends_on 直接跑。后果是主同步还没落库，反写策略已经开始按 tid 找 ID，找不到就空写，CRM 那边状态没变，业务员以为同步失败，实际上主单据还在路上。稳妥的做法是显式声明上下游依赖。

第三，状态字段写死成「已同步」。上线第二个月，业务部门要求区分「部分发货」「已发货完成」两种状态，代码改了一整天。如果一开始就用表达式或映射表配置，改一处即可。

第四，源端和目标端用同一个整点调度（比如都是 */10 * * * *），瞬时并发上来后 CRM 限流，批量 429。这里我们采用「增量与全量双轨 + 错峰偏移」，源端 1-59/10、目标端 8-59/10，把同一时刻的并发摊开。

第五，幂等键选错。一开始我们用 rec_id 当幂等键，结果反写失败的订单重试时，rec_id 没变但状态确实没写进去，重试逻辑失效。改成 (tid + 状态字段) 组合幂等后，重试才稳。

适用场景与不适用场景

适用：CRM 与订单/ERP 系统集成，需要在 CRM 侧展示同步结果或触发后续业务流程（如下推发货单、关单）。不适用：需要回写的内容超过一个状态字段（例如要回写物流单号、回写明细行），这种场景应该走完整 SYNC 策略，而不是单条 EXECUTE 状态反写。