角色管理模块
概述
角色模块用于管理系统角色和权限分配，支持角色与菜单、权限、部门的多对多关联，是 RBAC（基于角色的访问控制）的核心组件。
模块路径：backend-fastapi/core/role/
API 前缀：/api/core/roles
数据模型
python
class Role(BaseModel):
__tablename__ = "core_role"
name: str # 角色名称
code: str # 角色编码（唯一）
role_type: int # 角色类型
status: bool # 角色状态（启用/禁用）
priority: int # 角色优先级（数字越大优先级越高）
description: str # 角色描述
remark: str # 备注信息角色类型 (role_type)
| 值 | 说明 |
|---|---|
0 | 系统角色（不可删除） |
1 | 自定义角色 |
关联表
角色与其他实体通过中间表建立多对多关系：
| 关联表 | 说明 |
|---|---|
core_role_menu | 角色-菜单关联 |
core_role_permission | 角色-权限关联 |
core_role_dept | 角色-部门关联（用于数据权限） |
服务层
RoleService 继承 BaseService，提供以下方法：
基础操作
| 方法 | 说明 |
|---|---|
create(db, data) | 创建角色（处理多对多关系） |
update(db, record_id, data) | 更新角色（处理多对多关系） |
get_by_id_with_relations(db, record_id) | 获取角色详情（含关联数据） |
get_all_active(db) | 获取所有启用的角色 |
get_by_ids(db, ids) | 批量获取角色 |
search(db, keyword, page, page_size) | 搜索角色 |
权限管理
| 方法 | 说明 |
|---|---|
update_menus_permissions(db, role_id, menu_ids, permission_ids) | 更新角色的菜单和权限 |
update_permissions(db, role_id, permission_ids) | 更新角色的权限 |
get_menu_permission_tree(db, role) | 获取角色的菜单权限树 |
get_role_menus(db, role, application_id) | 获取角色的菜单列表 |
get_menu_permissions(db, role, menu_id) | 获取指定菜单的权限列表 |
用户管理
| 方法 | 说明 |
|---|---|
get_role_users(db, role_id, page, page_size, username) | 获取角色下的用户列表 |
add_users_to_role(db, role_id, user_ids) | 将用户添加到角色 |
remove_users_from_role(db, role_id, user_ids) | 从角色中移除用户 |
get_user_count(db, role_id) | 获取角色下的用户数量 |
批量操作
| 方法 | 说明 |
|---|---|
batch_update_status(db, ids, status) | 批量更新状态（系统角色不能禁用） |
batch_delete(db, ids, hard) | 批量删除 |
can_delete(db, role_id) | 检查角色是否可删除 |
copy_role(db, source_role_id, new_name, new_code) | 复制角色 |
缓存清除
当角色的菜单或权限变更时，系统自动清除相关缓存：
python
async def _invalidate_role_related_cache(cls, role_id: str):
# 1. 清除菜单路由缓存
await MenuService.invalidate_cache()
# 2. 清除该角色的 API 权限 Redis 缓存
await clear_role_permission_cache(role_id)
# 3. 清除所有用户的 Redis 用户信息缓存
await delete_all_cached_user_info()API 接口
基础 CRUD
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | / | 创建角色 |
| GET | / | 获取角色列表 |
| GET | /{record_id} | 获取角色详情 |
| PUT | /{record_id} | 更新角色 |
| DELETE | /{record_id} | 删除角色 |
权限配置
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /{role_id}/menus | 获取角色菜单树 |
| GET | /{role_id}/menus/{menu_id}/permissions | 获取菜单权限列表 |
| PUT | /{role_id}/menus-permissions | 更新菜单和权限 |
用户管理
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /{role_id}/users | 获取角色用户列表 |
| POST | /{role_id}/users | 添加用户到角色 |
| DELETE | /{role_id}/users | 从角色移除用户 |
其他
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /{role_id}/copy | 复制角色 |
| GET | /active | 获取所有启用的角色 |
请求/响应示例
创建角色
请求：
json
POST /api/core/roles
{
"name": "项目经理",
"code": "project_manager",
"role_type": 1,
"priority": 50,
"description": "项目管理角色",
"menu_ids": ["menu001", "menu002"],
"permission_ids": ["perm001", "perm002"]
}获取菜单权限树
响应：
json
{
"menu_tree": [
{
"id": "menu001",
"label": "系统管理",
"checked": true,
"children": [
{
"id": "menu002",
"label": "用户管理",
"checked": true,
"children": [
{
"id": "perm001",
"label": "新增用户",
"code": "user:add",
"permission_type": 0,
"permission_type_display": "按钮权限",
"checked": true
}
]
}
]
}
],
"selected_menu_ids": ["menu001", "menu002"],
"selected_permission_ids": ["perm001"]
}与其他模块的关系
- 用户模块：用户通过
core_user_role关联多个角色 - 菜单模块：角色通过
core_role_menu关联菜单 - 权限模块：角色通过
core_role_permission关联权限 - 部门模块：角色通过
core_role_dept关联部门（数据权限）