diff --git a/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/mapper/SysDeptMapper.java b/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/mapper/SysDeptMapper.java
index 8cf6d3982..196eefb3c 100644
--- a/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/mapper/SysDeptMapper.java
+++ b/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/mapper/SysDeptMapper.java
@@ -20,12 +20,30 @@ import java.util.List;
  */
 public interface SysDeptMapper extends BaseMapperPlus<SysDept, SysDeptVo> {
 
+    /**
+     * 构建角色对应的部门 SQL 查询语句
+     *
+     * <p>该 SQL 用于查询某个角色关联的所有部门 ID，常用于数据权限控制</p>
+     *
+     * @param roleId 角色ID
+     * @return 查询部门ID的 SQL 语句字符串
+     */
     default String buildDeptByRoleSql(Long roleId) {
         return """
                 select dept_id from sys_role_dept where role_id = %d
             """.formatted(roleId);
     }
 
+    /**
+     * 构建 SQL 查询，用于获取当前角色拥有的部门中所有的父部门ID
+     *
+     * <p>
+     * 该 SQL 用于 deptCheckStrictly 场景下，排除非叶子节点（父节点）用。
+     * </p>
+     *
+     * @param roleId 角色ID
+     * @return SQL 语句字符串，查询角色下部门的所有父部门ID
+     */
     default String buildParentDeptByRoleSql(Long roleId) {
         return """
                 select parent_id from sys_dept where dept_id in (
diff --git a/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/mapper/SysMenuMapper.java b/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/mapper/SysMenuMapper.java
index d71c2998e..1af2872e7 100644
--- a/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/mapper/SysMenuMapper.java
+++ b/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/mapper/SysMenuMapper.java
@@ -15,6 +15,16 @@ import java.util.List;
  */
 public interface SysMenuMapper extends BaseMapperPlus<SysMenu, SysMenuVo> {
 
+    /**
+     * 构建用户权限菜单 SQL
+     *
+     * <p>
+     * 查询用户所属角色所拥有的菜单权限，用于权限判断、菜单加载等场景
+     * </p>
+     *
+     * @param userId 用户ID
+     * @return SQL 字符串，用于 inSql 条件
+     */
     default String buildMenuByUserSql(Long userId) {
         return """
                 select menu_id from sys_role_menu where role_id in (
@@ -23,12 +33,34 @@ public interface SysMenuMapper extends BaseMapperPlus<SysMenu, SysMenuVo> {
             """.formatted(userId);
     }
 
+    /**
+     * 构建角色对应的菜单ID SQL 子查询
+     *
+     * <p>
+     * 用于根据角色ID查询其所拥有的菜单权限（用于权限标识、菜单显示等场景）
+     * 通常配合 inSql 使用
+     * </p>
+     *
+     * @param roleId 角色ID
+     * @return 查询菜单ID的 SQL 子查询字符串
+     */
     default String buildMenuByRoleSql(Long roleId) {
         return """
                 select menu_id from sys_role_menu where role_id = %d
             """.formatted(roleId);
     }
 
+    /**
+     * 构建角色所关联菜单的父菜单ID查询 SQL
+     *
+     * <p>
+     * 用于配合菜单勾选树结构的 {@code menuCheckStrictly} 模式，过滤掉非叶子节点（父菜单），
+     * 只返回角色实际勾选的末级菜单
+     * </p>
+     *
+     * @param roleId 角色ID
+     * @return SQL 语句字符串（查询菜单的父菜单ID）
+     */
     default String buildParentMenuByRoleSql(Long roleId) {
         return """
                 select parent_id from sys_menu where menu_id in (
diff --git a/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/mapper/SysPostMapper.java b/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/mapper/SysPostMapper.java
index c244f40f9..679ebacc7 100644
--- a/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/mapper/SysPostMapper.java
+++ b/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/mapper/SysPostMapper.java
@@ -48,10 +48,10 @@ public interface SysPostMapper extends BaseMapperPlus<SysPost, SysPostVo> {
     }
 
     /**
-     * 查询用户所属岗位组
+     * 根据用户ID查询其关联的岗位列表
      *
      * @param userId 用户ID
-     * @return 结果
+     * @return 岗位信息列表
      */
     default List<SysPostVo> selectPostsByUserId(Long userId) {
         return this.selectVoList(new LambdaQueryWrapper<SysPost>()
diff --git a/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/mapper/SysRoleMapper.java b/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/mapper/SysRoleMapper.java
index 1d3a0bb77..41e25039e 100644
--- a/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/mapper/SysRoleMapper.java
+++ b/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/mapper/SysRoleMapper.java
@@ -20,6 +20,12 @@ import java.util.List;
  */
 public interface SysRoleMapper extends BaseMapperPlus<SysRole, SysRoleVo> {
 
+    /**
+     * 构建根据用户ID查询角色ID的SQL子查询
+     *
+     * @param userId 用户ID
+     * @return 查询用户对应角色ID的SQL语句字符串
+     */
     default String buildRoleByUserSql(Long userId) {
         return """
                 select role_id from sys_user_role where user_id = %d
diff --git a/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/ISysConfigService.java b/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/ISysConfigService.java
index 60863b8d3..a101643e8 100644
--- a/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/ISysConfigService.java
+++ b/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/ISysConfigService.java
@@ -14,7 +14,13 @@ import java.util.List;
  */
 public interface ISysConfigService {
 
-
+    /**
+     * 分页查询参数配置列表
+     *
+     * @param config    查询条件
+     * @param pageQuery 分页参数
+     * @return 参数配置分页列表
+     */
     TableDataInfo<SysConfigVo> selectPageConfigList(SysConfigBo config, PageQuery pageQuery);
 
     /**
diff --git a/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/ISysDictDataService.java b/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/ISysDictDataService.java
index 2ff49bc77..fdabd3170 100644
--- a/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/ISysDictDataService.java
+++ b/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/ISysDictDataService.java
@@ -14,7 +14,13 @@ import java.util.List;
  */
 public interface ISysDictDataService {
 
-
+    /**
+     * 分页查询字典数据列表
+     *
+     * @param dictData  查询条件
+     * @param pageQuery 分页参数
+     * @return 字典数据分页列表
+     */
     TableDataInfo<SysDictDataVo> selectPageDictDataList(SysDictDataBo dictData, PageQuery pageQuery);
 
     /**
diff --git a/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/ISysDictTypeService.java b/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/ISysDictTypeService.java
index c2704db09..e3a04def2 100644
--- a/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/ISysDictTypeService.java
+++ b/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/ISysDictTypeService.java
@@ -15,7 +15,13 @@ import java.util.List;
  */
 public interface ISysDictTypeService {
 
-
+    /**
+     * 分页查询字典类型列表
+     *
+     * @param dictType  查询条件
+     * @param pageQuery 分页参数
+     * @return 字典类型分页列表
+     */
     TableDataInfo<SysDictTypeVo> selectPageDictTypeList(SysDictTypeBo dictType, PageQuery pageQuery);
 
     /**
diff --git a/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/ISysLogininforService.java b/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/ISysLogininforService.java
index 6b3b7a6b7..1bc1ea9ff 100644
--- a/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/ISysLogininforService.java
+++ b/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/ISysLogininforService.java
@@ -14,7 +14,13 @@ import java.util.List;
  */
 public interface ISysLogininforService {
 
-
+    /**
+     * 分页查询登录日志列表
+     *
+     * @param logininfor 查询条件
+     * @param pageQuery  分页参数
+     * @return 登录日志分页列表
+     */
     TableDataInfo<SysLogininforVo> selectPageLogininforList(SysLogininforBo logininfor, PageQuery pageQuery);
 
     /**
diff --git a/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/ISysNoticeService.java b/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/ISysNoticeService.java
index 8ec999d01..8482cd0ce 100644
--- a/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/ISysNoticeService.java
+++ b/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/ISysNoticeService.java
@@ -14,7 +14,13 @@ import java.util.List;
  */
 public interface ISysNoticeService {
 
-
+    /**
+     * 分页查询通知公告列表
+     *
+     * @param notice    查询条件
+     * @param pageQuery 分页参数
+     * @return 通知公告分页列表
+     */
     TableDataInfo<SysNoticeVo> selectPageNoticeList(SysNoticeBo notice, PageQuery pageQuery);
 
     /**
diff --git a/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/ISysOperLogService.java b/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/ISysOperLogService.java
index 957351023..e8b340c73 100644
--- a/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/ISysOperLogService.java
+++ b/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/ISysOperLogService.java
@@ -14,6 +14,13 @@ import java.util.List;
  */
 public interface ISysOperLogService {
 
+    /**
+     * 分页查询操作日志列表
+     *
+     * @param operLog   查询条件
+     * @param pageQuery 分页参数
+     * @return 操作日志分页列表
+     */
     TableDataInfo<SysOperLogVo> selectPageOperLogList(SysOperLogBo operLog, PageQuery pageQuery);
 
     /**
diff --git a/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/ISysPostService.java b/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/ISysPostService.java
index 511d842ee..1caaab282 100644
--- a/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/ISysPostService.java
+++ b/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/ISysPostService.java
@@ -14,7 +14,13 @@ import java.util.List;
  */
 public interface ISysPostService {
 
-
+    /**
+     * 分页查询岗位列表
+     *
+     * @param post      查询条件
+     * @param pageQuery 分页参数
+     * @return 岗位分页列表
+     */
     TableDataInfo<SysPostVo> selectPagePostList(SysPostBo post, PageQuery pageQuery);
 
     /**
diff --git a/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/ISysRoleService.java b/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/ISysRoleService.java
index 5b320c0d3..c6f674ddf 100644
--- a/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/ISysRoleService.java
+++ b/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/ISysRoleService.java
@@ -16,11 +16,17 @@ import java.util.Set;
  */
 public interface ISysRoleService {
 
-
+    /**
+     * 分页查询角色列表
+     *
+     * @param role      查询条件
+     * @param pageQuery 分页参数
+     * @return 角色分页列表
+     */
     TableDataInfo<SysRoleVo> selectPageRoleList(SysRoleBo role, PageQuery pageQuery);
 
     /**
-     * 根据条件分页查询角色数据
+     * 根据条件查询角色数据
      *
      * @param role 角色信息
      * @return 角色数据集合信息
@@ -195,8 +201,29 @@ public interface ISysRoleService {
      */
     int insertAuthUsers(Long roleId, Long[] userIds);
 
+    /**
+     * 根据角色ID清除该角色关联的所有在线用户的登录状态（踢出在线用户）
+     *
+     * <p>
+     * 先判断角色是否绑定用户，若无绑定则直接返回
+     * 然后遍历当前所有在线Token，查找拥有该角色的用户并强制登出
+     * 注意：在线用户量过大时，操作可能导致 Redis 阻塞，需谨慎调用
+     * </p>
+     *
+     * @param roleId 角色ID
+     */
     void cleanOnlineUserByRole(Long roleId);
 
+    /**
+     * 根据用户ID列表清除对应在线用户的登录状态（踢出指定用户）
+     *
+     * <p>
+     * 遍历当前所有在线Token，匹配用户ID列表中的用户，强制登出
+     * 注意：在线用户量过大时，操作可能导致 Redis 阻塞，需谨慎调用
+     * </p>
+     *
+     * @param userIds 需要清除的用户ID列表
+     */
     void cleanOnlineUser(List<Long> userIds);
 
 }
diff --git a/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/impl/SysConfigServiceImpl.java b/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/impl/SysConfigServiceImpl.java
index ed65ae45c..c9b3e478c 100644
--- a/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/impl/SysConfigServiceImpl.java
+++ b/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/impl/SysConfigServiceImpl.java
@@ -41,6 +41,13 @@ public class SysConfigServiceImpl implements ISysConfigService, ConfigService {
 
     private final SysConfigMapper baseMapper;
 
+    /**
+     * 分页查询参数配置列表
+     *
+     * @param config    查询条件
+     * @param pageQuery 分页参数
+     * @return 参数配置分页列表
+     */
     @Override
     public TableDataInfo<SysConfigVo> selectPageConfigList(SysConfigBo config, PageQuery pageQuery) {
         LambdaQueryWrapper<SysConfig> lqw = buildQueryWrapper(config);
diff --git a/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/impl/SysDictDataServiceImpl.java b/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/impl/SysDictDataServiceImpl.java
index baf1bba99..018f04338 100644
--- a/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/impl/SysDictDataServiceImpl.java
+++ b/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/impl/SysDictDataServiceImpl.java
@@ -33,6 +33,13 @@ public class SysDictDataServiceImpl implements ISysDictDataService {
 
     private final SysDictDataMapper baseMapper;
 
+    /**
+     * 分页查询字典数据列表
+     *
+     * @param dictData  查询条件
+     * @param pageQuery 分页参数
+     * @return 字典数据分页列表
+     */
     @Override
     public TableDataInfo<SysDictDataVo> selectPageDictDataList(SysDictDataBo dictData, PageQuery pageQuery) {
         LambdaQueryWrapper<SysDictData> lqw = buildQueryWrapper(dictData);
diff --git a/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/impl/SysDictTypeServiceImpl.java b/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/impl/SysDictTypeServiceImpl.java
index 3491e887e..0ef908d30 100644
--- a/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/impl/SysDictTypeServiceImpl.java
+++ b/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/impl/SysDictTypeServiceImpl.java
@@ -48,6 +48,13 @@ public class SysDictTypeServiceImpl implements ISysDictTypeService, DictService
     private final SysDictTypeMapper baseMapper;
     private final SysDictDataMapper dictDataMapper;
 
+    /**
+     * 分页查询字典类型列表
+     *
+     * @param dictType  查询条件
+     * @param pageQuery 分页参数
+     * @return 字典类型分页列表
+     */
     @Override
     public TableDataInfo<SysDictTypeVo> selectPageDictTypeList(SysDictTypeBo dictType, PageQuery pageQuery) {
         LambdaQueryWrapper<SysDictType> lqw = buildQueryWrapper(dictType);
diff --git a/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/impl/SysLogininforServiceImpl.java b/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/impl/SysLogininforServiceImpl.java
index 72b497eca..c388d9919 100644
--- a/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/impl/SysLogininforServiceImpl.java
+++ b/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/impl/SysLogininforServiceImpl.java
@@ -108,6 +108,13 @@ public class SysLogininforServiceImpl implements ISysLogininforService {
         return "[" + msg.toString() + "]";
     }
 
+    /**
+     * 分页查询登录日志列表
+     *
+     * @param logininfor 查询条件
+     * @param pageQuery  分页参数
+     * @return 登录日志分页列表
+     */
     @Override
     public TableDataInfo<SysLogininforVo> selectPageLogininforList(SysLogininforBo logininfor, PageQuery pageQuery) {
         Map<String, Object> params = logininfor.getParams();
diff --git a/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/impl/SysNoticeServiceImpl.java b/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/impl/SysNoticeServiceImpl.java
index 19a3ff59a..aa4135f1e 100644
--- a/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/impl/SysNoticeServiceImpl.java
+++ b/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/impl/SysNoticeServiceImpl.java
@@ -3,6 +3,7 @@ package org.dromara.system.service.impl;
 import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
 import com.baomidou.mybatisplus.core.toolkit.Wrappers;
 import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
+import lombok.RequiredArgsConstructor;
 import org.dromara.common.core.utils.MapstructUtils;
 import org.dromara.common.core.utils.ObjectUtils;
 import org.dromara.common.core.utils.StringUtils;
@@ -16,7 +17,6 @@ import org.dromara.system.domain.vo.SysUserVo;
 import org.dromara.system.mapper.SysNoticeMapper;
 import org.dromara.system.mapper.SysUserMapper;
 import org.dromara.system.service.ISysNoticeService;
-import lombok.RequiredArgsConstructor;
 import org.springframework.stereotype.Service;
 
 import java.util.Arrays;
@@ -34,6 +34,13 @@ public class SysNoticeServiceImpl implements ISysNoticeService {
     private final SysNoticeMapper baseMapper;
     private final SysUserMapper userMapper;
 
+    /**
+     * 分页查询通知公告列表
+     *
+     * @param notice    查询条件
+     * @param pageQuery 分页参数
+     * @return 通知公告分页列表
+     */
     @Override
     public TableDataInfo<SysNoticeVo> selectPageNoticeList(SysNoticeBo notice, PageQuery pageQuery) {
         LambdaQueryWrapper<SysNotice> lqw = buildQueryWrapper(notice);
diff --git a/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/impl/SysOperLogServiceImpl.java b/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/impl/SysOperLogServiceImpl.java
index 27c2f32d5..9399c901d 100644
--- a/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/impl/SysOperLogServiceImpl.java
+++ b/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/impl/SysOperLogServiceImpl.java
@@ -49,6 +49,13 @@ public class SysOperLogServiceImpl implements ISysOperLogService {
         insertOperlog(operLog);
     }
 
+    /**
+     * 分页查询操作日志列表
+     *
+     * @param operLog   查询条件
+     * @param pageQuery 分页参数
+     * @return 操作日志分页列表
+     */
     @Override
     public TableDataInfo<SysOperLogVo> selectPageOperLogList(SysOperLogBo operLog, PageQuery pageQuery) {
         LambdaQueryWrapper<SysOperLog> lqw = buildQueryWrapper(operLog);
diff --git a/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/impl/SysPostServiceImpl.java b/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/impl/SysPostServiceImpl.java
index ad1055ac0..c859a8e6a 100644
--- a/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/impl/SysPostServiceImpl.java
+++ b/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/impl/SysPostServiceImpl.java
@@ -41,6 +41,13 @@ public class SysPostServiceImpl implements ISysPostService, PostService {
     private final SysDeptMapper deptMapper;
     private final SysUserPostMapper userPostMapper;
 
+    /**
+     * 分页查询岗位列表
+     *
+     * @param post      查询条件
+     * @param pageQuery 分页参数
+     * @return 岗位分页列表
+     */
     @Override
     public TableDataInfo<SysPostVo> selectPagePostList(SysPostBo post, PageQuery pageQuery) {
         Page<SysPostVo> page = baseMapper.selectPagePostList(pageQuery.build(), buildQueryWrapper(post));
diff --git a/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/impl/SysRoleServiceImpl.java b/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/impl/SysRoleServiceImpl.java
index 0851be90d..db2da3125 100644
--- a/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/impl/SysRoleServiceImpl.java
+++ b/ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/impl/SysRoleServiceImpl.java
@@ -54,6 +54,13 @@ public class SysRoleServiceImpl implements ISysRoleService, RoleService {
     private final SysUserRoleMapper userRoleMapper;
     private final SysRoleDeptMapper roleDeptMapper;
 
+    /**
+     * 分页查询角色列表
+     *
+     * @param role      查询条件
+     * @param pageQuery 分页参数
+     * @return 角色分页列表
+     */
     @Override
     public TableDataInfo<SysRoleVo> selectPageRoleList(SysRoleBo role, PageQuery pageQuery) {
         Page<SysRoleVo> page = baseMapper.selectPageRoleList(pageQuery.build(), this.buildQueryWrapper(role));
@@ -61,7 +68,7 @@ public class SysRoleServiceImpl implements ISysRoleService, RoleService {
     }
 
     /**
-     * 根据条件分页查询角色数据
+     * 根据条件查询角色数据
      *
      * @param role 角色信息
      * @return 角色数据集合信息
@@ -489,6 +496,17 @@ public class SysRoleServiceImpl implements ISysRoleService, RoleService {
         return rows;
     }
 
+    /**
+     * 根据角色ID清除该角色关联的所有在线用户的登录状态（踢出在线用户）
+     *
+     * <p>
+     * 先判断角色是否绑定用户，若无绑定则直接返回
+     * 然后遍历当前所有在线Token，查找拥有该角色的用户并强制登出
+     * 注意：在线用户量过大时，操作可能导致 Redis 阻塞，需谨慎调用
+     * </p>
+     *
+     * @param roleId 角色ID
+     */
     @Override
     public void cleanOnlineUserByRole(Long roleId) {
         // 如果角色未绑定用户 直接返回
@@ -520,6 +538,16 @@ public class SysRoleServiceImpl implements ISysRoleService, RoleService {
         });
     }
 
+    /**
+     * 根据用户ID列表清除对应在线用户的登录状态（踢出指定用户）
+     *
+     * <p>
+     * 遍历当前所有在线Token，匹配用户ID列表中的用户，强制登出
+     * 注意：在线用户量过大时，操作可能导致 Redis 阻塞，需谨慎调用
+     * </p>
+     *
+     * @param userIds 需要清除的用户ID列表
+     */
     @Override
     public void cleanOnlineUser(List<Long> userIds) {
         List<String> keys = StpUtil.searchTokenValue("", 0, -1, false);