聚水潭其他入库单到星辰其他入库单:一条策略讲透库存单据同步

这个策略解决什么问题

在零售与仓配一体的业务里,「其他入库单」往往承载着退货入库、盘盈、调拨入库、组装拆卸等非采购类入库场景。某零售企业在实际项目中,门店每天会有几十到上百张此类单据散落在聚水潭,财务与总仓却要求在金蝶云星辰中按单据实时记账。两边系统单据号不互通、字段口径不一致,如果全靠人工二次录入,3 个月后账实差往往能差出几十万。

这条策略要解决的,就是让聚水潭的其他入库单按时、按口径同步到星辰,在星辰侧直接生成可审核、可入账的单据。我们用轻易云数据集成平台(Qeasy)承接,中间层做编码映射与字段口径收敛,源与目标系统之间不再直接耦合。

数据流向与字段映射

整体链路是单向同步,典型三段式:

聚水潭(其他入库单) → 轻易云集成平台(中间层) → 金蝶云星辰(其他入库单)

关键字段对照如下,实际项目里通常还需要按星辰侧的组织、库存方向再做一次映射:

这里「仓库编码」「物料编码」两张映射表,是轻易云上编码映射集中管理最典型的落地方式。后续如果客户再开新仓、上新品,只需要在映射表里加一行,不必改策略主体。

在轻易云上如何配置

在轻易云数据集成平台的策略编辑里,这条策略通常由 4 个核心配置块组成:

1. 数据源注册:聚水潭侧用其开放接口拉单,星辰侧用其单据保存接口写入。两侧的认证信息分别登记到轻易云的连接器里,不在策略正文里硬编码。
2. 拉单条件:增量起点之后,按 modified ≥ 上次成功时间 拉取;全量触发时清空游标,按业务日期范围重拉。
3. 字段映射与转换脚本:表头字段做日期格式、库存方向统一;表体按行做编码映射;对 qty 做正负号校验,负数直接进退库逻辑。
4. 写入与回执:写入星辰后,把星辰返回的单据内码回写到中间层,作为后续对账和重跑的锚点。

实施步骤

我们通常把上线拆成 3 个阶段,客户现场反复验证后才切正式调度:

• 阶段 1:增量起点确定。在测试环境选一个明确的截止时间点(例如某天 23:59),从该点之后只同步增量。这一步最容易翻车——起点选早了会重复,选晚了会漏单。稳妥的做法是先用全量把历史数据补齐,再用增量追新。
• 阶段 2:全量触发与核对。一次性把存量单据按日期分批同步,每批跑完后两边对账。轻易云上常见的做法是表头表体分阶段:先把表头批量写入并暂存,再按单据逐张补表体,避免星辰侧接口在批量模式下报错。
• 阶段 3:调度频率落地。零售场景一般按 5~15 分钟轮询增量;盘后做一次对账任务,把当日单据总数与金额双向核对。增量与全量双轨——增量追实时,全量兜底,任意一边异常都可重跑。

踩坑复盘

1. 单据号幂等键没设计好。聚水潭的 io_id 在星辰侧不是天然唯一键,如果按 单据编号 做幂等,改单后会误判为新单。稳妥做法是用源系统主键 + 写入时间戳组合。
2. 仓库编码口径不一致。聚水潭里「总仓」和星辰里「主仓」其实是同一个仓,但编码不同。靠写死在策略里不可持续,编码映射集中管理才是长期方案。
3. 数量正负号被吃掉。其他入库单里调拨出库是负数,前端表格如果按文本处理会丢符号,导致星辰侧数量翻倍。转换脚本里要强制做数值化与符号保留。
4. 改单与作废没回传。聚水潭上修改一张已同步单据时,如果只追增量时间戳,容易漏掉中间版本。需要在中间层保留最近 N 个版本,星辰侧按版本号覆盖。
5. 跨组织多账套混跑。同一份策略被多个组织复用时,组织标识必须显式带在请求参数里,不然星辰会按默认组织写入,造成单据错账套。

适用场景与不适用场景

适用:聚水潭作为门店与仓库前端、星辰作为财务与总账后端,需要把非采购类入库单按时同步入账的零售、仓配一体企业。 不适用:星辰侧有强审批流、单据状态机复杂,且希望单据由人工在星辰侧创建的纯财务场景;以及需要跨多组织、多账套并行且每套都要独立编码体系的大型集团,这种场景应拆成多条策略按组织维度分别维护。