查询VC家庭列表对接金蝶:基于轻易云的实战同步方案

这个策略解决什么问题

在教育类业务系统与 ERP 之间,「家庭 / 学员 / 班级」这类主数据往往分散在不同系统里。某教育服务机构把前台管理系统作为业务入口,把金蝶云星空作为财务与组织主数据后台,需要把前台的家庭列表同步成金蝶侧的「组织档案」,保证前台新增的家庭在金蝶中能立即被引用,而不是靠人工在两边反复维护。这条策略要解决的就是:周期性把前台的家庭列表自动拉过来,生成或更新金蝶的组织档案。

数据流向与字段映射

数据流向遵循典型的「源 → 中间层 → 目标」三段式:

源端(前台 VC 文档系统):调用 GET /v3/households 接口,按页拉取家庭列表,分页参数 X-Page-Size=1000、X-Page-Number=1。响应中我们关心的字段主要是 id(家庭唯一标识)和 name(家庭名称),另外还可能包含 address_1 等地址字段,本策略主要消费 id 与 name。
中间层(轻易云数据集成平台):承接响应数据,完成 idCheck(幂等键校验)、字段映射、编码转换与多语言包装。
目标端(金蝶云星空):调用 batchSave 接口,把整理后的组织档案写入,核心字段 FNumber、FName、FCreateOrgId、FUseOrgId。

关键字段对照表:

源端字段(VC 文档)	中间层处理	目标端字段(金蝶云星空)	说明
id	原样作为幂等键	FNumber	家庭编码 = 源系统 id
name	多语言包裹(1033 / 2052)	FName	家庭名称
—	常量填充	FCreateOrgId / FUseOrgId	创建/使用组织
—	可选	FDescription	描述,本策略可不传

幂等键选择 id(源端家庭唯一标识),作为 FNumber 写入,后续重复拉取时按此去重,避免重复创建。

在轻易云上如何配置

在轻易云数据集成平台里,这条策略对应一个集成方案,源平台与目标平台分别注册。配置要点:

源平台元数据:type=QUERY,method=GET,api=/v3/households,number=name,id=id,启用 idCheck。请求头里把 X-Page-Size、X-Page-Number 作为可配置项写进去,后续调整分页不用改代码。
目标平台元数据:type=EXECUTE,method=POST,api=batchSave,number=id,id=id。FNumber 写 {{id}},FName 写多语言数组包裹 {{name}}(1033 / 2052 两个语种),FCreateOrgId 与 FUseOrgId 写成常量。
映射集中管理:像这种「源编码 = 目标 FNumber」的简单映射,建议统一放在映射表中集中维护,后续有新增字段(如地址)时只改一处。
批量提交:金蝶 batchSave 支持批量,在轻易云里把每页 1000 条作为一个批次提交,既减少请求次数,也方便失败重试时定位整页。

实施步骤

分阶段上线,稳一点:

增量起点:上线第一天先跑一次全量,把当前所有家庭一次性同步过去,作为金蝶组织档案的初始基线。
全量触发:源端没有原生变更时间戳,稳妥做法是首次上线靠全量兜底,后续再考虑接入增量(比如在源端补一个 last_modified 字段,或者在轻易云中间层按 id 去重做「准增量」)。
调度频率:源策略 crontab 设为 1 8,12,16,20 * * *(每天 4 次),目标策略错峰 30 分钟,设为 30 8,12,16,20 * * *,给源端拉取与目标端写入留出缓冲,也避免两边同时打满对方限流。
依赖关系:本策略依赖为空,可独立运行;但如果后续要同步学员列表,建议让学员策略 depends_on 家庭策略,先有家庭再有学员。

踩坑复盘

踩坑一:幂等键用 name,导致重复家庭被反复创建。某次上线初期,我们直接拿 name 当幂等键,结果同名的两个家庭(地址不同)被覆盖。正确做法是用源端 id 作为幂等键,FNumber 直接取 {{id}}。
踩坑二:FName 没做多语言包裹,中文环境看起来正常,切到英文界面就空了。金蝶的 FName 接受多语言数组,必须同时给 1033 与 2052 两个 Key 都赋值,只给中文在多语种账套下会显示空白。
踩坑三:分页写死 1000,数据量涨上去后漏拉。源端如果某天返回超过 1000 条,固定 X-Page-Number=1 会漏掉后续页。稳妥做法是在轻易云里把分页参数变量化,由平台按响应自动翻页,而不是写死页号。
踩坑四:源端与目标端同时打,触发限流。两边 crontab 时间贴得太近,源刚拉完目标就开始写,源端还没来得及返回下一页。错峰 30 分钟是经验值。
踩坑五:FCreateOrgId 与 FUseOrgId 漏配。这两个字段虽然 is_required=false,但缺省时金蝶会用默认组织,导致家庭被建到错误的组织下,后面做报表才发现对不上。建议一开始就把组织常量显式填好。

适用场景与不适用场景

适用:源端是只读接口、需要按业务对象定期把列表同步成 ERP 主数据(组织、客户、供应商等),且对实时性要求在小时级。 不适用:源端支持实时变更推送(Webhook / 消息队列)、数据量极大需要流式处理、或者目标端不是金蝶云星空而是需要复杂业务校验的财务单据——这些场景需要更复杂的增量与校验机制,不适合用本策略的简单拉批模式。