这个策略解决什么问题(场景与价值)
某零售企业在私域电商平台用聚水潭做店铺、订单与售后管理，在后端 ERP 用金蝶云·星空旗舰版做财务与库存核算。售后流程里，用户退回来的货需要先在聚水潭里做"实际收货"确认，再把这部分入库冲销回流到 ERP，否则库存和应收都会对不上账。这条策略就是把聚水潭的售后单（销售退仓-实际收货）按修改时间增量抓到轻易云，再落成金蝶云·星空的退货单。我们用轻易云数据集成平台（Qeasy）承接，整条链路跑在客户内网私有化环境里。
数据流向与字段映射（源 → 中间层 → 目标）
源端：聚水潭开放平台 /open/aftersale/received/query，POST 请求，日期类型 date_type=4（按修改时间），按页分页拉取（page_size=50）。
中间层：轻易云承担调度、抓取、清洗与映射。
目标端：金蝶云·星空 /kapi/v2/.../im_saloutbill/batchAddV2，生成销售退货单。
关键字段对照：
| 业务含义 | 聚水潭源字段 | 轻易云变量 | 金蝶云·星空目标字段 |
|---|---|---|---|
| 单据编号 | io_id | {{io_id}} | billno |
| 客户编码 | shop_id | {{shop_id}} | customer_number |
| 单据类型 | -- | -- | billtype_number（im_SalOutBill_STD_BT_S_R） |
| 库存组织 | -- | -- | org_number（100） |
| 结算币别 | -- | -- | settlecurrency_number（CNY） |
| 销售组织 | -- | -- | bizorg_number |
| 修改时间窗 | modified_begin / modified_end | {{LAST_SYNC_TIME}} / {{CURRENT_TIME}} | -- |
源端 idCheck=true，以 io_id 作为幂等键，避免重跑产生重复退货单。
在轻易云上如何配置
在轻易云集成平台里进入该策略的"集成流程"，按以下要点配置。
源组件 ：选择聚水潭 WebAPI 适配器，填入 /open/aftersale/received/query，method=POST，开启 autoFillResponse 自动解析返回；分页参数 page_index / page_size 显式声明；时间窗用平台内置变量 LAST_SYNC_TIME 与 CURRENT_TIME，避免硬编码时间。
中间层 ：用轻易云的字段映射做轻清洗。shop_id 在轻易云里维护一份"店铺编码 → 金蝶客户编码"的映射表，客户现场的常见做法是把编码映射集中管理到一个独立字典表，后续其他策略也直接引用，减少散落。io_id 原样带入目标 billno，并开启 idCheck，已写过的单据直接跳过。
目标组件 ：选择金蝶云·星空旗舰版 RESTful 适配器，调用 batchAddV2，billtype_number 写死为销售退货单类型编码 im_SalOutBill_STD_BT_S_R，org_number 与 settlecurrency_number 按客户账套填常量；表头单据字段写完后，表体行项目（FEntity）按源单明细循环展开。
运行模式 ：源 crontab 设置为 05,35 * * * *，目标落库 crontab 设置为 20,50 * * * *，源比目标提前 15 分钟，留出抓取、清洗、写入的窗口。
实施步骤（分阶段调度）
第一步：物料先行。该策略依赖物料和店铺映射先打通。先确认上游"聚水潭商品 ← 金蝶物料"策略已经稳定运行，再启动本策略。
第二步：店铺映射初始化。在轻易云里准备好聚水潭店铺 ID 与金蝶客户编码的对照表，首次全量灌入。
第三步：首次全量触发 。手动把 LAST_SYNC_TIME 调整到业务上线日，手动跑一次，把历史售后收货全量推到金蝶，确认表头和表体行数无误。
第四步：切换为增量 。全量验收后，恢复 LAST_SYNC_TIME 为系统变量，让源组件按修改时间窗每 30 分钟拉一次。客户现场常见做法是"增量与全量双轨"：全量手动兜底、增量自动跑。
第五步：表头表体分阶段上线。如果一次同步涉及表头+多行表体，先上线表头校验单据能否创建，再放开表体；这样做可以在出错时快速定位是头的问题还是行的问题。
第六步：上线后监控 。在轻易云的运行监控里盯着源组件的"本次拉取条数"、目标组件的"成功/失败数"，以及 idCheck 命中比例，连续观察 24 小时。
踩坑复盘
- date_type 没设对：date_type 默认值不是"修改时间"，拉回来的数据会少一大截，客户现场典型的错误是忘改成 4。稳妥的做法是显式写死，并在源组件说明里标注用途。
- 时间窗窄导致漏单 ：crontab 设得太稀疏，或者源目标时间窗没留 buffer，会漏掉跨窗口的售后单。客户现场常见应对是把源
crontab与目标crontab错开 15 分钟。 - shop_id 不是金蝶客户编码 ：聚水潭的 shop_id 是平台店铺 ID，不能直接塞进
customer_number，否则金蝶会报"客户不存在"。必须做一层映射，且映射表要有版本号管理。 - 幂等键没起作用 ：
idCheck看似打开了，但如果手动改了LAST_SYNC_TIME重新跑全量，仍然会重复推。稳妥做法是给目标billno加唯一约束，重复直接报错回写轻易云，由轻易云告警而不是静默成功。 - 表头过表体不过：很多翻车都出在表体 FEntity 上，比如计量单位不一致、仓库编码没维护、退货原因字段缺失。建议先单独跑一条带表体的样例，确认行项目能落，再放量。
适用场景与不适用场景
适用：私域电商售后退仓需要回流到 ERP 入账的零售企业，订单量级在每日数千单以内、需要按修改时间增量同步。不适用：实时性要求秒级同步的场景、需要双向冲突合并的场景、以及没有稳定店铺-客户编码映射的场景。