销售出库单同步实战：金蝶云星空到MySQL的增量落地方案

这个策略解决什么问题

在某医药流通企业的实际项目里，ERP端的销售出库单需要实时落到数据中台的MySQL库，供下游BI、对账系统和物流跟踪使用。看似简单的"单据同步"，真正落地时却要解决三类问题：金蝶主从结构怎么扁平化落库、基础资料字段取编码还是取名称、按什么节奏增量才不会漏单也不会压垮源系统。我们用**轻易云数据集成平台（Qeasy）**承接这条链路，把金蝶云星空的SAL_OUTSTOCK按7分钟节奏推到MySQL单表，整套方案在客户现场稳定运行至今。

数据流向与字段映射

整体走向是：金蝶云星空 → 轻易云中间层 → MySQL。金蝶侧使用executeBillQuery（POST分页查询，FormId=SAL_OUTSTOCK）按FApproveDate增量拉取，返回扁平化结果（每行=一条出库分录，主表字段在每行中重复）；目标端落到MySQL单表fky_jd_out_stock，以FEntity_FEntryID作为去重依据，用REPLACE INTO实现upsert。

关键字段对照（节选）：

源字段	目标字段	映射类型	业务说明
FEntity_FEntryID	FEntity_FEntryID	DIRECT	销售出库分录行ID，主键依据
FBillNo	FBillNo	DIRECT	单据编号
FSaleOrgId.FName	FSaleOrgId_FName	TRANSFORM	销售组织名称
FCustomerID.FNumber	FCustomerID	TRANSFORM	客户编码（用于关联）
FCustomerID.FName	FCustomerName	TRANSFORM	客户名称（用于展示）
FMaterialID.FNumber	FMaterialID	TRANSFORM	物料编码
FStockID.FNumber / .FName	FStockID / FStockName	TRANSFORM	仓库编码与名称
FRealQty	FRealQty	DIRECT	实发数量（目标端为string）
FApproveDate	FApproveDate	DIRECT	审核日期，增量起点

编码与名称采用双轨映射：客户、物料、仓库、批号取FNumber便于跨系统关联；组织、部门、销售员、承运商等取FName便于业务人员直接读懂。

在轻易云上如何配置

在轻易云数据集成平台里，这条策略的核心配置围绕"源端查询 + 目标端执行"两段展开：

源端（金蝶侧）：metadata.api=executeBillQuery，effect=QUERY，请求体里把FEntity_FEntryID、FBillNo、FCustomerID.FNumber/FName等需要拉取的字段按{{字段.子属性}}语法一一列出；分页由{{PAGINATION_PAGE_SIZE}}和{{PAGINATION_START_ROW}}控制；增量条件写在FilterString上：FApproveDate>='{{LAST_SYNC_TIME|datetime}}'。
目标端（MySQL侧）：metadata.api=batchexecute，effect=EXECUTE，idCheck=true，开启主键去重；请求数组里把上游字段值通过{{}}模板注入到目标列；写入方式为REPLACE INTO，按FEntity_FEntryID去重；单条队列写入量limit=200。
调度：源端*/7 * * * *（每7分钟拉取），目标端3-59/7 * * * *（每7分钟写入，错开3分钟），避免读写相互挤压。

整条链路没有配置自定义脚本（Scripts为空），所有转换都在字段映射层完成。

实施步骤

我们把这套方案拆成三个阶段推进，避免一次性把全量数据压上线。

增量起点初始化：上线前先用历史最大审核日期作为LAST_SYNC_TIME初值，从这个时间点开始往后增量。如果担心源头数据有回溯修改，建议先做一次小窗口全量回刷，再切到增量。
全量触发（一次性）：在策略首次上线或大版本切换时，临时调整调度为单次触发，把所需时间窗内的单据一次性拉齐，确认目标端条数与源端一致后再恢复*/7节奏。
稳态调度：源端*/7 * * * *拉取，目标端3-59/7 * * * *写入，错峰3分钟；日常监控三件事——FApproveDate水位的推进、目标端FEntity_FEntryID唯一性、写入队列的积压情况。

踩坑复盘

典型错误一：基础资料只取名称。某次对接时下游做对账，发现客户编码对不上，最后只能回溯加字段。稳妥的做法是：关联字段取FNumber，展示字段取FName，从第一天就双轨配置，不要等出问题再补。
典型错误二：没分阶段，全量直接灌。金蝶一次返回几万条单据，源端分页拉满后目标端REPLACE INTO会因唯一键冲突产生大量回写，触发主键竞争。稳妥的做法是表头表体分阶段、先小窗口验证、再放大窗口，批量写入限制在200条/批以内。
典型错误三：类型隐式转换翻车。FRealQty源端是float、目标端是string，写入时如果不做格式化，遇到科学计数法或精度截断就会让下游对账对不齐。稳妥的做法是在映射层显式格式化数值，避免依赖数据库隐式转换。
典型错误四：增量起点设错。把FCreateDate当成增量条件，结果审核中单据被漏掉；务必使用FApproveDate作为金蝶单据的增量边界。
典型错误五：源端目标端同时调度同分钟。读写同时触发容易压垮金蝶接口。错峰3分钟是经验值，源端先拉、目标端后写的节奏最稳。

适用场景与不适用场景

适用：ERP与中台之间需要近实时（分钟级）落库、做对账或BI取数；单据体量适中、能用扁平表承接。不适用：源端单据存在复杂的主子表回写、需要严格事务一致性的场景；以及下游必须保留主从结构、不能接受字段重复存储的场景，这时应改用主表+明细表双表方案。