组织架构

组织架构说明

组织架构的定义

组织结构说明

字段	类型	是否必须	描述
id	LONG	否	自增 id
name	STRING	是	名称
code	STRING	是	组织编码，全局唯一
source	STRING	是	组织来源，api创建固定值为internal
createdAt	DATETIME	否	创建的时间
createdBy	INTEGER	否	创建用户的 id
updatedAt	DATETIME	否	最后更新的时间
updatedBy	INTEGER	否	最后修改用户的 id
email	STRING	否	组织邮箱
parentId	INTEGER	否	上级组织id
orderNo	INTEGER	否	组织排序号
parentCode	STRING	否	上级组织编码，新增修改时不是必须传递
isRoot	BOOLEAN	否	只有将非根节点修改为根节点时需要传递

接口说明

创建组织

创建组织。

请求URL

POST /api/orgs HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

请求参数

URL 参数

无

request body 参数

组织结构说明

返回对象的格式说明

组织结构说明

接口示例1: 创建组织

Request

POST /api/orgs HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

// Request Body:
{
  "name": "组织名称",
  "description": "",
  "parentId": 29,
  "code": "112233",
  "orderNo": 1
}

Response

HTTP/1.1 200 Ok
Content-Type: application/json

{
  "version": "version@9a5e106#6730f0d",
  "code": 0,
  "msg": "success",
  "data": {
    "id": 31,
    "name": "组织名称",
    "description": "",
    "createdBy": 2,
    "createdAt": "2022-08-09 15:23:05",
    "updatedBy": 2,
    "updatedAt": "2022-08-09 15:23:05",
    "parentId": 29,
    "source": "internal",
    "code": "112233",
    "parentCode": "1122",
    "orderNo": 1
  }
}

修改组织

修改组织。

请求URL

PUT /api/orgs/{orgId} HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

请求参数

URL 参数

字段	类型	是否必须	说明
orgId	LONG	是	修改组织的 id

request body 参数

组织结构说明

返回对象的格式说明

组织结构说明

接口示例1: 修改组织

Request

PUT /api/orgs/{orgId} HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

// Request Body:
{
  "id":31,
  "name": "组织名称updated",
  "description": "",
  "parentId": 29,
  "code": "112233",
  "orderNo": 1
}

Response

HTTP/1.1 200 Ok
Content-Type: application/json

{
  "version": "version@9a5e106#6730f0d",
  "code": 0,
  "msg": "success",
  "data": {
    "id": 31,
    "name": "组织名称updated",
    "description": "",
    "updatedBy": 2,
    "updatedAt": "2022-08-09 15:25:54",
    "parentId": 29,
    "source": "internal",
    "code": "112233",
    "parentCode": "1122",
    "orderNo": 1
  }
}

删除组织

删除组织。

请求URL

DELETE /api/orgs/{orgId} HTTP/1.1

请求参数

URL 参数

字段	类型	是否必须	说明
orgId	LONG	是	组织的 id

request body 参数

无

说明

组织有下级组织无法删除，组织中有用户无法删除。需要删除下级组织和用户才能删除该组织。

接口示例1: 删除组织

Request

DELETE /api/orgs/{orgId} HTTP/1.1

Response

HTTP/1.1 200 Ok
Content-Type: application/json

{
  "version": "version@9a5e106#6730f0d",
  "code": 0,
  "msg": "success"
}

通过id查询组织

通过id查询组织。

请求URL

GET /api/orgs/{orgId} HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

请求参数

URL 参数

字段	类型	是否必须	说明
orgId	LONG	是	组织的 id

request body 参数

无

返回对象的格式说明

组织结构说明

接口示例1: 通过id查询组织

Request

GET /api/orgs/{orgId} HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

Response

HTTP/1.1 200 Ok
Content-Type: application/json

{
  "version": "version@9a5e106#6730f0d",
  "code": 0,
  "msg": "success",
  "data": {
    "id": 31,
    "name": "组织名称updated",
    "description": "",
    "createdBy": 2,
    "createdAt": "2022-08-09 15:23:05",
    "updatedBy": 2,
    "updatedAt": "2022-08-09 15:25:54",
    "parentId": 29,
    "source": "internal",
    "code": "112233",
    "parentCode": "1122",
    "orderNo": 1
  }
}

通过code查询组织

通过code查询组织。

请求URL

GET /api/orgs/code/{orgCode} HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

请求参数

URL 参数

字段	类型	是否必须	说明
orgCode	STRING	是	组织的 code

request body 参数

无

返回对象的格式说明

组织结构说明

接口示例1: 通过code查询组织

Request

GET /api/orgs/code/{orgCode} HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

Response

HTTP/1.1 200 Ok
Content-Type: application/json

{
    "version": "version@9a5e106#6730f0d",
    "code": 0,
    "msg": "success",
    "data": {
        "id": 31,
        "name": "组织名称updated",
        "description": "",
        "createdBy": 2,
        "createdAt": "2022-08-09 15:23:05",
        "updatedBy": 2,
        "updatedAt": "2022-08-09 15:25:54",
        "parentId": 29,
        "source": "internal",
        "code": "112233",
        "parentCode": "1122",
        "orderNo": 1,
        "delete": false
    }
}

通过 code 修改组织

通过 code 修改组织。

请求URL

PUT /api/orgs/code/{orgCode} HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

请求参数

URL 参数

字段	类型	是否必须	说明
orgCode	STRING	是	修改组织的 code

request body 参数

组织结构说明

返回对象的格式说明

组织结构说明

接口示例1: 通过 code 修改组织

Request

PUT /api/orgs/code/{orgCode} HTTP/1.1
Content-Type: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

// Request Body:
{
  "name": "组织名称updated",
  "description": "",
  "parentId": 29,
  "code": "112233",
  "parentCode": "1122",
  "orderNo": 1
}

Response

HTTP/1.1 200 Ok
Content-Type: application/json

{
  "version": "version@9a5e106#6730f0d",
  "code": 0,
  "msg": "success",
  "data": {
    "id": 31,
    "name": "组织名称updated",
    "description": "",
    "updatedBy": 2,
    "updatedAt": "2022-08-09 15:25:54",
    "parentId": 29,
    "source": "internal",
    "code": "112233",
    "parentCode": "1122",
    "orderNo": 1
  }
}

通过 code 删除组织

通过 code 删除组织。

请求URL

DELETE /api/orgs/code/{orgCode} HTTP/1.1

请求参数

URL 参数

字段	类型	是否必须	说明
orgCode	STRING	是	组织的 code

request body 参数

无

说明

组织有下级组织无法删除，组织中有用户无法删除。需要删除下级组织和用户才能删除该组织。

接口示例1: 通过 code 删除组织

Request

DELETE /api/orgs/code/{orgCode} HTTP/1.1

Response

HTTP/1.1 200 Ok
Content-Type: application/json

{
  "version": "version@9a5e106#6730f0d",
  "code": 0,
  "msg": "success"
}

查询组织列表

查询组织列表。

请求URL

GET /api/orgs HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

请求参数

URL 参数

字段	类型	是否必须	说明
parentId	LONG	否	组织的父级 id ，不传则从根结点查询
fetchChild	BOOLEAN	否	是否递归查询所有下级组织，默认为false

request body 参数

无

返回对象的格式说明

组织结构说明

接口示例1: 查询组织列表

Request

GET /api/orgs HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

Response

HTTP/1.1 200 Ok
Content-Type: application/json

{
    "version": "version@9a5e106#6730f0d",
    "code": 0,
    "msg": "success",
    "data": [
        {
            "id": 1,
            "name": "第一级组织",
            "description": "",
            "createdBy": 2,
            "createdAt": "2022-08-09 10:37:35",
            "updatedBy": 2,
            "updatedAt": "2022-08-09 10:37:35",
            "source": "internal",
            "code": "1",
            "orderNo": 0,
            "delete": false
        }
    ]
}

查询子部门及用户

查询组织列表。

请求URL

GET /api/orgs/depts-users?parentId={parentId} HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

请求参数

URL Query 参数

字段	类型	是否必须	说明
parentId	LONG	否	组织的父级 id ，不传则从根结点查询

无

返回对象的格式说明

字段	类型	说明
version	STRING	当前系统版本哈希值
data.subOrgs	JSON ARRAY	组织结构说明
data.users	JSON ARRAY	用户结构说明

接口示例1: 查询子部门及用户

Request

GET /api/orgs/depts-users?parentId={parentId} HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

Response

HTTP/1.1 200 Ok
Content-Type: application/json

{
  "version": "version@9a5e106#6730f0d",
  "code":0,
  "msg":"success",
  "data":{
    "subOrgs":[
      {
        "id":23,
        "name":"开发部",
        "description":"",
        "createdBy":11630,
        "createdAt":"2023-07-12 15:23:48",
        "updatedBy":11630,
        "updatedAt":"2023-07-12 15:23:48",
        "parentId":1,
        "code":"490058140",
        "parentCode":"1",
        "orderNo":1,
        "delete":false
      }
    ],
    "users":[
      {
        "id":159,
        "name":"test",
        "email":"anonymous@hengshi.com",
        "description":"user import from LDAP.",
        "isDelete":false,
        "loginName":"test"
      }
    ]
  }
}

导入组织架构

1. 新增或者更新组织架构，更新是可以通过id/code找到已经存在的组织架构，通过parentId/parentCode维护父子关系。
2. 批量新增时需要先新增父节点再新增子节点，所以传数组参数时父节点要在子节点的前面。

请求URL

POST /api/orgs/batch/import HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

请求参数

request body 参数

字段	类型	是否必须	说明
orgs	LIST<JSONOBJECT>	是	数组的元素是组织架构，参考组织结构说明

返回对象的格式说明

字段	类型	说明
version	STRING	当前系统版本哈希值
code	LONG	成功为0
msg	STRING	错误信息

接口示例1: 导入组织架构

Request

POST /api/orgs/batch/import HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

[
	{
		"code": "parent1",
		"name": "parent1"
	},
	{
		"code": "sub1",
		"name": "sub1",
		"parentCode": "parent1"
	},
	{
		"code": "sub1_1",
		"name": "sub1_1",
		"parentCode": "sub1"
	}
]

Response

HTTP/1.1 200 Ok
Content-Type: application/json

{
	"version": "xxx",
	"code": 0,
	"msg": "success"
}

批量删除组织架构

1. 需要删除的组织架构下不能包含子节点和用户。

请求URL

POST /api/orgs/batch/delete HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

请求参数

request body 参数

字段	类型	是否必须	说明
org	JSON OBJECT	是	组织架构
org.ids	LIST<LONG>	否	组织架构 id 集合
org.codes	LIST<STRING>	否	组织架构 code 集合

ids/codes需要有一个非空，不支持同时设置，优先级ids>codes。

返回对象的格式说明

字段	类型	说明
version	STRING	当前系统版本哈希值
code	LONG	成功为0
msg	STRING	错误信息

接口示例1: 批量删除组织架构

Request

POST /api/orgs/batch/delete HTTP/1.1
Accept: application/json
Cookie: csrf=183f1c4...; sid=26ee552d...; _USER_SESSION_ID=f2a01083...

{
	"codes": [
		"sub1_1",
		"sub1",
		"parent1"
	]
}

Response

HTTP/1.1 200 Ok
Content-Type: application/json

{
	"version": "xxx",
	"code": 0,
	"msg": "success"
}