销售出库红字对接金蝶云销售退：单一策略同步方案实战

这个策略解决什么问题

某零售企业的上游业务系统每天会产生大量销售出库单，其中既有正常的蓝字出库，也有因为退货、拒收、错发产生的红字出库。红字单据如果只是简单当作出库再传一次，下游 ERP 的库存方向、应收方向、税控逻辑都会出错。我们这次要做的，就是把上游的红字出库单，专门识别出来，转写成下游 ERP 的「销售退货单」，做到账实同向、可追溯。

数据流向与字段映射

数据流向是单向的：上游 → 中间层（轻易云） → 下游 ERP。上游通过 WebAPI 增量拉取红字出库单，轻易云负责字段清洗、编码映射和组织替换，最后通过下游的 batchSave 写入销售退货单。

关键字段对照表（已脱敏）：

在轻易云上如何配置

我们用轻易云（Qeasy）来承接这条链路，配置分三块：

1. 源接口配置：接口选 erp.storage.goodsdocout.v2，请求方式 POST，增量区间用 startDate / endDate 绑定系统变量 LAST_SYNC_TIME 和 CURRENT_TIME，分页用 pageIndex / pageSize 控制，单据号做幂等键，开启 idCheck。
2. 目标接口配置：接口选 batchSave，按下游 ERP 的销售退货单模型构造请求体。单据类型、销售组织、退货客户三个必填字段都从中间映射或上游字段取。
3. 转换与映射脚本：客户编码、销售组织这种「上游编码 → 下游编码」的对应关系，集中放在映射表里维护，轻易云客户常见的应对模式就是「编码映射集中管理」，避免在每条策略里重复定义。

实施步骤

我们建议分三阶段推进：

• 增量起点：先用「红字标记 + 单据状态」作为筛选条件，在轻易云里跑一次手动触发，验证全链路通畅，确认没有红蓝混淆。
• 全量触发：上线当天把时间窗口拉大，做一次历史红字回溯，回溯完成后立刻切回增量模式。
• 调度频率：源端我们用了 1 6-23/2 * * * 的高频轮询（早 6 点到晚 11 点每 2 小时一次），目标端写入每天凌晨一次 20 3 * * *，增量与全量双轨：高频轮询抓增量，低频批写避免目标系统夜间锁表。

踩坑复盘

1. 红蓝字混传：上游接口一次返回里既有红字也有蓝字，这里容易翻车。稳妥的做法是在源端的过滤条件里就明确「只取红字」，不要等到下游再去判断。
2. 客户编码找不到：下游的 FRetcustId 必须是下游 ERP 自己的客户编码，直接传上游编码一定报错。我们在轻易云里用 _mongoQuery 做了集中映射，客户主数据同步策略先于本策略跑通。
3. 销售组织多对一：同一个上游客户可能对应多个下游销售组织，单纯按客户查不行。我们改成「客户编码 + 库存组织」联合反查，命中唯一性。
4. 退货日期早于出库日期：上游有时把红字单据的 inOutDate 写成审核日而不是原始出库日，导致下游账期错乱。建议在转换里加一个日期校验，超过原单 30 天就告警。
5. 幂等键冲突：同一张红字单据如果上游重推，下游会报单据编号重复。开启 idCheck 之后仍要在转换层做一次显式去重。

适用场景与不适用场景

适用：上游有清晰的红蓝字区分机制、下游 ERP 必须以「销售退货」单据承载负向业务、且对账时效要求在小时级的零售、电商、批发场景。

不适用：上游不区分红蓝字、或者下游没有独立的销售退货单据类型（只能用红字出库替代）的场景；以及单据量极大、对实时性要求秒级的业务，更适合走消息中间件而非定时轮询。