学员主数据从 VC 文档同步到金蝶云星空:一个策略的实战拆解

这个策略解决什么问题

学员主数据从源系统推到金蝶云星空,看似只是「拉一组列表写进去」。但客户现场真正折磨人的,是分页、编码映射、组织默认值这三个细节。我们用轻易云数据集成平台(Qeasy)承接之后,把它收成一个 A→B 的单策略,目标是把源端的学员列表稳定地落到金蝶的「客户」档案上,后续业务单据直接引用,不再让运营手工补录。

数据流向与字段映射

源端是一个标准的 WebAPI 分页查询接口(/v3/students,GET),通过 X-Page-Size 与 X-Page-Number 两个请求头翻页,每页 1000 条。目标端是金蝶云星空的 batchSave 执行接口(POST),按客户档案写入。

中间层是轻易云的策略引擎,负责拉取、清洗、字段拼装、落库与回写。关键字段对照如下:

FName 在金蝶侧是多语言结构(1033 / 2052 等),模板里要用 JSON 数组写法,把姓名按语言分别塞进去,而不是塞一个字符串,这是金蝶 batchSave 接口的硬性约定。

在轻易云上如何配置

在轻易云集成平台里,这套策略只配一条源、条目标,加一个调度,不需要写脚本。

源端配置。API 选 /v3/students,GET,idCheck=true。number 指向 first_name 只是为了让元数据里有可识别的业务键,真正幂等键是 id。请求参数里固定 X-Page-Size=1000、X-Page-Number=1 起跑,翻页由平台自动接管。响应里把 id / first_name / middle_name / last_name 这几个字段都勾出来,方便下游引用。

目标端配置。API 选 batchSave,POST。FNumber={{id}},FName 用多语言模板拼成三段:{{first_name}} {{middle_name}} {{last_name}},中间有空值时,稳妥的做法是在模板里用空字符串兜底,而不是直接拼出多余空格。FCreateOrgId 和 FUseOrgId 都写常量 102,别忘了它们——少了 FUseOrgId,金蝶会报组织必填。

映射策略。轻易云客户常见的做法是把编码映射集中管理,放成一张映射表,本策略只引用不维护,后续家庭、订单等策略共用同一张表,改一处全部生效。表头表体分阶段也值得提一句:本期只是「学员档案」表头写入,后续如果要把学员与家庭的关联关系带进来,建议拆成第二条策略,不要把家庭号硬塞进学员接口里。

实施步骤

1. 冷启动全量:第一次上线,源端数据量可控时,直接用全量分页拉取跑一遍,把基准客户档案铺到金蝶。这一步建议放在业务低峰期,避免 batchSave 写满冲掉正常单据。
2. 增量起点:以源端 id 为游标记录增量起点。轻易云的增量与全量双轨模式很适合这种场景——后台始终按游标跑增量,需要时一键切回全量校验。
3. 调度频率:源端 crontab 写成 1 7,12,16,20 * * *(每小时档的 1 分),目标端延后半小时,写成 30 7,12,16,20 * * *,留出网络和分页的窗口。
4. 上线观察:连续跑三个调度窗口,盯住分页是否翻完、写入是否报错、组织字段是否为空。
5. 纳入运维:把这条策略纳入日常巡检,异常重试交给平台处理,不再需要人工盯。

踩坑复盘

1. FName 写成纯字符串。金蝶 batchSave 期望的是多语言 JSON 数组,不是单个字符串。我们第一次配的时候图省事直接拼,返回 200 但档案名称为空,排查花了大半天。
2. FUseOrgId 漏配。很多同学只配 FCreateOrgId,以为「使用组织」会默认带出来。金蝶不会替你猜,缺这个字段直接拒收。
3. middle_name 空值拼出多余空格。如果中间名是空,直接拼接会变成「张 三」,姓名里多一个空格,后续报表对不齐。稳妥的做法是模板里做空值跳过,或者用统一的三段拼接函数处理。
4. 分页只跑第一页。X-Page-Number 写死成 1,源端数据超过 1000 条就丢。轻易云的分页器会自动按响应里的总页数翻,不要在源端配置里手动改这个值。
5. 幂等键选错。用 first_name 当幂等键,遇到同名学员就会互相覆盖。这里 id 才是源端唯一键,FNumber 直接透传 id 就对了。

适用场景与不适用场景

适用:源端有标准分页查询接口、目标端是金蝶云星空、需要把外部主数据沉淀为客户/学员档案。不适用:源端数据需要复杂清洗(如合并家庭、合并地址)、或目标端要触发审批流而非直接落档的场景——后者建议拆成「先落草稿,再触发审核」的两段式。