聚水潭与金蝶云星辰集成方案：8 策略打通订单与库存双向同步
场景与价值
电商零售商家普遍同时使用聚水潭管理线上店铺与金蝶云星辰管理财务库存,两套系统的数据长期割裂会带来三类典型问题:销售出库单在金蝶侧需要二次录入,商品库存数量在两边不一致,以及异常发生时缺乏统一告警通道。本文给出一套通用的双向集成方案,涵盖 8 个策略、4 类基础资料查询与 1 个企业微信告警通道,在集成平台(中间层)完成编码映射、字段转换与重试调度,使两套系统围绕"销售订单"与"即时库存"形成闭环。
方案的核心价值在于:以销售出库单为主线解决财务侧的入账延迟,以库存反向写入盘点单解决盘点数与账面数的不一致,并通过统一的告警通道将所有策略的执行状态可视化。该方案不绑定特定集成平台,适用于绝大多数 ETL 或数据同步产品。
集成架构与数据流
整体架构分为四层。源系统层包含聚水潭(支持奇门与非奇门两种接口模式)与金蝶云星辰 V2;中间层为集成平台,负责编码映射、字段转换、异常重试与调度;目标系统层根据数据流向不同,既包含金蝶云星辰也包含聚水潭;通知层为企业微信,用于推送异常状态。
数据流向共四条:
- 聚水潭 → 金蝶云星辰:奇门销售出库单(
jushuitan.saleout.list.query)与非奇门销售出库单(/open/orders/out/simple/query),通过增量拉取后写入金蝶销售出库单接口(/jdy/v2/scm/sal_out_bound)。 - 金蝶云星辰 → 聚水潭:商品即时库存(
/jdy/v2/scm/inventory)按仓库维度拆分后,写入聚水潭盘点单(/open/jushuitan/inventoryv2/upload),使用type=check实现全量覆盖。 - 金蝶云星辰 → 集成平台:物料、仓库、物流公司、账户管理四类基础资料以
QUERY_ONLY模式拉取至中间层,供编码映射与业务校验使用。 - 集成平台 → 企业微信:定期查询
StrategyErrorDetail,将失败明细推送至群机器人。
执行依赖方面,基础资料查询(策略 1~4)需先于业务单据同步执行,供店铺→客户、SKU→物料、仓库编码的映射使用;企业微信告警策略可独立调度。
接口清单
| 策略 | 源平台/接口 | 目标平台/接口 | 数据对象 | 同步方向 |
|---|---|---|---|---|
| 1 | 金蝶云星辰 /jdy/v2/bd/material | 集成平台 | 物料 | B→PLATFORM |
| 2 | 金蝶云星辰 /jdy/v2/bd/store | 集成平台 | 仓库 | B→PLATFORM |
| 3 | 金蝶云星辰 物流公司接口 | 集成平台 | 物流公司 | B→PLATFORM |
| 4 | 金蝶云星辰 账户管理接口 | 集成平台 | 账户 | B→PLATFORM |
| 5 | 聚水潭奇门 jushuitan.saleout.list.query | 金蝶云星辰 /jdy/v2/scm/sal_out_bound | 销售出库单 | A→B |
| 6 | 聚水潭非奇门 /open/orders/out/simple/query | 金蝶云星辰 /jdy/v2/scm/sal_out_bound | 销售出库单 | A→B |
| 7 | 金蝶云星辰 /jdy/v2/scm/inventory | 聚水潭 /open/jushuitan/inventoryv2/upload | 商品库存→盘点单 | B→A |
| 8 | 集成平台 StrategyErrorDetail | 企业微信 | 错误明细 | PLATFORM→企微 |
注:A=聚水潭,B=金蝶云星辰 V2
实施要点
奇门与非奇门双路径的销售出库单同步是本方案的主策略。两者源接口、增量字段(start_time/end_time 与 modified_begin/modified_end)、日期字段优先级(pay_date vs io_date)都不同,但目标单据结构一致,因此字段映射可复用。重点处理:shop_id→customer_number 与 sku_id→material_number 两类编码映射;so_id+remark 拼接为单据备注便于追溯;delivery_type_id=6 固定为快递配送;bill_source=ISV 标识数据来源。
库存反向写入盘点单需要按 stock_number 维度拆分提交,任一仓库失败不影响其他仓。商品未映射到 sku_id 时跳过该明细并触发告警,而非整体失败。so_id 字段使用随机数占位,避免与线上单号冲突。
基础资料查询统一使用毫秒级时间戳(LAST_SYNC_TIME 后追加三个零)实现增量,支持 modify_start_time/modify_end_time 过滤。物料查询需调用明细接口(/jdy/v2/bd/material_detail)获取价格等扩展字段。
异常处理分四类:网络类(超时、5xx)采用指数退避重试 3 次;限流类(429)固定间隔重试 5 次;业务校验失败(4xx)不重试,记录失败日志与源表状态;编码映射缺失不重试,即时告警。所有失败均通过企业微信通道推送。
最佳实践
- 调度分阶段执行:基础资料(策略 1~4)并行启动后,业务单据(策略 5、6)再启动,最后执行库存→盘点单(策略 7),告警策略(策略 8)独立高频运行。
- 编码统一优于映射维护:若业务允许,推动聚水潭 SKU 编码与金蝶物料编码保持一致,可显著降低映射表维护成本。
- 初始化与日常分离:首次部署采用全量模式(移除时间过滤),日常运行切换至增量;全量修复通过单独任务执行,不与高频调度混跑。
- 幂等写入防重复:使用
idCheck或源单据号作为唯一键去重,避免重试与并发导致的重复单据。 - 告警阈值分级:单策略失败率 >10% 触发警告,连续失败 ≥3 次或 API 可用性 <95% 触发严重告警,关键业务单据延迟超过 2 个调度周期立即通知运维。
- 敏感信息脱敏:方案 ID、租户 ID、API Key 等不应硬编码在同步逻辑中,应通过平台配置中心注入并加密存储。