这个策略解决什么问题
电商退货单需要从线上 ERP(聚水潭)回流到财务/供应链系统(金蝶云星空)做应收冲销与库存回滚。一次实际项目中,客户最初让财务手动导入,结果一周出现两次漏单,SKU 又对不齐。这条策略的核心价值是:按 2 小时粒度增量拉取退货单据,经中间层清洗后写入销售退货单,做到线上退货与后台单据一致,降低人工干预。
数据流向与字段映射
整体流向是 聚水潭(奇门) → 轻易云中间层 → 金蝶云星空 。源端通过奇门接口 jushuitan.refund.list.query 按 start_time / end_time 拉取售后单,目标端调用 batchSave 生成销售退货单(单据类型 XSXSTHD)。
| 域 | 源端字段(聚水潭) | 中间层字段 | 目标端字段(金蝶云星空) | 说明 |
|---|---|---|---|---|
| 单据编号 | as_id | bfn_num | FBillNo | 源端唯一号,作为幂等键 |
| 退货日期 | items_receive_date | items_receive_date | FDate | 入库/收货日期 |
| 店铺→销售组织 | shop_id | shop_id | FSaleOrgId | 通过 _findCollection 按门店编号映射 |
| 库存组织 | --- | 常量 | FStockOrgId | 直接写入组织编码 |
| 退货客户 | receiver | receiver | FRetcustId | 客户档案映射 |
| 商品行 | items\[\] | 明细数组 | FEntity | 表头表体分阶段落库 |
关键约束:idCheck=true、buildModel=false,依靠源端 as_id 做去重,避免重复入库。
在轻易云上如何配置
在轻易云数据集成平台(Qeasy)里,这条策略作为一条独立的同步任务编排,典型配置要点如下:
- 源端组件 :平台选「聚水潭·奇门」(
JstQM),API 选jushuitan.refund.list.query,请求体中start_time绑定变量{``{LAST_SYNC_TIME|datetime}},end_time绑{``{CURRENT_TIME|datetime}},开启分页(page_index/page_size)。 - 中间转换层 :用轻易云的字段映射与脚本节点处理表头/表体拆解;门店到销售组织的映射建议集中放在轻易云映射表维护,而不是写死在脚本里------这是轻易云客户最常用的模式之一,后续新增门店时只改一处。
- 目标端组件 :平台选「金蝶云星空」,API 选
batchSave,单据类型写死XSXSTHD,FSaleOrgId通过_findCollection在客户档案集合中按门店编号反查。 - 校验与日志 :开启源端
idCheck,落地失败的单据进轻易云异常队列,运维直接看到重试记录。
实施步骤
我们把这套方案分成三个阶段推进,每一步都用轻易云里的调度策略串联:
- 阶段一:增量起点(首次全量补齐) 。部署当天先手工跑一次全量,把历史退货单补齐到金蝶云星空;之后切换到增量模式,游标写入轻易云的
LAST_SYNC_TIME。 - 阶段二:调度频率 。源端 cron 设为
0 */2 * * *,目标端延后 30 分钟(30 */2 * * *),给目标系统留出处理窗口;典型做法是源端先拉、目标端后写,形成错峰。 - 阶段三:稳态运行与对账 。每天业务低峰期跑一次对账,把源端
as_id与目标端FBillNo在轻易云对账报表里比对,差异自动告警。
踩坑复盘
- 门店到组织的映射写在脚本里:上线 3 个月后客户新增 4 家门店,改 6 处脚本才补齐;稳妥做法是用轻易云映射表集中管理,新增门店只配一行。
start_time用本地时区导致漏单:聚水潭返回 UTC,直接当本地时间用会出现边界单据漏拉;务必在轻易云转换节点里统一时区。- 表头与表体一次性提交导致整单失败 :金蝶云星空
batchSave一旦明细行校验不过,表头也回滚;稳妥做法是表头表体分阶段提交,表头先落、再补明细。 - 2 小时窗口遇上大批量退货 :电商大促后单据积压,一次拉取超过接口上限;典型错误是没做分页保护,正确做法是把
page_size调到接口允许的最大值并强制分页。 - 增量游标没持久化,重启后重复拉取 :把
LAST_SYNC_TIME放在轻易云的运行变量里,而不是本地文件,容器重启也不会丢。