外部目录同步
本章介绍如何将钉钉、企业微信、飞书或 LDAP 中已有的组织架构同步至本实例，包括来源配置、差异审阅与应用、认领处理、角色同步。
权限要求：本功能的全部操作仅超级管理员可执行。
1. 同步机制
理解以下三点是正确使用本功能的前提。
全量拉取，人工确认后落库
每次同步都会从外部系统拉取完整的组织快照，与本实例的绑定关系比对后计算出差异。系统不提供增量同步。
同步分为两个阶段，中间必须经过人工确认：
同步预览（拉取并计算差异，不改动任何数据） → 人工审阅并勾选 → 应用（写入数据）点击「应用已选」之前的所有操作均不会改动实例数据。
仅支持配置一个来源
本实例只能配置一个外部组织来源，四类来源（钉钉、企业微信、飞书、LDAP）择一使用。
外部标识不进入业务数据
外部系统的标识与实例内对象的对应关系保存在独立的绑定关系中，外部标识本身不会写入部门或用户的业务信息。
2. 配置来源
功能入口：控制台 →「组织同步」。
2.1 通用配置项
| 配置项 | 输入方式 | 说明 |
|---|---|---|
| 来源类型 | 下拉选择 | 钉钉、企业微信、飞书、LDAP |
| 企业 ID | 文本输入 | 按来源类型填写，见 2.2 |
| 应用 ID | 文本输入 | 按来源类型填写，见 2.2 |
| 密钥 | 密码输入 | 直接粘贴密钥值。详见 2.3 |
| 权威模式 | 下拉选择 | 决定同步冲突时以哪一方为准，详见第 5 节 |
| 匹配策略 | 下拉选择 | 决定发现疑似同一对象时的处理方式，详见第 4 节 |
| 锚点部门 | 选择 | 指定外部组织挂载到本实例的哪个部门之下。默认「未设置（默认挂到公司根）」 |
| 登录来源码 | 文本输入 | 用于标识这批用户的登录来源 |
| 备注 | 文本输入 | 选填 |
2.2 各来源的填写对应关系
| 来源类型 | 企业 ID | 应用 ID | 密钥 |
|---|---|---|---|
| 钉钉 | 填 CorpId | 填 Client ID | 填 Client Secret |
| 企业微信 | 填 CorpID | 留空 | 填应用 Secret |
| 飞书 | 留空 | 填 App ID | 填 App Secret |
| LDAP | — | — | 填 Bind 密码 |
选择 LDAP 时，表单另外提供一组专属配置：主机地址、端口、是否使用 LDAPS、是否使用 StartTLS、Bind DN、Base DN、用户过滤器、部门过滤器，以及登录名、姓名、邮箱、手机、工号五项属性的映射。
LDAP 连接明细保存后不在表单中回显；全部留空表示沿用已保存值，修改连接时须完整重填。
本轮已核对：连接明细保持留空时，通用策略与备注可正常保存，保存后测试连接仍成功；重填连接明细时当前页面保存失败。两条链路须分别判断。
本例只连接本机 OpenLDAP 的虚构目录，字段按测试目录配置；明细不回显时须完整重填。
本机LDAP连接：127.0.0.1:13890，Bind DN与Base DN仅指向教程测试目录
LDAP用户和部门过滤器，以及uid、cn、mail、mobile属性映射
LDAP姓名、邮箱、手机和工号属性映射，并选择仅补全空字段与人工确认匹配
2.3 关于密钥
密钥直接粘贴到输入框中提交，保存后不再回显，输入框显示「已设置，留空表示不修改」。修改其他配置时保持该项为空即可。
也可将密钥值填写为 env:变量名 的形式，此时系统改为从服务运行环境中读取该变量的值。此方式需要部署人员预先在服务器上设置对应的环境变量。
安全说明：当前版本的密钥以未加密的形式保存在服务端，这是 0.1 阶段的明确取舍。密钥保存后不会再在任何界面上显示。请据此评估服务端数据的访问管控要求。
2.4 测试连接
配置保存后，点击「测试连接」验证凭据是否正确。连接成功时显示「连接成功：部门 X · 用户 Y」，失败时显示具体错误信息。
配置保存前无法测试，界面提示「保存配置后即可测试连接」。来源被停用后仍可执行测试连接，便于调试，但不能执行预览与应用。
示例展示配置入口；实际同步需要企业目录或 LDAP 的有效连接信息，不能仅凭保存配置判断同步成功。
外部组织同步来源、权威模式与匹配策略
以下保留已保存连接，LDAP明细未重填；通用策略保存和保存后的连接测试均通过，不代表连接编辑和组织写入已通过。
沿用已保存LDAP连接、密钥和角色同步关闭状态，仅调整本机目录演练备注；LDAP连接明细保持未改
不重填LDAP连接明细时，通用同步策略与备注保存成功；这不代表LDAP连接编辑和组织应用已修复
通用策略保存后再次测试连接，原LDAP连接仍返回部门1、用户1，证明留空沿用配置有效
目录源通过测试准备接口预置后，真实连接返回1个部门、1个用户。当前页面的保存失败另有截图，不能据此声称网页保存已通过。
对已预置的本机LDAP目录执行测试连接，真实返回部门1、用户1
3. 同步的执行
3.1 手动执行
- 点击「同步预览」。系统建立一个后台任务，拉取外部数据并计算差异；
- 任务完成后打开「差异审阅」界面，逐项查看；
- 勾选需要应用的差异；
- 点击「应用已选」并确认。
同步策略：仅补全空字段、冲突人工确认、手动同步、关闭角色同步，锚点为公司根目录
同步预览真实产生3项低风险新建差异：教程采购部、目录演练员及成员关系，尚未写入
3.2 定时执行
将同步模式配置为定时后，系统按设定周期自动执行。定时执行只产生预览结果，不会自动写入数据，仍需管理员进入审阅界面确认后应用。
定时周期在本页配置，无需到定时任务页面单独设置。
3.3 差异的类型
差异按对象分为部门、用户、成员关系、角色授予、同步角色五类，每条差异标注一种变更动作：
新建、更新、认领绑定、移动、冲突、离职、停用、跳过、授予角色、回收角色。
3.4 应用前的确认
点击「应用已选」后，系统列出本次将执行的不可撤销操作明细，例如：停用部门若干个、将若干人置为离职（同时撤销其在线会话）、回收成员关系若干条、回收角色授予若干条。
确认后执行。应用后无法一键撤销。
应用前确认3条已审阅的新建差异；本例不包含停用、离职或角色授予
3.5 应用结果
逐条差异独立应用，其中一条失败不影响其余条目。结果分三种情况显示：
| 结果 | 显示内容 |
|---|---|
| 全部成功 | 已应用 X，跳过 Y，失败 Z，冲突 W |
| 部分成功 | 部分应用成功：成功 X，失败 Y，跳过 Z，冲突 W |
| 全部失败 | 应用失败：失败 X，跳过 Y，冲突 Z |
失败条目会记录具体原因并在明细中展示。界面提供只重试失败项的入口，已成功的条目不会重复执行，无需重新预览。
本轮应用差异返回服务器内部错误，任务仍为已预览；没有将3项新对象的写入计为成功。
目录差异应用返回服务器内部错误；任务仍处于已预览，本例没有完成组织写入
4. 认领：避免产生重复对象
当本实例中已存在与外部同名或同编码的部门或用户时，应将两者关联为同一对象，而非新建一个重复对象。这一关联动作称为认领。
自动匹配的判断依据
| 对象 | 判断依据 |
|---|---|
| 部门 | 编码相同（强匹配）；或名称相同且其上级部门已完成绑定（弱匹配） |
| 用户 | 登录名、手机号或邮箱相同 |
匹配到候选的差异项会提示「已匹配候选，可直接认领」。
匹配策略决定发现候选时的处理方式：
| 策略 | 行为 |
|---|---|
| 冲突待人工确认 | 默认。标记为冲突，等待人工裁决 |
| 自动绑定已有对象 | 自动认领为同一对象 |
| 跳过 | 不处理该条 |
手动认领：在差异审阅界面，对「新建」类型的差异可选择「绑定到既有部门…」或「绑定到既有用户…」，将其认领至现有对象。完成上级部门的认领后，其下级部门通常会逐层自动认领。
限制：冲突项永远不可勾选应用，只能通过认领消解。而认领仅对部门与用户两类开放——成员关系、角色授予的冲突没有消解入口，只能通过调整配置或本地数据后重新预览来规避。
5. 权威模式：冲突时以谁为准
当同一对象在外部与本实例中的信息不一致时，由权威模式决定处理方式：
| 权威模式 | 行为 | 适用情况 |
|---|---|---|
| 外部覆盖本地 | 以外部数据为准，覆盖本地修改，包括将本地有值而外部为空的字段清空 | 完全以外部系统为准的场景。启用时界面提示「外部将覆盖本地改动，请确认后再启用」 |
| 仅记录不覆盖 | 只生成差异记录供查看，不写入本地 | 希望先观察差异的场景 |
| 仅补全本地空字段 | 只填充本地为空的字段，不覆盖已有内容 | 界面标注为推荐，风险最低 |
重要限制：权威模式仅作用于显示名、手机、邮箱三个字段。部门的名称与排序变更不受权威模式约束，始终会生成更新。
本地编辑不受保护：由同步建立的对象在本实例中可以自由编辑，系统只在用户列表中打上「外部同步」标识作为提示，不阻止修改。但这些修改可能在下一轮同步中被覆盖，是否覆盖取决于权威模式。
6. 外部对象消失时的处理
当某个对象在外部系统中被删除，下一轮同步会按以下方式处理，均不执行物理删除：
| 对象 | 处理方式 |
|---|---|
| 部门 | 停用 |
| 用户 | 置为离职状态，回收由同步建立的部门归属关系，并强制下线其全部登录会话 |
| 成员关系 | 标记失效 |
🔴 同步不会自动创建交接单。 因为交接必须指定接收人，而批量同步无法判断应由谁接手。应用结果中会提示「本次有 N 人被置为离职，同步不会自动创建交接单，请前往离职交接为其指定接收人」，并提供跳转入口。请逐个处理，详见工作交接。
7. 角色同步
开启「角色同步」后，每次同步预览会一并拉取外部系统的用户组或角色，在本实例中建立对应角色并同步成员归属。
外部角色与本实例已有角色重名时，按配置的策略处理：
| 策略 | 行为 |
|---|---|
| 重名时加后缀新建角色 | 新建一个带指定后缀的角色，与既有角色并存 |
| 重名时合并到同名角色 | 将外部组成员直接加入既有的同名角色 |
⚠️ 合并模式需谨慎使用。外部组成员将获得该同名角色已配置的全部权限。启用前须确认两边的角色语义确实一致。系统角色永远不会被合并，这是不可突破的限制。
8. 配置示例：首次接入
- 在「组织同步」中选择来源类型，按第 2.2 节填写对应的标识与密钥，权威模式先选择「仅补全本地空字段」，匹配策略保持默认的「冲突待人工确认」；
- 保存配置，点击「测试连接」，确认返回部门与用户的数量；
- 若实例中已有手工建立的部门，先设置锚点部门，避免外部组织挂载到不期望的位置；
- 点击「同步预览」，等待任务完成；
- 在差异审阅中先只勾选少量部门应用，核对结果是否符合预期；
- 确认无误后再逐步扩大勾选范围，完成全量同步；
- 处理冲突项：对确属同一对象的，使用认领绑定；
- 同步完成后，检查各部门是否设置了在职的部门主管，否则会影响审批流程的取人，详见部门管理。
9. 使用限制与注意事项
| 限制 | 说明 |
|---|---|
| 无增量同步 | 每次均为全量拉取，组织规模较大时预览耗时较长 |
| 无并发保护 | 同一配置可同时发起多个预览任务，应避免重复点击 |
| 停用后不可预览与应用 | 来源被停用后仅保留测试连接功能 |
| 冲突项无法直接应用 | 只能通过认领消解，且成员关系与角色授予的冲突没有消解入口 |
| 权威模式仅覆盖三个字段 | 部门名称与排序始终更新，不受该配置约束 |
| 应用后无法撤销 | 执行前须核对差异清单 |
| 密钥未加密保存 | 当前版本的明确取舍，需相应管控服务端数据的访问权限 |
当前演练实例重填LDAP连接明细后保存返回请求体格式错误，组织应用返回服务器错误；沿用已有连接的通用策略保存已通过，正式接入仍须解决未通过步骤。
LDAP表单保存请求体格式错误；这张图不代表连接配置已通过界面保存