一单位一平台

主题

HzTech2026-01-04
3965
16.6m

人员管理接口文档 ​

概述 ​

人员管理模块提供了子应用向一单位一平台查询和同步人员数据的能力，支持人员信息的查询、人员搜索、角色部门查询等功能。所有接口遵循国密 SM2/SM4 数字信封加密方案，确保数据传输安全。

交互方向 ​

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

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

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

使用场景 ​

  • 子应用→一单位一平台(查询): 子应用向一单位一平台查询人员详情
  • 子应用→一单位一平台(查询): 子应用向一单位一平台查询人员列表(支持分页和条件筛选)
  • 子应用→一单位一平台(查询): 子应用向一单位一平台搜索人员
  • 子应用→一单位一平台(查询): 子应用向一单位一平台查询人员角色、部门等关联信息
  • 数据同步: 子应用通过人员列表接口定期同步一单位一平台的人员数据

接口设计原则 ​

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

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

适用范围 ​

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

术语定义 ​

核心概念 ​

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

操作语义 ​

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

重要提示:

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

系统架构 ​

数据流向 ​

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

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

接口列表 ​

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

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

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

接口详情 ​

1.1 查询人员详情 ​

接口说明

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

请求方式

POST

请求地址

POST /hztech-application/user/detail

交互方向

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

完整时序图

请求参数

参数名类型必填说明示例值
idString是用户ID"1123598821738675203"

HTTP 请求示例

http
POST /hztech-application/user/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": "1123598821738675203"
}

HTTP 响应示例

json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": "1123598821738675203",
    "createUser": "1123598821738675201",
    "createDept": "1123598813738675201",
    "createTime": "2019-04-27 17:03:38",
    "updateUser": "1123598821738675201",
    "updateTime": "2019-04-27 17:03:38",
    "status": 1,
    "isDeleted": 0,
    "tenantId": "000000",
    "code": "",
    "userType": 1,
    "account": "manager",
    "name": "经理",
    "realName": "经理",
    "avatar": "https://hztech.cn/images/logo-small.png",
    "email": "ma****@hztech.vip",
    "phone": "",
    "birthday": "2018-08-08 00:00:00",
    "sex": 1,
    "roleId": "1123598816738675204",
    "deptId": "1123598813738675202",
    "postId": "1123598817738675206",
    "leaderId": "",
    "isLeader": 0,
    "employmentStatus": "1",
    "tenantName": "管理组",
    "userTypeName": "WEB",
    "roleName": "经理",
    "deptName": "常州分公司",
    "dataSource": -1,
    "postName": "技术经理",
    "sexName": "男",
    "userExt": ""
  }
}

错误响应示例

json
{
  "code": 2501,
  "message": "用户不存在",
  "timestamp": 1735516801000
}

1.2 人员列表查询 ​

接口说明

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

请求方式

POST

请求地址

POST /hztech-application/user/list

交互方向

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

完整时序图

请求参数

参数名类型必填说明示例值
pageNumInteger否页码(默认1)1
pageSizeInteger否每页数量(默认20)20
realNameString否真实姓名(模糊查询)"张"
accountString否账号(精确查询)"manager"
deptIdString否部门ID"1123598813738675202"
statusInteger否状态(1:启用,0:禁用)1
employmentStatusString否在职状态("1":在职,"0":离职)"1"

HTTP 请求示例

http
POST /hztech-application/user/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,
  "deptId": "1123598813738675202",
  "status": 1,
  "employmentStatus": "1"
}

HTTP 响应示例

json
{
  "code": 200,
  "message": "success",
  "data": {
    "total": 100,
    "pageNum": 1,
    "pageSize": 20,
    "pages": 5,
    "list": [
      {
        "id": "1123598821738675203",
        "account": "manager",
        "realName": "经理",
        "email": "ma****@hztech.vip",
        "phone": "",
        "sex": 1,
        "deptId": "1123598813738675202",
        "deptName": "常州分公司",
        "postName": "技术经理",
        "roleName": "经理",
        "status": 1,
        "employmentStatus": "1",
        "createTime": "2019-04-27 17:03:38"
      }
    ]
  }
}

1.3 人员搜索 ​

接口说明

根据关键词搜索人员。支持按姓名、手机号、邮箱搜索。

请求方式

POST

请求地址

POST /hztech-application/user/search

交互方向

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

完整时序图

请求参数

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

HTTP 请求示例

http
POST /hztech-application/user/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": "经理",
  "searchType": "all",
  "pageNum": 1,
  "pageSize": 20
}

HTTP 响应示例

json
{
  "code": 200,
  "message": "success",
  "data": {
    "total": 5,
    "pageNum": 1,
    "pageSize": 20,
    "list": [
      {
        "id": "1123598821738675203",
        "account": "manager",
        "realName": "经理",
        "phone": "",
        "email": "ma****@hztech.vip",
        "deptName": "常州分公司"
      }
    ]
  }
}

1.4 查询人员角色 ​

接口说明

查询指定人员的角色列表。

请求方式

POST

请求地址

POST /hztech-application/user/roles

交互方向

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

完整时序图

请求参数

参数名类型必填说明示例值
idString是用户ID"1123598821738675203"

HTTP 请求示例

http
POST /hztech-application/user/roles 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
{}

HTTP 响应示例

json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": "1123598821738675203",
    "account": "manager",
    "realName": "经理",
    "roleId": "1123598816738675204",
    "roleName": "经理"
  }
}

1.5 查询人员部门 ​

接口说明

查询人员所属部门信息。

请求方式

POST

请求地址

POST /hztech-application/user/department

交互方向

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

完整时序图

请求参数

参数名类型必填说明示例值
idString是用户ID"1123598821738675203"

HTTP 请求示例

http
POST /hztech-application/user/department 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
{}

HTTP 响应示例

json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": "1123598821738675203",
    "account": "manager",
    "realName": "经理",
    "deptId": "1123598813738675202",
    "deptName": "常州分公司"
  }
}

数据模型 ​

人员对象 (User) ​

完整的人员数据结构:

json
{
  "id": "string",                      // 用户ID(系统生成)
  "createUser": "string",              // 创建人ID
  "createDept": "string",              // 创建部门ID
  "createTime": "string",              // 创建时间
  "updateUser": "string",              // 更新人ID
  "updateTime": "string",              // 更新时间
  "status": 1,                         // 账号状态(1:启用,0:禁用)
  "isDeleted": 0,                      // 是否删除(1:已删除,0:未删除)
  "tenantId": "string",                // 租户ID
  "code": "string",                    // 用户编码
  "userType": 1,                       // 用户类型
  "account": "string",                 // 账号(登录名)
  "name": "string",                    // 用户名
  "realName": "string",                // 真实姓名
  "avatar": "string",                  // 头像URL
  "email": "string",                   // 邮箱
  "phone": "string",                   // 手机号
  "birthday": "string",                // 生日
  "sex": 1,                            // 性别(1:男,2:女)
  "roleId": "string",                  // 角色ID
  "deptId": "string",                  // 部门ID
  "postId": "string",                  // 岗位ID
  "leaderId": "string",                // 直属领导ID
  "isLeader": 0,                       // 是否领导(1:是,0:否)
  "employmentStatus": "string",        // 在职状态
  "tenantName": "string",              // 租户名称
  "userTypeName": "string",            // 用户类型名称
  "roleName": "string",                // 角色名称
  "deptName": "string",                // 部门名称
  "dataSource": -1,                    // 数据来源
  "postName": "string",                // 岗位名称
  "sexName": "string",                 // 性别名称
  "userExt": "string"                  // 用户扩展信息
}

字段说明 ​

字段类型必填说明约束
idString是用户唯一标识系统生成,不可修改
accountString是账号(登录名)4-50个字符,全局唯一
realNameString是真实姓名2-50个字符
emailString否邮箱格式验证
phoneString否手机号11位数字
sexInteger是性别1或2
avatarString否头像URLURL格式
deptIdString否部门ID关联部门表
deptNameString否部门名称冗余字段
postIdString否岗位ID关联岗位表
postNameString否岗位名称冗余字段
roleIdString否角色ID关联角色表
roleNameString否角色名称冗余字段
statusInteger是账号状态1或0
isDeletedInteger是是否删除1或0
employmentStatusString否在职状态"1"或"0"
birthdayString否生日YYYY-MM-DD HH:mm:ss
createTimeString是创建时间YYYY-MM-DD HH:mm:ss
updateTimeString是更新时间YYYY-MM-DD HH:mm:ss
createUserString否创建人ID用户ID
updateUserString否更新人ID用户ID
createDeptString否创建部门ID部门ID
tenantIdString是租户ID租户标识
tenantNameString否租户名称冗余字段
codeString否用户编码自定义编码
userTypeInteger是用户类型数字标识
userTypeNameString否用户类型名称冗余字段
nameString否用户名冗余字段
leaderIdString否直属领导ID用户ID
isLeaderInteger否是否领导1或0
dataSourceInteger否数据来源数字标识
userExtString否用户扩展信息JSON字符串

枚举值说明 ​

性别 (sex):

  • 1: 男
  • 2: 女

账号状态 (status):

  • 1: 启用
  • 0: 禁用

是否删除 (isDeleted):

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

是否领导 (isLeader):

  • 1: 是领导
  • 0: 不是领导

在职状态 (employmentStatus):

  • "1": 在职
  • "0": 离职

错误码 ​

业务错误码 ​

错误码说明处理建议
2501用户不存在检查id是否正确
2502用户编码已存在使用其他编码
2503账号已存在使用其他账号
2504部门不存在检查deptId是否正确
2505参数错误检查请求参数
2506无数据权限检查用户是否有权限查看该数据

系统错误码 ​

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

相关文档 ​

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

最近更新