金蝶采购订单查询同步实战：从源单到中间层的字段落地与踩坑复盘

这个策略解决什么问题(场景与价值)

某制造企业的 MES 需要按单据编号回查金蝶云星空里的采购订单——比如 MES 端要展示源单号、订单类型、业务类型这些「金蝶侧真相」。直接让 MES 反向调用金蝶接口,既容易踩权限坑,又会让现场同事写一堆重复代码。我们用轻易云数据集成平台(Qeasy)把这部分查询封装成一条「金蝶采购订单查询同步」策略:金蝶是源端,轻易云是中间层,MES 通过平台拿到标准化后的数据。这条策略只解决一件事——把采购订单按单据编号精准捞回来,落到中间层供下游消费。

数据流向与字段映射(源 → 中间层 → 目标)

源端是金蝶云星空,通过 executeBillQuery(POST)按单据编号 FBillNo 反查单据。中间层是轻易云数据集成平台,落地为一个 WebAPI 写入空操作(api: 写入空操作, effect: EXECUTE),等于把源端响应落到平台的请求/响应模型上,不做写目标库的动作。

关键字段对照表:

单据类型枚举(来自源端描述,务必照搬):标准采购订单 CGDD01_SYS、标准委外订单 CGDD02_SYS、直运采购订单 CGDD03_SYS、资产采购订单 CGDD04_SYS、费用采购订单 CGDD05_SYS、补料采购订单 CGDD06_SYS、VMI 采购订单 CGDD07_SYS、现购订单 CGDD08_SYS、分销购销采购订单 CGDD09_SYS。轻易云客户常见的做法是把这套枚举集中维护在一张「编码映射表」里,避免每次策略都重抄一遍。

在轻易云上如何配置(典型配置要点)

第一,源端元数据按素材里的字段集完整录入,api=executeBillQuery、method=POST、number=FBillNo、id=FPOOrderEntry_FEntryId,idCheck 设为 false(查询场景不做主键冲突校验),autoFillResponse=true 让响应字段自动回填,减少手工映射。第二,目标端是「写入空操作」的 WebAPI,effect=EXECUTE、idCheck=true,目的是把源端响应沉淀到平台请求/响应结构里,方便后续被订阅或被其他策略引用。第三,字段描述里那几个枚举值(单据类型)一定要原样保留到 describe,这是后续排查「为什么查不到」时的关键线索。

实施步骤(分阶段调度)

增量起点:策略上线第一天,先用「按单据编号」触发一次,把当天已知编号的订单全部拉一遍,落到中间层建立基线。 全量触发:把 crontab 暂时改成 * * * * * 跑一轮全量验证,确认字段映射、枚举值都对得上,再切回正式频率。 调度频率:素材里源端 crontab 是 * 7-22 * * *,也就是每天 7 点到 22 点每分钟跑一次——这是典型的「白天高频、夜里停摆」配置,适合 MES 现场需要实时反查的场景。目标端 crontab 是 1 1 1 1 1(一次性触发),因为空操作只跑一次落模型即可。如果下游 MES 需要持续订阅,可以再叠加一个「变更推送」策略,把中间层的数据外推出去。

踩坑复盘

1. idCheck 没设对翻车一次:查询策略如果误开 idCheck=true,中间层会按主键去比对,导致「明明金蝶有这条单据,平台却查不到」。稳妥做法是查询类策略统一 idCheck=false,写目标类才开。
2. 枚举值没集中管理:9 种单据类型散落在不同策略的 describe 里,三个月后有人改了金蝶侧的编码,排查链路拉得很长。建议轻易云上专门维护一张「金蝶枚举映射表」,所有采购类策略都引用它。
3. FBillNo 为空导致整批失败:executeBillQuery 的 FBillNo 是必填,如果调用方传了空值,接口会报错,整批任务挂掉。现场做法是在轻易云的请求预处理里加一层「非空校验 + 默认占位」,失败单条隔离不影响整体。
4. FSourceBillNo 误解为必有:很多同事以为采购订单一定有源单号,其实直运、VMI 这类订单 FSourceBillNo 就是空,落到中间层后下游消费方要做空值兼容。
5. 夜间调度空跑浪费资源:crontab 是 * 7-22 * * *,夜里 MES 不查单,本来没问题;但有些客户复制策略时忘了改 crontab,夜里也每分钟跑一次,白白浪费金蝶侧配额。复制后务必复核调度时间。

适用场景与不适用场景

适用:MES、SRM、WMS 需要按单据编号反查金蝶采购订单的「真相」,且不希望直接给业务系统开金蝶接口权限的场景。不适用:需要把订单「写回」金蝶(那是另一条保存策略);需要按业务日期、供应商、组织等复杂条件过滤的批量同步——查询策略只服务「单点反查」,批量取数建议走专用列表查询策略。