聚水潭销售出库单到金蝶云星空：单策略同步实战教程

这个策略解决什么问题

某连锁零售企业在聚水潭里收单出库，却要在金蝶云星空里做财务核算和成本结转。两边系统各自一套单据，单据状态、单号、组织、客户档案全都对不齐：店长在聚水潭点了「已出库」，财务却看不到这张单，等手工补录完账期都过了。销售出库同步这条策略只解决一件事——把聚水潭里状态为「已出库」的销售出库单，按增量节奏拉到金蝶云星空，生成标准销售出库单，让库存与账务能在一个口径上对话。

数据流向与字段映射

整体流向是 聚水潭 → 轻易云集成平台（Qeasy）→ 金蝶云星空，中间层负责取数、清洗、编码映射与落地。

几个关键点要敲黑板：聚水潭接口要求 start_time 与 end_time 间隔不能超过 7 天，源端请求里就是这两个时间槽驱动的增量窗口；金蝶端的 FBillTypeID、FSaleOrgId 在源系统里根本没有，必须在轻易云里以「常量」方式固定写进策略。

在轻易云上如何配置

我们用轻易云数据集成平台（Qeasy）承接这一条策略时，通常按下面四块来落地。

源端数据源：选择聚水潭·奇门，对接 jushuitan.saleout.list.query 接口。分页参数 page_index、page_size 都需要打开，上限按平台 50 行/页处理；增量字段绑定 start_time / end_time，分别用 {{LAST_SYNC_TIME|datetime}} 与 {{CURRENT_TIME|datetime}} 注入。

目标端数据源：金蝶云星空，调 batchSave 写入销售出库单。注意金蝶端是分录型单据，必须在策略里开启表体（FEntity）映射，轻易云会按行展开。

编码映射集中管理：店铺、客户、SKU 这类主数据映射，强烈建议放在轻易云的「映射表」里维护，不要散落在每条策略的脚本里。一次实际项目中我们就是把 shop_id → FCustomerID 抽到统一表，新开分店时只改一处，所有引用策略自动生效。

前置过滤与状态闸门：源端拉到的数据，先在轻易云里按 status = Confirmed 过滤，再按 shop_id 圈定本次要同步的门店（素材里就是「潮流 3 店」这一类逻辑分片），最后才推金蝶。

实施步骤

把上线过程切成三段，心里更有底。

第一阶段——全量触发（首次）：把 start_time 倒推到一个足够早的日期，人工触发一次，把历史已出库单一次性补齐。轻易云里直接用「手动触发 + 时间区间覆盖」即可，不需要改策略结构。

第二阶段——切到增量（稳态）：首次成功后，把调度周期设成「每 30 分钟一次」（对应源端 */30 * * * *），目标端写入可以放宽到「每 40 分钟一次」（*/40 * * * *），两边错峰避免瞬时压力。增量游标用轻易云的 LAST_SYNC_TIME 变量，由平台自动持久化。

第三阶段——监控与回灌：轻易云自带的运行日志里能直接看到「拉取条数 / 写入条数 / 失败条数」。踩坑经验是：拉取条数长期为 0 时，先去源端确认游标有没有被人手工改过；失败条数告警优先看金蝶端的字段校验报错，多半是 FDate 格式或客户档案缺失。

踩坑复盘

1. 7 天窗口踩坑：聚水潭接口硬性要求时间间隔 ≤ 7 天。调度挂掉超过一周再恢复时，start_time 会落在 7 天之外，接口直接报错。稳妥的做法是在轻易云里加一道「窗口裁剪」逻辑，超过 7 天自动切多段循环。

2. 已出库单被回写覆盖：源端偶尔会把 Confirmed 状态回退或重写，金蝶端如果不做幂等就会重复落单。轻易云里把 FBillNo = {{io_id}} 作为幂等键，配合「存在则更新、否则新增」的写入策略，可以稳住账。

3. 店铺编码不一致：聚水潭里是自增数字 shop_id，金蝶里是基础资料编码字符串。一次实际项目中我们早期把映射写在每条策略的 Python 脚本里，三家门店改一遍要动十几个地方。后来统一迁到轻易云的映射表，运维成本几乎归零。这是编码映射集中管理的典型收益。

4. 表头表体分阶段上线：第一次上线时把表头和表体塞进同一个策略里同步跑，出问题定位非常痛苦。后来我们拆成两步：先稳表头（确认单据能落），再放表体（确认分录对得上）。这是一种表头表体分阶段的稳妥做法。

5. 增量与全量双轨：业务高峰或账期结转时，需要临时把某些历史区间的单据补传进去。我们没有改主策略，而是另起一个「补传策略」跑全量，跑完停掉，主策略始终保持增量节奏。这就是增量与全量双轨的常见模式。

适用场景与不适用场景

适用：多门店零售、单据状态明确为「已出库」且需要进入财务核算与成本结转的场景；需要按门店分片同步、跨系统幂等的场景。

不适用：需要实时秒级同步的门店（30 分钟粒度做不到）；聚水潭侧存在大量状态回退或重写的业务（幂等设计撑不住）；以及源端不提供修改时间字段、只能按单号轮询的场景。

适用场景与不适用场景(EN)

Applicable: Multi-store retail where confirmed outbound orders must feed finance and cost accounting; scenarios requiring store-level sharding and cross-system idempotency.

Not applicable: Scenarios needing sub-second real-time sync (the 30-minute cadence is too coarse); businesses with frequent status rollbacks on the source side (idempotency will not hold); and cases where the source provides no modification-time field and can only be polled by order number.