数据同步接口文档

概述

本文档描述了平台内所有支持的数据同步接口。这些接口提供统一的数据同步功能，支持批量数据同步和同步信息查询。

接口地址前缀

所有接口地址都需要添加统一前缀：/api

鉴权说明

OAuth2 Token 获取

所有需要 SCOPE_client 权限的接口都必须先通过以下方式获取访问令牌：

获取Token接口：POST /api/login/oauth/token

请求方式：POST

请求头：

头部名称	头部描述	示例
Content-Type	内容类型，支持标准的表单类型，必需	application/x-www-form-urlencoded
Authorization	认证凭据，支持Basic和Bearer的令牌。	如下：

Basic认证方式，使用clientId:clientSecret进行base64编码:Basic ZGF0YU1hbmFnZXI6JDEkUy9pWTNjOHMkZzJRVXFqZElIa3RNNWFHenZLMEtIMQ==

参考实现：

java

request.addHeader(OAuthConstants.HEADER, OAuthConstants.BASIC + ' '
                  + base64Encoder.encodeToString(
                    String.format("%s:%s", clientId, clientSecret).getBytes(Charset.forName("UTF-8"))));

请求体（表单格式）：

参数名称	参数描述	示例
grant_type	权限授予类型，固定为client_credentials	client_credentials
scope	作用于，固定为client	client

请求示例：

bash

# 获取client token
POST /api/login/oauth/token
Authorization: Basic ZGF0YU1hbmFnZXI6JDEkUy9pWTNjOHMkZzJRVXFqZElIa3RNNWFHenZLMEtIMQ==
Content-Type: application/x-www-form-urlencoded

scope=client&grant_type=client_credentials

响应示例：

json

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzY29wZSI6WyJjbGllbnQiXSwiZXhwIjoxNjA4Nzc3ODUzLCJqdGkiOiJkMmQzYjMwNC04MTg5LTQ3ZjMtYjZmMS1mNDU0NDg4ZjM4ZjAiLCJjbGllbnRfaWQiOiJ0ZXN0In0.VXa8ksq9eObFA4Cov5PPxgaLSOejywqPgFOjTWUT-yoflKuGNyMe45X--4T1txwW0zTqbe9OF8lDHeUzVb5IdE0kAPkZ16cj3a4PGAB0_O9d6JaM0mLu2NL-O6woFMGpN8rwfSHR00KJem6ZDFyCy3o8FSopOiMMG7FD6nTfatO6bZtKOX66Oe5tv68NAU9LHMUZUkCTi3FZa3zPfCByr7tWmh3tuKycdhw6QR_orqSsAnPKlfsbaTCY7yAYDtFuYUccypbtEHoxinMuoaRWndcDfzOLxzhjXBHakhK9AKLiJr3uyyHTkq_p5DtxQU2u8SyA9QdCaA5IevFpcN-gOQ",
  "token_type": "bearer",
  "expires_in": 41309,
  "scope": "client",
  "jti": "d2d3b304-8189-47f3-b6f1-f454488f38f0"
}

请求头要求

获取token后，所有API调用都必须在请求头中携带访问令牌：

http

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

权限要求

POST /sync: 需要 SCOPE_client 或 SCOPE_ui 权限
GET /sync: 需要 SCOPE_client 权限

通用响应格式

json

{
  "code": 200,
  "message": "操作成功",
  "data": "具体数据内容",
  "timestamp": "2024-01-01T00:00:00Z"
}

完整调用示例

以下是一个完整的接口调用流程示例：

获取访问令牌：

bash

curl -X POST /api/login/oauth/token \
  -H "Authorization: Basic ZGF0YU1hbmFnZXI6JDEkUy9pWTNjOHMkZzJRVXFqZElIa3RNNWFHenZLMEtIMQ==" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "scope=client&grant_type=client_credentials"

使用令牌调用同步接口：

bash

curl -X POST /api/data/users/sync \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzY29wZSI6WyJjbGllbnQiXSwiZXhwIjoxNjA4Nzc3ODUzLCJqdGkiOiJkMmQzYjMwNC04MTg5LTQ3ZjMtYjZmMS1mNDU0NDg4ZjM4ZjAiLCJjbGllbnRfaWQiOiJ0ZXN0In0.VXa8ksq9eObFA4Cov5PPxgaLSOejywqPgFOjTWUT-yoflKuGNyMe45X--4T1txwW0zTqbe9OF8lDHeUzVb5IdE0kAPkZ16cj3a4PGAB0_O9d6JaM0mLu2NL-O6woFMGpN8rwfSHR00KJem6ZDFyCy3o8FSopOiMMG7FD6nTfatO6bZtKOX66Oe5tv68NAU9LHMUZUkCTi3FZa3zPfCByr7tWmh3tuKycdhw6QR_orqSsAnPKlfsbaTCY7yAYDtFuYUccypbtEHoxinMuoaRWndcDfzOLxzhjXBHakhK9AKLiJr3uyyHTkq_p5DtxQU2u8SyA9QdCaA5IevFpcN-gOQ" \
  -H "Content-Type: application/json" \
  -d '[{
    "name": "张三",
    "username": "zhangsan",
    "email": "zhangsan@example.com",
    ...
  }]'

同步结果对象 (SyncVo)

json

{
  "success": 10,     // 成功数量
  "failed": 2,       // 失败数量
  "updated": 8,      // 更新数量
  "total": 12,       // 总数量
  "msg": "同步完成", // 同步消息
  "list": []         // 同步后的数据列表
}

1. 职级数据同步接口

基础信息

控制器: RankController
基础路径: /api/login/ranks
实体类型: Rank (职级)

1.1 批量同步职级数据

接口地址: POST /api/login/ranks/sync

入参字段说明 (`List<Rank>`)

字段名	类型	必填	描述	示例值	备注
id	String	否	主键ID	"507f1f77bcf86cd799439011"	新增时可不传，系统自动生成
code	String	否	编号	"RANK001"	业务编码
name	String	是	名称	"处长"	职级/职务名称
pos	Double	否	排序位置	65535.0	用于排序，系统自动计算
type	String	是	类型	"JOB"	枚举值：JOB(职务)、RANK(职级)
createTime	String	否	创建时间	"2024-01-01 10:00:00"	ISO 8601格式，系统自动生成
modifyTime	String	否	修改时间	"2024-01-01 10:00:00"	ISO 8601格式，系统自动更新
creator	String	否	创建者	"admin"	创建人用户名
creatorId	String	否	创建者ID	"507f1f77bcf86cd799439011"	创建人用户ID
modifier	String	否	修改者	"admin"	修改人用户名
modifierId	String	否	修改者ID	"507f1f77bcf86cd799439011"	修改人用户ID
delete	Boolean	否	删除标记	false	逻辑删除标记

请求示例：

json

[
  {
    "name": "处长",
    "code": "RANK001", 
    "type": "JOB"
  },
  {
    "name": "科员",
    "code": "RANK002",
    "type": "RANK"
  }
]

出参字段说明 (`SyncVo<Rank>`)

字段名	类型	描述	示例值
success	Integer	成功同步数量	5
failed	Integer	失败同步数量	0
updated	Integer	更新同步数量	3
total	Integer	总同步数量	5
msg	String	同步消息	"职级数据同步完成"
list	`List<Rank>`	同步后的数据列表	见下方Rank结构

响应示例：

json

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "success": 5,
    "failed": 0,
    "updated": 3,
    "total": 5,
    "msg": "职级数据同步完成",
    "list": [
      {
        "id": "507f1f77bcf86cd799439011",
        "name": "处长",
        "code": "RANK001",
        "type": "JOB",
        "pos": 65535.0,
        "createTime": "2024-01-01 10:00:00"
      }
    ]
  }
}

1.2 获取职级同步信息

接口地址: GET /api/login/ranks/sync

出参字段说明 (`List<Rank>`)

返回职级实体列表，字段结构与POST接口入参相同。

响应示例：

json

{
  "code": 200,
  "message": "操作成功", 
  "data": [
    {
      "id": "507f1f77bcf86cd799439011",
      "name": "处长",
      "code": "RANK001",
      "type": "JOB",
      "pos": 65535.0,
      "createTime": "2024-01-01 10:00:00",
      "modifyTime": "2024-01-01 10:00:00"
    }
  ]
}

2. 角色数据同步接口

基础信息

控制器: RoleController
基础路径: /api/data/roles
实体类型: Role (角色)

2.1 批量同步角色数据

接口地址: POST /api/data/roles/sync

入参字段说明 (`List<Role>`)

字段名	类型	必填	描述	示例值	备注
id	String	否	主键ID	"507f1f77bcf86cd799439011"	新增时可不传，系统自动生成
code	String	否	编号	"ROLE001"	业务编码
name	String	是	名称	"系统管理员"	角色名称
pos	Double	否	排序位置	65535.0	用于排序，系统自动计算
description	String	否	角色描述	"拥有系统全部权限"	角色功能描述
mark	String	否	角色标识	"ADMIN"	角色唯一标识符
permissions	`List<Permission>`	否	权限列表	[{"id": "permissionId"}]	关联的权限对象列表
createTime	String	否	创建时间	"2024-01-01 10:00:00"	ISO 8601格式，系统自动生成
modifyTime	String	否	修改时间	"2024-01-01 10:00:00"	ISO 8601格式，系统自动更新
creator	String	否	创建者	"admin"	创建人用户名
creatorId	String	否	创建者ID	"507f1f77bcf86cd799439011"	创建人用户ID
modifier	String	否	修改者	"admin"	修改人用户名
modifierId	String	否	修改者ID	"507f1f77bcf86cd799439011"	修改人用户ID
delete	Boolean	否	删除标记	false	逻辑删除标记

请求示例：

json

[
  {
    "name": "系统管理员",
    "code": "ROLE001",
    "description": "拥有系统全部权限",
    "mark": "ADMIN",
    "permissions": [
      {"id": "507f1f77bcf86cd799439011"}
    ]
  }
]

出参字段说明 (`SyncVo<Role>`)

字段名	类型	描述	示例值
success	Integer	成功同步数量	3
failed	Integer	失败同步数量	0
updated	Integer	更新同步数量	2
total	Integer	总同步数量	3
msg	String	同步消息	"角色数据同步完成"
list	`List<Role>`	同步后的数据列表	见下方Role结构

响应示例：

json

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "success": 3,
    "failed": 0,
    "updated": 2,
    "total": 3,
    "msg": "角色数据同步完成",
    "list": [
      {
        "id": "507f1f77bcf86cd799439011",
        "name": "系统管理员",
        "code": "ROLE001",
        "description": "拥有系统全部权限",
        "mark": "ADMIN",
        "permissions": [
          {
            "id": "507f1f77bcf86cd799439012",
            "name": "用户管理"
          }
        ]
      }
    ]
  }
}

2.2 获取角色同步信息

接口地址: GET /api/data/roles/sync

出参字段说明 (`List<Role>`)

返回角色实体列表，字段结构与POST接口入参相同。

响应示例：

json

{
  "code": 200,
  "message": "操作成功",
  "data": [
    {
      "id": "507f1f77bcf86cd799439011",
      "name": "系统管理员", 
      "code": "ROLE001",
      "description": "拥有系统全部权限",
      "mark": "ADMIN",
      "permissions": [
        {
          "id": "507f1f77bcf86cd799439012",
          "name": "用户管理"
        }
      ]
    }
  ]
}

3. 用户数据同步接口

基础信息

控制器: UserController
基础路径: /api/data/users
实体类型: User (用户)

3.1 批量同步用户数据

接口地址: POST /api/data/users/sync

入参字段说明 (`List<User>`)

字段名	类型	必填	描述	示例值	备注
基础字段
id	String	否	主键ID	"507f1f77bcf86cd799439011"	新增时可不传，系统自动生成
code	String	否	编号	"USER001"	业务编码
name	String	是	姓名	"张三"	用户真实姓名
pos	Double	否	排序位置	65535.0	用于排序，系统自动计算
用户基本信息
username	String	是	用户名	"zhangsan"	登录用户名，唯一
email	String	是	邮箱	"zhangsan@example.com"	邮箱地址，唯一
phone	String	否	电话号码	"13800138000"	手机号码，唯一
gender	String	否	性别	"MALE"	枚举值：MALE(男)、FEMALE(女)
birthDate	String	否	出生日期	"1990-01-01"	yyyy-MM-dd格式
workDate	String	否	工作日期	"2020-01-01"	yyyy-MM-dd格式
idCardNo	String	否	身份证号	"110101199001011234"	18位身份证号码
用户状态信息
userType	String	否	用户类型	"NORMAL"	枚举值：SUPER_ADMIN、ADMIN、DEPARTMENT、NORMAL、UNDERTAKE、INFORMATION、LEADER
userStatus	String	否	用户状态	"NORMAL"	枚举值：NORMAL(正常)、LOCKED(已锁定)、DISABLED(已禁用)、EXPIRED(已过期)
enable	Boolean	否	是否启用	true	启用状态
expireDate	String	否	有效期	"2024-12-31"	yyyy-MM-dd格式
secretLevel	String	否	涉密级别	"NORMAL"	枚举值：NORMAL(一般涉密)、IMPORTANT(重要涉密)、KERNEL(核心涉密)
关联信息
rank	Object	否	职级		关联的职级对象
job	Object	否	职务		关联的职务对象
organizations	`List<Object>`	否	所属部门	[{"id": "orgId"}]	关联的组织机构列表
linkedUsers	`List<Object>`	否	关联外部用户	[{"id": "extUserId"}]	关联的外部用户列表
系统字段
shadowUsername	String	否	影子用户名	"shadow_zhangsan"	影子账户用户名
jitUserId	String	否	部级系统用户ID	"jit_user_123"	JIT平台用户标识
审计字段
createTime	String	否	创建时间	"2024-01-01 10:00:00"	ISO 8601格式，系统自动生成
modifyTime	String	否	修改时间	"2024-01-01 10:00:00"	ISO 8601格式，系统自动更新
creator	String	否	创建者	"admin"	创建人用户名
creatorId	String	否	创建者ID	"507f1f77bcf86cd799439011"	创建人用户ID
modifier	String	否	修改者	"admin"	修改人用户名
modifierId	String	否	修改者ID	"507f1f77bcf86cd799439011"	修改人用户ID
delete	Boolean	否	删除标记	false	逻辑删除标记

请求示例：

json

[
  {
    "name": "张三",
    "username": "zhangsan",
    "email": "zhangsan@example.com",
    "phone": "13800138000",
    "gender": "MALE",
    "userType": "NORMAL",
    "userStatus": "NORMAL",
    "enable": true,
    "birthDate": "1990-01-01",
    "workDate": "2020-01-01",
    "expireDate": "2024-12-31",
    "organizations": [
      {"id": "507f1f77bcf86cd799439011"}
    ]
  }
]

出参字段说明 (`SyncVo<User>`)

字段名	类型	描述	示例值
success	Integer	成功同步数量	10
failed	Integer	失败同步数量	1
updated	Integer	更新同步数量	8
total	Integer	总同步数量	11
msg	String	同步消息	"用户数据同步完成"
list	`List<User>`	同步后的数据列表	见下方User结构

响应示例：

json

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "success": 10,
    "failed": 1,
    "updated": 8,
    "total": 11,
    "msg": "用户数据同步完成",
    "list": [
      {
        "id": "507f1f77bcf86cd799439011",
        "name": "张三",
        "username": "zhangsan",
        "email": "zhangsan@example.com",
        "phone": "138****8000",
        "gender": "MALE",
        "userType": "NORMAL",
        "userStatus": "NORMAL",
        "enable": true,
        "organizations": [
          {
            "id": "507f1f77bcf86cd799439012",
            "name": "技术部"
          }
        ]
      }
    ]
  }
}

3.2 获取用户同步信息

接口地址: GET /api/data/users/sync

出参字段说明 (`List<User>`)

返回用户实体列表，字段结构与POST接口入参相同。注意：敏感字段（如手机号、身份证号）会进行脱敏处理。

响应示例：

json

{
  "code": 200,
  "message": "操作成功",
  "data": [
    {
      "id": "507f1f77bcf86cd799439011",
      "name": "张三",
      "username": "zhangsan",
      "email": "zhangsan@example.com",
      "phone": "138****8000",
      "gender": "MALE",
      "userType": "NORMAL",
      "userStatus": "NORMAL",
      "enable": true,
      "birthDate": "1990-01-01",
      "workDate": "2020-01-01",
      "expireDate": "2024-12-31",
      "organizations": [
        {
          "id": "507f1f77bcf86cd799439012",
          "name": "技术部"
        }
      ]
    }
  ]
}

4. 权限数据同步接口

基础信息

控制器: PermissionController (继承自 TreeController)
基础路径: /api/data/permissions
实体类型: Permission (权限)

4.1 批量同步权限数据

接口地址: POST /api/data/permissions/sync

入参字段说明 (`List<Permission>`)

字段名	类型	必填	描述	示例值	备注
基础字段
id	String	否	主键ID	"507f1f77bcf86cd799439011"	新增时可不传，系统自动生成
code	String	否	编号	"PERM001"	业务编码
name	String	是	权限名称	"用户管理"	权限标识名称
pos	Double	否	排序位置	65535.0	用于排序，系统自动计算
权限专有字段
title	String	否	权限显示标题	"用户管理"	前端显示的标题
icon	String	否	权限图标	"user"	图标标识
hasChild	String	否	是否可展开	"true"	是否有子权限
target	String	否	权限动作	"/users"	权限对应的路径或标识
type	String	是	权限类型	"MENU"	枚举值：MENU(菜单权限)、BUTTON(按钮权限)
description	String	否	权限描述	"用户管理相关功能"	权限功能说明
menu	`List<String>`	否	所属菜单	["system", "user"]	菜单层级路径
树形结构字段
parentId	String	否	父节点ID	"507f1f77bcf86cd799439010"	父权限ID，顶级为"0"
depth	Integer	否	树深度	1	树形结构层级深度
children	`List<Permission>`	否	子节点	[]	子权限列表，查询时填充
审计字段
createTime	String	否	创建时间	"2024-01-01 10:00:00"	ISO 8601格式，系统自动生成
modifyTime	String	否	修改时间	"2024-01-01 10:00:00"	ISO 8601格式，系统自动更新
creator	String	否	创建者	"admin"	创建人用户名
creatorId	String	否	创建者ID	"507f1f77bcf86cd799439011"	创建人用户ID
modifier	String	否	修改者	"admin"	修改人用户名
modifierId	String	否	修改者ID	"507f1f77bcf86cd799439011"	修改人用户ID
delete	Boolean	否	删除标记	false	逻辑删除标记

请求示例：

json

[
  {
    "name": "用户管理",
    "code": "PERM001",
    "title": "用户管理",
    "type": "MENU",
    "target": "/users",
    "parentId": "0",
    "depth": 1,
    "menu": ["system", "user"]
  }
]

出参字段说明 (`SyncVo<Permission>`)

字段名	类型	描述	示例值
success	Integer	成功同步数量	15
failed	Integer	失败同步数量	0
updated	Integer	更新同步数量	12
total	Integer	总同步数量	15
msg	String	同步消息	"权限数据同步完成"
list	`List<Permission>`	同步后的数据列表	见下方Permission结构

响应示例：

json

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "success": 15,
    "failed": 0,
    "updated": 12,
    "total": 15,
    "msg": "权限数据同步完成",
    "list": [
      {
        "id": "507f1f77bcf86cd799439011",
        "name": "用户管理",
        "code": "PERM001",
        "title": "用户管理",
        "type": "MENU",
        "target": "/users",
        "parentId": "0",
        "depth": 1,
        "children": []
      }
    ]
  }
}

4.2 获取权限同步信息

接口地址: GET /api/data/permissions/sync

出参字段说明 (`List<Permission>`)

返回权限实体列表，字段结构与POST接口入参相同。返回的是扁平化的权限列表，不包含树形结构。

响应示例：

json

{
  "code": 200,
  "message": "操作成功",
  "data": [
    {
      "id": "507f1f77bcf86cd799439011",
      "name": "用户管理",
      "code": "PERM001",
      "title": "用户管理",
      "type": "MENU",
      "target": "/users",
      "parentId": "0",
      "depth": 1,
      "menu": ["system", "user"],
      "createTime": "2024-01-01 10:00:00"
    }
  ]
}

5. 组织机构数据同步接口

基础信息

控制器: OrganizationController (继承自 TreeController)
基础路径: /api/data/organizations
实体类型: Organization (组织机构)

5.1 批量同步组织机构数据

接口地址: POST /api/data/organizations/sync

入参字段说明 (`List<Organization>`)

字段名	类型	必填	描述	示例值	备注
基础字段
id	String	否	主键ID	"507f1f77bcf86cd799439011"	新增时可不传，系统自动生成
code	String	否	编号	"ORG001"	业务编码
name	String	是	组织名称	"技术部"	组织机构全称
pos	Double	否	排序位置	65535.0	用于排序，系统自动计算
组织专有字段
simpleName	String	否	简称	"技术部"	组织机构简称
attribute	String	否	独立属性	"NORMAL_DEPARTMENT"	枚举值：NORMAL_DEPARTMENT(普通部门)、INDIVIDUAL_DEPARTMENT(独立部门)、INDIVIDUAL_UNIT(独立单位)
jitOrgId	String	否	JIT平台组织ID	"jit_org_123"	JIT平台对应的组织标识
树形结构字段
parentId	String	否	父节点ID	"507f1f77bcf86cd799439010"	父组织ID，顶级为"0"
depth	Integer	否	树深度	1	树形结构层级深度
children	`List<Organization>`	否	子节点	[]	子组织列表，查询时填充
审计字段
createTime	String	否	创建时间	"2024-01-01 10:00:00"	ISO 8601格式，系统自动生成
modifyTime	String	否	修改时间	"2024-01-01 10:00:00"	ISO 8601格式，系统自动更新
creator	String	否	创建者	"admin"	创建人用户名
creatorId	String	否	创建者ID	"507f1f77bcf86cd799439011"	创建人用户ID
modifier	String	否	修改者	"admin"	修改人用户名
modifierId	String	否	修改者ID	"507f1f77bcf86cd799439011"	修改人用户ID
delete	Boolean	否	删除标记	false	逻辑删除标记

请求示例：

json

[
  {
    "name": "技术部",
    "code": "ORG001",
    "simpleName": "技术部",
    "attribute": "NORMAL_DEPARTMENT",
    "parentId": "0",
    "depth": 1,
    "jitOrgId": "jit_org_123"
  }
]

出参字段说明 (`SyncVo<Organization>`)

字段名	类型	描述	示例值
success	Integer	成功同步数量	20
failed	Integer	失败同步数量	0
updated	Integer	更新同步数量	15
total	Integer	总同步数量	20
msg	String	同步消息	"组织机构数据同步完成"
list	`List<Organization>`	同步后的数据列表	见下方Organization结构

响应示例：

json

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "success": 20,
    "failed": 0,
    "updated": 15,
    "total": 20,
    "msg": "组织机构数据同步完成",
    "list": [
      {
        "id": "507f1f77bcf86cd799439011",
        "name": "技术部",
        "code": "ORG001",
        "simpleName": "技术部",
        "attribute": "NORMAL_DEPARTMENT",
        "parentId": "0",
        "depth": 1,
        "jitOrgId": "jit_org_123",
        "children": []
      }
    ]
  }
}

5.2 获取组织机构同步信息

接口地址: GET /api/data/organizations/sync

出参字段说明 (`List<Organization>`)

返回组织机构实体列表，字段结构与POST接口入参相同。返回的是扁平化的组织列表，不包含树形结构。

响应示例：

json

{
  "code": 200,
  "message": "操作成功",
  "data": [
    {
      "id": "507f1f77bcf86cd799439011",
      "name": "技术部",
      "code": "ORG001",
      "simpleName": "技术部",
      "attribute": "NORMAL_DEPARTMENT",
      "parentId": "0",
      "depth": 1,
      "jitOrgId": "jit_org_123",
      "createTime": "2024-01-01 10:00:00",
      "modifyTime": "2024-01-01 10:00:00"
    }
  ]
}

错误码说明

错误码	说明
200	操作成功
400	请求参数错误
401	未授权访问
403	权限不足
500	服务器内部错误

Token失效处理

当token过期或无效时，接口会返回401错误：

json

{
  "code": 401,
  "message": "Unauthorized",
  "data": null,
  "timestamp": "2024-01-01T00:00:00Z"
}

此时需要重新调用 /api/login/oauth/token 接口获取新的访问令牌。

Token检查接口

可以通过以下接口检查token是否有效：

接口地址：GET /api/login/oauth/check_token

请求参数：token - 要检查的bearer token

请求示例：

bash

GET /api/login/oauth/check_token?token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc19hZG1pbiI6ZmFsc2UsInVzZXJfbmFtZSI6InRlc3QiLCJzY29wZSI6WyJjbGllbnQiXSwiZXhwIjoxNjA4ODY2ODc1LCJhdXRob3JpdGllcyI6WyJjc3l5YiJdLCJqdGkiOiIzOGUwZTJhYi0yZGEyLTQ1MWQtOGQzMC1iYmUyZjdjODA5YjMiLCJjbGllbnRfaWQiOiJ0ZXN0In0.aivkqjYtWnT3itPhc7tA70hHO1y7HZmpZAbqT9LG2pUIZ0X7x_f4xntbp3lrpB2h2dsmWWV6limBUybK13TyXxC8dQ3XdpSUJmQwq3PNdaI1YlW-2jYLHUPef1Bv2DSR3rtZTaeMtT5poP0MiKNtD4XSxpWC0wO_48e0UCkaPoYWfl5RKBhXoXNalojcmBwEFJvppnx-hY87GbLt7DO1T2fZSLRq-SI3ZW202DIVjza8RzOXw0XOR-AsW3KqzpgHfAdRHqLMhFFw3Ps8GRtRYnCYSNllncxJ5x4cpDjtSNr4l_09GDulJ15VZwcMEdJsfIQZ1FI7LiyShTpw1gN5qA

响应示例：

json

{
  "is_admin": false,
  "user_name": "test",
  "scope": ["client"],
  "active": true,
  "exp": 1608866875,
  "authorities": ["csyyb"],
  "jti": "38e0e2ab-2da2-451d-8d30-bbe2f7c809b3",
  "client_id": "test"
}

字段类型说明

枚举值参考

枚举类型	可选值	说明
RankType	JOB, RANK	职务、职级
Gender	MALE, FEMALE	男、女
UserType	SUPER_ADMIN, ADMIN, DEPARTMENT, NORMAL, UNDERTAKE, INFORMATION, LEADER	用户类型
UserStatus	NORMAL, LOCKED, DISABLED, EXPIRED	正常、已锁定、已禁用、已过期
SecretLevel	NORMAL, IMPORTANT, KERNEL	一般涉密、重要涉密、核心涉密
PermissionType	MENU, BUTTON	菜单权限、按钮权限
OrgAttribute	NORMAL_DEPARTMENT, INDIVIDUAL_DEPARTMENT, INDIVIDUAL_UNIT	普通部门、独立部门、独立单位

数据类型说明

数据类型	格式说明	示例
String	字符串	"示例文本"
Boolean	布尔值	true, false
Integer	整数	123
Double	双精度浮点数	65535.0
Date	日期格式(yyyy-MM-dd)	"2024-01-01"
DateTime	日期时间格式(yyyy-MM-dd HH:mm:ss)	"2024-01-01 10:00:00"
`List<Object>`	对象数组	[{"id": "xxx"}]

注意事项

权限控制: 所有同步接口都需要相应的OAuth2权限范围
Token管理:
- client_credentials模式的token有效期较长，强烈建议缓存该token
- token过期时，可以使用refresh_token进行token刷新操作
- 建议在token过期前主动刷新，避免接口调用失败
OAuth认证:
- 使用Basic认证方式，将clientId:clientSecret进行base64编码
- Content-Type必须为application/x-www-form-urlencoded
- 请求体使用表单格式，不是JSON格式
数据格式:
- 日期字段使用 yyyy-MM-dd 格式
- 日期时间字段使用 yyyy-MM-dd HH:mm:ss 格式
- 所有枚举值严格区分大小写
字段约束:
- name字段为所有实体的必填字段
- username、email、phone在用户表中具有唯一性约束
- id字段新增时可不传，系统自动生成MongoDB ObjectId
批量限制: 建议每次同步数据量不超过1000条
事务性: 批量同步操作具有事务性，部分失败不会影响成功的数据
幂等性: 相同数据的重复同步是安全的，基于id字段进行判断
树形结构:
- 权限和组织机构支持树形结构
- parentId为"0"表示根节点
- depth从1开始计算，表示树的层级深度
- children字段仅在查询时填充，同步时忽略
关联字段:
- 关联对象（如permissions、organizations等）只需传入{id: "objectId"}格式
- 系统会自动建立DBRef关联关系
敏感信息: 查询接口返回的敏感字段（手机号、身份证号）会进行脱敏处理
Client凭证安全: clientId和clientSecret需要妥善保管，不要暴露在客户端代码中

数据同步接口文档 ​

概述 ​

接口地址前缀 ​

鉴权说明 ​

OAuth2 Token 获取 ​

请求头要求 ​

权限要求 ​

通用响应格式 ​

完整调用示例 ​

同步结果对象 (SyncVo) ​

1. 职级数据同步接口 ​

基础信息 ​

1.1 批量同步职级数据 ​

入参字段说明 (List<Rank>) ​

请求示例： ​

出参字段说明 (SyncVo<Rank>) ​

响应示例： ​

1.2 获取职级同步信息 ​

出参字段说明 (List<Rank>) ​

响应示例： ​

2. 角色数据同步接口 ​

基础信息 ​

2.1 批量同步角色数据 ​

入参字段说明 (List<Role>) ​

请求示例： ​

出参字段说明 (SyncVo<Role>) ​

响应示例： ​

2.2 获取角色同步信息 ​

出参字段说明 (List<Role>) ​

响应示例： ​

3. 用户数据同步接口 ​

基础信息 ​

3.1 批量同步用户数据 ​

入参字段说明 (List<User>) ​

请求示例： ​

出参字段说明 (SyncVo<User>) ​

响应示例： ​

3.2 获取用户同步信息 ​

出参字段说明 (List<User>) ​

响应示例： ​

4. 权限数据同步接口 ​

基础信息 ​

4.1 批量同步权限数据 ​

入参字段说明 (List<Permission>) ​

请求示例： ​

出参字段说明 (SyncVo<Permission>) ​

响应示例： ​

4.2 获取权限同步信息 ​

出参字段说明 (List<Permission>) ​

响应示例： ​

5. 组织机构数据同步接口 ​

基础信息 ​

5.1 批量同步组织机构数据 ​

入参字段说明 (List<Organization>) ​

请求示例： ​

出参字段说明 (SyncVo<Organization>) ​

响应示例： ​

5.2 获取组织机构同步信息 ​

出参字段说明 (List<Organization>) ​

响应示例： ​

错误码说明 ​

Token失效处理 ​

Token检查接口 ​

字段类型说明 ​

枚举值参考 ​

数据类型说明 ​

注意事项 ​

数据同步接口文档

概述

接口地址前缀

鉴权说明

OAuth2 Token 获取

请求头要求

权限要求

通用响应格式

完整调用示例

同步结果对象 (SyncVo)

1. 职级数据同步接口

基础信息

1.1 批量同步职级数据

入参字段说明 (`List<Rank>`)

请求示例：

出参字段说明 (`SyncVo<Rank>`)

响应示例：

1.2 获取职级同步信息

出参字段说明 (`List<Rank>`)

响应示例：

2. 角色数据同步接口

基础信息

2.1 批量同步角色数据

入参字段说明 (`List<Role>`)

请求示例：

出参字段说明 (`SyncVo<Role>`)

响应示例：

2.2 获取角色同步信息

出参字段说明 (`List<Role>`)

响应示例：

3. 用户数据同步接口

基础信息

3.1 批量同步用户数据

入参字段说明 (`List<User>`)

请求示例：

出参字段说明 (`SyncVo<User>`)

响应示例：

3.2 获取用户同步信息

出参字段说明 (`List<User>`)

响应示例：

4. 权限数据同步接口

基础信息

4.1 批量同步权限数据

入参字段说明 (`List<Permission>`)

请求示例：

出参字段说明 (`SyncVo<Permission>`)

响应示例：

4.2 获取权限同步信息

出参字段说明 (`List<Permission>`)

响应示例：

5. 组织机构数据同步接口

基础信息

5.1 批量同步组织机构数据

入参字段说明 (`List<Organization>`)

请求示例：

出参字段说明 (`SyncVo<Organization>`)

响应示例：

5.2 获取组织机构同步信息

出参字段说明 (`List<Organization>`)

响应示例：

错误码说明

Token失效处理

Token检查接口

字段类型说明

枚举值参考

数据类型说明

注意事项