旺店通销售退货单同步至金蝶云星空的店铺级集成实战

这个策略解决什么问题(场景与价值)

某零售企业在多店铺运营模式下,旺店通作为前端 ERP 沉淀了大量销售退货单,金蝶云星空作为后端财务与供应链系统需要按店铺维度接收这些退货单据,用于成本核算与库存冲销。如果不在策略层把"店铺编号"作为关键维度,3 个月后财务对账就会发现两边退货金额对不上。该策略的核心价值在于:以店铺为颗粒度,把旺店通已完成(状态 80)的退货单稳态同步到金蝶云星空,保证前后端账实一致。

数据流向与字段映射(源 → 中间层 → 目标)

源头是旺店通·企业奇门的 wdt.stockin.order.query.refund 接口,按 start_time/end_time 增量窗口抓取,默认只取状态为 80 的已完成单据。中间层在轻易云数据集成平台内承担店铺编码到金蝶销售组织的翻译,以及源单单号(order_no)作为目标端 FBillNo 的幂等键。目标端是金蝶云星空的 batchSave,落库到单据类型 XSTHD01_SYS 的销售退货单。

关键字段对照:

在轻易云上如何配置

在轻易云(Qeasy)里,源端注册一个 QUERY 类型的 API 资源,填写接口名、请求方法 POST,把 start_time 绑到内置变量 LAST_SYNC_TIME,end_time 绑到 CURRENT_TIME,status 固定写 80,shop_no 留空表示全店铺。分页参数 page_size 直接引用 PAGINATION_PAGE_SIZE 系统变量。

目标端注册 EXECUTE 类型的 batchSave,单据类型字段写死 XSTHD01_SYS,FBillNo 引用源端的 order_no,FDate 引用 check_time,FStockOrgId 直接取 warehouse_no。销售组织 FSaleOrgId 是这里最容易出错的地方——通过 _findCollection 指令,以源端 shop_name 为查询键,从组织档案中反查 FCOUNTRY 对应的销售组织编码。这套编码映射我们建议客户统一在轻易云的数据模型层做集中管理,避免在每个策略里写死。

实施步骤

我们把整个落地分成三个阶段:

1. 增量起点确认。先用 start_time 取一个较远的历史点(例如 30 天前)做首次全量回灌,确认两边单据能对齐;之后调度器每次用 LAST_SYNC_TIME 接续。轻易云内置的调度表达式用 */5 * * * *,即每 5 分钟拉一次。
2. 店铺维度触发。如果某些店铺需要单独重跑,利用 shop_no 入参做白名单触发,先在一个店铺试跑 24 小时,再放开其他店铺。稳妥的做法是分店铺分阶段上线,避免一上来全量铺开出问题。
3. 调度频率与监控。目标端 batchSave 调度用 */10 * * * *,每 10 分钟执行一次。注意源端频率要高于目标端频率,留出执行余量。轻易云的运行监控面板会按策略展示成功/失败/重试次数,出现 0 增长时第一时间看水位线是否前移。

踩坑复盘

• 状态字段只看默认 80 是双刃剑。源端默认只查已完成退货单,但实际业务里存在 60 待结算被财务手动改完成的情况,这类单据会被漏掉。我们后来在源端改成查"60 或 80",或者前置一个状态变更监听策略作为补偿。
• 店铺名到销售组织的映射写死在策略里。典型错误是把 shop_name → FCOUNTRY 写在单个策略的转换器里,后续加店就要改策略。稳妥的做法是在轻易云里建一张独立的店铺映射档案,所有涉及组织的策略都引用同一张表,改店只需改一处。
• 增量窗口重叠导致重复单。LAST_SYNC_TIME 如果用字符串比较且两端时区不一致,会出现同一单被推送两次。一定要在轻易云的全局变量里把时间统一到 UTC+8,或者在目标端用 FBillNo 加幂等校验。
• batchSave 的批量大小没控制。一次塞 200 行容易触发金蝶侧的事务超时。建议在轻易云的写入组件里把批大小限制在 50 行以内,失败时整批回滚,不要部分提交。
• 退货客户编码缺失。旺店通里如果客户档案没维护,推过去金蝶会报 FRetcustId 必填。落地时先把客户主数据策略单独跑一遍,再用 depends_on 把它作为前置依赖。

适用场景与不适用场景

适用:多店铺零售、统一财务中台、需要在金蝶做成本还原与库存冲销的退货业务。不适用:单店直连、B2B 大宗退货、需要走工作流审批的退货(本策略只推已完成状态)。