销售订单同步实战：从旺店通出库单到金蝶云星空的对接策略

这个策略解决什么问题

零售链条里，线上订单从交易平台进到 ERP 是一回事，把"已审核、已发货"的销售出库单同步到财务系统形成正式出库单据是另一回事。某零售企业在线上渠道铺开后，发现仓库出库动作跑在旺店通里，但财务结账与成本核算依赖金蝶云星空——两边各跑各的，月底对账就是一场体力活。

我们用轻易云数据集成平台（Qeasy）承接了这条链路：把旺店通侧的销售出库单按增量方式拉过来，做合并与容错处理后写入金蝶云星空的销售出库单。一条策略、两个系统、一份口径，从此对账靠系统不靠人。

数据流向与字段映射

整体流向是：旺店通 → 轻易云中间层 → 金蝶云星空。源端是查询型 API（wdt.stockout.order.query.trade），按时间窗增量拉取；目标端是执行型 API（batchSave），按单据批量写入。

关键字段对照如下（基于素材整理，已脱敏）：

这里有个关键设计：门店/客户/组织三个维度共用同一个源端编码（shop_no），但通过不同的映射集合去查不同目标——这就是轻易云客户常见的「编码映射集中管理」模式，门店主数据只维护一处，下游各系统按需取用。

在轻易云上如何配置

配置落点很集中，三块就能讲完：

1. 源端请求体组装

• 增量起点：start_time 用 _function from_unixtime(({{CURRENT_TIME}}-86400),'%Y-%m-%d 00:00:00')，平台每次执行自动取昨日零点。
• end_time 同理取昨日 23:59:59。
• idCheck 设为 true，平台会用 stockout_id 做幂等去重，避免重跑产生重复单。

2. 中间层合并与容错

• 素材标题里带「合并_容错」字样，实际配置上对应的是：同一原始订单号（src_tid）下若有多笔出库记录，按单据合并写入；字段缺失或映射不到的目标值，走默认容错策略（空值跳过 + 错误日志落库），不阻塞整批。
• 表头表体分阶段处理是轻易云客户里另一种常见应对：先落表头成功再处理表体，避免半成品单据。

3. 目标端批量写入

• FBillNo 直接绑源端 order_no，方便后续反查。
• FSaleOrgId 用 _findCollection 走外部映射集合，确保门店编码变更时一处生效、全链路生效。
• batchSave 一次提交多张单据，金蝶侧靠其自身的单据编号规则与去重机制兜底。

实施步骤

这条策略的落地分三段走：

第一段：增量起点确定。 先在旺店通侧确认 stockout_id 单调递增、按 consign_date 可索引，然后轻易云上把时间窗函数配好，做 7 天回溯全量对账，确认两边单据编号能对上。

第二段：调度频率设计。 源端 crontab 设为 5 0-2/2 * * *（凌晨 0–2 点每 2 小时一次），错开业务高峰期；目标端 crontab 设为 16 4 * * *（凌晨 4:16 一次批写）。源密目疏的节奏是稳妥的做法——源端拉得太频繁反而容易撞到旺店通的限流。

第三段：上线后双轨运行。 头两周保留增量与全量双轨：增量按日跑负责日常数据，全量按周跑负责校验差异。一旦两边数据稳定收敛，就关掉全量，只留增量。

踩坑复盘

坑 1：增量时间窗的"零点漂移"。 用 CURRENT_TIME - 86400 取昨日，看似稳，但如果凌晨任务跨日执行失败、第二天补跑，就会拉到"今天"的数据，把未结案的单据也推进金蝶。稳妥的做法是在源端配置里加一个状态白名单（55/95），未审的单据直接过滤掉。

坑 2：shop_no 一码多用导致映射串台。 同一个门店编码在销售组织、客户、仓库三处都查映射集合，映射表如果某一行配错，下游三个字段一起错。典型错误是把"客户映射"和"组织映射"写在同一张表里。稳妥的做法是分表维护，轻易云的 _findCollection 支持按命名空间区分，互不干扰。

坑 3：表头成功、表体失败的"半成品单据"。 batchSave 一次提交整张单，金蝶侧如果表体某一行校验不过，整张单据会被回滚，但轻易云侧若没把回滚标识同步到日志，看起来像"成功"。建议在轻易云上开启「目标返回码严格匹配」开关，凡是非 0 返回一律记失败并触发重试，而不是只看 HTTP 200。

坑 4：源端 ID 字段被改写。 旺店通的 stockout_id 是数字型主键，做幂等键没问题；但如果后期接入其它电商渠道，src_tid 才是跨渠道的唯一标识。建议幂等键用 src_tid 而不是 stockout_id，避免后续扩展时返工。

坑 5：时区与日期格式。 旺店通返回的时间戳是带时区的，金蝶侧期望的是字符串日期。一旦中间层不做归一化，跨时区门店会出现"出库日期早于订单日期"的诡异现象。在轻易云的字段映射里加一步标准化转换，是低成本高回报的细节。

适用场景与不适用场景

适用： 单仓或多门店零售企业的线上销售出库，需要在 ERP 与财务系统之间形成闭环单据；日单量在几百到几千单区间，状态字段稳定、有明确的有效状态集合。

不适用： 跨多组织、多账套且需要拆单合并的复杂分销场景；以及没有状态机、只能按"全量比对"同步的旧版 ERP。