菜单与角色重点文件和方法

菜单决定客户端页面结构，角色权限记录提供模块操作，用户角色关系决定授权对象。普通 CRUD 的默认方法见 CRUD 方法参考。

本页按重点文件查阅方法；表内方法名可打开源码。重载共享的约束写在表前，差异在各行说明。源码链接固定到核对版本，接入前提见快速开始。

SystemMenuService

源码：SystemMenuService；实现：SystemMenuServiceImpl。

菜单业务接口。clientId/client 是字符串客户端标识；禁用和显示是两项独立状态。

方法 / 重载	用途、参数与返回值	注意事项
listEnableByClientId(String clientId)	等价于 listByClientId(clientId,false,true)，返回启用且显示的菜单 PO 列表。	与 App 列表读取的“启用但不过滤显示”不同。
listByClientId(String clientId, Boolean isDisable, Boolean isShow)	按客户端及可选状态查询 List<SystemMenu>；null 状态不筛选。	不按当前用户权限裁剪。
updateDisableById(Long menuId, Integer disable)	必取菜单，null 切换，非 null 取 disable%2，写库后刷新全局权限版本。	负数取模仍可能负值，调用前限制 0/1；非原子读改写。
updateShowById(Long menuId, Integer show)	同样规则更新显示状态并刷新全局版本。	show=false 不等于禁止访问该菜单对应接口。
queryByModule(String module, String client)	按菜单 code、client 和 isDisable=0 查单条 PO，缺失 null。	不检查 isShow；多条匹配可能 selectOne 失败。
sort(SystemMenuAdvancedSortForm form)	逐个 item 调 Mapper.updateSortById，返回 void。	不自动事务、不刷新全局权限版本，服务不调用 form.check。

SystemMenuServiceImpl

源码：SystemMenuServiceImpl。

实现上方五项操作，并增加查询条件和权限版本 Hook。

方法 / 重载	用途、参数与返回值	注意事项
lambdaQueryWrapper(SystemMenuQuery query)	code/title 模糊匹配，parentId/isDisable/isShow/clientId 等值，创建时间与 ID 倒序。	不自动校验父子循环或重复 code。
checkAfter()	返回写入后设置全局权限版本的函数，再原样返回 VO。	不是数据库事务提交后通知，缓存更新时间可能先于事务提交。
afterDelete(Long pk)	父级删除后置处理后刷新全局版本，返回 Boolean。	仅被显式调用的路径生效。
deleteById(Long id)	显式 beforeDelete→父类删除→afterDelete。	不级联删除所有子菜单/角色权限；继承的批删不逐项经过此覆盖。

SystemRoleService

源码：SystemRoleService；实现：SystemRoleServiceImpl。

角色列表和禁用操作；列表默认不过滤角色禁用状态。

方法 / 重载	用途、参数与返回值	注意事项
listByUserId(Long userId)	查绑定角色 ID，再取角色 PO 列表。	无客户端限定，不保证与关系顺序相同。
listByUserId(Long userId, String client)	按用户绑定和客户端查角色，空绑定返回空。	仍不剔除禁用角色，不等价于最终授权结果。
updateDisableById(Long roleId, Integer disable)	必取角色，切换或取模更新禁用值，再刷新全局版本。	直接 Mapper 更新，无通用更新 Hook；应只传 0/1。

SystemRoleServiceImpl

源码：SystemRoleServiceImpl。

实现上述角色查询与状态变更，同时将 DTO 中的 permissions 做整组替换。

方法 / 重载	用途、参数与返回值	注意事项
lambdaQueryWrapper(SystemRoleQuery query)	禁用值/客户端等值、名称模糊，创建时间与 ID 倒序。	Query 非 null，未设置条件不限制。
addByDto(SystemRoleDto dto)	先通用创建角色，再 save(roleId,permissions)。	角色与权限写入无整体事务；权限失败可能留下角色。
updateByDto(Long id, SystemRoleDto dto)	先更新角色，再整体替换 permissions。	permissions=null/空表示清空，不是保留旧权限。
checkAfter()	返回刷新全局权限版本的 VO 后置函数。	版本可能在 permissions 写入前刷新。
afterDelete(Long pk)	调用父 Hook 并刷新全局版本。	不单独删除业务对象。
deleteById(Long id)	先 beforeDelete 清关系，再删角色，再 afterDelete。	无覆盖全部步骤的事务。
afterQueryVo(SystemRoleVo vo)	读取当前角色权限并回填 permissions。	VO 列表不会逐条调用详情 Hook；不应对 null 手工调用。
beforeDelete(Long pk)	删除角色权限及用户绑定后返回 pk。	这是有数据库副作用的 Hook，不是纯校验。

SystemRolePermissionService

源码：SystemRolePermissionService；实现：SystemRolePermissionServiceImpl。

读写角色到菜单的权限字符串。不同角色的权限可合并，但权限字符串本身不是已验证的操作枚举。

方法 / 重载	用途、参数与返回值	注意事项
listByUserId(Long userId)	按用户绑定角色返回权限记录列表。	无客户端限定。
listByUserId(Long userId, String clientId)	先按客户端查用户角色，再查权限记录。	角色禁用未在此路径统一过滤。
listByRoleId(Long roleId)	查单个角色的权限记录列表。	无记录返回空，不是异常。
listByRoleIdList(List<Long> roleIdList)	按多个角色查权限，null/空列表返回空。	不验证角色状态。
mapMenuPermissionByUserId(Long userId, String client)	返回 menuId→权限字符串 Map；同菜单以逗号拼接。	不去重、不校验权限是否合法，不检查菜单禁用。
save(Long roleId, List<SystemRolePermissionDto> permissions)	先删角色全部权限，再将 DTO 转 PO、强制设置目标 roleId 后批插。	null/空会清空；无事务，不自动刷新权限版本。
deleteByRoleId(Long roleId)	删除该角色全部权限。	单独调用不会刷新全局权限版本。
listPermissionByRoleIdListAndMenuId(Collection<Long> roleIdList, Long menuId)	按角色集合和菜单返回权限字符串列表，空角色返回空。	没有 split/去重，调用方决定如何解释操作名。

SystemRolePermissionServiceImpl 直接实现上表除默认 mapMenuPermissionByUserId 之外的七项方法，无额外对外业务入口。其 save 直接调用 Mapper.insertBatch，与 MapperUtil 的惰性分组问题不是同一路径。

SystemUserRoleService

源码：SystemUserRoleService；实现：SystemUserRoleServiceImpl。

管理用户与角色绑定。APPEND_UPDATE 追加缺失关系，FORCE_UPDATE 先删除目标用户全部绑定再重建；服务不禁止调整调用者自己，管理端 Controller 才做该检查。

方法 / 重载	用途、参数与返回值	注意事项
listRoleIdByUserId(Long userId)	读取角色 ID 列表。	没有 distinct、禁用或客户端过滤。
deleteByUserId(Long userId)	删除该用户全部角色绑定，并刷新用户角色版本。	不删除角色实体。
deleteByRoleId(Long roleId)	删除该角色的所有用户绑定，并刷新全局版本。	影响所有绑定该角色的用户。
bind(Long userId, Collection<Long> roleIdList, UserRoleBindTypeEnum userRoleBindTypeEnum)	单用户、多角色；只绑定查询到的角色，完成后更新用户版本，返回 void。	实现有事务；用户集合空/模式 null 无操作；强制模式空目标会清空旧绑定；不验证用户存在、角色启用或客户端归属。
bind(Collection<Long> userIdList, Long roleId, UserRoleBindTypeEnum userRoleBindTypeEnum)	多用户、单角色；只绑定查询到的角色，完成后更新用户版本，返回 void。	实现有事务；用户集合空/模式 null 无操作；强制模式空目标会清空旧绑定；不验证用户存在、角色启用或客户端归属。
bind(Collection<Long> userIdList, Collection<Long> roleIdList, UserRoleBindTypeEnum userRoleBindTypeEnum)	多用户、多角色；只绑定查询到的角色，完成后更新用户版本，返回 void。	实现有事务；用户集合空/模式 null 无操作；强制模式空目标会清空旧绑定；不验证用户存在、角色启用或客户端归属。
unbind(Long userId, Collection<Long> roleIdList)	单用户、多角色；删交集关系，刷新用户权限版本，返回 void。	集合重载 null/空集合不操作；单 ID 包装使用 Set.of，不能传 null。事务不等于并发防重。
unbind(Collection<Long> userIdList, Long roleId)	多用户、单角色；删交集关系，刷新用户权限版本，返回 void。	集合重载 null/空集合不操作；单 ID 包装使用 Set.of，不能传 null。事务不等于并发防重。
unbind(Collection<Long> userIdList, Collection<Long> roleIdList)	多用户、多角色；删交集关系，刷新用户权限版本，返回 void。	集合重载 null/空集合不操作；单 ID 包装使用 Set.of，不能传 null。事务不等于并发防重。

SystemUserRoleServiceImpl 直接实现列表、两种删除及集合版本 bind/unbind；便捷单 ID 重载在接口内。追加是先查后插，关系表无组合唯一索引，不能保证并发不重复。角色整体操作样例见角色与授权。

AppSystemMenuController

源码：AppSystemMenuController。

HTTP 前缀 /api/app/system/menu，从当前登录身份取 userId/client，返回 ResultModel。

方法 / 重载	用途、参数与返回值	注意事项
tree()	GET /tree；查询当前客户端启用菜单，填入用户权限、组树并裁剪。	不按 isShow 过滤；保留有权限后代所需祖先，裁剪规则见当前用户查询页。
all()	GET /all；返回当前客户端全部启用菜单的平铺列表并附权限。	不移除无权限项；不能把“出现在列表中”当授权成功。

AppSystemRoleController

源码：AppSystemRoleController。

当前用户查询 Controller，客户端取自登录身份。完整路径见当前用户查询。

方法 / 重载	用途、参数与返回值	注意事项
self()	GET /self；返回当前用户、当前客户端的角色 List<SystemRoleMapVo>，由 ResultModel 包装。	不等价于最终有效权限，查询链未统一过滤禁用角色。

AppSystemRolePermissionController

源码：AppSystemRolePermissionController。

当前用户查询 Controller，客户端取自登录身份。完整路径见当前用户查询。

方法 / 重载	用途、参数与返回值	注意事项
self()	GET /self；返回当前用户、当前客户端的角色权限 List<SystemRolePermissionMapVo>，由 ResultModel 包装。	不等价于最终有效权限，查询链未统一过滤禁用角色。

AdminSystemMenuController

源码：AdminSystemMenuController。

HTTP 前缀 /api/admin/system/menu，各方法带对应操作权限；应用仍需真正接入安全切面。

方法 / 重载	用途、参数与返回值	注意事项
page(SystemMenuQuery query)	POST /page，返回 VO 分页。	按提交 Query 筛选，不自动当前客户端。
tree(SystemMenuQuery query)	POST /tree，查询 MAP 后按父子 ID 组树。	没有 App 的用户权限裁剪。
add(SystemMenuDto dto)	POST /，校验 DTO 后新增，返回 VO。	父子关系合法性见菜单管理页。
update(Long menuId, SystemMenuDto dto)	PUT /{menuId}，checkUpdate(menuId) 后更新。	服务直接调用不自动执行该表单检查。
delete(Long menuId)	DELETE /{menuId}，确认后删除，data=true。	不保证清理后代和引用权限。
getById(Long menuId)	GET /{menuId}，返回必取 VO。	缺失抛业务异常。
updateDisable(Long menuId, Integer disable)	PUT /disable/{menuId}/{disable}，更新禁用状态。	返回 R.success()，data 未赋值。
updateShow(Long menuId, Integer show)	PUT /show/{menuId}/{show}，更新显示状态。	data 未赋值；不代替权限校验。
sort(SystemMenuAdvancedSortForm form)	PUT /advanced/sort，form.check 后逐项改排序。	非整体事务，data 未赋值。

AdminSystemRoleController

源码：AdminSystemRoleController。

HTTP 前缀 /api/admin/system/role，操作权限覆盖查询、写入及删除。所有结果由 ResultModel 包装。

方法 / 重载	用途、参数与返回值	注意事项
all(SystemRoleQuery query)	POST /all，返回 VO 列表。	全量列表，控制筛选规模。
page(SystemRoleQuery query)	POST /page，返回 VO 分页。	不是直接 Mapper 返回值。
map(SystemRoleQuery query)	POST /map，返回轻量 MapVo 列表。	不自动加载详情附属信息。
add(SystemRoleDto dto)	POST /，DTO 校验后新增，返回 VO。	角色新增还保存 permissions。
update(Long roleId, SystemRoleDto dto)	PUT /{roleId}，校验 DTO 后更新，返回 VO。	角色更新整体替换 permissions。
delete(Long roleId)	DELETE /{roleId}，确认后删记录，data=true。	角色先删关系再删实体，无整体事务。
getById(Long roleId)	GET /{roleId}，必取详情。	缺失抛业务异常。
updateDisable(Long roleId, Integer disable)	PUT /disable/{roleId}/{disable}，改禁用值并刷新版本。	data 未赋值；按 0/1 传入。

AdminSystemRolePermissionController

源码：AdminSystemRolePermissionController。

HTTP 前缀 /api/admin/system/role/permission，操作权限覆盖查询、写入及删除。所有结果由 ResultModel 包装。

方法 / 重载	用途、参数与返回值	注意事项
all(SystemRolePermissionQuery query)	POST /all，返回 VO 列表。	全量列表，控制筛选规模。
page(SystemRolePermissionQuery query)	POST /page，返回 VO 分页。	不是直接 Mapper 返回值。
map(SystemRolePermissionQuery query)	POST /map，返回轻量 MapVo 列表。	不自动加载详情附属信息。
add(SystemRolePermissionDto dto)	POST /，DTO 校验后新增，返回 VO。	单独编辑权限关系不刷新全局权限版本。
update(Long systemRolePermissionId, SystemRolePermissionDto dto)	PUT /{systemRolePermissionId}，校验 DTO 后更新，返回 VO。	不自动刷新全局权限版本。
delete(Long systemRolePermissionId)	DELETE /{systemRolePermissionId}，确认后删记录，data=true。	仅删该权限关系。
getById(Long systemRolePermissionId)	GET /{systemRolePermissionId}，必取详情。	缺失抛业务异常。

AdminSystemUserRoleController

源码：AdminSystemUserRoleController。

HTTP 前缀 /api/admin/system/user/role，写入表单经 check，禁止目标用户集合包含当前用户。

方法 / 重载	用途、参数与返回值	注意事项
bind(UserRoleBindForm form)	POST /bind；按 bindType 转模式后委托绑定。	返回 R.success()；强制模式可能清空全部绑定，见服务语义。
unbind(UserRoleUnbindForm form)	POST /unbind；删除用户与角色交集关系。	不能用于自己角色调整；不删除角色实体。
listRoleIdListByUserId(Long userId)	GET /bind/{userId}；返回角色 ID 列表。	不按当前客户端/禁用状态过滤。

接入与验证

按快速开始准备菜单、角色、权限与绑定数据，再通过当前用户查询比较管理端、App、认证 RoleHook 的结果。以同一禁用角色分别调用这些入口，可观察“绑定存在”与“运行时权限生效”的差别，不能用一个接口的结果替代全部授权判断。