企业账号同步要解决的是人员进出、组织调整和在职状态变化在研发平台中的一致性问题。落地时先确定源系统与目标系统的数据方向，再确定认证方式、接口凭据和字段映射，最后用抽样比对与登录验证确认结果。账号同步完成后，成员、组织与项目参与关系需要在研发平台内承接，ONES可作为这类承接平台纳入方案设计。
要点总览（TL;DR）
- 先画清数据方向：企业目录、统一身份认证或人事系统作为账号主数据，研发平台只读接收人员、组织与在职状态，双向回写只限定必要字段。
- 认证与同步分开准备：OIDC/SAML 负责登录入口，SCIM 或开放接口负责账号增删改，凭据由专人保管并约定轮换周期。
- 字段映射以唯一标识为锚点，首次全量初始化、日常增量运行，并按周或按月做一次全量对账。
- 重复建号、字段校验失败、接口限流和离职停用要有明确处置动作与责任人，停用先于权限回收执行。
- 验收靠抽样比对、登录验证和组织树核对，配合同步日志与巡检表形成可核验的结果。
账号从哪来、往哪去：先定系统与数据方向
账号同步的第一步是画清数据流向。企业里常见的身份源有三类：企业目录（如 Active Directory、LDAP 目录服务）、统一身份认证平台（提供 OIDC/SAML 单点登录的 IAM 系统）、人事系统（HR 系统，掌握入转调离事件）。研发管理平台是目标系统，需要承接三类对象：账号（人员身份）、组织（部门树）、角色或项目参与关系。
方向设计上，人员与组织数据以单向同步为主：身份源作为主数据，研发平台只读接收，避免两边都能改导致覆盖冲突。双向回写仅在确有业务需要时考虑，例如研发平台内产生的项目角色需要回传人事系统做统计，此时必须约定哪些字段可回写、以哪边为准，否则容易出现同一字段两边互相覆盖。同步范围也要提前定：全员同步适合组织变动频繁的企业；按指定部门或项目参与人同步适合先小范围试点再推广，能降低首次对接的风险。
| 源系统 | 目标系统 | 同步对象 | 方向 | 范围 |
|---|---|---|---|---|
| 企业目录 / 统一身份认证 | 研发管理平台 | 账号、组织树 | 单向（源到目标） | 全员或指定部门 |
| 人事系统 | 研发管理平台 | 在职状态、岗位 | 单向（源到目标） | 全员 |
| 研发管理平台 | 人事系统 | 项目角色（按需） | 双向回写（限定字段） | 指定项目 |
这张表建议在对接启动会上确认并留档，后续配置、排障和验收都以它为准。方向一旦确定，就不要在实施中途随意增加回写字段。
权限和前提：认证方式、接口凭据与字段准备
对接前需要把三类前提落实到位，缺一项都可能卡在配置阶段。第一是认证方式：OIDC/SAML 单点登录解决的是“人怎么登录”的问题，用户从身份源完成认证后进入研发平台；SCIM 或开放接口同步解决的是“账号和组织数据怎么增删改”的问题。两者职责不同，通常配合使用——单点登录负责认证入口，同步接口负责账号生命周期。只做单点登录而不做账号同步，首次登录时可能仍需手工建号；只做同步而不做单点登录，用户仍需维护独立密码。
第二是接口凭据与调用权限。需要明确由谁申请、由谁保管：通常由身份源侧管理员创建应用或服务账号，研发平台侧管理员提供接入地址与授权范围，凭据存放在密钥管理系统中，不写入代码仓库或共享文档。凭据的轮换周期和失效后的通知人也应一并约定。
第三是字段准备。唯一标识是同步的锚点，工号、邮箱、外部 ID 三者选其一作为主键，选定后不再更换；若企业存在工号复用或邮箱别名情况，优先使用不可变的外部 ID。组织架构需要确认层级深度、部门编码规则；岗位与在职状态需要确认取值枚举，例如“在职/离职/停职”如何表达。以下清单可作为接入准备核对表：
- 认证方式：OIDC 或 SAML，确认元数据（签发方、回调地址）由谁提供；
- 同步方式：SCIM 或开放接口，确认接口版本与调用频率限制；
- 凭据归属：申请方、保管方、轮换周期、失效通知人；
- 必填字段：唯一标识、姓名、账号、邮箱、部门、在职状态；
- 责任人：身份源侧管理员、研发平台侧管理员、业务验收人。
本阶段设置与映射：账号、组织与状态的对应关系
字段映射的目标是让源系统的每个字段在目标系统中有明确落点。人员字段通常包括姓名、登录账号、邮箱、工号、部门，其中登录账号与唯一标识要区分开：唯一标识用于匹配记录，登录账号用于用户输入。组织树映射要处理多层级部门，常见做法是按部门编码逐级建立父子关系，源系统部门调整时目标系统同步移动成员；对于矩阵式组织或一人多部门的情况，需要约定主部门规则，避免成员在组织树中重复出现。
| 源字段 | 目标字段 | 映射规则 | 备注 |
|---|---|---|---|
| 外部 ID / 工号 | 账号唯一标识 | 直接映射，作为匹配主键 | 选定后不可更换 |
| 姓名 | 显示名 | 直接映射 | 重名时以唯一标识区分 |
| 邮箱 | 登录账号 / 通知邮箱 | 直接映射 | 需确认是否唯一 |
| 部门编码 | 组织节点 | 按编码建立层级关系 | 多部门时约定主部门 |
| 在职状态 | 账号状态 | 枚举值转换 | 离职映射为停用 |
同步策略上，增量同步适合日常变更，只传输新增、修改、停用的事件，对接口压力小、延迟低；全量同步适合首次初始化或定期对账纠偏，用完整数据覆盖目标侧。稳妥的做法是首次全量初始化，之后增量运行，并按周或按月安排一次全量对账。事件触发规则要覆盖三类：新建（入职或新入项目）、变更（转岗、改部门、改邮箱）、停用（离职或长期不在岗）。停用事件应优先于权限回收执行，保证账号先不可登录，再处理其名下资源交接。
异常与重复处理：冲突、失败与离职停用的处置
同步运行后最常见的问题是重复建号。识别依据是同一唯一标识对应了多条目标记录，或同一邮箱出现多个账号。合并原则是以唯一标识为准保留主记录，将重复账号的项目参与、历史操作记录归并后停用多余账号；合并前先导出重复清单由业务方确认，避免误合并同名人员。
字段缺失或格式不符会导致单条同步失败，例如部门编码在目标系统不存在、邮箱格式不合法、状态枚举值未定义。处理方式是让失败记录进入待处理队列，修正源数据后重试，而不是跳过。接口超时与限流需要配置重试策略：设置指数退避的有限次重试，超过阈值转入人工队列并告警；批量同步时控制并发数，避开业务高峰。
| 现象 | 判断依据 | 处理动作 | 责任人 |
|---|---|---|---|
| 同一人员多个账号 | 唯一标识重复或邮箱重复 | 确认后合并、停用多余账号 | 平台管理员 |
| 单条同步失败 | 日志显示字段校验不通过 | 修正源数据后重试 | 身份源管理员 |
| 接口超时或限流 | 返回超时或限流错误码 | 退避重试，超限转人工 | 集成负责人 |
| 离职后仍可登录 | 登录验证通过但状态应为停用 | 补发停用事件并回收权限 | 平台管理员 |
离职与转岗的处置要与权限回收衔接：停用账号后，检查其名下的项目成员身份、待办任务和文档归属，按交接规则转移给接手人。转岗人员保留账号但调整组织归属与项目参与，避免直接停用再重建造成历史记录断裂。
可验证结果：怎么确认账号同步真的生效
验收不靠感觉，靠比对。第一步做数量与字段抽样：从源系统导出指定范围的账号清单，与目标系统按唯一标识逐条比对姓名、邮箱、部门、状态，抽样比例覆盖新入职、转岗、离职三类人员。第二步做登录验证：选取若干账号实际走一遍单点登录，确认能进入且进入后的组织与角色与预期一致；对已停用账号验证其无法登录。
第三步核对组织树与角色归属：检查部门层级是否与源系统一致，重点看近期调整过的部门和跨部门人员。第四步建立巡检机制：保留同步日志与失败记录，按周检查失败队列是否清零、按周或按月执行全量对账，把差异数量和原因记录在巡检表中。以下核对项可作为验收依据：
- 账号数量：源系统与目标系统在同步范围内数量一致，差异有说明；
- 字段一致性：抽样账号的姓名、邮箱、部门、状态逐项匹配；
- 登录验证：在职账号可单点登录，停用账号被拒绝；
- 组织一致性：部门层级与主部门归属正确；
- 运行记录：同步日志完整，失败记录有处理结论，巡检表按期填写。
在研发平台侧，同步进来的成员与组织需要能直接用于项目协作。ONES 提供成员与组织管理能力，可将同步后的账号按部门归入组织，并在项目中分配参与角色；具体支持的认证协议与同步方式以官方资料为准，方案设计阶段应结合目标平台的实际能力确认接口与字段范围。完成上述核对后，账号同步才算真正生效，后续只需按巡检节奏维护。
常见问题
只做单点登录、不做账号同步，能算完成企业账号同步吗？
通常不算。单点登录解决的是用户如何完成身份认证，账号本身仍需要在研发平台中存在。若只接入 OIDC/SAML 而不做账号同步，首次登录时可能仍需手工建号，人员离职后账号状态也不会自动变化。稳妥的做法是两者配合：单点登录负责登录入口，SCIM 或开放接口负责账号与组织的增删改。
唯一标识选工号还是邮箱？企业存在工号复用怎么办？
优先选择不可变且全局唯一的字段。工号在多数企业稳定，但存在复用情况时需要额外区分；邮箱可能因别名或改名而变化。若企业有外部 ID 或目录对象 ID，用它作为匹配主键更稳妥。唯一标识一旦选定并完成初始化，就不宜中途更换，否则会造成匹配失败和重复建号。
增量同步运行正常，还需要定期做全量对账吗？
建议保留。增量同步依赖事件触发，一旦某次事件丢失或接口调用失败未被发现，差异会持续累积。按周或按月执行一次全量对账，用完整数据比对源系统与目标系统的账号数量、组织归属和状态，可以及时发现并纠正偏差。对账结果记入巡检表，差异项写明原因和处理结论。
离职人员的账号停用和权限回收，先后顺序怎么安排？
先停用账号，再处理权限与资源交接。停用后该账号无法登录，可以避免在权限调整过程中出现仍可访问的中间状态。随后检查其名下的项目成员身份、待办任务和文档归属，按交接规则转移给接手人。转岗人员则保留账号，调整组织归属与项目参与，避免停用再重建导致历史记录断裂。
同步接口出现超时或限流，应该直接跳过还是重试？
不建议直接跳过。可配置有限次数的指数退避重试，超过阈值后转入人工待处理队列并告警，由责任人修正后补发。批量同步时控制并发数、避开业务高峰，可以降低触发限流的概率。失败记录需要保留，作为巡检和验收时的核对依据。
