客户仓即时库存同步实战：从金蝶云星空拉到 MySQL 报表库的一条策略讲透

这个策略解决什么问题

在面向客户仓的业务里，销售、采购、财务几乎每天都在问同一件事：客户仓里某物料现在到底还有多少？这些数字必须既新鲜、又不影响 ERP 在线性能。源系统是金蝶云星空里的即时库存账，目标是一套 MySQL 报表库——下游的 BI、对账、订单跟单都从这里取数。本策略只解决一件事：把金蝶云星空中"客户仓"类型的即时库存，按 FID 增量拉到 MySQL 的中转表里，新增就插、有变化就改，绝不允许物理删除（策略名里的"勿删 FF100003"就是项目里立的死规矩）。

数据流向与字段映射

整体链路是单向的：金蝶云星空（executeBillQuery）→ 轻易云集成平台中间层 → MySQL 报表库（WebAPI 写 SQL）。

源端来自金蝶云星空的库存查询接口，关键字段如下：

目标端落在一张 MySQL 表（演示命名为 kingdee_STK_Inventory），写库用 INSERT 主语句；源端没带过来的 FMtoNo / FStockStatusId / FStockLocId / FStockUnitId / FStockOrgId / FOwnerId 等维度，由上游另一条策略在表里维护好，本策略不要重写——这是客户现场反复强调过的边界。

在轻易云上如何配置

我们用轻易云数据集成平台（Qeasy）承接这条链路，三个核心配置点值得展开：

1. 源端元数据：API 选 executeBillQuery，method POST，autoFillResponse 打开，ID 字段用 FID，关掉 idCheck——库存数据不存在"单据编号"概念，用 FID 做幂等键更稳。
2. 目标端元数据：API 选自定义 WebAPI execute，主参数用 main_params 传绑定变量，main_sql 字段写 INSERT 语句。注意源端目标端 idCheck 表现不一样：目标端必须开 idCheck=true，让轻易云按 FID 维护批次与去重，避免同一次调度内重复写。
3. 编码映射集中管理：FStockId / FMaterialId 这种基础资料编码，务必用轻易云的"映射表"统一维护。客户现场吃过亏：散落在多个策略里的硬编码，两个月后改一处忘一处，两边数字对不齐。把映射集中放，半年后再加仓库只要改一处。

实施步骤

按上线节奏分三步走，是这套客户仓同步最稳妥的姿势：

• 第一步：增量起点。先用一次全量把存量数据铺到 MySQL；后续调度只看 FID > last_max_id 的增量。客户现场约定每天 12:15 与 18:15 各跑一次，源端 cron 是 10 12,18 * * *，目标端延迟 5 分钟启动，留出拉取与转换的窗口。
• 第二步：全量触发。仅在以下情况跑全量：金蝶云星空做了库存初始化、新增了客户仓类型、或者表结构变更。平时绝不允许反复全量，否则下游 BI 报表会被刷穿。
• 第三步：调度频率微调。客户仓库存比成品仓波动更频繁（销售出库节奏快），如果发现可用量长期滞后，可以再插一档 14:00 的调度。增量与全量双轨：日常增量，月初全量校验一次，是轻易云客户常见的应对模式。

踩坑复盘

在客户现场，这条策略踩过几个典型坑：

• ON DUPLICATE KEY UPDATE 一开始是打开的——稳妥的做法是先关掉，因为源端只要一重复就会覆盖下游手工维护的维度字段；后来我们改成纯 INSERT + 独立 UPSERT 策略来更新。
• 批次 FLot 为空字符串时，写 SQL 直接报类型错。需要在轻易云的字段清洗里把空串统一替换为 NULL，或在 main_sql 里用 NULLIF(:FLot,'')。
• "勿删 FF100003"这条规矩差点被绕过。源端如果某天查不到这条记录，轻易云默认会把它从结果集"软移除"，导致下游表里这条记录成为孤儿。正确做法是在轻易云的目标端配置里把"目标端不存在则删除"关掉，本策略只做新增和修改。
• 客户仓与自有仓用同一张表时，仓库过滤一定要下推到源端。否则会把所有仓库的库存都拉过来，下游分析按 FStockId 过滤时性能很差。我们在源端 filter 里固定只拉 客户仓类型仓库，源端 SQL 层面就减负。
• 调度 cron 错位。源端 12:10 拉、目标端 12:15 写看似安全，但金蝶接口偶发慢响应时会跨点。稳妥的做法是给目标端加一个"完成时间检查"，超过 18:30 就告警，不要把任务堆到夜里。

适用场景与不适用场景

适合：客户仓/委外仓/VMI 仓等需要频繁被下游查询、但又不希望在线 ERP 直接对外暴露库存数据的场景；以及需要把库存快照沉淀到 BI/对账报表库的链路。不适合：需要秒级实时库存的强一致场景（如拣货台），以及需要做物理库存初始化或冻结库存核算的场景——这些应该走金蝶云星空自身的库存事务，不在本策略覆盖范围。