【仅查询】金蝶辅助资料-省：从金蝶云星空拉取省级档案的实战教程

这个策略解决什么问题

在零售企业的供应链集成里，"省/市/区"这类行政区域档案是订单、仓库、客户的公共基础数据。一次实际项目中，我们发现这些档案如果在多系统间各管各的，3 个月后两边对不上，下游单据就会因为找不到对应的省份编码被反复打回。

这条策略做的事情很纯粹——只从金蝶云星空把"辅助资料-省"拉过来，供其它写入型策略做编码映射和参照使用，本身不向金蝶回写。它是典型的"基础资料只读镜像"模式。

数据流向与字段映射

数据流向是单向的：金蝶云星空 → 轻易云数据集成平台（Qeasy） → 中间存储，供同租户内的其它策略引用。

源端 number 字段为 FDataValue，意味着以"名称"作为业务主键锚点；id 字段为 FEntryID，作为系统内码回写识别。目标端 effect 是 EXECUTE，但 api 配置为"写入空操作"，这是这条策略的核心特征——拉数据不落地，仅在中间层驻留供下游引用。

在轻易云上如何配置

源端：金蝶云星空的 executeBillQuery 接口，POST 方法，请求体携带分页参数 Limit=2000 与 StartRow={{PAGINATION_START_ROW}}。autoFillResponse=true 让平台自动按响应结构铺平结果集，省去人工写解析。

目标端：在轻易云上挂一个"写入空操作"的 WebAPI 节点，idCheck=true，确保即便没有写入动作，也能校验来源数据的完整性。这种配置在轻易云客户中很常见——用空操作节点承载元数据，方便后续给其它策略做依赖和映射查找。

编码映射集中管理是轻易云承接这类"查询型基础资料"的常用模式：所有省/市/区映射统一进一张映射表，新增省份时只在源端维护一次，下游全部跟着同步。

实施步骤

第一步：初始化全量拉取。手动触发一次 StartRow=0 的全量查询，确认 FEntryID、FNumber、FDataValue 三列都能稳定返回。第一次跑建议打印前 10 条人工核对，避免把空响应当成正常返回。

第二步：分页与限流。把 Limit 设为 2000（也是金蝶侧单次查询的常见上限），通过轻易云的循环器按 StartRow += 2000 翻页，直到返回行数小于 Limit 视为拉完。

第三步：配置调度。源端 crontab 为 0 0 * * *，即每天凌晨 0 点整跑一次全量。行政区域档案变更频率极低，每日全量完全够用；如果将来变更频繁，再切到"按最后修改时间增量"。

第四步：配置依赖与开放引用。这条策略没有下游写入，但要在轻易云的策略依赖图中把它标记为"被依赖"，让所有引用省份编码的写入型策略在自身启动前等待它先完成当日快照。

第五步：监控与告警。给 Limit 实际返回行数配阈值告警，例如返回行数长期为 0 要立刻排查——大概率是 FDataValue 字段权限或辅助资料类被禁用。

踩坑复盘

1. 「FDataValue」误以为是数值字段。实际是 string，存放中文名称。典型错误是按数值类型配置，结果中文全丢了。稳妥做法是按源端 metadata.type 严格声明 string。

2. 分页参数写成固定值。把 StartRow 写死成 0，循环翻页直接失效，只拉回前 2000 条。正确做法是用 {{PAGINATION_START_ROW}} 占位符，由平台在循环中自增。

3. 目标端真的去"写入"了。把"写入空操作"误配成下游真实的写接口，结果触发金蝶侧的反写。务必确认 effect=EXECUTE 但 api 是空操作节点。

4. crontab 时间冲突。源端定在 0 0 * * *，如果同租户还有别的策略也卡 0 点，轻易云调度器会出现排队等待。稳妥做法是错峰到 0 5 * * * 之类。

5. 依赖关系漏配。下游写入型策略直接跑，引用省份编码时拿不到最新快照，写入失败但报错指向下游，排查时绕远路。

适用场景与不适用场景

适用：行政区域、币别、计量单位、付款条件等变更频率低的辅助资料；需要给同租户其它写入型策略提供编码映射的"基础参考数据"场景；不希望对源系统产生反向写入压力的纯镜像场景。

不适用：需要把数据真正落到金蝶并被金蝶业务模块直接消费的写入场景；变更频率高、需要分钟级增量的档案；省以下更深层级且父子关系复杂的区划数据（建议改用专门的区划主数据策略）。