角色管理接口文档

一、接口说明

本模块提供角色管理相关接口，包括角色的CRUD操作、状态切换、菜单权限树查询等功能。

二、角色管理接口

2.1 分页查询角色列表

接口地址： POST /sys/role/page

请求方式： POST（FORMDATA格式）

请求参数示例（表单参数）：

pageNum=1
pageSize=10
name=管理员
status=1

请求字段说明：

字段	类型	必填	说明
pageNum	Integer	否	当前页（默认1，最小1）
pageSize	Integer	否	每页条数（默认20，最小1）
name	String	否	角色名称（模糊查询）
status	Integer	否	状态：0-禁用 1-启用

响应示例：

{
    "code": 200,
    "msg": "success",
    "data": {
        "records": [
            {
                "id": 1,
                "name": "普通用户",
                "description": "普通用户角色",
                "userCount": 10,
                "status": 1,
                "createTime": "2024-01-01 10:00:00",
                "isSuper": 0
            }
        ],
        "total": 1,
        "size": 10,
        "current": 1,
        "pages": 1
    }
}

响应字段说明：

字段	类型	说明
code	Integer	响应状态码：200-成功 500-失败
msg	String	响应消息
data.records[].id	Long	角色ID
data.records[].name	String	角色名称
data.records[].description	String	角色描述
data.records[].userCount	Integer	角色用户数
data.records[].status	Integer	状态：0-禁用 1-启用
data.records[].createTime	String	创建时间
data.records[].isSuper	Integer	是否超级管理员：0-否 1-是

2.2 获取角色详情

接口地址： GET /sys/role/{id}

请求方式： GET

路径参数：

id: 角色ID（必填）

响应示例：

{
    "code": 200,
    "msg": "success",
    "data": {
        "id": 1,
        "name": "普通用户",
        "description": "普通用户角色",
        "dataScope": 1,
        "isSuper": 0,
        "status": 1,
        "menuIds": [1, 2, 3],
        "menuTree": [
            {
                "id": 1,
                "title": "系统管理",
                "parentId": 0,
                "sort": 1,
                "children": []
            }
        ]
    }
}

响应字段说明：

字段	类型	说明
code	Integer	响应状态码：200-成功 500-失败
msg	String	响应消息
data.id	Long	角色ID
data.name	String	角色名称
data.description	String	角色描述
data.dataScope	Integer	数据权限范围（平台端返回null）
data.isSuper	Integer	是否超级管理员：0-否 1-是
data.status	Integer	状态：0-禁用 1-启用
data.menuIds	List<Long>	已授权的功能权限ID列表(用于回显勾选)
data.menuTree	List<SysRoleMenuTreeVO>	菜单权限树

menuTree字段说明：

字段	类型	说明
id	Long	菜单ID
title	String	菜单名称
parentId	Long	父级菜单ID（顶级为0）
sort	BigDecimal	排序
children	List	子菜单列表

错误响应：

错误信息	说明
角色不存在	角色ID无效
角色不属于当前租户	跨租户访问

2.3 新增角色

接口地址： POST /sys/role/save

请求方式： POST（JSON格式）

请求参数示例：

{
    "name": "普通用户",
    "description": "普通用户角色",
    "dataScope": 1,
    "menuIds": [1, 2, 3]
}

请求字段说明：

字段	类型	必填	说明
name	String	是	角色名称，最长20字符，仅中文英文数字
description	String	否	角色描述，最长100字符
dataScope	Integer	否	数据权限范围（平台端不传，租户端必传） 1-仅本人 2-本部门 3-本部门及子部门 4-全部
menuIds	List<Long>	是	功能权限ID列表

响应示例：

{
    "code": 200,
    "msg": "success",
    "data": null
}

错误响应：

错误信息	说明
角色名称不能为空	name参数缺失
角色名称最长20个字符	name超长
角色名称只能包含中文、英文、数字	name格式错误
角色描述最长100个字符	description超长
数据权限范围不能为空	租户端未传dataScope
数据权限范围值无效	dataScope值不在1-4范围内
菜单权限不能为空	menuIds参数缺失
角色名称已存在	同一租户下角色名称重复
菜单ID不存在	menuIds包含无效ID
菜单ID不在租户有效权限范围内	租户端menuIds超出套餐权限

2.4 修改角色

接口地址： POST /sys/role/update

请求方式： POST（JSON格式）

请求参数示例：

{
    "id": 1,
    "name": "普通用户",
    "description": "普通用户角色",
    "dataScope": 1,
    "menuIds": [1, 2, 3]
}

请求字段说明：

字段	类型	必填	说明
id	Long	是	角色ID
name	String	是	角色名称，最长20字符，仅中文英文数字
description	String	否	角色描述，最长100字符
dataScope	Integer	否	数据权限范围（平台端不传，租户端必传） 1-仅本人 2-本部门 3-本部门及子部门 4-全部
menuIds	List<Long>	是	菜单ID列表

响应示例：

{
    "code": 200,
    "msg": "success",
    "data": null
}

错误响应：

错误信息	说明
角色ID不能为空	id参数缺失
角色不存在	角色ID无效
角色不属于当前租户	跨租户访问
超级管理员角色不允许此操作	尝试修改超级管理员
角色名称已存在	同一租户下角色名称重复
数据权限范围值无效	dataScope值不在1-4范围内
菜单ID不存在	menuIds包含无效ID
菜单ID不在租户有效权限范围内	租户端menuIds超出套餐权限

2.5 启用/禁用角色

接口地址： POST /sys/role/enable-or-disable

请求方式： POST（JSON格式）

请求参数示例：

{
    "id": 1,
    "status": 0
}

请求字段说明：

字段	类型	必填	说明
id	Long	是	角色ID
status	Integer	是	目标状态：0-禁用 1-启用

响应示例：

{
    "code": 200,
    "msg": "success",
    "data": null
}

错误响应：

错误信息	说明
角色ID不能为空	id参数缺失
状态不能为空	status参数缺失
状态值无效	status值不为0或1
角色不存在	角色ID无效
角色不属于当前租户	跨租户访问
超级管理员角色不允许此操作	尝试操作超级管理员
当前角色正在使用中，禁止删除或禁用	禁用时角色下有用户

2.6 删除角色

接口地址： GET /sys/role/delete/{id}

请求方式： GET

路径参数：

id: 角色ID（必填）

响应示例：

{
    "code": 200,
    "msg": "success",
    "data": null
}

错误响应：

错误信息	说明
角色不存在	角色ID无效
角色不属于当前租户	跨租户访问
超级管理员角色不允许此操作	尝试删除超级管理员
当前角色正在使用中，禁止删除或禁用	角色下有用户

2.7 获取菜单权限树

接口地址： GET /sys/role/menu-tree

请求方式： GET

响应示例：

{
    "code": 200,
    "msg": "success",
    "data": [
        {
            "id": 1,
            "title": "系统管理",
            "parentId": 0,
            "sort": 1,
            "children": [
                {
                    "id": 2,
                    "title": "用户管理",
                    "parentId": 1,
                    "sort": 1,
                    "children": []
                }
            ]
        }
    ]
}

响应字段说明：

字段	类型	说明
code	Integer	响应状态码：200-成功 500-失败
msg	String	响应消息
data[].id	Long	菜单ID
data[].title	String	菜单名称
data[].parentId	Long	父级菜单ID（顶级为0）
data[].sort	BigDecimal	排序
data[].children	List	子菜单列表

业务逻辑说明：

平台端：返回所有平台菜单（tenant_type = 0）

租户端：返回租户所有套餐权限的并集

四、角色下拉接口

4.1 获取角色下拉列表

接口地址： GET /option/role-options

请求方式： GET

请求参数：

字段	类型	必填	说明
status	Integer	否	状态筛选，默认只返回启用状态的角色

响应示例：

{
    "code": 200,
    "msg": "success",
    "data": [
        {
            "id": 1,
            "name": "普通用户"
        }
    ]
}

响应字段说明：

字段	类型	说明
code	Integer	响应状态码：200-成功 500-失败
msg	String	响应消息
data[].id	Long	角色ID
data[].name	String	角色名称

业务逻辑说明：

只返回当前租户下的角色

排除超级管理员角色

默认只返回启用状态的角色

五、数据权限范围说明

5.1 数据权限范围枚举

值	名称	说明	适用端
null	-	平台端不配置数据权限	平台端
1	仅本人	只能查看自己创建的数据	租户端
2	本部门	可以查看本部门所有数据	租户端
3	本部门及子部门	可以查看本部门及下级部门数据	租户端
4	全部	可以查看所有数据	租户端

角色管理接口文档

一、接口说明#

二、角色管理接口#

2.1 分页查询角色列表#

2.2 获取角色详情#

2.3 新增角色#

2.4 修改角色#

2.5 启用/禁用角色#

2.6 删除角色#

2.7 获取菜单权限树#

四、角色下拉接口#

4.1 获取角色下拉列表#

五、数据权限范围说明#

5.1 数据权限范围枚举#

一、接口说明

二、角色管理接口

2.1 分页查询角色列表

2.2 获取角色详情

2.3 新增角色

2.4 修改角色

2.5 启用/禁用角色

2.6 删除角色

2.7 获取菜单权限树

四、角色下拉接口

4.1 获取角色下拉列表

五、数据权限范围说明

5.1 数据权限范围枚举