这个策略解决什么问题
某零售企业的售后链路里，聚水潭负责电商前端，金蝶云·星空旗舰版负责后端财务与库存。当抖音线下订单发生退货，仓库实际收货后，售后单要在两个系统里各登记一次------人工二次录入既慢又错。我们用轻易云数据集成平台承接，把聚水潭"销售退仓-实际收货"单据按时间窗拉取，直接生成金蝶侧的退货单，让库存与应收冲减有据可依。
数据流向与字段映射
整体流向：聚水潭（售后单查询）→ 轻易云中间层 → 金蝶云·星空旗舰版（退货单写入）。
源端接口为 /open/aftersale/received/query，POST 方式，分页拉取。关键入参：
modified_begin/modified_end：增量时间窗，由轻易云调度自动填充上次同步时间到当前时间。date_type：本场景固定传4（按修改时间）。page_index/page_size：分页参数，轻易云内一般给1和50，循环翻页。shop_id：店铺编号，作为过滤条件传入。
源端返回里，io_id 既作为业务单号又作为幂等键，配合 idCheck=true 实现去重。
目标端接口为 /kapi/v2/.../im_saloutbill/batchAddV2，关键写入字段：
| 目标字段 | 含义 | 来源 / 处理方式 |
|---|---|---|
| org_number | 库存组织编码 | 常量 100 |
| customer_number | 客户编码 | {``{shop_id}} 映射，需在轻易云编码映射表里维护店铺→客户对照 |
| billtype_number | 单据类型编码 | 常量 im_SalOutBill_STD_BT_S_R（退货出库单） |
| settlecurrency_number | 结算币别 | 常量 CNY |
| billno | 单号 | {``{io_id}}，与源端幂等键一致 |
| bizorg_number | 销售组织编码 | 常量配置 |
中间层承担三件事：分页聚合、时间窗推进、编码映射。
在轻易云上如何配置
第一步建源端数据源，选聚水潭适配器，填入应用密钥（不在文档里展开）；第二步建目标数据源，选金蝶云·星空旗舰版适配器，填好账套信息（脱敏略）。第三步建集成策略，把上面两个 JSON 元数据粘进去------轻易云会自动渲染请求/响应字段面板。
重点配置三处：
- 增量水位 ：源端
modified_begin用变量{``{LAST_SYNC_TIME|datetime}}，modified_end用{``{CURRENT_TIME|datetime}}，轻易云每次调度自动推进。 - 幂等控制 ：目标端开启
idCheck，主键取源端io_id，重复请求直接跳过。 - 编码映射：客户编码、组织编码、单据类型编码集中放在轻易云的"映射表"里维护，不要散落在脚本里------这是轻易云客户最常见的做法之一，后期加店铺或改组织只改一处。
实施步骤
我们在客户现场一般分三步走：
- 全量初始化 ：把
modified_begin临时改成固定历史起点，跑一次全量，确认金蝶侧退货单能正确生成、库存冲减无误。 - 切换增量：全量通过后，恢复时间窗变量，跑 3--5 个调度周期（每 30 分钟一次），核对单据号是否连续、有无重复或漏单。
- 常态调度 ：源端策略 cron 设为
05,35 * * * *，目标端策略设为20,50 * * * *，错峰执行，给目标端留出写入与回写窗口。
回写检查建议每天做一次：抽样 5 单，对比两边金额、客户、仓库是否一致。
踩坑复盘
- 时间窗未推进 ：早期版本有人把
modified_begin写死成常量，结果每次调度都拉同一批数据。稳妥的做法是确认轻易云调度日志里LAST_SYNC_TIME是否在递增。 io_id重复入库 ：聚水潭售后单存在改单重推场景，必须依赖idCheck+ 幂等键，不能只看单据状态。- 客户编码找不到：店铺上线后忘了在轻易云映射表里补客户编码，目标端会整批失败。映射集中管理就是为这种场景准备的。
- 库存组织与销售组织混用 ：金蝶退货出库单里
org_number（库存组织）与bizorg_number（销售组织）是两个字段，源端不直接给，配置时务必确认两个常量分别对应什么。 - 目标端限流：金蝶 batchAddV2 单次提交过大容易触发限流，建议轻易云端把单据按批次切分，每批 50 单以内。