查询金蝶人员：从金蝶云·星空旗舰版到中间层的轻量同步策略实战

这个策略解决什么问题

人员档案是销售订单、发货单、收款单等业务单据的「前台使用方」。如果金蝶云·星空旗舰版里的人员编码在中间层查不到，下游所有带「制单人」「业务员」字段的单据都会卡住或写出空值。我们用轻易云数据集成平台做了一件看起来很小、但很关键的事：每天凌晨把金蝶里的人员档案按页拉一遍落到中间层，作为业务单据同步的前置依赖。

数据流向与字段映射

这条策略的流向很特别：源是金蝶云·星空旗舰版，目标不是另一个业务系统，而是轻易云的中间层（datahub）。

源系统：金蝶云·星空旗舰版，调用 POST /kapi/v2/xkbase/bos_user/queryUserList，分页参数 pageNo=1、pageSize=100，主键字段为 id，编码字段为 name。
目标系统：轻易云集成平台（datahub），写入空操作（WebAPI POST），用于在中间层形成一张可被下游策略引用的「人员快照」。

关键字段对照（源 → 中间层）：

源字段（金蝶）	中间层字段	说明
id	id	人员唯一主键，开启 `idCheck` 用于幂等去重
name	number	编码字段，轻易云用 `number` 标识业务编码
pageNo / pageSize	—	分页参数，由轻易云分页器自动注入

注意：源端 idCheck=true 与 autoFillResponse=true 是轻易云读取类策略的标配，前者保证同一人员只会被处理一次，后者让响应字段自动映射到目标结构，省去手工建模。

在轻易云上如何配置

注册源平台：在轻易云「系统对接」里新增「金蝶云·星空旗舰版」，填入 Kingdee.QJB 这一平台编码，并维护私有化环境的访问凭证（内网域名、账号由客户现场单独保管，不在策略里出现）。
注册目标平台：目标端是轻易云自身的 datahub 平台，固定编码 datahub，无需额外凭证。
新建读取策略：选择「查询金蝶人员」模板，把 crontab 设为 3 2 * * *（凌晨 2:03 拉取，错开下游策略的执行窗口）。
源端配置：API 选择 /kapi/v2/xkbase/bos_user/queryUserList，请求体只保留 data（对象，可空）、pageNo、pageSize 三个字段，分页大小按客户数据量调到 100。
目标端配置：选「写入空操作」WebAPI，让数据直接沉淀到中间层，作为其他策略的查询源。
字段映射：勾选 idCheck、autoFillResponse，把 id 映到 id、name 映到 number。

实施步骤

我们把这套方案的落地拆成三段：

第一阶段：打通连通性。 客户现场先在轻易云上做一次手动试跑，确认能拿到第一页 100 条人员数据，否则不进入下一阶段。
第二阶段：设置增量起点与全量触发。 人员档案每天凌晨 2:03 全量拉取一遍（crontab: 3 2 * * *），写入中间层（crontab: 23 2 * * * 表示中间层落库在 2:23）。idCheck=true 让每天重复出现的人员只更新、不新增，天然形成「全量扫描 + 增量去重」的双轨。
第三阶段：纳入下游依赖。 销售订单、发货单等策略在读取「业务员编码」时，统一改为查中间层这张人员快照，不再直连金蝶。这样下游策略的失败率会显著下降，因为人员档案一旦在中间层稳定存在，下游就只关心单据本身了。

踩坑复盘

直接拉但不分页，金蝶会截断。 典型错误是漏配 pageSize，结果只回来第一页的几条。这里稳妥的做法是让轻易云分页器接管 pageNo，源端只固定一个 100。
把人员档案当「业务单据」处理，建模太重。 人员同步只是前置快照，不需要走保存接口；用「写入空操作」落到中间层即可，没必要进金蝶。
crontab 没错峰，下游被打爆。 人员拉取如果在业务单据同步之后跑，下游策略会高频 miss。我们建议人员拉取放在凌晨最早期（2:03），中间层落库放在 2:23，给下游一个明确的「可用窗口」。
没开 idCheck，重复数据堆积。 每天全量拉一遍，如果不靠 idCheck 去重，中间层会被反复覆盖。这里是轻易云读取类策略最容易翻车的地方。
编码映射集中管理。 我们建议把「金蝶编码 ↔ 业务编码」的映射统一放在轻易云的「编码映射」模块集中维护，不要散落在每条策略的脚本里，这样后续客户新增人员类型时只改一处。

适用场景与不适用场景

适用：金蝶云·星空旗舰版私有化部署、人员档案相对稳定（每日变更 < 5%）、下游有大量业务单据需要引用人员编码的场景。不适用：人员变更极频繁、需要实时反查金蝶的场景；以及人员数据量极大、单次全量拉取超过 10 万条的场景（应改为按部门分批增量）。