金蝶云星空辅助资料查询策略实战：单点拉取 + 中间层落地的稳健做法

这个策略解决什么问题（场景与价值）

某零售企业的销售团队反馈：业务员在下单时填写的"行业类型""客户来源""区域划分"等辅助资料字段，源头其实在金蝶云星空里。每次新单进来都要人工去对一次，三个月下来两边字典已经对不上号。我们用轻易云数据集成平台（Qeasy）承接了一个最小但极关键的策略——查询金蝶辅助资料：定时把金蝶云星空里的辅助资料字典拉到中间层，让下游所有写入策略都拿这份"权威字典"做参照。这个策略不直接写业务单据，但它决定了后续 9 个同步策略能不能跑得稳。

数据流向与字段映射

数据流向是典型的 源 → 中间层 → 目标 三段式，但这一策略里目标端是一个"空写入"，目的是把拉到的数据钉在中间层供其他策略读取。

源端（金蝶云星空）通过 executeBillQuery 这个 WebAPI 拉取辅助资料单据，按 FNumber 作为主键识别。中间层是轻易云集成平台自身的暂存区，每个字段都按元数据声明的类型落地。目标端配置为 写入空操作，POST 一个空请求体，作用是触发一次标准的"拉取-落地-可被订阅"闭环。

关键字段对照：

注意源端把 FId.FNumber 这种带点的复合字段，在中间层用下划线展平成 FId_FNumber，这是金蝶 WebAPI 返回结构里非常常见的形态。

在轻易云上如何配置

进入轻易云数据集成平台的策略配置页，新建"查询类"策略，三处要点：

1. 源平台选择：选金蝶云星空（Kingdee.Cloud），API 选 executeBillQuery，method = POST，effect 标记为 QUERY。这里一定要勾上 autoFillResponse: true，让平台自动把响应字段映射成中间层 schema，省掉手工建表。
2. 目标平台选择：选轻易云集成平台自身（datahub），API 选"写入空操作"，request 与 response 都留空。idCheck 设为 true，保证重复拉取时按主键去重，不会把字典撑爆。
3. 元数据声明：把上面那张字段表完整录入，is_required 一律 false，因为辅助资料字段普遍可空；如果漏标，后期字段对不上排查起来非常痛苦。

另外有个细节：buildModel 保持 false，不让平台自动建模——辅助资料的结构由金蝶侧控制，我们只做"忠实搬运"，不要让平台替我们猜。

实施步骤

我们把这个策略拆成三个阶段上线，客户现场跑下来的节奏大致是这样：

第一步：增量起点对齐。上线前先用一次全量拉取作为基线，把金蝶侧所有辅助资料一次性灌进中间层。手动触发一次即可，不必放进调度。

第二步：调度频率设定。源端 crontab 设为 34 3 * * *（凌晨 3 点 34 分），目标端空写入设为 23 2 * * *（凌晨 2 点 23 分）。两段时间错开，是为了让"目标空写入"先于"源端再次拉取"完成——轻易云客户里常见的应对模式之一就是"表头表体分阶段"，这里我们借用思路，把"落地动作"和"拉取动作"分到不同时间窗，避免并发写。

第三步：依赖与可观测。这一策略不依赖其他策略（depends_on: []），但下游所有同步策略都隐式依赖它。建议在轻易云上挂一个运行看板，每天看一眼"目标空写入"是否成功——一旦它失败，下游 9 个策略拿到的字典就会是陈旧的。

踩坑复盘

踩坑 1：复合字段没展平。第一次跑的时候，FId.FNumber 原样进了中间层，下游策略按 FId_FNumber 查，全是 null。稳妥的做法是在元数据里就声明展平后的字段名，不要等下游报错了再补。

踩坑 2：idCheck 没开。某次金蝶侧返回里夹了一条重复编码的脏数据，没开主键校验直接把中间层写出了两行，下游按主键 join 时随机取一行——典型翻车。

踩坑 3：autoFillResponse 与手工 schema 混用。早期版本里我们既勾了自动填充又手工改了字段，结果两边对不上，运行不报错但字段全是空。建议二选一：要不就纯自动，要不就纯手工。

踩坑 4：调度时间撞车。源端和目标端如果都用同一时刻触发，并发写入时偶尔会出现中间层"读到一半"的脏读。错开 1 小时以上基本能规避，这也是轻易云客户里常见的"增量与全量双轨"思路的延伸。

踩坑 5：把"空写入"理解成"不写"。其实空写入是一次完整的事务边界，轻易云靠它来触发订阅通知和后续策略。如果误配成"跳过"，下游根本不知道字典已经更新。

适用场景与不适用场景

适用：基础资料字典需要做权威源对齐、下游多个写入策略都要引用同一份参照、源系统字段含复合结构需要展平后再分发。

不适用：辅助资料本身变动频繁到分钟级（应改用实时事件触发）、源系统没有稳定的 WebAPI 查询接口、或者字典体量极小不值得单独建一个策略。