辅助资料集值拉取实战：金蝶云星空到 MySQL 的数据回流策略

这个策略解决什么问题

在金蝶云星空作为后端 ERP 的项目里，前端业务系统（这里是 MySQL 业务库）经常需要一份 ERP 侧的辅助资料集值副本——比如自定义类别下的编码、名称、备注、禁用状态等。如果让业务端去直连金蝶的 WebAPI，每多一个查询场景就要重写一次鉴权和分页逻辑；用轻易云数据集成平台把这条回流链路做成一个独立策略后，业务端只需要查 MySQL 即可，编码与名称的对照也能在一张表里集中维护。

数据流向与字段映射

整体流向是：金蝶云星空（源，executeBillQuery）→ 轻易云集成平台（中间层，做字段映射与去重）→ MySQL（目标，UPSERT 写入）。

关键字段对照：

我们特意把 FId 与 FId_fname 一起拉回来，业务端按名称筛选时就不用再做一次跨表 join。

在轻易云上如何配置

源端配置：选择金蝶云星空平台，API 用 executeBillQuery（POST，QUERY 语义），主键字段取 FEntryID，业务编号字段取 FId_fname，启用 idCheck，关闭 buildModel。这样拉回来的就是结构化的扁平结果集，便于后面直接落库。

目标端配置：选择 MySQL 平台，API 走 execute（POST，EXECUTE 语义）。main_sql 使用 INSERT ... ON DUPLICATE KEY UPDATE 的 UPSERT 语句，main_params 用命名参数绑定。注意 value 里保留 :FEntryID 这种占位符，轻易云会根据字段名自动绑定。

调度设置：源策略 cron 写 3 2 * * *，目标策略写 23 2 * * *，两者错开 20 分钟，避免源还没查完就开始写。

实施步骤

1. 增量起点：首次上线前，先在金蝶里确认 FEntryID 的最大值，作为本次拉取的起点 FEntryID > {startId}；写入策略里加一段「起点参数」逻辑，第一次跑全量，之后只跑增量。
2. 全量触发：在轻易云里把策略的 isFirst 开关打开，跑一次历史全量；跑完后立刻关掉，避免下次调度又把全量拉一遍。
3. 调度频率：辅助资料集值变化频率不高，按天调度足够；如果某个类别需要近实时，再单独拉一条分钟级策略，编码映射集中管理在平台里维护。
4. 校验：写一条断言策略，比对 MySQL 端 COUNT(*) 与金蝶端查询总数，差异 > 0 时告警。

踩坑复盘

• 典型错误是把 FId_fname 当成普通字符串字段。它其实是金蝶侧的类别「显示字段」，如果目标表没建好索引，业务端按名称查会全表扫。我们通常在 MySQL 端对 (FId, FNumber) 建联合唯一索引，让 UPSERT 真正生效。
• executeBillQuery 默认分页容易漏数据。金蝶的分页是按行号来的，如果中间过程中源端新增了行，单纯按 offset 翻页会跳行。稳妥的做法是上一句提到的 FEntryID 增量条件 + 排序，而不是纯分页。
• ON DUPLICATE KEY UPDATE 忘记带主键或唯一键。一旦目标表没有唯一约束，UPSERT 就会退化成多次 INSERT，数据被重复写入。我们上线前一定会先 SHOW INDEX 确认。
• 状态字段被覆盖丢失。例如目标端业务系统本来手动把 FForbidStatus 改过，UPSERT 一跑就被金蝶原值覆盖。处理方式是 ON DUPLICATE KEY UPDATE 里只更新真正会变化的字段，状态字段保持原值。
• 跨时区调度漂移。私有化环境里服务器时区不一定和数据库一致，cron 表达式建议写 UTC，并在轻易云里显式标注时区，避免凌晨任务跑偏。

适用场景与不适用场景

适用：辅助资料集值、自定义类别、单据状态字典等低频变更、需要在前端做编码→名称翻译的场景。 不适用：高并发写入、需要事务一致性的单据体（如销售订单表头表体）；这类更适合走单据同步策略，而不是辅助资料回流。