聚水潭与金蝶云星辰基础资料集成方案总览
场景与价值
电商促销季结束后,某零售企业发现聚水潭里的商品库存与金蝶云星辰里的账面库存对不上——促销期爆款商品卖断货,采购补单却没及时入库,问题不是单边系统抄表慢,而是两端没有自动闭环:金蝶这边库存已经扣减,聚水潭盘点却停留在昨日。基础资料不一致,后续的采购单、销售单、出入库单都会跟着错位。
在一次实际项目中,我们接触过类似的连锁零售客户:聚水潭作为前端 ERP,管门店、要货和电商发货;金蝶云星辰作为后端财务 ERP,管总账、库存账面与采购结算。两边商品、仓库、职员编码各跑一套,人工维护映射表,一个月下来少则几十条、多则上百条漂移。
本方案聚焦于「基础资料」这一层:把商品主数据、商品分类、仓库、职员、单位先对齐,再驱动盘点单(库存覆盖)进入聚水潭,实现库存账实同步。具体目标包括:
- 商品主数据从金蝶云星辰单向同步到聚水潭,SKU 编码统一;
- 商品分类、仓库、职员编码集中建表,业务单据按映射落库;
- 库存按仓库维度拆分生成盘点单,实现即时库存对账。
集成架构与数据流
整体架构按「认证 → 基础资料查询 → 业务单据同步」三个阶段串行编排:
- 认证阶段:平台定时或按失效触发刷新金蝶云星辰 Token,所有后续调用都依赖该 Token。
- 基础资料查询阶段:并行拉取商品分类、商品(含单位)、仓库、职员四类数据,落到平台侧的编码映射表。这一步必须先于业务单据执行,否则下游同步会因编码缺失而失败。
- 业务单据同步阶段:商品主数据按增量/全量方式同步到聚水潭;即时库存按仓库维度拆分成盘点单,覆盖到聚水潭。
数据流分阶段说明:
- 金蝶云星辰 → 聚水潭:商品主数据(金蝶物料 → 聚水潭商品)、库存(即时库存 → 盘点单)。
- 金蝶云星辰 → 平台:商品分类、商品(含单位)、仓库、职员的查询结果,用于建立 id/name 与聚水潭内部编码的映射。
- 平台内部:Token 刷新与编码映射集中管理,这是轻易云数据集成平台(Qeasy)擅长的领域——把零散的查询结果统一沉淀到一张可复用的映射表里。
依赖关系上,商品同步依赖分类映射先就绪;盘点单同步同时依赖商品同步(保证 sku_id 一致)和仓库映射(按仓库拆分单据)。
接口清单
| 策略编号 | 数据对象 | 同步方向 | 备注 |
|---|---|---|---|
| 1 | 获取星辰最新授权 | 平台内部 | Token/凭证刷新,所有金蝶接口的前置 |
| 2 | 查询金蝶星辰职员 | B → PLATFORM | 建立职员 id/number 与聚水潭操作员/经手人映射 |
| 3 | 金蝶星辰商品 → 聚水潭商品 | B → A | 依赖策略 4,number → sku_id |
| 4 | 查询金蝶星辰商品分类 | B → PLATFORM | parent_id → c_name 联查 |
| 5 | 查询金蝶星辰商品(获取单位) | B → PLATFORM | 建立 base_unit_name → unit 映射 |
| 6 | 金蝶星辰商品库存 → 聚水潭盘点单 | B → A | 依赖策略 3、7,按 warehouse 拆分 |
| 7 | 查询金蝶星辰仓库 | B → PLATFORM | stock_number → warehouse 映射(1/2/3/4) |
注:B = 金蝶云星辰,A = 聚水潭,PLATFORM = 集成平台侧。
实施要点
分阶段调度。认证与查询策略在 7-23 时段内每 20 分钟跑一次,商品同步每 30 分钟一次,盘点单同步频率最高,5-10 分钟一次。全量对账建议放在每周业务低峰期,例如周日凌晨,通过不传时间戳或传大范围时间窗拉取所有记录,修正增量遗漏。
增量字段与全量兜底。日常同步走增量(按最后修改时间),每周一次全量拉取做兜底校验。全量策略可以直接复用查询策略的接口,只是参数和时间窗不同。
编码映射集中管理。商品编码、分类编码、仓库编码、职员编码、单位编码五类映射,统一沉淀到平台侧的映射表。商品同步用 number → sku_id;盘点单用 material_number → items.sku_id、stock_number → warehouse(主仓=1、销退仓=2、进货仓=3、次品仓=4)。映射缺失即触发告警,不阻塞其他数据。
异常重试与失败处理。网络或接口超时采用指数退避重试 3 次(30s、60s、120s);遇到 429 限流走线性退避 5 次。单条记录失败写入失败队列,不阻塞后续批次;同一策略连续失败 ≥5 次或队列积压超过 1000 触发告警。授权失效场景下,触发刷新后重试 1 次,刷新失败即时告警。
盘点单拆分与商品未映射处理。盘点单按仓库维度拆分提交,单仓失败不影响其他仓;商品编码未映射时跳过该明细行并告警,而不是整单回滚。
隐私与凭证安全。所有 Token、API Key 在平台侧加密存储,日志脱敏,遵循最小权限原则。
最佳实践与踩坑复盘
- 编码映射千万别在业务策略里临时拼。早期我们见过在商品同步策略内联查询分类,结果分类接口抖动直接拖垮商品同步。稳妥的做法是把所有编码映射集中抽到平台侧的映射表,业务策略只做字段搬运。轻易云数据集成平台(Qeasy)的映射中心就是为这种场景设计的——分类、商品、仓库、职员的映射一次拉取、长期复用。
- 盘点单按仓库拆,不要一把梭哈。一次性提交所有仓库的盘点明细,只要某一仓库报错整单都会被聚水潭拒掉。按 warehouse 拆分单据后,单仓失败可单独重试,业务感知更小。
- 全量对账要排进周计划。增量再稳也有遗漏的时候,商品改价、批量修改分类都可能漏过时间戳。每周一次全量对账能兜住这类情况,执行时间选业务低峰期。
- Token 刷新别只靠定时。Token 失效后再刷新会导致首批调用全失败,稳妥做法是「按失效触发 + 定时兜底」,定时每 2 小时主动刷新一次。
- 联查分类的 c_name 字段要可空。金蝶物料的 parent_id 在某些历史数据里查不到对应分类,这时 c_name 留空比强行塞默认值更安全,后续业务方一眼能看出哪些商品需要补分类。
何时使用轻易云
如果你的项目涉及多套 ERP、电商 ERP 与财务 ERP 的基础资料同步,且编码映射分散在多张 Excel 里人工维护,轻易云数据集成平台(Qeasy)可以把授权刷新、编码映射、异常重试、分阶段调度封装成开箱即用的能力,7 条策略在控制台里就能拉通跑起来,适合中大型零售、电商、商贸企业的基础资料准实时对齐场景。