用户与部门数据同步 OpenAPI 接口文档（V4.0支持）

一、 概述

本文档用于指导第三方系统（如 OA、HR等）将组织架构（部门）与用户数据同步至本系统。

📖 参考文档：系统对接与集成指南

---

二、 鉴权与准备工作

1. 权限要求（重要）

• 必须使用超级管理员（admin）账号登录系统，在「系统管理 / 开放平台（OpenAPI）」中创建应用并生成专属的 AppId 与 AppSecret。
• 注意：本组接口涉及核心组织架构与用户数据维护，仅支持由 admin 账号创建的 OpenAPI 凭证 访问，普通用户创建的应用无权调用。

2. 鉴权方式（HTTP Basic Auth）

请求 Header 中需携带 Authorization：

Authorization: Basic <base64(appId:appSecret)>

例如：AppId 为 38yqXlTkebVpEZnQ，AppSecret 为 M72wXkpmsYYwu6ryMIF5ipnHGcQXJF4h，则值为 Basic Mzh5cVhsVGtlYlZwRVpuUTpNNzJ3WGtwbXNZWXd1NnJ5TUlGNWlwbkhHY1FYSkY0aA==。

3. 数据传输规范

• 请求格式：Content-Type: application/json;charset=UTF-8
• 请求协议：HTTP / HTTPS POST

---

三、 核心同步机制

1. 冲突自动降级为更新（幂等友好）
   • 部门保存：若指定的部门 ID 已存在，或同层级下已存在相同名称的部门，接口会自动降级为更新现有部门。
   • 用户保存：若指定的 ID 已存在，或登录账号（userName）已存在，接口会自动降级为更新现有用户。
2. “待同步”兜底机制
   • 当新增/更新部门或用户时，若指定的上级部门（parentId）或所属部门（deptId）在系统中暂不存在，系统会自动创建/获取顶级的 “待同步” 部门，并将该部门/用户临时挂载到“待同步”下，确保同步任务不会因依赖顺序问题而失败中断。

---

四、 部门同步接口

1. 保存部门（新增/冲突降级修改）

• 接口地址：POST /open/system/dept/save
• 接口说明：保存部门数据。若部门已存在则自动更新，若指定的 parentId 不存在则自动挂在“待同步”部门下。

请求参数

参数名	类型	必填	说明
id	String	否	部门ID（建议传入三方系统的部门唯一标识，支持数字或字符串）
parentId	String	否	父部门ID。不传或传 0 表示顶级部门；若指定ID在系统中不存在，自动挂在“待同步”部门下
deptName	String	是	部门名称
orderNum	Integer	否	显示排序号（默认 0）
leader	String	否	部门负责人
phone	String	否	联系电话
email	String	否	部门邮箱
status	String	否	部门状态：0 正常（默认），1 停用

请求示例

{
  "id": "1001",
  "parentId": "0",
  "deptName": "技术研发中心",
  "orderNum": 1,
  "leader": "张三",
  "phone": "13800138000",
  "email": "zhangsan@example.com",
  "status": "0"
}

响应示例

{
  "code": 200,
  "msg": "操作成功",
  "data": 1001
}

---

2. 修改部门

• 接口地址：POST /open/system/dept/update
• 接口说明：显式修改已有部门的基础信息及层级关系。

请求参数

参数名	类型	必填	说明
id	String	是	部门ID
parentId	String	否	上级部门ID（不能设置自己为上级部门）
deptName	String	否	部门名称
orderNum	Integer	否	显示排序号
leader	String	否	部门负责人
phone	String	否	联系电话
email	String	否	部门邮箱
status	String	否	部门状态：0 正常，1 停用

请求示例

{
  "id": "1001",
  "deptName": "技术研发中心（架构调整）",
  "orderNum": 2,
  "leader": "李四"
}

响应示例

{
  "code": 200,
  "msg": "操作成功",
  "data": "修改成功"
}

---

3. 删除部门

• 接口地址：POST /open/system/dept/delete
• 接口说明：删除指定部门。若部门下存在子部门或关联用户，将拒绝删除。

请求参数

参数名	类型	必填	说明
id / deptId	String	否	单个待删除的部门ID（与 deptIds 至少传一个）
deptIds	Array[String]	否	批量待删除的部门ID列表

请求示例

{
  "id": "1003"
}

或批量删除：

{
  "deptIds": ["1003", "1004"]
}

响应示例

{
  "code": 200,
  "msg": "操作成功",
  "data": "删除成功"
}

---

五、 用户同步接口

1. 保存用户（新增/冲突降级修改）

• 接口地址：POST /open/system/user/save
• 接口说明：保存用户数据。若账号（userName）或 id 已存在则自动更新；若部门不存在则挂在“待同步”部门下。

请求参数

参数名	类型	必填	说明
id	String	否	用户ID（建议传入三方系统的用户唯一标识）
userName	String	是	用户登录账号（系统中唯一）
nickName	String	是	用户姓名 / 昵称
deptId	String	否	归属部门ID（若不存在自动挂在“待同步”部门下）
phonenumber	String	否	手机号码
email	String	否	用户邮箱
password	String	否	登录密码（若不传默认初始化为 123456）
sex	String	否	性别：0 男，1 女，2 未知（默认 2）
status	String	否	帐号状态：0 正常（默认），1 停用

请求示例

{
  "userName": "zhangsan_test",
  "nickName": "张三",
  "deptId": "1001",
  "phonenumber": "13912345678",
  "email": "zhangsan@example.com",
  "password": "Password123!",
  "sex": "0",
  "status": "0"
}

响应示例

{
  "code": 200,
  "msg": "操作成功",
  "data": 10086
}

---

2. 修改用户

• 接口地址：POST /open/system/user/update
• 接口说明：修改已有用户的信息。

请求参数

参数名	类型	必填	说明
id	String	否	用户ID（id 与 userName 至少填一个）
userName	String	否	用户登录账号
nickName	String	否	用户姓名 / 昵称
deptId	String	否	归属部门ID
phonenumber	String	否	手机号码
email	String	否	用户邮箱
password	String	否	重置密码（不传或为空则不修改）
sex	String	否	性别：0 男，1 女，2 未知
status	String	否	帐号状态：0 正常，1 停用

请求示例

{
  "userName": "zhangsan_test",
  "nickName": "张三（研发一组）",
  "deptId": "1002"
}

响应示例

{
  "code": 200,
  "msg": "操作成功",
  "data": "修改成功"
}

---

3. 删除用户

• 接口地址：POST /open/system/user/delete
• 接口说明：删除指定用户（支持根据 ID 或账号删除；超管账号受保护不可删除）。

请求参数

参数名	类型	必填	说明
id / userId	String	否	单个用户ID
userIds	Array[String]	否	批量用户ID列表
userName	String	否	单个用户登录账号
userNames	Array[String]	否	批量用户账号列表

请求示例

{
  "userName": "zhangsan_test"
}

或批量根据 ID/账号 删除：

{
  "userNames": ["user_a", "user_b"],
  "userIds": ["1001", "1002"]
}

响应示例

{
  "code": 200,
  "msg": "操作成功",
  "data": "删除成功"
}

---

六、 统一响应与错误码

字段名	类型	说明
code	Integer	状态码：200 表示成功，其它均为失败
msg	String	提示信息（操作成功 / 错误原因描述）
data	Object	业务返回数据（保存成功时返回实体 ID，修改/删除返回结果提示）

常见错误返回：

{
  "code": 500,
  "msg": "无权限访问，仅限超级管理员调用",
  "data": null
}