主题
角色管理接口文档
概述
角色管理模块提供了一单位一平台向子应用同步角色数据的能力，以及子应用向一单位一平台查询角色数据的能力，支持角色的创建、更新、删除以及查询等功能。所有接口遵循国密 SM2/SM4 数字信封加密方案，确保数据传输安全。
交互方向
本模块包含以下交互方向:
| 交互方向 | 接口类型 | 子应用实现要求 | 说明 |
|---|---|---|---|
| 一单位一平台→子应用(推送) | 创建角色、更新角色、删除角色 | ✅ 必须实现接收接口 | 一单位一平台主动推送角色数据变更,子应用需实现对应接收接口 |
| 子应用→一单位一平台(查询) | 角色详情查询、角色列表查询 | ❌ 无需实现 | 子应用主动查询角色数据,一单位一平台提供查询接口 |
重要说明:
- 对于"一单位一平台→子应用"的推送接口,子应用必须实现对应的接收接口
- 对于"子应用→一单位一平台"的查询接口,子应用直接调用一单位一平台提供的接口,无需额外实现
使用场景
- 一单位一平台→子应用(推送): 一单位一平台向子应用推送角色创建、更新、删除操作
- 子应用→一单位一平台(查询): 子应用向一单位一平台查询角色详情、角色列表
- 数据同步: 子应用通过角色列表接口定期同步一单位一平台的角色数据
接口设计原则
所有接口均采用国密 SM2/SM4 数字信封加密方案:
- 统一 POST 方式：所有接口使用 POST 方法,业务参数在 encryptData 中加密传输
- 无路径参数：URL 路径中不包含任何业务参数(如 roleId),所有业务参数均在加密报文中
- 安全性：通过 SM2 混合加密和数字签名确保数据传输的机密性、完整性和不可抵赖性
适用范围
适用于需要统一管理用户角色和权限的子应用系统。
术语定义
核心概念
| 术语 | 说明 |
|---|---|
| 一单位一平台 | 核心管理平台,负责数据存储、权限管理、接口路由等核心功能 |
| 子应用 | 接入一单位一平台的独立业务系统,通过一单位一平台网关与其他系统交互 |
| 网关 | 一单位一平台的统一入口,负责路由转发、身份认证、权限控制、速率限制等 |
操作语义
| 术语 | 说明 | 数据流向 | 接口实现方 |
|---|---|---|---|
| 查询 | 主动请求获取数据 | 子应用→一单位一平台 | 一单位一平台实现 |
| 推送 | 主动通知数据变更 | 一单位一平台→子应用 | 子应用实现接收 |
重要提示:
- "查询"表示子应用主动向一单位一平台请求数据,由一单位一平台提供查询接口
- "推送"表示一单位一平台主动通知子应用数据变更,子应用必须实现对应的接收接口
系统架构
数据流向
查询流程(子应用→一单位一平台)
子应用 → [加密请求] → 一单位一平台 → [加密响应] → 子应用推送流程(一单位一平台→子应用)
一单位一平台 → [加密推送] → 子应用接收接口 → [加密响应] → 一单位一平台重要: 对于推送接口,子应用必须实现接收接口
接口列表
一单位一平台→子应用(推送接口)
| 接口名称 | 请求地址 | 交互方向 | 说明 |
|---|---|---|---|
| 创建角色 | POST /ydyp/role/create | 主→子(推送) | 创建新角色 |
| 更新角色 | POST /ydyp/role/update | 主→子(推送) | 更新角色信息 |
| 删除角色 | POST /ydyp/role/delete | 主→子(推送) | 删除角色 |
⚠️ 重要提示: 以上"主→子(推送)"接口需要子应用实现接收接口,接收一单位一平台推送的角色数据变更
子应用→一单位一平台(查询接口)
| 接口名称 | 请求地址 | 交互方向 | 说明 |
|---|---|---|---|
| 角色详情查询 | POST /hztech-application/role/detail | 子→主(查询) | 获取单个角色 |
| 角色列表查询 | POST /hztech-application/role/list | 子→主(查询) | 分页查询角色列表 |
注: 所有业务参数均在 encryptData 中加密传输,URL 路径中不包含任何业务参数。
接口详情
1.1 创建角色
⚠️ 子应用需实现此接口
本接口需要子应用实现接收接口,接收一单位一平台推送的角色创建通知。
实现要求:
- 子应用需在一单位一平台注册接收接口地址
- 接收接口必须验签并解密一单位一平台的推送数据
- 接收接口需返回加密的响应报文
时序说明:
- 一单位一平台检测到角色创建事件
- 一单位一平台向子应用注册的接收地址发送加密推送
- 子应用接收接口验签、解密、处理数据
- 子应用返回加密响应
接口说明
创建新的角色,用于系统权限管理。一单位一平台向子应用推送新角色数据。
请求方式
POST
请求地址
POST /ydyp/role/create
交互方向
一单位一平台 → 子应用 (推送)
完整时序图
请求参数
| 参数名 | 类型 | 必填 | 说明 | 示例值 |
|---|---|---|---|---|
| roleName | String | 是 | 角色名称 | "系统管理员" |
| roleCode | String | 是 | 角色编码 | "ADMIN" |
| description | String | 否 | 角色描述 | "系统管理员角色" |
| status | Integer | 否 | 状态(1:启用,0:禁用) | 1 |
| sort | Integer | 否 | 排序号 | 0 |
HTTP 请求示例
http
POST /ydyp/role/create HTTP/1.1
Host: subapp.example.com
Content-Type: application/json
{
"appId": "MAIN_SYSTEM",
"version": "1.0",
"timestamp": 1735516800000,
"nonce": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"encryptKey": "MIIBOgIBAAJBAKj34GkxFhD90vcNLYLInFEX6...",
"encryptData": "U2FsdGVkX1+jmZn5KqWYEgjPkQKpH5KqWYEg...",
"sign": "MEUCIQDZ5KqWYEgjPkQKpH5KqWYEgjPkQKpH5KqWY..."
}encryptData 解密后的业务数据
json
{
"roleName": "系统管理员",
"roleCode": "ADMIN",
"description": "系统管理员角色",
"status": 1,
"sort": 0
}响应参数
| 参数名 | 类型 | 说明 | 示例值 |
|---|---|---|---|
| code | Integer | 响应码(200:成功) | 200 |
| message | String | 响应消息 | "success" |
| data.roleId | String | 角色ID | "ROLE_001" |
| data.createTime | String | 创建时间 | "2026-01-04T00:00:00" |
HTTP 响应示例
json
{
"code": 200,
"message": "success",
"data": {
"roleId": "ROLE_001",
"createTime": "2026-01-04T00:00:00"
},
"timestamp": 1735516801500
}错误响应示例
json
{
"code": 2002,
"message": "角色编码已存在",
"timestamp": 1735516801000
}1.2 更新角色
⚠️ 子应用需实现此接口
本接口需要子应用实现接收接口,接收一单位一平台推送的角色更新通知。
实现要求:
- 子应用需在一单位一平台注册接收接口地址
- 接收接口必须验签并解密一单位一平台的推送数据
- 接收接口需返回加密的响应报文
接口说明
更新已有角色的信息。一单位一平台向子应用推送角色更新数据。
请求方式
POST
请求地址
POST /ydyp/role/update
交互方向
一单位一平台 → 子应用 (推送)
完整时序图
请求参数
| 参数名 | 类型 | 必填 | 说明 | 示例值 |
|---|---|---|---|---|
| roleId | String | 是 | 角色ID | "ROLE_001" |
| roleName | String | 否 | 角色名称 | "超级管理员" |
| description | String | 否 | 角色描述 | "系统最高管理员" |
| status | Integer | 否 | 状态(1:启用,0:禁用) | 1 |
| sort | Integer | 否 | 排序号 | 1 |
HTTP 请求示例
http
POST /ydyp/role/update HTTP/1.1
Host: subapp.example.com
Content-Type: application/json
{
"appId": "MAIN_SYSTEM",
"version": "1.0",
"timestamp": 1735516800000,
"nonce": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"encryptKey": "MIIBOgIBAAJBAKj34GkxFhD90vcNLYLInFEX6...",
"encryptData": "U2FsdGVkX1+jmZn5KqWYEgjPkQKpH5KqWYEg...",
"sign": "MEUCIQDZ5KqWYEgjPkQKpH5KqWYEgjPkQKpH5KqWY..."
}encryptData 解密后的业务数据
json
{
"roleId": "ROLE_001",
"roleName": "超级管理员",
"description": "系统最高管理员",
"status": 1,
"sort": 1
}HTTP 响应示例
json
{
"code": 200,
"message": "success",
"data": {
"roleId": "ROLE_001",
"updateTime": "2026-01-04T00:01:00"
},
"timestamp": 1735516801500
}错误响应示例
json
{
"code": 2001,
"message": "角色不存在",
"timestamp": 1735516801000
}1.3 删除角色
⚠️ 子应用需实现此接口
本接口需要子应用实现接收接口,接收一单位一平台推送的角色删除通知。
实现要求:
- 子应用需在一单位一平台注册接收接口地址
- 接收接口必须验签并解密一单位一平台的推送数据
- 接收接口需返回加密的响应报文
接口说明
删除指定的角色。一单位一平台向子应用推送角色删除指令。
请求方式
POST
请求地址
POST /ydyp/role/delete
交互方向
一单位一平台 → 子应用 (推送)
完整时序图
请求参数
| 参数名 | 类型 | 必填 | 说明 | 示例值 |
|---|---|---|---|---|
| roleId | String | 是 | 角色ID | "ROLE_001" |
HTTP 请求示例
http
POST /ydyp/role/delete HTTP/1.1
Host: subapp.example.com
Content-Type: application/json
{
"appId": "MAIN_SYSTEM",
"version": "1.0",
"timestamp": 1735516800000,
"nonce": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"encryptKey": "MIIBOgIBAAJBAKj34GkxFhD90vcNLYLInFEX6...",
"encryptData": "U2FsdGVkX1+jmZn5KqWYEgjPkQKpH5KqWYEg...",
"sign": "MEUCIQDZ5KqWYEgjPkQKpH5KqWYEgjPkQKpH5KqWY..."
}encryptData 解密后的业务数据
json
{
"roleId": "ROLE_001"
}HTTP 响应示例
json
{
"code": 200,
"message": "success",
"data": {
"roleId": "ROLE_001"
},
"timestamp": 1735516801500
}错误响应示例
json
{
"code": 2004,
"message": "角色已被用户使用,无法删除",
"timestamp": 1735516801000
}1.4 角色详情查询
接口说明
查询单个角色的详细信息。子应用向一单位一平台请求角色数据。
请求方式
POST
请求地址
POST /hztech-application/role/detail
交互方向
子应用 → 一单位一平台 (查询)
完整时序图
请求参数
| 参数名 | 类型 | 必填 | 说明 | 示例值 |
|---|---|---|---|---|
| roleId | String | 是 | 角色ID | "ROLE_001" |
HTTP 请求示例
http
POST /hztech-application/role/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
{
"roleId": "ROLE_001"
}HTTP 响应示例
json
{
"code": 200,
"message": "success",
"data": {
"roleId": "ROLE_001",
"roleName": "系统管理员",
"roleCode": "ADMIN",
"description": "系统管理员角色",
"status": 1,
"sort": 0,
"createTime": "2026-01-04T00:00:00",
"updateTime": "2026-01-04T00:00:00"
},
"timestamp": 1735516801500
}错误响应示例
json
{
"code": 2001,
"message": "角色不存在",
"timestamp": 1735516801000
}1.5 角色列表查询
接口说明
分页查询角色列表。子应用向一单位一平台请求角色列表数据。结果按照更新时间倒序排列。
请求方式
POST
请求地址
POST /hztech-application/role/list
交互方向
子应用 → 一单位一平台 (查询)
完整时序图
请求参数
| 参数名 | 类型 | 必填 | 说明 | 示例值 |
|---|---|---|---|---|
| pageNum | Integer | 否 | 页码(默认1) | 1 |
| pageSize | Integer | 否 | 每页数量(默认20) | 20 |
| roleName | String | 否 | 角色名称(模糊查询) | "管理员" |
| roleCode | String | 否 | 角色编码(精确查询) | "ADMIN" |
| status | Integer | 否 | 状态(1:启用,0:禁用) | 1 |
HTTP 请求示例
http
POST /hztech-application/role/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,
"status": 1
}HTTP 响应示例
json
{
"code": 200,
"message": "success",
"data": {
"total": 100,
"pageNum": 1,
"pageSize": 20,
"pages": 5,
"list": [
{
"roleId": "ROLE_001",
"roleName": "系统管理员",
"roleCode": "ADMIN",
"description": "系统管理员角色",
"status": 1,
"sort": 0,
"createTime": "2026-01-04T00:00:00",
"updateTime": "2026-01-04T00:00:00"
}
]
},
"timestamp": 1735516801500
}数据模型
角色对象 (Role)
完整的角色数据结构:
json
{
"roleId": "string", // 角色ID(系统生成)
"roleName": "string", // 角色名称
"roleCode": "string", // 角色编码(唯一)
"description": "string", // 角色描述
"status": 1, // 状态: 1-启用, 0-禁用
"sort": 0, // 排序号
"createTime": "2026-01-04T00:00:00", // 创建时间
"updateTime": "2026-01-04T00:00:00" // 更新时间
}字段说明
| 字段 | 类型 | 必填 | 说明 | 约束 |
|---|---|---|---|---|
| roleId | String | 是 | 角色唯一标识 | 系统生成,不可修改 |
| roleName | String | 是 | 角色名称 | 2-50个字符 |
| roleCode | String | 是 | 角色编码 | 英文大写+下划线,全局唯一 |
| description | String | 否 | 角色描述 | 最多200个字符 |
| status | Integer | 是 | 状态 | 1或0 |
| sort | Integer | 否 | 排序号 | 数值越小越靠前 |
| createTime | String | 是 | 创建时间 | ISO 8601格式 |
| updateTime | String | 是 | 更新时间 | ISO 8601格式 |
枚举值说明
角色状态 (status):
1: 启用0: 禁用
错误码
业务错误码
| 错误码 | 说明 | 处理建议 |
|---|---|---|
| 2001 | 角色不存在 | 检查roleId是否正确 |
| 2002 | 角色编码已存在 | 使用其他编码 |
| 2003 | 角色名称已存在 | 使用其他名称 |
| 2004 | 角色已被用户使用,无法删除 | 先移除用户的该角色 |
| 2005 | 角色权限分配失败 | 检查权限ID是否存在 |
| 2006 | 角色权限移除失败 | 检查权限ID是否属于该角色 |
| 2007 | 角色编码格式错误 | 使用英文大写+下划线格式 |
系统错误码
| 错误码 | 说明 | 处理建议 |
|---|---|---|
| 1001 | 时间戳过期 | 同步系统时间 |
| 1002 | 重复请求 | 检查nonce生成逻辑 |
| 1003 | 签名验证失败 | 检查密钥配置 |
| 1004 | 解密失败 | 检查密钥配置 |
| 1005 | appId不存在 | 检查appId注册 |
| 1006 | 业务逻辑错误 | 根据具体错误处理 |
相关文档
文档版本: v1.0.0 最后更新: 2026-01-04