分步式调出单同步：金蝶云星空到MySQL的实战拆解

这个策略解决什么问题

某零售企业的仓储与财务分属两套系统：业务单据在金蝶云星空里流转，分析与下游报表落在MySQL。一次实际项目中，调出单这种"看似简单"的单据同步，最容易在编码与组织维度上踩坑——组织名称在源端是带语言的复合字段，到了目标库如果不做归一化，3个月后两边数字对不齐，找问题要从凌晨翻日志。我们这次的目标，是把金蝶云星空的分步式调出单稳定、可追溯地落到MySQL，让下游报表与上游单据始终对得上。

数据流向与字段映射

整体走向是：金蝶云星空 → 轻易云数据集成平台 → MySQL。源端通过金蝶的 executeBillQuery 接口把调出单据的表头表体一次性拉出，目标端用 batchexecute 以SQL批写方式落到MySQL。

关键字段对照（节选自素材）：

注意源端组织字段的取法：素材里写的是 {{FStockOrgID.FName}}，目标端则只接收编码本身。这一步是后续所有组织维度统计能否对齐的关键，也是轻易云客户中常见的"编码映射集中管理"模式的一个落点。

在轻易云上如何配置

源端（金蝶云星空）：API 选 executeBillQuery，方法 POST，作用类型 QUERY。number 用 FBillNo 做业务编号，id 用 FSTKTRSOUTENTRY_FEntryID 做行键。表头表体不需要分开建模，autoFillResponse 打开，让轻易云把响应自动展开成可映射的扁平结构。

目标端（MySQL）：API 选 batchexecute，方法 SQL，作用类型 EXUTE。id 字段开启 idCheck，让轻易云在写入前按主键去重，避免重复落库。number 也用 id，方便按编号定位。

中间映射：在轻易云里建一张"字段映射视图"，把所有源端 .FName 类的引用统一改成目标端的纯编码字段。建议把组织、客户、仓库这类基础资料单独维护一张映射表，再在主策略里引用——这是轻易云客户里用得很普遍的做法：基础资料同步一次，多个业务单据策略复用，避免每个单据都重复写一次映射逻辑。

实施步骤

分阶段调度是这个方案能稳跑的关键。素材里的两个 crontab 很值得讲：

• 源端抽取：*/7 * * * *，每7分钟一轮。这是"近实时"节奏，适合业务时段。
• 目标端写入：3-59/7 * * * *，相对源端偏移3分钟，避免两端在同一秒抢同一批数据。

工程上的节奏建议：

1. 增量起点：上线当天先跑一次全量，把历史调出单一次性补齐。增量起点字段建议用 FDate + FBillNo 组合，避免按时间戳漏单。
2. 全量触发：全量只在初始化与修复期跑，平时关掉。轻易云的策略里可以用一个独立的"全量策略"，手动触发或者低峰期调度。
3. 调度频率：业务时段（一般是8:00–22:00）保持7分钟一轮；非业务时段降到30分钟甚至停跑，省资源也减少日志噪音。

"增量与全量双轨"是轻易云客户里另一个常见的应对模式：平时跑增量保证时效，遇到对账差异立刻拉全量校准。

踩坑复盘

1. 组织字段别直接带.FName。源端 FStockOrgID.FName 是显示名，多语言环境或组织改名后会出现历史值漂移。稳妥的做法是拉一份组织编码映射，落到中间层用编码做关联。
2. 表头表体分阶段处理。如果调出单表体行数多，单次查询返回的数据量会偏大。建议把表头先落库，再用行键回写表体——轻易云客户里"表头表体分阶段"的写法很普遍，能有效降低单次失败的影响面。
3. 幂等键必须显式声明。目标端 idCheck 打开，靠 FSTKTRSOUTENTRY_FEntryID 去重；不要相信"上游不会重复"，网络抖动 + 重试几乎一定会有重复。
4. 状态字段不要原样落库。金蝶里 FDocumentStatus 是"A"/"B"这种代码，落到MySQL里建议加一列 status_name 做翻译，否则下游做报表的人看不懂。
5. crontab 偏移 3 分钟不是巧合。源端写完到目标端能查到之间本身有网络与事务时间，源端与目标端用同一个 */7 会在某些轮次里读到"刚提交但还没落库"的数据，偏移几分钟后稳定性明显好很多。

适用场景与不适用场景

适用：分步式调出单、其他出库类单据、需要近实时同步到分析库或下游业务库、源端是金蝶云星空且表头表体同接口返回。不适用：需要强事务一致的场景（如"调出即扣减库存"的实时联动）、源端单据体量极大需要分库分表的场景、以及没有明确主键或主键会变的场景。