同步组织与员工

使用身份：客户端模式 Token（grant_type=client_credentials）
业务背景：集成开发方需要把自身系统的组织架构、员工账号初始化同步到 SView 企业看图系统；客户端 Token 只能做组织架构同步，无法操作文件、项目业务。
重要约束：部门必须按层级自上而下创建，父部门优先完成创建；创建员工时引用的部门 integrationId 必须已经在 企业看图 系统存在。

前置准备

1. 从 SView 实施处获取 client_id、client_secret、tenant‑id；
2. 集成开发方准备好完整组织树：部门 integrationId、部门名称、层级关系；员工 integrationId、手机号、所属部门、账号角色。

详细调用流程

1. 获取客户端 Access Token 接口：POST /auth/oauth2/token
   • Header：Authorization 填Basic base64(clientId:clientSecret)，Content‑Type 为application/x‑www‑form‑urlencoded，带上全套公共 Header；
   • Body 表单参数：grant_type=client_credentials，scope=server；
   • 接收返回access_token、expires_in；集成开发方缓存该令牌，用于后续组织同步。
2. 【可选步骤，调试 / 定时同步建议执行】校验令牌有效性 接口：GET /auth/token/check_token
   • Query 参数传入 token 值；携带公共 Header；
   • 返回 ok=true 代表令牌有效，读取 expiresAt 可以判断剩余有效期。
3. 循环批量创建部门（从上到下，先父后子） 接口：POST /login‑register/open‑api/departments
   • Header：Authorization 为Bearer {客户端access_token} + 全套公共 Header；Content‑Type=application/json；
   • Body 入参：
     • integrationId：集成开发方部门唯一 ID；
     • deptName：部门名称；
     • sortOrder：部门排序；
     • parentDeptIntegrationId：根部门传"0"，子部门填写父部门的集成方 integrationId；
   • 成功返回 deptId（SView 内部部门 ID，集成开发方可按需记录，业务主要还是使用 integrationId）。
4. 循环批量创建员工成员 接口：POST /login‑register/open‑api/employees
   • Header：Authorization 为Bearer {客户端access_token} + 全套公共 Header；Content‑Type=application/json；
   • Body 入参：
     • integrationId：集成开发方用户唯一标识（后续个人登录核心字段）；
     • mobile：手机号，必填；
     • name：用户姓名；
     • password：不传自动生成 6 位随机密码；
     • roleCode：ROLE_GENERAL普通用户 / ROLE_ENT_CHILD_ADMIN子管理员（系统最多支持 3 个管理员账号）；
     • deptIntegrationIds：所属部门 integrationId，多个使用英文逗号分隔，部门必须已提前创建；
     • remark：备注信息；
   • 成功返回 userId（SView 内部用户 ID）。

集成开发方需要留存的数据

务必保存每个员工的integrationId，后续获取个人 Token、加入项目全部依赖该字段。

高频踩坑说明

1. 颠倒部门创建顺序，子部门先于父部门提交，返回业务异常；
2. 重复提交相同 integrationId（部门 / 用户）触发报错；
3. 使用客户端 Token 调用文件、项目接口，返回鉴权 / 业务报错；文件项目业务必须使用个人身份 Token。