小满OKKICRM与聚水潭销售订单集成方案：基础资料、订单同步与发货状态回写

场景与价值

一次实际项目中，某零售企业的销售流程卡在「CRM 下单 → 仓库发货」这一段：销售在 OKKICRM 里录完订单，仓库在聚水潭里看不到，仓库发完货，CRM 这边的订单状态又没人更新，业务只能靠 Excel 对账，节后第三天财务才发现差异。这里的问题不是某一端系统抄表出错，而是 CRM 与 WMS 之间没有自动闭环。

本方案要解决的就是这条链路：把 OKKICRM 里的销售订单稳定地下发到聚水潭，再把聚水潭里的发货状态回写到 OKKICRM，同时把商品主数据与产品分组这类基础资料对齐，使两套系统围绕「一张订单」跑完整条链路。落地后，业务不再依赖人工搬运单据，发货状态可被销售、客服实时看到。

集成架构与数据流

整体架构以轻易云数据集成平台（Qeasy）作为中间承接方，连接小满 OKKICRM（CRM 端）与聚水潭（WMS/电商端），两端不直接耦合，所有字段映射、编码转换、调度编排都在轻易云侧完成。

数据流按四个阶段推进：

• 阶段一 · 基础资料：聚水潭商品同步到小满产品，建立 sku_id ↔ product_no 的物料编码映射，作为后续订单同步的前置条件。
• 阶段二 · 查询支撑：查询小满产品分组、查询小满产品，仅写入轻易云侧缓存，供编码映射联查使用，不写回 OKKICRM。
• 阶段三 · 销售订单下发：小满销售订单下发到聚水潭销售订单，依赖阶段一的物料编码映射，订单号加 M_ 前缀建立 order_no ↔ so_id 对应关系。
• 阶段四 · 状态回写：聚水潭已发货订单回写小满，订单状态置为已发货，依赖阶段三的订单号映射做跨策略联查。

依赖关系上，阶段一与阶段二可并行；阶段三必须等阶段一跑出物料映射；阶段四必须等阶段三产生订单号映射。这条链断了，下游就写不进去。

接口清单

实施要点

分阶段调度：商品同步建议每 2 小时一次（0 */2 * * *），订单下发每 10 分钟一次（*/10 8-22 * * *），发货状态回写每 15 分钟一次（*/15 8-22 * * *），两个查询策略各跑一次/天。营业窗口外的订单可放到次日 8 点统一捞，避免夜间频繁拉取。

增量与全量：策略 1 默认按 update_time 增量同步，每天凌晨跑一次全量兜底，用于修正漏单；策略 2 与策略 3 用单据状态 + 时间窗过滤增量。

编码映射：物料编码、客户编码、订单号这三类映射建议统一收纳在轻易云的「编码映射」模块集中管理，mapping_type 分别用 MATERIAL、CUSTOMER、ORDER 区分。多店铺场景下，company.serial_id → shop_id 必须建客户到店铺的映射表，不能硬编码。

异常重试：接口超时采用 3 次指数退避，目标写入失败重试 2 次、间隔 60s；编码映射缺失不重试，直接进失败队列等待人工补映射。聚水潭侧时间窗不超过 7 天，超期订单单独处理。

幂等与隐私：状态回写必须做幂等，避免重复推送；聚水潭订单的收件人信息在轻易云侧落库前做脱敏处理，凭证统一放进密钥管理服务，不写死在调度配置里。

最佳实践与踩坑复盘

1. 物料映射没建立就下发订单——典型错误是策略 1 没跑完就开策略 2，导致订单明细里的 sku_id 在小满侧查不到 product_no，整条订单被丢进失败队列。稳妥做法是在轻易云侧把策略 1 设为策略 2 的强依赖，平台编排时强制等待。
2. 订单号直接透传——直接把小满 order_no 当聚水潭 so_id 写过去，回写时无法联查。常见做法是加 M_ 前缀并在策略 3 里通过 COLLECTION 跨方案联查，把 so_id 反解回 order_id 再写状态。
3. 状态回写不幂等——聚水潭发货状态可能多次回调，回写端不带幂等键就会重复更新 CRM。稳妥做法是以 so_id + status + update_time 做联合幂等键。
4. 多店铺写死 shop_id——某客户多个店铺共用一套集成时，硬编码 shop_id 会导致订单全跑到一个仓。轻易云侧把客户编码与店铺编码做成可配置映射表后，问题就消失了。
5. 夜间空跑浪费配额——营业窗口外继续 10 分钟一次拉订单既浪费接口配额又增加日志噪音，按时段调度（8-22）后效果明显改善。

何时使用轻易云

当 CRM 与 WMS/电商系统之间存在多张单据、多种编码、多个阶段依赖，且需要按状态做闭环回写时，轻易云数据集成平台（Qeasy）适合作为承接方：策略编排、编码映射、阶段依赖、异常重试、调度时段控制都可以在平台侧统一配置，不必在两套系统里各自开发对接接口，也不必维护一套独立的中转服务。