一单位一平台

主题

HzTech2026-01-04
3496
14.3m

部门管理接口文档 ​

概述 ​

部门管理模块提供了子应用向一单位一平台查询部门数据的能力，支持部门信息的查询、树形结构查询、部门搜索等功能。部门采用树形结构组织，支持多级嵌套。所有接口遵循国密 SM2/SM4 数字信封加密方案，确保数据传输安全。

交互方向 ​

本模块包含以下交互方向:

交互方向接口类型子应用实现要求说明
子应用→一单位一平台(查询)查询部门详情、部门列表、部门树、部门搜索❌ 无需实现子应用主动查询部门数据,一单位一平台提供查询接口

重要说明: 本模块所有接口均为"子应用→一单位一平台"查询接口,子应用直接调用一单位一平台提供的接口,无需额外实现。

使用场景 ​

  • 子应用→一单位一平台(查询): 子应用向一单位一平台查询部门详情
  • 子应用→一单位一平台(查询): 子应用向一单位一平台查询部门列表(支持分页和条件筛选)
  • 子应用→一单位一平台(查询): 子应用向一单位一平台查询部门树结构
  • 子应用→一单位一平台(查询): 子应用向一单位一平台搜索部门
  • 数据同步: 子应用通过部门列表或部门树接口定期同步一单位一平台的部门数据

接口设计原则 ​

所有接口均采用国密 SM2/SM4 数字信封加密方案:

  1. 统一 POST 方式：所有接口使用 POST 方法,业务参数在 encryptData 中加密传输
  2. 无路径参数：URL 路径中不包含任何业务参数(如 departmentId),所有业务参数均在加密报文中
  3. 安全性：通过 SM2 混合加密和数字签名确保数据传输的机密性、完整性和不可抵赖性

适用范围 ​

适用于子应用向一单位一平台查询部门数据以及同步部门信息到本地的场景。

术语定义 ​

核心概念 ​

术语说明
一单位一平台核心管理平台,负责数据存储、权限管理、接口路由等核心功能
子应用接入一单位一平台的独立业务系统,通过一单位一平台网关与其他系统交互
网关一单位一平台的统一入口,负责路由转发、身份认证、权限控制、速率限制等

操作语义 ​

术语说明数据流向接口实现方
查询主动请求获取数据子应用→一单位一平台一单位一平台实现

重要提示:

  • "查询"表示子应用主动向一单位一平台请求数据,由一单位一平台提供查询接口

系统架构 ​

数据流向 ​

查询流程(子应用→一单位一平台) ​

子应用 → [加密请求] → 一单位一平台 → [加密响应] → 子应用

接口列表 ​

子应用→一单位一平台(查询接口) ​

接口名称请求地址交互方向说明
查询部门详情POST /hztech-application/department/detail子→主(查询)获取单个部门信息
部门列表查询POST /hztech-application/department/list子→主(查询)分页查询部门列表
部门树查询POST /hztech-application/department/tree子→主(查询)获取部门树结构
部门搜索POST /hztech-application/department/search子→主(查询)搜索部门

注: 所有业务参数均在 encryptData 中加密传输,URL 路径中不包含任何业务参数。

接口详情 ​

1.1 查询部门详情 ​

接口说明

查询单个部门的详细信息。子应用向一单位一平台请求部门数据。

请求方式

POST

请求地址

POST /hztech-application/department/detail

交互方向

子应用 → 一单位一平台 (查询)

完整时序图

请求参数

参数名类型必填说明示例值
idString是部门ID"1123598813738675201"

HTTP 请求示例

http
POST /hztech-application/department/detail HTTP/1.1
Host: main.example.com
Content-Type: application/json

{
  "appId": "SUB_APP_001",
  "version": "1.0",
  "timestamp": 1735516800000,
  "nonce": "f6a7b8c9-d0e1-1234-5678-9abcdef01234",
  "encryptKey": "MIIBOgIBAAJBAKj34GkxFhD90vcNLYLInFEX6...",
  "encryptData": "U2FsdGVkX1+jmZn5KqWYEgjPkQKpH5KqWYEg...",
  "sign": "MEUCIQDZ5KqWYEgjPkQKpH5KqWYEgjPkQKpH5KqWY..."
}

encryptData 解密后的业务数据

json
{
  "id": "1123598813738675201"
}

HTTP 响应示例

json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": "1993612618892795906",
    "tenantId": "000000",
    "parentId": "0",
    "fullName": "ISV",
    "deptName": "ISV",
    "ancestors": "0",
    "leaderId": "",
    "deptCategory": 1,
    "sort": 1,
    "remark": "",
    "status": 1,
    "isDeleted": 0,
    "hasChildren": true,
    "dataSource": -1,
    "parentName": "",
    "deptCategoryName": "公司"
  }
}

错误响应示例

json
{
  "code": 2601,
  "message": "部门不存在",
  "timestamp": 1735516801000
}

1.2 部门列表查询 ​

接口说明

分页查询部门列表。支持按父部门、状态等条件筛选。结果按照更新时间倒序排列。

请求方式

POST

请求地址

POST /hztech-application/department/list

交互方向

子应用 → 一单位一平台 (查询)

完整时序图

请求参数

参数名类型必填说明示例值
pageNumInteger否页码(默认1)1
pageSizeInteger否每页数量(默认20)20
deptNameString否部门名称(模糊查询)"ISV"
parentIdString否父部门ID"0"
statusInteger否状态(1:启用,0:禁用)1

HTTP 请求示例

http
POST /hztech-application/department/list HTTP/1.1
Host: main.example.com
Content-Type: application/json

{
  "appId": "SUB_APP_001",
  "version": "1.0",
  "timestamp": 1735516800000,
  "nonce": "f6a7b8c9-d0e1-1234-5678-9abcdef01234",
  "encryptKey": "MIIBOgIBAAJBAKj34GkxFhD90vcNLYLInFEX6...",
  "encryptData": "U2FsdGVkX1+jmZn5KqWYEgjPkQKpH5KqWYEg...",
  "sign": "MEUCIQDZ5KqWYEgjPkQKpH5KqWYEgjPkQKpH5KqWY..."
}

encryptData 解密后的业务数据

json
{
  "pageNum": 1,
  "pageSize": 20,
  "parentId": "0",
  "status": 1
}

HTTP 响应示例

json
{
  "code": 200,
  "message": "success",
  "data": {
    "total": 50,
    "pageNum": 1,
    "pageSize": 20,
    "pages": 3,
    "list": [
      {
        "id": "1993612618892795906",
        "tenantId": "000000",
        "parentId": "0",
        "fullName": "ISV",
        "deptName": "ISV",
        "ancestors": "0",
        "leaderId": "",
        "deptCategory": 1,
        "sort": 1,
        "remark": "",
        "status": 1,
        "isDeleted": 0,
        "hasChildren": true,
        "dataSource": -1,
        "parentName": "",
        "deptCategoryName": "公司"
      }
    ]
  }
}

1.3 部门树查询 ​

接口说明

查询完整的部门树结构。返回所有部门及其层级关系。

请求方式

POST

请求地址

POST /hztech-application/department/tree

交互方向

子应用 → 一单位一平台 (查询)

完整时序图

请求参数

参数名类型必填说明示例值
statusInteger否状态(1:启用,0:禁用,空表示所有)1

HTTP 请求示例

http
POST /hztech-application/department/tree HTTP/1.1
Host: main.example.com
Content-Type: application/json

{
  "appId": "SUB_APP_001",
  "version": "1.0",
  "timestamp": 1735516800000,
  "nonce": "f6a7b8c9-d0e1-1234-5678-9abcdef01234",
  "encryptKey": "MIIBOgIBAAJBAKj34GkxFhD90vcNLYLInFEX6...",
  "encryptData": "U2FsdGVkX1+jmZn5KqWYEgjPkQKpH5KqWYEg...",
  "sign": "MEUCIQDZ5KqWYEgjPkQKpH5KqWYEgjPkQKpH5KqWY..."
}

encryptData 解密后的业务数据

json
{
  "status": 1
}

HTTP 响应示例

json
{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": "1993612618892795906",
      "tenantId": "000000",
      "parentId": "0",
      "fullName": "ISV",
      "deptName": "ISV",
      "ancestors": "0",
      "leaderId": "",
      "deptCategory": 1,
      "sort": 1,
      "remark": "",
      "status": 1,
      "isDeleted": 0,
      "hasChildren": true,
      "dataSource": -1,
      "parentName": "",
      "deptCategoryName": "公司",
      "children": [
        {
          "id": "1993612619815542785",
          "tenantId": "000000",
          "parentId": "1993612618892795906",
          "fullName": "默认单位",
          "deptName": "默认单位",
          "ancestors": "0,1993612618892795906",
          "leaderId": "",
          "deptCategory": 1,
          "sort": 1,
          "remark": "",
          "status": 1,
          "isDeleted": 0,
          "hasChildren": false,
          "dataSource": -1,
          "parentName": "",
          "deptCategoryName": "公司"
        }
      ]
    }
  ]
}

1.4 部门搜索 ​

接口说明

根据关键词搜索部门。支持按部门名称、编码搜索。

请求方式

POST

请求地址

POST /hztech-application/department/search

交互方向

子应用 → 一单位一平台 (查询)

完整时序图

请求参数

参数名类型必填说明示例值
keywordString是搜索关键词"技术"
searchTypeString否搜索类型(all/name/code)"all"
pageNumInteger否页码(默认1)1
pageSizeInteger否每页数量(默认20)20

HTTP 请求示例

http
POST /hztech-application/department/search HTTP/1.1
Host: main.example.com
Content-Type: application/json

{
  "appId": "SUB_APP_001",
  "version": "1.0",
  "timestamp": 1735516800000,
  "nonce": "f6a7b8c9-d0e1-1234-5678-9abcdef01234",
  "encryptKey": "MIIBOgIBAAJBAKj34GkxFhD90vcNLYLInFEX6...",
  "encryptData": "U2FsdGVkX1+jmZn5KqWYEgjPkQKpH5KqWYEg...",
  "sign": "MEUCIQDZ5KqWYEgjPkQKpH5KqWYEgjPkQKpH5KqWY..."
}

encryptData 解密后的业务数据

json
{
  "keyword": "ISV",
  "searchType": "all",
  "pageNum": 1,
  "pageSize": 20
}

HTTP 响应示例

json
{
  "code": 200,
  "message": "success",
  "data": {
    "total": 5,
    "pageNum": 1,
    "pageSize": 20,
    "list": [
      {
        "id": "1993612618892795906",
        "deptName": "ISV",
        "fullName": "ISV",
        "parentId": "0",
        "parentName": "",
        "deptCategoryName": "公司"
      }
    ]
  }
}

数据模型 ​

部门对象 (Department) ​

完整的部门数据结构:

json
{
  "id": "string",                      // 部门ID(系统生成)
  "tenantId": "string",                // 租户ID
  "parentId": "string",                // 父部门ID(根部门为"0")
  "fullName": "string",                // 部门全称
  "deptName": "string",                // 部门名称
  "ancestors": "string",               // 祖级列表(逗号分隔的ID)
  "leaderId": "string",                // 部门负责人ID
  "deptCategory": 1,                   // 部门类别(1:公司)
  "sort": 0,                           // 排序号
  "remark": "string",                  // 备注
  "status": 1,                         // 状态: 1-启用, 0-禁用
  "isDeleted": 0,                      // 是否删除(1:已删除,0:未删除)
  "hasChildren": false,                // 是否有子部门
  "dataSource": -1,                    // 数据来源
  "parentName": "string",              // 父部门名称
  "deptCategoryName": "string",        // 部门类别名称
  "children": []                       // 子部门列表(仅在树形结构中)
}

字段说明 ​

字段类型必填说明约束
idString是部门唯一标识系统生成,不可修改
tenantIdString是租户ID租户标识
parentIdString是父部门ID根部门为"0"
fullNameString是部门全称完整部门名称
deptNameString是部门名称2-100个字符
ancestorsString是祖级列表逗号分隔的ID列表,如"0,1,2"
leaderIdString否部门负责人ID关联用户表
deptCategoryInteger是部门类别1:公司,2:部门
sortInteger是排序号数值越小越靠前
remarkString否备注最多500个字符
statusInteger是状态1:启用,0:禁用
isDeletedInteger是是否删除1:已删除,0:未删除
hasChildrenBoolean是是否有子部门true/false
dataSourceInteger否数据来源数据来源标识
parentNameString否父部门名称冗余字段
deptCategoryNameString否部门类别名称"公司"或"部门"
childrenArray否子部门列表仅在树形结构中返回

枚举值说明 ​

部门状态 (status):

  • 1: 启用
  • 0: 禁用

是否删除 (isDeleted):

  • 1: 已删除
  • 0: 未删除

部门类别 (deptCategory):

  • 1: 公司
  • 2: 部门

是否有子部门 (hasChildren):

  • true: 有子部门
  • false: 无子部门

树形结构说明 ​

部门采用递归树形结构:

  • 根部门的 parentId 为 "0"
  • 每个部门可包含多个子部门,通过 children 字段返回
  • ancestors 字段记录从根部门到当前部门的完整路径,如 "0,1993612618892795906"
  • hasChildren 标识当前部门是否有子部门
  • 查询部门树时,会递归返回所有层级的子部门

错误码 ​

业务错误码 ​

错误码说明处理建议
2601部门不存在检查departmentId是否正确
2602部门编码已存在使用其他编码
2603部门名称已存在使用其他名称
2604父部门不存在检查parentId是否正确
2605部门层级超限检查部门层级深度
2606部门循环引用检查parentId不能是部门自身或子部门
2607部门存在下级,无法删除先删除子部门
2608部门存在人员,无法删除先转移或删除部门人员

系统错误码 ​

错误码说明处理建议
1001时间戳过期同步系统时间
1002重复请求检查nonce生成逻辑
1003签名验证失败检查密钥配置
1004解密失败检查密钥配置
1005appId不存在检查appId注册
1006业务逻辑错误根据具体错误处理

相关文档 ​

文档版本: v1.0.0 最后更新: 2026-01-04

最近更新