System项目AI文档

Appearance

组织架构模块接口规范 ​

文档编号: SYS-INT-API-ORG-001
模块: 组织架构 (ORG)
基础路径: /api/v1/orgs
版本: v1
日期: 2026-03-09
作者: 系统架构师
状态: ✅ 已评审

一、模块概述 ​

1.1 功能说明 ​

组织架构模块提供部门管理和岗位管理功能，支持树形结构的组织架构管理，实现人员和部门的关联。

1.2 接口列表 ​

序号接口名称方法路径权限要求
1查询部门树GET/depts/treeorg:read
2创建部门POST/deptsorg:create
3查询部门详情GET/depts/{id}org:read
4更新部门PUT/depts/{id}org:update
5删除部门DELETE/depts/{id}org:delete
6查询部门用户GET/depts/{id}/usersorg:read, user:read
7查询岗位列表GET/postsorg:read
8创建岗位POST/postsorg:create
9更新岗位PUT/posts/{id}org:update
10删除岗位DELETE/posts/{id}org:delete

二、接口详细定义 ​

1. 查询部门树 ​

基本信息 ​

项目内容
接口名称查询部门树
请求方法GET
接口路径/api/v1/orgs/depts/tree
权限要求org:read

请求参数 ​

Query参数:

参数名类型必填说明示例
statusinteger否状态：0-禁用，1-启用1

响应数据 ​

成功响应:

json
{
  "code": 0,
  "data": [
    {
      "id": 1,
      "code": "company",
      "name": "总公司",
      "parentId": 0,
      "path": "/1/",
      "level": 1,
      "sort": 1,
      "leader": "张总",
      "phone": "010-12345678",
      "email": "company@example.com",
      "status": 1,
      "statusName": "启用",
      "userCount": 100,
      "children": [
        {
          "id": 2,
          "code": "tech",
          "name": "技术部",
          "parentId": 1,
          "path": "/1/2/",
          "level": 2,
          "sort": 1,
          "leader": "李经理",
          "phone": "010-12345679",
          "email": "tech@example.com",
          "status": 1,
          "statusName": "启用",
          "userCount": 30,
          "children": [
            {
              "id": 3,
              "code": "backend",
              "name": "后端组",
              "parentId": 2,
              "path": "/1/2/3/",
              "level": 3,
              "sort": 1,
              "leader": "王组长",
              "status": 1,
              "statusName": "启用",
              "userCount": 15,
              "children": []
            }
          ]
        }
      ]
    }
  ],
  "error": null,
  "message": "ok"
}

字段说明:

字段类型说明
idinteger部门ID
codestring部门编码
namestring部门名称
parentIdinteger父部门ID，0表示顶级部门
pathstring部门路径，如 /1/2/3/
levelinteger部门层级
sortinteger排序号
leaderstring负责人姓名
phonestring联系电话
emailstring邮箱
statusinteger状态：0-禁用，1-启用
statusNamestring状态名称
userCountinteger部门用户数
childrenarray子部门列表

2. 创建部门 ​

基本信息 ​

项目内容
接口名称创建部门
请求方法POST
接口路径/api/v1/orgs/depts
权限要求org:create

请求参数 ​

Body参数 (application/json):

参数名类型必填说明示例
codestring是部门编码，唯一，2-50字符frontend
namestring是部门名称，2-50字符前端组
parentIdinteger否父部门ID，默认02
sortinteger否排序号，默认02
leaderstring否负责人姓名赵组长
phonestring否联系电话010-12345680
emailstring否邮箱frontend@example.com
statusinteger否状态：0-禁用，1-启用，默认11

请求示例 ​

http
POST /api/v1/orgs/depts
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

{
  "code": "frontend",
  "name": "前端组",
  "parentId": 2,
  "sort": 2,
  "leader": "赵组长",
  "phone": "010-12345680",
  "email": "frontend@example.com",
  "status": 1
}

响应数据 ​

成功响应:

json
{
  "code": 0,
  "data": {
    "id": 4,
    "code": "frontend",
    "name": "前端组",
    "parentId": 2,
    "path": "/1/2/4/",
    "level": 3,
    "status": 1,
    "createTime": "2024-03-09T10:00:00Z"
  },
  "error": null,
  "message": "ok"
}

3. 查询部门详情 ​

基本信息 ​

项目内容
接口名称查询部门详情
请求方法GET
接口路径/api/v1/orgs/depts/{id}
权限要求org:read

请求参数 ​

Path参数:

参数名类型必填说明示例
idinteger是部门ID2

响应数据 ​

json
{
  "code": 0,
  "data": {
    "id": 2,
    "code": "tech",
    "name": "技术部",
    "parentId": 1,
    "parentName": "总公司",
    "path": "/1/2/",
    "level": 2,
    "sort": 1,
    "leader": "李经理",
    "phone": "010-12345679",
    "email": "tech@example.com",
    "status": 1,
    "statusName": "启用",
    "userCount": 30,
    "createTime": "2024-01-01T10:00:00Z",
    "updateTime": "2024-03-09T10:00:00Z"
  },
  "error": null,
  "message": "ok"
}

4. 更新部门 ​

基本信息 ​

项目内容
接口名称更新部门
请求方法PUT
接口路径/api/v1/orgs/depts/{id}
权限要求org:update

请求参数 ​

Path参数:

参数名类型必填说明示例
idinteger是部门ID2

Body参数:

参数名类型必填说明
namestring否部门名称
sortinteger否排序号
leaderstring否负责人
phonestring否联系电话
emailstring否邮箱
statusinteger否状态

注意: 不能修改部门编码和父部门ID，如需调整部门位置，需使用专门的移动接口。

5. 删除部门 ​

基本信息 ​

项目内容
接口名称删除部门
请求方法DELETE
接口路径/api/v1/orgs/depts/{id}
权限要求org:delete

响应数据 ​

错误响应:

json
{
  "code": -1,
  "data": {
    "childrenCount": 3
  },
  "error": "该部门有子部门，无法删除",
  "message": "该部门有子部门，无法删除"
}

或

json
{
  "code": -1,
  "data": {
    "userCount": 10
  },
  "error": "该部门有关联用户，无法删除",
  "message": "该部门有关联用户，无法删除"
}

6. 查询部门用户 ​

基本信息 ​

项目内容
接口名称查询部门用户
请求方法GET
接口路径/api/v1/orgs/depts/{id}/users
权限要求org:read, user:read

请求参数 ​

Path参数:

参数名类型必填说明示例
idinteger是部门ID2

Query参数:

参数名类型必填说明示例
pageinteger否当前页码，默认11
sizeinteger否每页大小，默认1010
recursiveboolean否是否包含子部门用户，默认falsetrue

响应数据 ​

json
{
  "code": 0,
  "data": {
    "items": [
      {
        "id": 1,
        "username": "zhangsan",
        "nickname": "张三",
        "email": "zhangsan@example.com",
        "phone": "13800138000",
        "postName": "高级工程师",
        "isMainDept": true,
        "joinTime": "2024-01-01T10:00:00Z"
      }
    ],
    "total": 30
  },
  "error": null,
  "message": "ok"
}

字段说明:

字段类型说明
postNamestring岗位名称
isMainDeptboolean是否主部门
joinTimestring加入部门时间

7. 查询岗位列表 ​

基本信息 ​

项目内容
接口名称查询岗位列表
请求方法GET
接口路径/api/v1/orgs/posts
权限要求org:read

请求参数 ​

Query参数:

参数名类型必填说明示例
pageinteger否当前页码，默认11
sizeinteger否每页大小，默认1010
keywordstring否搜索关键词工程师
statusinteger否状态：0-禁用，1-启用1

响应数据 ​

json
{
  "code": 0,
  "data": {
    "items": [
      {
        "id": 1,
        "code": "senior-engineer",
        "name": "高级工程师",
        "level": 3,
        "levelName": "P7",
        "sort": 1,
        "status": 1,
        "statusName": "启用",
        "userCount": 10,
        "createTime": "2024-01-01T10:00:00Z"
      }
    ],
    "total": 20
  },
  "error": null,
  "message": "ok"
}

8. 创建岗位 ​

基本信息 ​

项目内容
接口名称创建岗位
请求方法POST
接口路径/api/v1/orgs/posts
权限要求org:create

请求参数 ​

Body参数:

参数名类型必填说明示例
codestring是岗位编码，唯一architect
namestring是岗位名称架构师
levelinteger否岗位等级5
levelNamestring否等级名称P9
sortinteger否排序号1
statusinteger否状态：0-禁用，1-启用1

请求示例 ​

http
POST /api/v1/orgs/posts
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

{
  "code": "architect",
  "name": "架构师",
  "level": 5,
  "levelName": "P9",
  "sort": 1,
  "status": 1
}

9. 更新岗位 ​

基本信息 ​

项目内容
接口名称更新岗位
请求方法PUT
接口路径/api/v1/orgs/posts/{id}
权限要求org:update

请求参数 ​

Path参数:

参数名类型必填说明示例
idinteger是岗位ID1

Body参数:

参数名类型必填说明
namestring否岗位名称
levelinteger否岗位等级
levelNamestring否等级名称
sortinteger否排序号
statusinteger否状态

10. 删除岗位 ​

基本信息 ​

项目内容
接口名称删除岗位
请求方法DELETE
接口路径/api/v1/orgs/posts/{id}
权限要求org:delete

响应数据 ​

错误响应 (409 Conflict):

json
{
  "code": 409,
  "message": "该岗位有关联用户，无法删除",
  "data": {
    "userCount": 5
  },
  "timestamp": 1709827200000
}

三、数据模型 ​

3.1 部门对象 (Department) ​

字段类型必填说明
idinteger是部门ID
codestring是部门编码，唯一，2-50字符
namestring是部门名称，2-50字符
parentIdinteger是父部门ID，0表示顶级
pathstring是部门路径，如 /1/2/3/
levelinteger是部门层级
sortinteger否排序号
leaderstring否负责人姓名
phonestring否联系电话
emailstring否邮箱
statusinteger是状态：0-禁用，1-启用
userCountinteger否部门用户数
createTimedatetime是创建时间
updateTimedatetime是更新时间

3.2 岗位对象 (Post) ​

字段类型必填说明
idinteger是岗位ID
codestring是岗位编码，唯一
namestring是岗位名称
levelinteger否岗位等级
levelNamestring否等级名称
sortinteger否排序号
statusinteger是状态：0-禁用，1-启用
userCountinteger否岗位用户数
createTimedatetime是创建时间
updateTimedatetime是更新时间

四、组织架构规则 ​

4.1 部门层级限制 ​

  • 最大层级：5级
  • 顶级部门：parentId = 0
  • 部门路径：自动计算，格式如 /1/2/3/

4.2 部门编码规则 ​

  • 格式：小写字母、数字、连字符
  • 唯一性：全系统唯一
  • 示例：company, tech, backend, frontend

4.3 岗位等级 ​

等级名称说明
1P5初级工程师
2P6中级工程师
3P7高级工程师
4P8资深工程师
5P9架构师

五、错误码 ​

错误码错误信息说明
400请求参数错误参数校验失败
401未认证Token无效或过期
403无权限用户无此操作权限
404部门/岗位不存在指定的ID不存在
409数据冲突编码已存在或有依赖关系
422层级超限部门层级超过最大限制
500服务器内部错误系统异常

六、相关文档 ​

七、评审记录 ​

7.1 评审意见 ​

序号评审项评审结果评审意见
1接口完整性✓ 通过覆盖部门和岗位管理所有功能
2接口规范性✓ 通过符合RESTful API设计规范
3树形结构✓ 通过部门树设计合理，支持5级层级
4岗位等级✓ 通过岗位等级体系（P5-P9）设计清晰
5数据模型✓ 通过模型设计完整，路径计算逻辑清晰

7.2 评审结论 ​

评审结论: 通过

评审意见: 组织架构模块接口规范完整，树形结构设计合理，岗位等级体系清晰，可作为开发依据。

7.3 签字确认 ​

角色姓名签字日期意见
技术总监张总_______________2026-03-09同意
系统架构师李工_______________2026-03-09同意
后端架构师王工_______________2026-03-09同意
前端负责人陈工_______________2026-03-09同意

八、修订记录 ​

版本日期作者变更内容
1.02026-03-09系统架构师初始版本，定义组织架构模块10个接口
1.12026-03-11系统架构师统一响应格式，与Mock服务保持一致

Released under the MIT License.

Copyright © 2026 linsir | 鄂ICP备99999999号