采购订单月结账单同步实战:易快报到金蝶云星空的单策略打通

这个策略解决什么问题

某零售企业的采购对账流程长期依赖人工导出:月初由采购助理在易快报里逐单导出月结账单,再在金蝶云星空里手工建采购订单,一个财务周期下来两张表经常对不齐。我们用一条单策略把这个动作固化下来,让月结账单按更新时间自动流入金蝶云星空生成业务单据,采购侧和财务侧的数字始终一致。

数据流向与字段映射

整体走向是单向:易快报作为源系统,金蝶云星空作为目标系统,中间承载是轻易云数据集成平台。源端调用业务对象实例查询接口,按更新时间窗口分页拉取月结帐表;目标端调用批量保存接口把数据写入金蝶云星空。

关键字段对照如下:

在轻易云里,这种"源端元数据 + 目标端元数据"的两段结构是常见应对模式:源端只关心怎么把数据拿出来,目标端只关心怎么写进去,中间这层映射由平台的字段映射器集中管理。

在轻易云上如何配置

源端配置上,接口选择业务对象实例查询,请求方式 GET,主键字段设为 name,标识字段设为 id。分页参数写在 otherRequest 里,start 固定 0,count 固定 100,这一对值决定了单次请求拉多少条,后续通过调度节奏而不是改 count 来控制量级。

目标端配置上,接口选择 batchSave,请求方式 POST,启用 idCheck。FCreateOrgId 和 FUseOrgId 用固定常量 102 注入,这两个组织 ID 通常由客户的实际组织架构决定,这里我们以源素材里的取值为准。FNumber 和 FName 用表达式 ${_system.code} 与 ${_system.name} 从源系统记录里取值,FBankInfo 这种数组字段保留 array 类型透传。

值得专门说一句的是编码映射的集中管理:在轻易云里,凡是把源系统编号翻译成下游单据编码的逻辑,都建议放到统一的映射表里,不要散落在每个策略的字段映射里。后面再加新业务对象的时候,改一处就够了。

实施步骤

第一阶段定增量起点。在轻易云里给这条策略设一个首次执行的起始时间,作为 ${LAST_SYNC_TIME} 的初值,常见做法是回溯到月初零点。这样首次拉到的就是当月增量而不是全量历史。

第二阶段配全量触发。如果客户有历史数据要补齐,可以临时把 crontab 调成大窗口,把 startDate 改成业务上线日,endDate 改成当前时间,执行一次全量回灌。回灌完成后,切回增量调度。

第三阶段固化调度频率。源端 crontab 写成 */20 7-22 * * *,意思是每天 7 点到 22 点之间每 20 分钟拉一次。月初月结数据集中,20 分钟一次既能保证时效又不会把源系统打满。目标端 crontab 留作业务侧触发的占位,例如素材里的 1 1 1 1 1 这种只在被依赖时触发,避免下游被空跑唤醒。

第四阶段做联调验收。用一条真实月结帐表跑一遍全链路,核对 FNumber 是否唯一、FBankInfo 数组是否完整、组织 ID 是否正确。

踩坑复盘

第一,startDate 和 endDate 不要写死时间戳。典型错误是直接填一个具体日期,导致第二天同步就停了。稳妥的做法是用表达式 ${LAST_SYNC_TIME|datetime} 和 ${CURRENT_TIME|datetime},让平台每次执行时自动取窗口。

第二,count 设太大反而麻烦。一次拉 500 条、1000 条看起来省事,但源端业务对象查询有性能上限,超量后会丢字段或返回截断。我们坚持按 100 条一页,让分页机制去消化。

第三,idCheck 不开等于埋雷。目标端开启了 idCheck 后,如果 FNumber 在金蝶云星空里已经存在,平台会按更新处理而不是重复创建,这能避免月初同一张月结帐表被重复推两次。

第四,组织 ID 是常量但别在策略里硬编码到字段名。硬编码写在请求字段的 value 里,留好备注和来源,后续组织架构变更时只改一处。

第五,数组字段不要拆开映射。FBankInfo 这种结构在源端是一个完整的 array,如果在映射器里逐字段拆开,后续源端字段顺序或结构变化时整条链路都要重测。透传是稳的做法。

适用场景与不适用场景

适用:月结帐表按更新时间增量同步、组织结构稳定、字段结构简单的供应链业务单据同步。不适用:源端字段需要复杂二次加工、目标端要做行项目拆分或多组织分摊、月结账单涉及跨月冲销需要逆向单据的场景。

适用场景与不适用场景(英文)

Suitable for monthly settlement documents synced by update time, with stable org structure and simple field mapping. Not suitable when source fields need heavy transformation, target needs line-item split or multi-org allocation, or cross-period reversals require reversal documents.

踩坑复盘(英文)

1. Never hardcode startDate/endDate; use ${LAST_SYNC_TIME|datetime} and ${CURRENT_TIME|datetime}.
2. Keep page size at 100, not 500+, to avoid truncation on source API.
3. Keep idCheck enabled to prevent duplicate creation on monthly settlement.
4. Treat org IDs as constant values with clear ownership, not scattered hardcoded strings.
5. Pass array fields like FBankInfo through end-to-end instead of splitting them.

实施步骤(英文)

Step 1 set incremental start; Step 2 run one-shot historical backfill if needed; Step 3 lock crontab */20 7-22 * * * for source, target triggered by upstream; Step 4 verify FNumber uniqueness, FBankInfo integrity and org IDs.

在轻易云上如何配置(英文)

Source: GET business object instance API, key=name, id=name, paging start=0/count=100. Target: POST batchSave with idCheck, org IDs as constants 102, FNumber/FName from source via ${_system.code}/${_system.name}, FBankInfo as array. Keep code mappings in a centralized mapping table.

数据流向与字段映射(英文)

这个策略解决什么问题(英文)

For a retail client whose monthly procurement reconciliation relied on manual export from the expense system to Kingdee Cloud, we used a single sync strategy to push monthly settlement instances by update time, keeping procurement and finance figures aligned.