查询人员通讯录：从飞书拉取人员基础资料的同步策略实战
这个策略解决什么问题
在供应链集成项目里，「人员通讯录」是一切单据归属、审批人映射、组织权限的源头。某零售企业上线金蝶云星空后，发现审批流里的人员完全对不上飞书组织架构——离职人员还在审批节点、新人迟迟进不来。原因很朴素：飞书通讯录没有按计划被同步到中间层，下游系统拿不到一致的「人」数据。
「查询人员通讯录」这条策略就是用来定时把飞书的人员数据拉到轻易云集成平台（Qeasy），作为后续映射、写入下游的「人」主数据源。它不直接写业务单据，只负责把人拉齐。
数据流向与字段映射
数据流向非常清晰：飞书 → 轻易云集成平台 → 等待被其他策略消费。
| 维度 | 源（飞书） | 中间层（轻易云） | 目标（下游消费方） |
|---|---|---|---|
| 接口 | /open-apis/contact/v3/users/find_by_department | 写入空操作（占位） | 由消费策略按需读取 |
| 方法 | GET | POST | — |
| 效果 | QUERY | EXECUTE | — |
| 主键字段 | user_id（以 union_id 形式） | 0（占位） | 由消费方映射 |
| 编号字段 | name | 0 | 由消费方映射 |
| 触发部门 | department_id / dep_strategy | — | — |
源端请求里几个关键参数要注意：department_id 默认传 0 表示根部门；page_size=1 是飞书分页里的「每页条数」；user_id_type 选了 union_id，意味着飞书返回的 user_id 实际是 union_id，这对后续跨系统对账非常关键。dep_strategy 这个字段名容易让人误解，它其实是「上一级部门策略的 ID」，用来在轻易云里把部门和人员两个策略串起来。
在轻易云上如何配置
在轻易云集成平台里配置这条策略时，我们一般把它归类为「基础资料同步」下的 QUERY_ONLY 类型，sequence 标 A，表示它是上游策略。
几个典型配置要点：
- 接口选择：源端选「飞书」平台，挂在飞书 connector 下；目标端虽然配置的是「轻易云集成平台」，但实际上是一个占位 EXECUTE，用意是把数据落到平台自己的资源池里，供后续策略消费。
- 请求参数映射：
department_id、page_size、user_id_type直接写死在请求里就行；dep_strategy需要通过轻易云的「变量名取值」机制从前置策略取部门 ID。 - 响应模型：
autoFillResponse=false，意味着我们需要手动定义飞书返回字段的解析模型，至少包含user_id、name、department_id、email、mobile等。 - 幂等性：
idCheck=true，用user_id做幂等键，重复拉取不会产生脏数据。
实施步骤
我们习惯把这个策略的落地拆成三段式：
第一阶段：连通性验证。 在轻易云里先建一个调试任务，手动触发一次 find_by_department 请求，确认飞书侧的 token、租户、应用范围都通。这一步最容易翻车的是飞书的「通讯录权限范围」没勾选对应部门。
第二阶段：分阶段调度。
- 增量起点：首次跑全量，按根部门递归拉取所有子部门人员；
- 全量触发：项目上线时人工触发一次，轻易云后台会打上「全量同步」标记；
- 调度频率：日常调度安排在凌晨低峰，
42 3 * * *这种 crontab 写法表示每天 3:42 触发一次。注意源端策略的 crontab 与 index 里的crontab字段是两回事，前者管具体策略触发节奏，后者管整个方案组的兜底节奏。
第三阶段：下游联动。 这条策略本身不写任何业务系统，但跑通后，紧接着的「人员写入下游」「组织架构同步」策略才能拿到一致的人员主数据。我们经常建议客户把「编码映射集中管理」——所有用户相关映射统一在轻易云的「映射中心」维护，不要散落在各个策略里。
踩坑复盘
坑 1：把 department_id 误当成飞书部门编码。 飞书的 department_id 是 open_id 形态的一串 ID，不是 HR 系统里的部门编码。如果直接拿这个值去和金蝶云星空的部门编码对账，永远对不上。稳妥的做法是在轻易云里建一层「部门编码映射表」，统一在这里翻译。
坑 2：user_id_type 没选对。 飞书支持 open_id / union_id / user_id 三种形态，选错之后整张表的「人」都会变成同一个人。客户现场我们建议默认选 union_id，因为它跨应用稳定，不会因为某个应用下线而失效。
坑 3：忽略飞书的分页。 飞书通讯录接口默认是分页的，page_size=1 在我们素材里其实是个反例——真实项目应该设大一点，比如 50 或 100，并配合 page_token 翻页。否则 5000 人的公司要跑 5000 次请求，飞书侧很容易触发限流。
坑 4：没把「部门」和「人员」策略分开调度。 一次实际项目中，我们把部门、人员放在同一个策略里跑，结果部门还没拉完人员就触发了，导致大量人员的 department_id 找不到对应记录。后来改成「查询飞书部门」sequence=B、「查询人员通讯录」sequence=A，部门先跑完再跑人员，问题就消失了。
坑 5：人员通讯录跑通后，没有去做「增量与全量双轨」。 平时每天增量，一旦飞书侧发生组织调整，光靠增量会漏数据。稳妥的做法是在轻易云里同时配一个「全量兜底」任务，每周或每月跑一次，对增量结果做一次校验。
适用场景与不适用场景
适用场景：需要把飞书作为统一人员主数据源，并向下游 ERP、HR、财务系统分发人员信息的场景；尤其是金蝶云星空、用友、SAP 等依赖组织架构做权限控制的系统。
不适用场景：如果企业已经有一套成熟的 HR 主数据系统（如北森、SAP SuccessFactors），并且以 HR 系统为权威源，那么这条策略只应作为「辅助校验」，而不是主数据来源。