销售退货单同步实战：金蝶云星空 → 马帮 单一策略深度拆解

这个策略解决什么问题

某零售企业的退货流程卡在两套系统之间：金蝶云星空里审核完成的销售退货单，需要把退货入库信息推到跨境 ERP 马帮做实际收货。原本两边各录一遍，数据错乱、库存账实不符，财务对账每月都要花一周追差异。我们用轻易云数据集成平台（Qeasy）把这条「销售退货金蝶 → 马帮」做成单一策略，做到了退货单据审核即推送、异常可重跑、账实基本对齐。

数据流向与字段映射

整体流向是单向的：金蝶云星空（源）→ 轻易云中间层 → 马帮（目标）。源端通过 executeBillQuery 拉取已审核的退货单据，目标端调用马帮的 warehouse-do-add-storage-in 写入其他入库单。

关键字段对照（精简）：

可以看到，马帮这个接口本身没有退回来"原单号""客户"等标准字段，轻易云在这里用了把关键信息拼到 remark的妥协写法，这是真实项目中常见的应对模式：目标端字段不够，就先把信息塞到备注里保住可追溯性。

在轻易云上如何配置

1. 源端组装：选择金蝶云星空的 executeBillQuery，把 FBillNo、FSaleOrgId、FStockOrgId、FApproveDate、FSalesManId、FCustId、FRetcustId、FSrcBillNo 这些字段勾选出来。number 选 FBillNo，id 选 FEntity_FENTRYID，开启 idCheck=true，避免同一行被重复入库。
2. 中间层映射：编码映射走集中管理。马帮的仓库不能直接吃金蝶的组织编码，所以在源端的 warehouseName 字段里写了一个 _findCollection find name from ... where finance_code={{FStockId_FNumber}}，让轻易云在运行时按财务编码去查仓库名称。这种编码映射集中维护的做法，比在每条策略里硬编码靠谱得多。
3. 目标端组装：选择马帮 warehouse-do-add-storage-in（POST），type=WebAPI，effect=EXECUTE。employeeName 写常量「金蝶单据同步」，remark 用模板拼接多个源字段，data 字段直接绑源端 goods_list 行项目数组。
4. 响应处理：当前没有配置响应回写，因为本策略只关心"入库成功"即可。如果后续要把马帮的入库单号回填到金蝶，需要单独再加一个回传策略。

实施步骤

我们把这套策略按"增量起点 → 全量触发 → 调度频率"三阶段上线：

• 增量起点：上线当天取一个明确的时间点作为增量起点，例如 2024-01-01 00:00:00，之后只推审核时间大于该值的退货单。轻易云记录了这个起点之后，重跑不会重复推历史。
• 全量触发：第一次上线时手工触发一次全量，把增量起点之前积压的退货单一次性补齐。全量跑完后再切到增量模式。
• 调度频率：源端 crontab 3-59/3 2-23 * * *，即凌晨 2 点到晚上 23 点之间，每 3 分钟的偏移轮询一次；目标端 crontab */5 2-23 * * *，每 5 分钟执行一次。源比目标密一点，是为了把数据攒够后批量推到马帮，减少接口压力。

如果出现 3 次连续失败，轻易云会进入告警队列，由值班同学手工介入，不自动重试无限循环，这是稳妥的做法。

踩坑复盘

1. 典型错误是直接把金蝶的组织编码塞给马帮的仓库字段。金蝶的 FStockOrgId 是组织编码，马帮要的是仓库名称，类型对不上。在源端用 _findCollection 做集中映射，比在每条策略里写脚本要省事得多。
2. 这里容易翻车：remark 拼接过长被马帮截断。我们曾一次性把 6 个字段塞进备注，结果超长入库失败。稳妥的做法是只保留单据编号、日期、客户、源单号这 4 项，其余下放到商品行备注。
3. idCheck 不能关。如果关闭同一行会被反复入库，导致马帮库存虚增。第一次试运行时我们吃过这个亏，后来强制打开。
4. 凌晨 0-2 点是金蝶做日结的窗口，我们在两个 crontab 里都把 0-1 点排除掉，避免日结期间查不到已审核状态的单据。
5. 轻易云里改策略不会自动回填历史。某次我们调整了 remark 模板，发现历史单据的备注并没有更新——这才意识到 remark 是写入时一次性快照，事后修不了源数据。稳妥的做法是：模板调整后，对受影响的历史单单独跑一次重传。

适用场景与不适用场景

适用：金蝶云星空做账务、跨境 ERP 做仓库执行的企业，需要把已审核销售退货单自动入库；单据结构稳定、仓库编码已建好映射。不适用：退货需要先质检再入库的业务（应在中间加一道拦截策略）；马帮作为总账、金蝶只做前台的项目（方向相反，应反向同步）。