金蝶云星空采购入库对接聚水潭:单策略同步实战教程
这个策略解决什么问题
某零售企业在做线上线下一体化时,采购入库是绕不开的一环:金蝶云星空作为 ERP 主账,记录真实的入库数量、成本与供应商;聚水潭作为前端电商履约系统,需要同一份入库数据驱动库存更新和对账。一旦两边对不上,财务和仓库就要花数小时逐单核对,月底更是噩梦。这条策略的目标很单纯:把金蝶云星空已审核的采购入库单,按既定节奏写入聚水潭的采购入库接口,让两边在「单据编号、供应商、仓库、行项目」四个维度对齐。
数据流向与字段映射
数据流是单向的:金蝶云星空(源) → 轻易云数据集成平台(中间层) → 聚水潭(目标)。中间层不落库,只做字段翻译与编码映射。
关键字段对照如下:
| 业务含义 | 金蝶云星空字段 | 聚水潭字段 | 处理方式 |
|---|---|---|---|
| 外部单号 | FBillNo | external_id | 直接传,作为幂等键 |
| 单据主键 | FInStockEntry_FEntryId | id | 平台生成回填 |
| 单据状态 | FDocumentStatus | (内部判断) | 仅推送已审核 |
| 收料组织 | FStockOrgId_FNumber | wms_co_id | 编码映射 |
| 仓库 | FStockId_FNumber | wms_co_id | 模板变量替换 |
| 供应商 | FSupplierId_FNumber | supplier_id | 跨表查找映射 |
几个值得展开的点:第一,聚水潭的 wms_co_id 在素材里实际取的是仓库编码,不是组织编码——这里要在中间层完成「组织→仓库」的语义转换;第二,供应商映射走 _findCollection 查表,意味着需要先把供应商主数据从金蝶同步到聚水潭并落一张映射表,这恰好是轻易云客户常见的「编码映射集中管理」做法。
在轻易云上如何配置
在轻易云数据集成平台(Qeasy)里,这条策略被建模为「源查询 + 目标执行」两个元数据文件,平台负责把它们编排成一个有向无环图。
源端配置要点:API 选 executeBillQuery(POST),用 FBillNo 作为单据号字段、FInStockEntry_FEntryId 作为行项目主键,开启 idCheck 做增量去重,buildModel=false 表示按声明字段精确拉取,避免把无关字段一并拖下来拖慢接口。
目标端配置要点:API 选 jushuitan.purchasein.upload(POST),buildModel=true 让平台按目标结构生成请求体;external_id 用模板 {{FBillNo}} 注入,作为幂等键;is_confirm 固定写 0,先入库不自动确认,留给人工二次复核;supplier_id 通过 _findCollection 跨源查找,把金蝶的供应商编码转成聚水潭的内部数字 ID。
实施步骤
阶段一:增量起点对齐。 上线当天先在金蝶侧记录一个「增量起点时间戳」,轻易云只拉该时间之后、且状态为已审核的单据,避免把历史包袱一次性倒进聚水潭。
阶段二:全量触发与回放。 对存量数据,在低峰期手动触发一次全量回放。轻易云会按单据号去重,即使与增量重叠也不会重复写入。这一步通常安排在夜间 23:00 之后。
阶段三:调度频率。 源端 executeBillQuery 配置 1-59/12 7-23 * * *,即工作时段每 12 分钟拉一次;目标端写入配置 */5 7-23 * * *,每 5 分钟尝试推送一次。源慢目标快,中间靠轻易云的任务队列自然削峰。
阶段四:供应商映射表预热。 在策略上线前,先跑通一条独立的「供应商主数据同步」策略,把映射表喂满;否则前几笔入库单会因为查不到 supplier 而写入失败。
踩坑复盘
- 签名是行项目主键,不是单据头主键。 第一次配的时候有人把
FID当成幂等键,结果同一张单据的多行被当成多笔独立入库,聚水潭直接拒收。稳妥做法是external_id用单据号FBillNo,行项目主键只用于内部去重。 is_confirm不要默认开成 1。 自动确认会让对账失去缓冲,一旦源头数据有误就污染下游。客户现场常见的做法是先0,等财务或仓储人工确认后再开。- 跨表查找的超时与缓存。
_findCollection在数据量大时第一次查询会慢,容易拖垮整条链路。建议在轻易云里给映射表加一层本地缓存,TTL 设 10–30 分钟。 - 时区与日期格式。 金蝶默认返回的
FDate是带时间的字符串,聚水潭只接日期。这里容易翻车,稳妥做法是在中间层显式截断到YYYY-MM-DD,不要把时分秒传过去。 - 依赖顺序。 这条策略隐式依赖「供应商主数据同步」「仓库对照表」两条策略上线。轻易云任务编排里要明确设置
depends_on,否则上游表为空时跑批会全部失败,且日志不直观。
适用场景与不适用场景
适用:单组织、供应商与仓库对照稳定的零售或分销企业,日均入库单在数百到数千量级。不适用:多组织间需要拆单改写的场景、需要按采购订单逐行匹配入库的业务,以及聚水潭侧要求实时秒级回写的场景——后者建议走事件驱动而不是定时轮询。