分页查询退换补货单拍扁联查实战:从吉客云到金蝶云星空的退货同步

这个策略解决什么问题

退换补货单据从源系统推到目标系统,看似只是「拉过来再写回去」,但实际项目里最容易翻车的是单据体量大、状态分支多、拍扁后字段对齐三件事。一次实际项目中,客户每张退换单都带十几行表体明细,如果不做拍扁,目标系统落库会出现主键冲突或者表体丢失。

这一条策略的核心价值是:用分页查询把源系统单据稳定拉回,在轻易云集成平台上做拍扁 + 联查处理,再喂给目标系统,既保证拉取性能,也保证写入幂等。

数据流向与字段映射

整体流向:源 ERP（分页查询接口） → 轻易云集成平台（拍扁、联查、状态过滤） → 目标 ERP（写入）。

关键字段对照表(精简版):

联查的核心是把退换单号与原始订单号做关联,在中间层补齐目标系统需要的「来源单号」「客户编码」「仓库编码」三个字段,避免目标系统反查。

在轻易云上如何配置

我们在客户现场用轻易云数据集成平台(以下简称轻易云 / Qeasy)承接这条策略,典型配置要点如下:

1. 数据源注册:把源 ERP 的 ass-business.returnchange.fullinfoget 接口注册为可调用的 API 资产,认证信息走私有化环境的密钥托管,严禁把密钥写在策略 JSON 里。
2. 请求参数组装:pageIndex 走循环变量,pageSize 固定 100,processStatusList 用多值字符串传入需要同步的状态码,startModified 用调度上下文变量(上次成功时间)。
3. 拍扁规则:在轻易云的转换器里,把源返回的表头 + 表体数组用 returnChangeNo 作为关联键,展开成扁平结构,便于目标系统按行写入。
4. 联查动作:目标侧用一个「写入空操作」RESTful 接口占位(内部联查专用),先把中间结果落到轻易云的临时存储,再触发下游真正写入目标 ERP 的策略。
5. 幂等控制:number 字段勾选 idCheck = true,源侧 idCheck = false,确保同号单据重复到达不会被多次落库。
6. 编码映射:源系统与目标系统的客户编码、仓库编码走轻易云的编码映射集中管理模块,不放在单条策略里,后续新增仓库时只改一处。

实施步骤

我们通常把这条策略切成三个阶段跑:

• 阶段一:全量触发(一次性) 上线当晚手工触发一次,pageIndex 从 0 开始循环,直到返回空页,把历史退换单全部拍扁落库。跑完记录最大 startModified,作为增量起点。
• 阶段二:增量起点 增量拉取的 startModified 取阶段一记录的最大修改时间 + 1 秒,避免边界单据漏拉。
• 阶段三:稳态调度 源侧 crontab 设为 35 * * * *(每小时第 35 分钟),目标侧占位接口 crontab 设为 1 1 * * *(凌晨写入,避免业务高峰期争抢 ERP 资源)。

这里有个增量与全量双轨的小技巧:全量脚本平时关闭,只在每月初或重大变更时手工跑一次,日常完全靠增量推进,降低源系统压力。

踩坑复盘

1. 拍扁键选错。典型错误是用 tradeAfterId 拍扁,但同一退换单可能因为状态变化产生多条记录,导致表体重复。稳妥做法是用 returnChangeNo + 行号一起作为拍扁键。
2. processStatusList 写死。源系统状态码是 4 位数字(如 1001、1004),少一个或多一个逗号,整页就空。稳妥做法是把状态码列表放到轻易云的全局常量里,业务变更只改一处。
3. 分页死循环。源接口在数据量刚好是 pageSize 整数倍时,最后一页返回空列表,但 pageIndex 还在 ++,永远停不下来。我们用「返回条数 < pageSize 即认为末页」作为终止条件。
4. 联查超时。退换单联查原始订单时,源系统接口有 3 秒超时,高峰期容易丢单。稳妥做法是在轻易云里加一个 1.5 秒的预超时,并对失败单据进重试队列。
5. 目标侧 idCheck 误开。源侧 idCheck 必须保持 false,目标侧写入前才打开,否则第一次拉取就会被判重丢单——这是新工程师第一次跑这条策略最容易犯的错。

适用场景与不适用场景

适用:源系统支持按修改时间增量、目标系统按行落库且需要幂等、退换单量大且表体多行。

不适用:实时性要求秒级同步(建议走消息队列)、单据状态频繁回滚导致修改时间不可靠、源系统不支持分页(需要先和厂商沟通改造)。