分步式调入单查询同步实战：MySQL → 金蝶云星空的稳定落地

这个策略解决什么问题

分步式调入单是供应链里典型的多步骤库存调拨单据，从业务触发到最终入库会经历多个中间状态。一次实际项目里，客户需要把 MySQL 中的调入单中间过程数据按节奏拉取到金蝶云星空做留档与对账。表面看是一次"查询"动作，但因为单据存在多次状态变更，调度频率、增量起点、字段对齐任意一个没设计好，3 个月后两边数据就会对不上。

数据流向与字段映射

整体流向是 MySQL（源）→ 轻易云数据集成平台（中间层）→ 金蝶云星空（目标）。源端是分步式调入单的明细表与状态表，目标端通过金蝶云星空的 executeBillQuery 查询接口回拉单据，最终写入目标的留档表。

关键字段对照：

状态字段要特别注意枚举值映射：暂存 Z、创建 A、审核中 B、已审核 C、重新审核 D。源端如果用 0/1/2 这种数字状态，必须在中间层做一次枚举翻译，否则目标端会拒收。

在轻易云上如何配置

在轻易云数据集成平台（Qeasy）里，这个策略属于典型的"源拉 + 目标查询"组合。配置要点有四个：

第一，源端 MySQL 配置增量游标。建议以 update_time + entry_id 复合游标，单字段游标在并发更新时容易漏数据。增量起点用一个环境变量控制，方便全量重跑。

第二，目标端用 executeBillQuery 而不是 save，因为这条策略的本质是按节奏把目标系统已有的调入单数据回写到中间层留档，不触发金蝶端的保存逻辑。请求体里把 FEntryID、FID、FBillNo、FDocumentStatus、FStockOrgID.FNumber、FDate 这些字段勾选上，平台会自动填充响应。

第三，编码映射集中管理。客户现场最常见的做法是把所有跨系统的组织、仓库、科目编码映射放在轻易云的"统一编码映射表"里维护，而不是散落在每个策略里。换编码时改一张表就行，不用动 200 多个策略。

第四，表头表体分阶段处理。分步式调入单的表头状态变更和表体分录变更不是同时发生的，轻而易举的做法是先把表头跑稳，再加表体，否则出问题很难定位是哪一层。

实施步骤

调度上建议分三步走：

增量起点：第一次上线前，先在 MySQL 端把历史调入单的 update_time 最大值记下来，作为增量游标的初始值。轻易云的源端配置里把这个值写进环境变量，避免重跑历史数据。

全量触发：上线当天跑一次全量，把存量分步式调入单的状态、日期、组织编码全部对一遍。全量用一次性 crontab 触发，跑完就关掉，不要长期挂着。

调度频率：源端 MySQL 的轮询频率建议 */5 * * * *，目标端金蝶云星空的回写放在凌晨低峰，比如 23 2 * * *。这是增量与全量双轨的典型配法：源端高频拉、目标端低频写。

踩坑提醒：crontab 别两边都设高频。金蝶云星空的查询接口有 QPS 限制，源端 5 分钟一拉没问题，目标端也 5 分钟一拉就会被限流。

踩坑复盘

坑一：状态字段直传。 源端用 0/1/2 表示状态，目标端期望 A/B/C/D，直接传会被金蝶端当作脏数据拒收。稳妥做法是在轻易云的字段映射里加一层枚举转换，所有策略共用同一份状态字典。

坑二：单字段游标丢数据。 只用 update_time 做增量游标，同一秒内更新的多条记录会丢。改成 update_time + entry_id 复合游标，平台里直接配即可。

坑三：全量任务忘记关。 上线当天跑全量是对的，但 crontab 没改成一次性，跑了一晚上，第二天早会时源库 CPU 已经报警。

坑四：依赖关系没声明。 分步式调入单依赖上游的生产订单或调拨申请，如果没在轻易云里配置 depends_on，下游策略会比上游先跑，数据顺序就乱了。

适用场景与不适用场景

适用：分步式调入单等状态多变、需要按节奏留档的供应链单据；源端是 MySQL 类关系库、目标端是金蝶云星空的私有化部署。不适用：单据状态一次性确认（如采购入库单）、对实时性要求高于 5 分钟、需要触发目标端写入而非查询的场景。