HR人员更新同步钉钉：方案设计与字段映射
功能概览
我们设计这个功能的初衷是解决HR主数据变更后，钉钉通讯录无法及时更新的问题。在中大型组织里，员工入职、转岗、合同主体调整等事件每天都在发生，如果依赖人工维护钉钉，既容易遗漏，也很难保证扩展属性的完整性。
「HR人员更新同步钉钉」是轻易云数据集成平台内置的一条标准同步策略模板，部署在DataHub的方案库中。它的核心职责是：以MySQL侧的HR员工表为源，调用钉钉开放平台的 topapi/v2/user/update 接口，将增量变更回写到钉钉用户的扩展属性 extension 中。
方案的数据流向是 MySQL → 钉钉，同步模式为「增量」。增量条件基于员工表的 upd_time 字段，并设置 15 天缓冲窗口，避免因时钟漂移或短窗口漏数。默认调度建议源端每 30 分钟一次，目标端错峰 3 分钟，避免两端在同一秒发起请求。
使用场景
典型使用场景是：HR系统作为人员主数据的唯一来源，钉钉作为协同办公的身份底座。当员工发生以下变更时，HR侧会写入新记录并打上 upd_time，本方案负责把这一次变更同步出去：
- 合同主体（合同公司）变更，例如员工从子公司A转入子公司B。
- 后续扩展，例如把工号、岗位、入职日期写入钉钉
extension。 - 修复因历史原因造成的钉钉扩展属性缺失或错误。
需要特别强调的是：本方案只负责「更新」，不负责「新增」和「离职」。新增员工和离职清理需要由配套的人员新增、人员离职同步策略承担，避免一个策略承担过多职责导致维护困难。
配置说明
1. 源端对象
源端由三张表关联而成：
base_user：员工主表，提供dingtalk_user_id、name、upd_time、whether_in_office等关键字段。file：员工附件/档案表，提供头像或编号等扩展信息。base_contract_company：合同公司表，提供company_name。
过滤条件共三条，缺一不可：
a.whether_in_office = 1：仅同步在职员工。a.dingtalk_user_id is not null：员工必须已经绑定钉钉，否则更新接口无法定位用户。c.company_name is not null：必须有合同公司，避免把空值写入扩展属性。
2. 目标端对象与映射
钉钉侧的目标对象是「通讯录用户」，使用 topapi/v2/user/update 接口更新扩展属性。当前方案只映射了两个字段：
| 目标字段 | 源字段/规则 | 映射类型 | 说明 |
|---|---|---|---|
| userid | dingtalk_user_id | DIRECT | 钉钉员工唯一标识，用于定位待更新用户 |
| extension | — | CONSTANT/null | 当前配置为空；若需同步公司信息，可映射为 {"公司": "{{company_name}}"} |
DIRECT 表示直接用 {{源字段}} 插值；CONSTANT 表示固定常量；COLLECTION 表示通过编码表查找；TRANSFORM 表示通过表达式或函数转换。当前方案以直接映射为主，不使用编码表。
3. 钉钉 extension 扩展字段的前置配置
钉钉 extension 是一个对象类型字段，最大长度 2000 字符。在使用本方案之前，必须先在钉钉管理后台的「通讯录 → 内部通讯录设置 → 成员字段管理」中预先添加对应的扩展属性（例如「公司」）。否则即使轻易云侧配置正确，接口调用也会因为目标端字段不存在而失败。
此外，钉钉的更新接口语义是「全量替换」：调用时未传入的扩展属性会被清空。因此若未来要同时同步公司、工号、岗位等多个扩展字段，需要在模板里把所有字段一次性映射齐全。
4. 调度与增量窗口
默认推荐：
- Source（源端）：
2-59/30 * * * *，从每小时的第 2 分钟开始，每 30 分钟一次。 - Target（目标端）：
5-59/30 * * * *，从每小时的第 5 分钟开始，错峰 3 分钟。
增量窗口使用表达式 a.upd_time > adddate(:upd_time, -15) 实现 15 天缓冲。15 天的设计是为了应对以下异常：
- 源端时钟比目标端慢；
- 源端某条记录的
upd_time因为手工修复而被回写； - 上游批量任务在凌晨集中写入，但调度没有捕获。
注意事项
- 本方案不做新增和离职：不要试图在
extension之外扩展新增/删除逻辑，请使用专用的人员新增、人员离职策略。 - extension 是替换语义：每次调用都会覆盖目标用户的所有扩展字段，务必保证映射完整。
- 必须先在钉钉后台建字段：轻易云侧无法替你在钉钉后台注册自定义字段，缺少这一步会导致同步失败但不易察觉。
- 过滤条件缺一不可：尤其要注意
whether_in_office = 1，否则离职员工的旧数据可能回写到钉钉。 - 错峰调度是建议值：当目标系统不止一个（例如同时写钉钉和企微）时，可进一步拉大两个 Target 的间隔，避免限流。
- 扩展字段 key 必须和后台一致：例如后台配置的是「公司」，模板里写「公司名」会写入失败。
- 当前未使用
_findCollection、_mongoQuery、_function：如未来需要按外部单号联查、做条件分支或格式转换，可参考DataHub的进阶应用文档引入这些能力，而不必新建策略。
按上述配置完成后，HR侧的员工主数据变更会以 30 分钟为周期、稳定地回写到钉钉通讯录的扩展属性中，从而保持两个系统之间的数据一致。