update 优化 统一补全代码注释

ruoyi-modules/ruoyi-demo/src/main/java/org/dromara/demo/service/ITestDemoService.java

@@ -20,22 +20,34 @@ public interface ITestDemoService {
     /**
      * 查询单个
      *
-     * @return
+     * @param id 主键
+     * @return 测试单表视图对象
      */
     TestDemoVo queryById(Long id);
 
     /**
-     * 查询列表
+     * 分页查询测试单表列表。
+     *
+     * @param bo 查询条件
+     * @param pageQuery 分页参数
+     * @return 分页结果
      */
     TableDataInfo<TestDemoVo> queryPageList(TestDemoBo bo, PageQuery pageQuery);
 
     /**
-     * 自定义分页查询
+     * 按自定义 SQL 分页查询测试单表列表。
+     *
+     * @param bo 查询条件
+     * @param pageQuery 分页参数
+     * @return 分页结果
      */
     TableDataInfo<TestDemoVo> customPageList(TestDemoBo bo, PageQuery pageQuery);
 
     /**
-     * 查询列表
+     * 查询符合条件的测试单表列表。
+     *
+     * @param bo 查询条件
+     * @return 结果列表
      */
     List<TestDemoVo> queryList(TestDemoBo bo);
 
@@ -43,7 +55,7 @@ public interface ITestDemoService {
      * 根据新增业务对象插入测试单表
      *
      * @param bo 测试单表新增业务对象
-     * @return
+     * @return 是否新增成功
      */
     Boolean insertByBo(TestDemoBo bo);
 
@@ -51,7 +63,7 @@ public interface ITestDemoService {
      * 根据编辑业务对象修改测试单表
      *
      * @param bo 测试单表编辑业务对象
-     * @return
+     * @return 是否修改成功
      */
     Boolean updateByBo(TestDemoBo bo);
 
@@ -60,12 +72,15 @@ public interface ITestDemoService {
      *
      * @param ids     主键集合
      * @param isValid 是否校验,true-删除前校验,false-不校验
-     * @return
+     * @return 是否删除成功
      */
     Boolean deleteWithValidByIds(Collection<Long> ids, Boolean isValid);
 
     /**
-     * 批量保存
+     * 批量保存测试单表数据。
+     *
+     * @param list 待保存数据
+     * @return 是否保存成功
      */
     Boolean saveBatch(List<TestDemo> list);
 }

ruoyi-modules/ruoyi-demo/src/main/java/org/dromara/demo/service/ITestTreeService.java

@@ -16,12 +16,16 @@ public interface ITestTreeService {
     /**
      * 查询单个
      *
-     * @return
+     * @param id 主键
+     * @return 测试树表视图对象
      */
     TestTreeVo queryById(Long id);
 
     /**
-     * 查询列表
+     * 查询符合条件的测试树表列表。
+     *
+     * @param bo 查询条件
+     * @return 结果列表
      */
     List<TestTreeVo> queryList(TestTreeBo bo);
 
@@ -29,7 +33,7 @@ public interface ITestTreeService {
      * 根据新增业务对象插入测试树表
      *
      * @param bo 测试树表新增业务对象
-     * @return
+     * @return 是否新增成功
      */
     Boolean insertByBo(TestTreeBo bo);
 
@@ -37,7 +41,7 @@ public interface ITestTreeService {
      * 根据编辑业务对象修改测试树表
      *
      * @param bo 测试树表编辑业务对象
-     * @return
+     * @return 是否修改成功
      */
     Boolean updateByBo(TestTreeBo bo);
 
@@ -46,7 +50,7 @@ public interface ITestTreeService {
      *
      * @param ids     主键集合
      * @param isValid 是否校验,true-删除前校验,false-不校验
-     * @return
+     * @return 是否删除成功
      */
     Boolean deleteWithValidByIds(Collection<Long> ids, Boolean isValid);
 }

ruoyi-modules/ruoyi-demo/src/main/java/org/dromara/demo/service/impl/TestDemoServiceImpl.java

@@ -32,11 +32,24 @@ public class TestDemoServiceImpl implements ITestDemoService {
 
     private final TestDemoMapper baseMapper;
 
+    /**
+     * 根据主键查询测试单表详情。
+     *
+     * @param id 主键
+     * @return 测试单表视图对象
+     */
     @Override
     public TestDemoVo queryById(Long id) {
         return baseMapper.selectVoById(id);
     }
 
+    /**
+     * 分页查询测试单表列表。
+     *
+     * @param bo 查询条件
+     * @param pageQuery 分页参数
+     * @return 分页结果
+     */
     @Override
     public TableDataInfo<TestDemoVo> queryPageList(TestDemoBo bo, PageQuery pageQuery) {
         LambdaQueryWrapper<TestDemo> lqw = buildQueryWrapper(bo);
@@ -45,7 +58,11 @@ public class TestDemoServiceImpl implements ITestDemoService {
     }
 
     /**
-     * 自定义分页查询
+     * 通过自定义 SQL 分页查询测试单表列表。
+     *
+     * @param bo 查询条件
+     * @param pageQuery 分页参数
+     * @return 分页结果
      */
     @Override
     public TableDataInfo<TestDemoVo> customPageList(TestDemoBo bo, PageQuery pageQuery) {
@@ -54,11 +71,23 @@ public class TestDemoServiceImpl implements ITestDemoService {
         return TableDataInfo.build(result);
     }
 
+    /**
+     * 查询符合条件的测试单表列表。
+     *
+     * @param bo 查询条件
+     * @return 结果列表
+     */
     @Override
     public List<TestDemoVo> queryList(TestDemoBo bo) {
         return baseMapper.selectVoList(buildQueryWrapper(bo));
     }
 
+    /**
+     * 构建测试单表动态查询条件。
+     *
+     * @param bo 查询条件
+     * @return 查询条件包装器
+     */
     private LambdaQueryWrapper<TestDemo> buildQueryWrapper(TestDemoBo bo) {
         Map<String, Object> params = bo.getParams();
         LambdaQueryWrapper<TestDemo> lqw = Wrappers.lambdaQuery();
@@ -72,6 +101,12 @@ public class TestDemoServiceImpl implements ITestDemoService {
         return lqw;
     }
 
+    /**
+     * 新增测试单表数据。
+     *
+     * @param bo 新增业务对象
+     * @return 是否新增成功
+     */
     @Override
     public Boolean insertByBo(TestDemoBo bo) {
         TestDemo add = MapstructUtils.convert(bo, TestDemo.class);
@@ -83,6 +118,12 @@ public class TestDemoServiceImpl implements ITestDemoService {
         return flag;
     }
 
+    /**
+     * 更新测试单表数据。
+     *
+     * @param bo 编辑业务对象
+     * @return 是否更新成功
+     */
     @Override
     public Boolean updateByBo(TestDemoBo bo) {
         TestDemo update = MapstructUtils.convert(bo, TestDemo.class);
@@ -99,6 +140,13 @@ public class TestDemoServiceImpl implements ITestDemoService {
         //TODO 做一些数据校验,如唯一约束
     }
 
+    /**
+     * 按主键集合删除测试单表数据，并按需执行删除前校验。
+     *
+     * @param ids 主键集合
+     * @param isValid 是否执行删除校验
+     * @return 是否删除成功
+     */
     @Override
     public Boolean deleteWithValidByIds(Collection<Long> ids, Boolean isValid) {
         if (isValid) {
@@ -111,6 +159,12 @@ public class TestDemoServiceImpl implements ITestDemoService {
         return baseMapper.deleteByIds(ids) > 0;
     }
 
+    /**
+     * 批量保存测试单表数据。
+     *
+     * @param list 待保存实体列表
+     * @return 是否保存成功
+     */
     @Override
     public Boolean saveBatch(List<TestDemo> list) {
         return baseMapper.insertBatch(list);

ruoyi-modules/ruoyi-demo/src/main/java/org/dromara/demo/service/impl/TestTreeServiceImpl.java

@@ -29,18 +29,36 @@ public class TestTreeServiceImpl implements ITestTreeService {
 
     private final TestTreeMapper baseMapper;
 
+    /**
+     * 根据主键查询测试树表详情。
+     *
+     * @param id 主键
+     * @return 测试树表视图对象
+     */
     @Override
     public TestTreeVo queryById(Long id) {
         return baseMapper.selectVoById(id);
     }
 
     // @DS("slave") // 切换从库查询
+    /**
+     * 查询符合条件的测试树表列表。
+     *
+     * @param bo 查询条件
+     * @return 结果列表
+     */
     @Override
     public List<TestTreeVo> queryList(TestTreeBo bo) {
         LambdaQueryWrapper<TestTree> lqw = buildQueryWrapper(bo);
         return baseMapper.selectVoList(lqw);
     }
 
+    /**
+     * 构建测试树表动态查询条件。
+     *
+     * @param bo 查询条件
+     * @return 查询条件包装器
+     */
     private LambdaQueryWrapper<TestTree> buildQueryWrapper(TestTreeBo bo) {
         Map<String, Object> params = bo.getParams();
         LambdaQueryWrapper<TestTree> lqw = Wrappers.lambdaQuery();
@@ -53,6 +71,12 @@ public class TestTreeServiceImpl implements ITestTreeService {
         return lqw;
     }
 
+    /**
+     * 新增测试树表数据。
+     *
+     * @param bo 新增业务对象
+     * @return 是否新增成功
+     */
     @Override
     public Boolean insertByBo(TestTreeBo bo) {
         TestTree add = MapstructUtils.convert(bo, TestTree.class);
@@ -64,6 +88,12 @@ public class TestTreeServiceImpl implements ITestTreeService {
         return flag;
     }
 
+    /**
+     * 更新测试树表数据。
+     *
+     * @param bo 编辑业务对象
+     * @return 是否更新成功
+     */
     @Override
     public Boolean updateByBo(TestTreeBo bo) {
         TestTree update = MapstructUtils.convert(bo, TestTree.class);
@@ -80,6 +110,13 @@ public class TestTreeServiceImpl implements ITestTreeService {
         //TODO 做一些数据校验,如唯一约束
     }
 
+    /**
+     * 按主键集合删除测试树表数据，并按需执行删除前校验。
+     *
+     * @param ids 主键集合
+     * @param isValid 是否执行删除校验
+     * @return 是否删除成功
+     */
     @Override
     public Boolean deleteWithValidByIds(Collection<Long> ids, Boolean isValid) {
         if (isValid) {

ruoyi-modules/ruoyi-generator/src/main/java/org/dromara/generator/config/GenConfig.java

@@ -39,6 +39,11 @@ public class GenConfig {
         return author;
     }
 
+    /**
+     * 注入代码生成作者配置。
+     *
+     * @param author 作者名称
+     */
     @Value("${author}")
     public void setAuthor(String author) {
         GenConfig.author = author;
@@ -48,6 +53,11 @@ public class GenConfig {
         return packageName;
     }
 
+    /**
+     * 注入代码生成基础包名配置。
+     *
+     * @param packageName 基础包名
+     */
     @Value("${packageName}")
     public void setPackageName(String packageName) {
         GenConfig.packageName = packageName;
@@ -57,6 +67,11 @@ public class GenConfig {
         return autoRemovePre;
     }
 
+    /**
+     * 注入是否自动移除表前缀配置。
+     *
+     * @param autoRemovePre 是否自动移除表前缀
+     */
     @Value("${autoRemovePre}")
     public void setAutoRemovePre(boolean autoRemovePre) {
         GenConfig.autoRemovePre = autoRemovePre;
@@ -66,6 +81,11 @@ public class GenConfig {
         return tablePrefix;
     }
 
+    /**
+     * 注入代码生成表前缀配置。
+     *
+     * @param tablePrefix 表前缀字符串
+     */
     @Value("${tablePrefix}")
     public void setTablePrefix(String tablePrefix) {
         GenConfig.tablePrefix = tablePrefix;

ruoyi-modules/ruoyi-generator/src/main/java/org/dromara/generator/config/MyBatisDataSourceMonitor.java

@@ -25,6 +25,9 @@ import java.util.Map;
 @Component
 public class MyBatisDataSourceMonitor implements DataSourceMonitor {
 
+    /**
+     * 初始化 anyline 与动态数据源联动所需的元数据解析策略。
+     */
     public MyBatisDataSourceMonitor() {
         // 调整执行模式为自定义
         ConfigTable.KEEP_ADAPTER = 2;
@@ -72,6 +75,8 @@ public class MyBatisDataSourceMonitor implements DataSourceMonitor {
 
     /**
      * 数据源唯一标识 如果不实现则默认feature
+     *
+     * @param runtime    数据运行时上下文
      * @param datasource 数据源
      * @return String 返回null由上层自动提取
      */
@@ -90,6 +95,7 @@ public class MyBatisDataSourceMonitor implements DataSourceMonitor {
      * ConfigTable.KEEP_ADAPTER=2 : 根据当前接口判断是否保持同一个数据源绑定同一个adapter<br/>
      * DynamicRoutingDataSource类型的返回false,因为同一个DynamicRoutingDataSource可能对应多类数据库, 如果项目中只有一种数据库 应该直接返回true
      *
+     * @param runtime    数据运行时上下文
      * @param datasource 数据源
      * @return boolean
      */

ruoyi-modules/ruoyi-generator/src/main/java/org/dromara/generator/constant/GenConstants.java

@@ -180,7 +180,7 @@ public interface GenConstants {
     String QUERY_EQ = "EQ";
 
     /**
-     * 需要
+     * 必填标识，对应前端表单规则中的必填字段配置。
      */
     String REQUIRE = "1";
 }

ruoyi-modules/ruoyi-generator/src/main/java/org/dromara/generator/controller/GenController.java

@@ -39,7 +39,11 @@ public class GenController extends BaseController {
     private final IGenTableService genTableService;
 
     /**
-     * 查询代码生成列表
+     * 分页查询代码生成业务列表。
+     *
+     * @param genTable 查询条件
+     * @param pageQuery 分页参数
+     * @return 代码生成列表
      */
     @SaCheckPermission("tool:gen:list")
     @GetMapping("/list")
@@ -51,6 +55,7 @@ public class GenController extends BaseController {
      * 修改代码生成业务
      *
      * @param tableId 表ID
+     * @return 表、字段与可选业务表信息
      */
     @RepeatSubmit()
     @SaCheckPermission("tool:gen:query")
@@ -67,7 +72,11 @@ public class GenController extends BaseController {
     }
 
     /**
-     * 查询数据库列表
+     * 分页查询数据库表列表。
+     *
+     * @param genTable 查询条件
+     * @param pageQuery 分页参数
+     * @return 数据库表列表
      */
     @SaCheckPermission("tool:gen:list")
     @GetMapping("/db/list")
@@ -79,6 +88,7 @@ public class GenController extends BaseController {
      * 查询数据表字段列表
      *
      * @param tableId 表ID
+     * @return 字段列表
      */
     @SaCheckPermission("tool:gen:list")
     @GetMapping(value = "/column/{tableId}")
@@ -92,6 +102,7 @@ public class GenController extends BaseController {
      *
      * @param tables   表名串
      * @param dataName 数据源名称
+     * @return 操作结果
      */
     @SaCheckPermission("tool:gen:import")
     @Log(title = "代码生成", businessType = BusinessType.IMPORT)
@@ -107,7 +118,10 @@ public class GenController extends BaseController {
     }
 
     /**
-     * 修改保存代码生成业务
+     * 保存代码生成业务配置。
+     *
+     * @param genTable 业务配置
+     * @return 操作结果
      */
     @SaCheckPermission("tool:gen:edit")
     @Log(title = "代码生成", businessType = BusinessType.UPDATE)
@@ -123,6 +137,7 @@ public class GenController extends BaseController {
      * 删除代码生成
      *
      * @param tableIds 表ID串
+     * @return 操作结果
      */
     @SaCheckPermission("tool:gen:remove")
     @Log(title = "代码生成", businessType = BusinessType.DELETE)
@@ -136,6 +151,7 @@ public class GenController extends BaseController {
      * 预览代码
      *
      * @param tableId 表ID
+     * @return 模板路径与生成代码内容映射
      */
     @SaCheckPermission("tool:gen:preview")
     @GetMapping("/preview/{tableId}")
@@ -147,6 +163,7 @@ public class GenController extends BaseController {
     /**
      * 生成代码（下载方式）
      *
+     * @param response HTTP 响应
      * @param tableId 表ID
      */
     @SaCheckPermission("tool:gen:code")
@@ -161,6 +178,7 @@ public class GenController extends BaseController {
      * 生成代码（自定义路径）
      *
      * @param tableId 表ID
+     * @return 操作结果
      */
     @SaCheckPermission("tool:gen:code")
     @Log(title = "代码生成", businessType = BusinessType.GENCODE)
@@ -174,6 +192,7 @@ public class GenController extends BaseController {
      * 同步数据库
      *
      * @param tableId 表ID
+     * @return 操作结果
      */
     @SaCheckPermission("tool:gen:edit")
     @Log(title = "代码生成", businessType = BusinessType.UPDATE)
@@ -187,6 +206,7 @@ public class GenController extends BaseController {
     /**
      * 批量生成代码
      *
+     * @param response HTTP 响应
      * @param tableIdStr 表ID串
      */
     @SaCheckPermission("tool:gen:code")
@@ -199,7 +219,10 @@ public class GenController extends BaseController {
     }
 
     /**
-     * 生成zip文件
+     * 将生成结果写出为 zip 文件流。
+     *
+     * @param response HTTP 响应
+     * @param data zip 二进制数据
      */
     private void genCode(HttpServletResponse response, byte[] data) throws IOException {
         response.reset();
@@ -212,7 +235,9 @@ public class GenController extends BaseController {
     }
 
     /**
-     * 查询数据源名称列表
+     * 查询当前可用数据源名称列表。
+     *
+     * @return 数据源名称集合
      */
     @SaCheckPermission("tool:gen:list")
     @GetMapping(value = "/getDataNames")

ruoyi-modules/ruoyi-generator/src/main/java/org/dromara/generator/domain/GenTable.java

@@ -152,7 +152,7 @@ public class GenTable extends BaseEntity {
     @TableField(exist = false)
     private String treeName;
 
-    /*
+    /**
      * 菜单id列表
      */
     @TableField(exist = false)
@@ -170,26 +170,61 @@ public class GenTable extends BaseEntity {
     @TableField(exist = false)
     private String parentMenuName;
 
+    /**
+     * 判断当前业务表是否采用树表模板。
+     *
+     * @return 树表模板返回 {@code true}
+     */
     public boolean isTree() {
         return isTree(this.tplCategory);
     }
 
+    /**
+     * 根据模板分类判断是否为树表模板。
+     *
+     * @param tplCategory 模板分类
+     * @return 树表模板返回 {@code true}
+     */
     public static boolean isTree(String tplCategory) {
         return tplCategory != null && StringUtils.equals(GenConstants.TPL_TREE, tplCategory);
     }
 
+    /**
+     * 判断当前业务表是否采用普通 CRUD 模板。
+     *
+     * @return 普通 CRUD 模板返回 {@code true}
+     */
     public boolean isCrud() {
         return isCrud(this.tplCategory);
     }
 
+    /**
+     * 根据模板分类判断是否为普通 CRUD 模板。
+     *
+     * @param tplCategory 模板分类
+     * @return 普通 CRUD 模板返回 {@code true}
+     */
     public static boolean isCrud(String tplCategory) {
         return tplCategory != null && StringUtils.equals(GenConstants.TPL_CRUD, tplCategory);
     }
 
+    /**
+     * 判断指定 Java 字段是否属于基类公共字段。
+     *
+     * @param javaField Java 字段名
+     * @return 基类公共字段返回 {@code true}
+     */
     public boolean isSuperColumn(String javaField) {
         return isSuperColumn(this.tplCategory, javaField);
     }
 
+    /**
+     * 根据模板分类与字段名判断是否属于基类公共字段。
+     *
+     * @param tplCategory 模板分类
+     * @param javaField   Java 字段名
+     * @return 基类公共字段返回 {@code true}
+     */
     public static boolean isSuperColumn(String tplCategory, String javaField) {
         return StringUtils.equalsAnyIgnoreCase(javaField, GenConstants.BASE_ENTITY);
     }

ruoyi-modules/ruoyi-generator/src/main/java/org/dromara/generator/domain/GenTableColumn.java

@@ -122,70 +122,163 @@ public class GenTableColumn extends BaseEntity {
      */
     private Integer sort;
 
+    /**
+     * 获取首字母大写后的 Java 字段名。
+     *
+     * @return 首字母大写的 Java 字段名
+     */
     public String getCapJavaField() {
         return StringUtils.capitalize(javaField);
     }
 
+    /**
+     * 判断当前列是否为主键列。
+     *
+     * @return 主键列返回 {@code true}
+     */
     public boolean isPk() {
         return isPk(this.isPk);
     }
 
+    /**
+     * 根据标识判断是否为主键列。
+     *
+     * @param isPk 主键标识
+     * @return 主键列返回 {@code true}
+     */
     public boolean isPk(String isPk) {
         return isPk != null && StringUtils.equals("1", isPk);
     }
 
+    /**
+     * 判断当前列是否为自增列。
+     *
+     * @return 自增列返回 {@code true}
+     */
     public boolean isIncrement() {
         return isIncrement(this.isIncrement);
     }
 
+    /**
+     * 根据标识判断是否为自增列。
+     *
+     * @param isIncrement 自增标识
+     * @return 自增列返回 {@code true}
+     */
     public boolean isIncrement(String isIncrement) {
         return isIncrement != null && StringUtils.equals("1", isIncrement);
     }
 
+    /**
+     * 判断当前列是否必填。
+     *
+     * @return 必填返回 {@code true}
+     */
     public boolean isRequired() {
         return isRequired(this.isRequired);
     }
 
+    /**
+     * 根据标识判断当前列是否必填。
+     *
+     * @param isRequired 必填标识
+     * @return 必填返回 {@code true}
+     */
     public boolean isRequired(String isRequired) {
         return isRequired != null && StringUtils.equals("1", isRequired);
     }
 
+    /**
+     * 判断当前列是否参与新增。
+     *
+     * @return 参与新增返回 {@code true}
+     */
     public boolean isInsert() {
         return isInsert(this.isInsert);
     }
 
+    /**
+     * 根据标识判断当前列是否参与新增。
+     *
+     * @param isInsert 新增标识
+     * @return 参与新增返回 {@code true}
+     */
     public boolean isInsert(String isInsert) {
         return isInsert != null && StringUtils.equals("1", isInsert);
     }
 
+    /**
+     * 判断当前列是否参与编辑。
+     *
+     * @return 参与编辑返回 {@code true}
+     */
     public boolean isEdit() {
         return isEdit(this.isEdit);
     }
 
+    /**
+     * 根据标识判断当前列是否参与编辑。
+     *
+     * @param isEdit 编辑标识
+     * @return 参与编辑返回 {@code true}
+     */
     public boolean isEdit(String isEdit) {
         return isEdit != null && StringUtils.equals("1", isEdit);
     }
 
+    /**
+     * 判断当前列是否参与列表展示。
+     *
+     * @return 参与列表展示返回 {@code true}
+     */
     public boolean isList() {
         return isList(this.isList);
     }
 
+    /**
+     * 根据标识判断当前列是否参与列表展示。
+     *
+     * @param isList 列表展示标识
+     * @return 参与列表展示返回 {@code true}
+     */
     public boolean isList(String isList) {
         return isList != null && StringUtils.equals("1", isList);
     }
 
+    /**
+     * 判断当前列是否参与查询条件。
+     *
+     * @return 参与查询返回 {@code true}
+     */
     public boolean isQuery() {
         return isQuery(this.isQuery);
     }
 
+    /**
+     * 根据标识判断当前列是否参与查询条件。
+     *
+     * @param isQuery 查询标识
+     * @return 参与查询返回 {@code true}
+     */
     public boolean isQuery(String isQuery) {
         return isQuery != null && StringUtils.equals("1", isQuery);
     }
 
+    /**
+     * 判断当前列是否为基类公共字段。
+     *
+     * @return 基类公共字段返回 {@code true}
+     */
     public boolean isSuperColumn() {
         return isSuperColumn(this.javaField);
     }
 
+    /**
+     * 根据字段名判断是否为基类公共字段。
+     *
+     * @param javaField Java 字段名
+     * @return 基类公共字段返回 {@code true}
+     */
     public static boolean isSuperColumn(String javaField) {
         return StringUtils.equalsAnyIgnoreCase(javaField,
             // BaseEntity
@@ -194,15 +287,31 @@ public class GenTableColumn extends BaseEntity {
             "parentName", "parentId");
     }
 
+    /**
+     * 判断当前列是否属于生成页面需要保留的白名单字段。
+     *
+     * @return 白名单字段返回 {@code true}
+     */
     public boolean isUsableColumn() {
         return isUsableColumn(javaField);
     }
 
+    /**
+     * 根据字段名判断是否属于生成页面需要保留的白名单字段。
+     *
+     * @param javaField Java 字段名
+     * @return 白名单字段返回 {@code true}
+     */
     public static boolean isUsableColumn(String javaField) {
         // isSuperColumn()中的名单用于避免生成多余Domain属性，若某些属性在生成页面时需要用到不能忽略，则放在此处白名单
         return StringUtils.equalsAnyIgnoreCase(javaField, "parentId", "orderNum", "remark");
     }
 
+    /**
+     * 从字段注释中解析字典读转换表达式。
+     *
+     * @return 形如 `0=男,1=女` 的转换表达式，无法解析时返回原始注释
+     */
     public String readConverterExp() {
         String remarks = StringUtils.substringBetween(this.columnComment, "（", "）");
         StringBuffer sb = new StringBuffer();

ruoyi-modules/ruoyi-generator/src/main/java/org/dromara/generator/service/GenTableServiceImpl.java

@@ -89,12 +89,25 @@ public class GenTableServiceImpl implements IGenTableService {
         return genTable;
     }
 
+    /**
+     * 分页查询已导入的代码生成业务表。
+     *
+     * @param genTable  业务表筛选条件
+     * @param pageQuery 分页参数
+     * @return 业务表分页结果
+     */
     @Override
     public TableDataInfo<GenTable> selectPageGenTableList(GenTable genTable, PageQuery pageQuery) {
         Page<GenTable> page = baseMapper.selectPage(pageQuery.build(), this.buildGenTableQueryWrapper(genTable));
         return TableDataInfo.build(page);
     }
 
+    /**
+     * 构造代码生成业务表查询条件。
+     *
+     * @param genTable 业务表筛选条件
+     * @return 包含数据源、表名、表注释和时间区间的查询包装器
+     */
     private QueryWrapper<GenTable> buildGenTableQueryWrapper(GenTable genTable) {
         Map<String, Object> params = genTable.getParams();
         QueryWrapper<GenTable> wrapper = Wrappers.query();
@@ -462,6 +475,9 @@ public class GenTableServiceImpl implements IGenTableService {
 
     /**
      * 查询表信息并生成代码
+     *
+     * @param tableId 业务表主键
+     * @param zip     代码压缩输出流
      */
     private void generatorCode(Long tableId, ZipOutputStream zip) {
         // 查询表信息
@@ -518,6 +534,12 @@ public class GenTableServiceImpl implements IGenTableService {
         }
     }
 
+    /**
+     * 查询业务表并补齐其列信息。
+     *
+     * @param tableId 业务表主键
+     * @return 包含字段集合的业务表实体
+     */
     private GenTable getGenTable(Long tableId) {
         GenTable table = baseMapper.selectById(tableId);
         if (ObjectUtil.isNull(table)) {
@@ -527,6 +549,12 @@ public class GenTableServiceImpl implements IGenTableService {
         return table;
     }
 
+    /**
+     * 批量填充业务表对应的字段列表。
+     *
+     * @param tables 业务表集合
+     * @return 已填充字段信息的业务表集合
+     */
     private List<GenTable> fillTableColumns(List<GenTable> tables) {
         if (CollUtil.isEmpty(tables)) {
             return tables;

ruoyi-modules/ruoyi-generator/src/main/java/org/dromara/generator/service/IGenTableService.java

@@ -26,16 +26,18 @@ public interface IGenTableService {
     /**
      * 查询业务列表
      *
-     * @param genTable 业务信息
-     * @return 业务集合
+     * @param genTable  业务信息
+     * @param pageQuery 分页参数
+     * @return 业务分页集合
      */
     TableDataInfo<GenTable> selectPageGenTableList(GenTable genTable, PageQuery pageQuery);
 
     /**
      * 查询据库列表
      *
-     * @param genTable 业务信息
-     * @return 数据库表集合
+     * @param genTable  业务信息
+     * @param pageQuery 分页参数
+     * @return 数据库表分页集合
      */
     TableDataInfo<GenTable> selectPageDbTableList(GenTable genTable, PageQuery pageQuery);
 

ruoyi-modules/ruoyi-generator/src/main/java/org/dromara/generator/util/GenUtils.java

@@ -21,6 +21,8 @@ public class GenUtils {
 
     /**
      * 初始化表信息
+     *
+     * @param genTable 待初始化的业务表对象
      */
     public static void initTable(GenTable genTable) {
         genTable.setClassName(convertClassName(genTable.getTableName()));
@@ -35,6 +37,9 @@ public class GenUtils {
 
     /**
      * 初始化列属性字段
+     *
+     * @param column 待初始化的列对象
+     * @param table  所属业务表对象
      */
     public static void initColumnField(GenTableColumn column, GenTable table) {
         String dataType = getDbType(column.getColumnType());
@@ -166,6 +171,7 @@ public class GenUtils {
      *
      * @param replacementm 替换值
      * @param searchList   替换列表
+     * @return 去除命中前缀后的字符串
      */
     public static String replaceFirst(String replacementm, String[] searchList) {
         String text = replacementm;
@@ -206,7 +212,7 @@ public class GenUtils {
      * 获取字段长度
      *
      * @param columnType 列类型
-     * @return 截取后的列类型
+     * @return 字段长度，未声明长度时返回 0
      */
     public static Integer getColumnLength(String columnType) {
         if (StringUtils.indexOf(columnType, "(") > 0) {

ruoyi-modules/ruoyi-generator/src/main/java/org/dromara/generator/util/VelocityInitializer.java

@@ -17,6 +17,8 @@ public class VelocityInitializer {
 
     /**
      * 初始化vm方法
+     *
+     * @throws RuntimeException 初始化 Velocity 引擎失败时抛出
      */
     public static void initVelocity() {
         Properties p = new Properties();

ruoyi-modules/ruoyi-generator/src/main/java/org/dromara/generator/util/VelocityUtils.java

@@ -43,7 +43,8 @@ public class VelocityUtils {
     /**
      * 设置模板变量信息
      *
-     * @return 模板列表
+     * @param genTable 代码生成业务表对象
+     * @return 初始化后的 Velocity 上下文
      */
     public static VelocityContext prepareContext(GenTable genTable) {
         String moduleName = genTable.getModuleName();
@@ -78,6 +79,12 @@ public class VelocityUtils {
         return velocityContext;
     }
 
+    /**
+     * 向模板上下文写入菜单相关变量。
+     *
+     * @param context  模板上下文
+     * @param genTable 代码生成业务表对象
+     */
     public static void setMenuVelocityContext(VelocityContext context, GenTable genTable) {
         String options = genTable.getOptions();
         Dict paramsObj = JsonUtils.parseMap(options);
@@ -85,6 +92,12 @@ public class VelocityUtils {
         context.put("parentMenuId", parentMenuId);
     }
 
+    /**
+     * 向树形模板上下文写入树字段相关变量。
+     *
+     * @param context  模板上下文
+     * @param genTable 代码生成业务表对象
+     */
     public static void setTreeVelocityContext(VelocityContext context, GenTable genTable) {
         String options = genTable.getOptions();
         Dict paramsObj = JsonUtils.parseMap(options);
@@ -141,6 +154,10 @@ public class VelocityUtils {
 
     /**
      * 获取文件名
+     *
+     * @param template 模板路径
+     * @param genTable 代码生成业务表对象
+     * @return 模板对应的目标文件相对路径
      */
     public static String getFileName(String template, GenTable genTable) {
         // 文件名称

ruoyi-modules/ruoyi-job/src/main/java/org/dromara/job/snailjob/TestAnnoJobExecutor.java

@@ -17,6 +17,12 @@ import org.springframework.stereotype.Component;
 @JobExecutor(name = "testJobExecutor")
 public class TestAnnoJobExecutor {
 
+    /**
+     * 执行示例注解任务。
+     *
+     * @param jobArgs 任务参数
+     * @return 执行结果
+     */
     public ExecuteResult jobExecute(JobArgs jobArgs) {
         SnailJobLog.LOCAL.info("testJobExecutor. jobArgs:{}", JsonUtil.toJsonString(jobArgs));
         SnailJobLog.REMOTE.info("testJobExecutor. jobArgs:{}", JsonUtil.toJsonString(jobArgs));

ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/controller/monitor/CacheController.java

@@ -26,7 +26,9 @@ public class CacheController {
     private final RedissonConnectionFactory connectionFactory;
 
     /**
-     * 获取缓存监控列表
+     * 获取 Redis 缓存监控信息。
+     *
+     * @return Redis 信息、库大小与命令统计
      */
     @SaCheckPermission("monitor:cache:list")
     @GetMapping()

ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/controller/monitor/SysLoginInfoController.java

@@ -36,7 +36,11 @@ public class SysLoginInfoController extends BaseController {
     private final ISysLoginInfoService loginInfoService;
 
     /**
-     * 获取系统访问记录列表
+     * 分页查询系统访问记录。
+     *
+     * @param loginInfo 查询条件
+     * @param pageQuery 分页参数
+     * @return 登录日志分页结果
      */
     @SaCheckPermission("monitor:logininfo:list")
     @GetMapping("/list")
@@ -45,7 +49,10 @@ public class SysLoginInfoController extends BaseController {
     }
 
     /**
-     * 导出系统访问记录列表
+     * 导出系统访问记录列表。
+     *
+     * @param loginInfo 查询条件
+     * @param response HTTP 响应
      */
     @Log(title = "登录日志", businessType = BusinessType.EXPORT)
     @SaCheckPermission("monitor:logininfo:export")
@@ -57,7 +64,9 @@ public class SysLoginInfoController extends BaseController {
 
     /**
      * 批量删除登录日志
+     *
      * @param infoIds 日志ids
+     * @return 操作结果
      */
     @SaCheckPermission("monitor:logininfo:remove")
     @Log(title = "登录日志", businessType = BusinessType.DELETE)
@@ -67,7 +76,9 @@ public class SysLoginInfoController extends BaseController {
     }
 
     /**
-     * 清理系统访问记录
+     * 清空系统访问记录。
+     *
+     * @return 操作结果
      */
     @SaCheckPermission("monitor:logininfo:remove")
     @Log(title = "登录日志", businessType = BusinessType.CLEAN)
@@ -78,6 +89,12 @@ public class SysLoginInfoController extends BaseController {
         return R.ok();
     }
 
+    /**
+     * 清除指定用户的登录失败锁定状态。
+     *
+     * @param userName 用户名
+     * @return 操作结果
+     */
     @SaCheckPermission("monitor:logininfo:unlock")
     @Log(title = "账户解锁", businessType = BusinessType.OTHER)
     @RepeatSubmit()

ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/controller/monitor/SysOperlogController.java

@@ -33,7 +33,11 @@ public class SysOperlogController extends BaseController {
     private final ISysOperLogService operLogService;
 
     /**
-     * 获取操作日志记录列表
+     * 分页查询操作日志记录。
+     *
+     * @param operLog 查询条件
+     * @param pageQuery 分页参数
+     * @return 操作日志分页结果
      */
     @SaCheckPermission("monitor:operlog:list")
     @GetMapping("/list")
@@ -42,7 +46,10 @@ public class SysOperlogController extends BaseController {
     }
 
     /**
-     * 导出操作日志记录列表
+     * 导出操作日志记录列表。
+     *
+     * @param operLog 查询条件
+     * @param response HTTP 响应
      */
     @Log(title = "操作日志", businessType = BusinessType.EXPORT)
     @SaCheckPermission("monitor:operlog:export")
@@ -54,7 +61,9 @@ public class SysOperlogController extends BaseController {
 
     /**
      * 批量删除操作日志记录
+     *
      * @param operIds 日志ids
+     * @return 操作结果
      */
     @Log(title = "操作日志", businessType = BusinessType.DELETE)
     @SaCheckPermission("monitor:operlog:remove")
@@ -64,7 +73,9 @@ public class SysOperlogController extends BaseController {
     }
 
     /**
-     * 清理操作日志记录
+     * 清空操作日志记录。
+     *
+     * @return 操作结果
      */
     @Log(title = "操作日志", businessType = BusinessType.CLEAN)
     @SaCheckPermission("monitor:operlog:remove")

ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/controller/monitor/SysUserOnlineController.java

@@ -36,10 +36,11 @@ import java.util.stream.Collectors;
 public class SysUserOnlineController extends BaseController {
 
     /**
-     * 获取在线用户监控列表
+     * 获取在线用户监控列表，并按 IP 或用户名条件过滤当前有效会话。
      *
      * @param ipaddr   IP地址
      * @param userName 用户名
+     * @return 在线用户分页数据
      */
     @SaCheckPermission("monitor:online:list")
     @GetMapping("/list")
@@ -76,9 +77,10 @@ public class SysUserOnlineController extends BaseController {
     }
 
     /**
-     * 强退用户
+     * 按 token 强制用户下线，适用于管理员踢除异常会话。
      *
      * @param tokenId token值
+     * @return 操作结果
      */
     @SaCheckPermission("monitor:online:forceLogout")
     @Log(title = "在线用户", businessType = BusinessType.FORCE)
@@ -93,7 +95,9 @@ public class SysUserOnlineController extends BaseController {
     }
 
     /**
-     * 获取当前用户登录在线设备
+     * 获取当前登录用户的在线设备列表，仅返回当前账号仍有效的 token 会话。
+     *
+     * @return 当前用户在线设备列表
      */
     @GetMapping()
     public TableDataInfo<SysUserOnline> getInfo() {
@@ -111,9 +115,10 @@ public class SysUserOnlineController extends BaseController {
     }
 
     /**
-     * 强退当前在线设备
+     * 强退当前账号下指定在线设备，避免误踢其他账号的会话。
      *
      * @param tokenId token值
+     * @return 操作结果
      */
     @Log(title = "在线设备", businessType = BusinessType.FORCE)
     @RepeatSubmit()

ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/controller/system/SysClientController.java

@@ -38,7 +38,11 @@ public class SysClientController extends BaseController {
     private final ISysClientService sysClientService;
 
     /**
-     * 查询客户端管理列表
+     * 分页查询客户端管理列表。
+     *
+     * @param bo 查询条件
+     * @param pageQuery 分页参数
+     * @return 客户端分页数据
      */
     @SaCheckPermission("system:client:list")
     @GetMapping("/list")
@@ -47,7 +51,10 @@ public class SysClientController extends BaseController {
     }
 
     /**
-     * 导出客户端管理列表
+     * 导出客户端管理列表，便于离线审计与配置核查。
+     *
+     * @param bo 查询条件
+     * @param response 响应流
      */
     @SaCheckPermission("system:client:export")
     @Log(title = "客户端管理", businessType = BusinessType.EXPORT)
@@ -58,9 +65,10 @@ public class SysClientController extends BaseController {
     }
 
     /**
-     * 获取客户端管理详细信息
+     * 获取单个客户端的详细配置信息。
      *
      * @param id 主键
+     * @return 客户端详情
      */
     @SaCheckPermission("system:client:query")
     @GetMapping("/{id}")
@@ -70,7 +78,10 @@ public class SysClientController extends BaseController {
     }
 
     /**
-     * 新增客户端管理
+     * 新增客户端配置，入库前先校验客户端 key 是否唯一。
+     *
+     * @param bo 客户端信息
+     * @return 操作结果
      */
     @SaCheckPermission("system:client:add")
     @Log(title = "客户端管理", businessType = BusinessType.INSERT)
@@ -84,7 +95,10 @@ public class SysClientController extends BaseController {
     }
 
     /**
-     * 修改客户端管理
+     * 修改客户端配置，避免重复占用同一个客户端 key。
+     *
+     * @param bo 客户端信息
+     * @return 操作结果
      */
     @SaCheckPermission("system:client:edit")
     @Log(title = "客户端管理", businessType = BusinessType.UPDATE)
@@ -98,7 +112,10 @@ public class SysClientController extends BaseController {
     }
 
     /**
-     * 状态修改
+     * 修改客户端启停状态。
+     *
+     * @param bo 客户端状态信息
+     * @return 操作结果
      */
     @SaCheckPermission("system:client:edit")
     @Log(title = "客户端管理", businessType = BusinessType.UPDATE)
@@ -108,9 +125,10 @@ public class SysClientController extends BaseController {
     }
 
     /**
-     * 删除客户端管理
+     * 批量删除客户端配置。
      *
      * @param ids 主键串
+     * @return 操作结果
      */
     @SaCheckPermission("system:client:remove")
     @Log(title = "客户端管理", businessType = BusinessType.DELETE)

ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/controller/system/SysConfigController.java

@@ -34,7 +34,11 @@ public class SysConfigController extends BaseController {
     private final ISysConfigService configService;
 
     /**
-     * 获取参数配置列表
+     * 分页查询参数配置列表。
+     *
+     * @param config 查询条件
+     * @param pageQuery 分页参数
+     * @return 参数配置分页结果
      */
     @SaCheckPermission("system:config:list")
     @GetMapping("/list")
@@ -43,7 +47,10 @@ public class SysConfigController extends BaseController {
     }
 
     /**
-     * 导出参数配置列表
+     * 导出参数配置列表。
+     *
+     * @param config 查询条件
+     * @param response HTTP 响应
      */
     @Log(title = "参数管理", businessType = BusinessType.EXPORT)
     @SaCheckPermission("system:config:export")
@@ -57,6 +64,7 @@ public class SysConfigController extends BaseController {
      * 根据参数编号获取详细信息
      *
      * @param configId 参数ID
+     * @return 参数配置详情
      */
     @SaCheckPermission("system:config:query")
     @GetMapping(value = "/{configId}")
@@ -68,6 +76,7 @@ public class SysConfigController extends BaseController {
      * 根据参数键名查询参数值
      *
      * @param configKey 参数Key
+     * @return 参数值
      */
     @GetMapping(value = "/configKey/{configKey}")
     public R<String> getConfigKey(@PathVariable String configKey) {
@@ -75,7 +84,10 @@ public class SysConfigController extends BaseController {
     }
 
     /**
-     * 新增参数配置
+     * 新增参数配置。
+     *
+     * @param config 参数配置
+     * @return 操作结果
      */
     @SaCheckPermission("system:config:add")
     @Log(title = "参数管理", businessType = BusinessType.INSERT)
@@ -90,7 +102,10 @@ public class SysConfigController extends BaseController {
     }
 
     /**
-     * 修改参数配置
+     * 修改参数配置。
+     *
+     * @param config 参数配置
+     * @return 操作结果
      */
     @SaCheckPermission("system:config:edit")
     @Log(title = "参数管理", businessType = BusinessType.UPDATE)
@@ -105,7 +120,10 @@ public class SysConfigController extends BaseController {
     }
 
     /**
-     * 根据参数键名修改参数配置
+     * 根据参数键名修改参数配置。
+     *
+     * @param config 参数配置
+     * @return 操作结果
      */
     @SaCheckPermission("system:config:edit")
     @Log(title = "参数管理", businessType = BusinessType.UPDATE)
@@ -120,6 +138,7 @@ public class SysConfigController extends BaseController {
      * 删除参数配置
      *
      * @param configIds 参数ID串
+     * @return 操作结果
      */
     @SaCheckPermission("system:config:remove")
     @Log(title = "参数管理", businessType = BusinessType.DELETE)
@@ -130,7 +149,9 @@ public class SysConfigController extends BaseController {
     }
 
     /**
-     * 刷新参数缓存
+     * 刷新参数缓存。
+     *
+     * @return 操作结果
      */
     @SaCheckPermission("system:config:remove")
     @Log(title = "参数管理", businessType = BusinessType.CLEAN)

ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/controller/system/SysDeptController.java

@@ -34,7 +34,10 @@ public class SysDeptController extends BaseController {
     private final ISysPostService postService;
 
     /**
-     * 获取部门列表
+     * 查询部门列表。
+     *
+     * @param dept 查询条件
+     * @return 部门列表
      */
     @SaCheckPermission("system:dept:list")
     @GetMapping("/list")
@@ -47,6 +50,7 @@ public class SysDeptController extends BaseController {
      * 查询部门列表（排除节点）
      *
      * @param deptId 部门ID
+     * @return 过滤后的部门列表
      */
     @SaCheckPermission("system:dept:list")
     @GetMapping("/list/exclude/{deptId}")
@@ -61,6 +65,7 @@ public class SysDeptController extends BaseController {
      * 根据部门编号获取详细信息
      *
      * @param deptId 部门ID
+     * @return 部门详情
      */
     @SaCheckPermission("system:dept:query")
     @GetMapping(value = "/{deptId}")
@@ -70,7 +75,10 @@ public class SysDeptController extends BaseController {
     }
 
     /**
-     * 新增部门
+     * 新增部门。
+     *
+     * @param dept 部门参数
+     * @return 操作结果
      */
     @SaCheckPermission("system:dept:add")
     @Log(title = "部门管理", businessType = BusinessType.INSERT)
@@ -84,7 +92,10 @@ public class SysDeptController extends BaseController {
     }
 
     /**
-     * 修改部门
+     * 修改部门。
+     *
+     * @param dept 部门参数
+     * @return 操作结果
      */
     @SaCheckPermission("system:dept:edit")
     @Log(title = "部门管理", businessType = BusinessType.UPDATE)
@@ -111,6 +122,7 @@ public class SysDeptController extends BaseController {
      * 删除部门
      *
      * @param deptId 部门ID
+     * @return 操作结果
      */
     @SaCheckPermission("system:dept:remove")
     @Log(title = "部门管理", businessType = BusinessType.DELETE)
@@ -136,6 +148,7 @@ public class SysDeptController extends BaseController {
      * 获取部门选择框列表
      *
      * @param deptIds 部门ID串
+     * @return 部门列表
      */
     @SaCheckPermission("system:dept:query")
     @GetMapping("/optionselect")

ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/controller/system/SysDictDataController.java

@@ -38,7 +38,11 @@ public class SysDictDataController extends BaseController {
     private final ISysDictTypeService dictTypeService;
 
     /**
-     * 查询字典数据列表
+     * 分页查询字典数据列表。
+     *
+     * @param dictData 查询条件
+     * @param pageQuery 分页参数
+     * @return 字典数据分页结果
      */
     @SaCheckPermission("system:dict:list")
     @GetMapping("/list")
@@ -47,7 +51,10 @@ public class SysDictDataController extends BaseController {
     }
 
     /**
-     * 导出字典数据列表
+     * 导出字典数据列表。
+     *
+     * @param dictData 查询条件
+     * @param response HTTP 响应
      */
     @Log(title = "字典数据", businessType = BusinessType.EXPORT)
     @SaCheckPermission("system:dict:export")
@@ -61,6 +68,7 @@ public class SysDictDataController extends BaseController {
      * 查询字典数据详细
      *
      * @param dictCode 字典code
+     * @return 字典数据详情
      */
     @SaCheckPermission("system:dict:query")
     @GetMapping(value = "/{dictCode}")
@@ -72,6 +80,7 @@ public class SysDictDataController extends BaseController {
      * 根据字典类型查询字典数据信息
      *
      * @param dictType 字典类型
+     * @return 字典数据列表
      */
     @GetMapping(value = "/type/{dictType}")
     public R<List<SysDictDataVo>> dictType(@PathVariable String dictType) {
@@ -83,7 +92,10 @@ public class SysDictDataController extends BaseController {
     }
 
     /**
-     * 新增字典数据
+     * 新增字典数据。
+     *
+     * @param dict 字典数据参数
+     * @return 操作结果
      */
     @SaCheckPermission("system:dict:add")
     @Log(title = "字典数据", businessType = BusinessType.INSERT)
@@ -98,7 +110,10 @@ public class SysDictDataController extends BaseController {
     }
 
     /**
-     * 修改保存字典数据
+     * 修改字典数据。
+     *
+     * @param dict 字典数据参数
+     * @return 操作结果
      */
     @SaCheckPermission("system:dict:edit")
     @Log(title = "字典数据", businessType = BusinessType.UPDATE)
@@ -116,6 +131,7 @@ public class SysDictDataController extends BaseController {
      * 删除字典数据
      *
      * @param dictCodes 字典code串
+     * @return 操作结果
      */
     @SaCheckPermission("system:dict:remove")
     @Log(title = "字典数据", businessType = BusinessType.DELETE)

ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/controller/system/SysDictTypeController.java

@@ -35,7 +35,11 @@ public class SysDictTypeController extends BaseController {
     private final ISysDictTypeService dictTypeService;
 
     /**
-     * 查询字典类型列表
+     * 分页查询字典类型列表。
+     *
+     * @param dictType 查询条件
+     * @param pageQuery 分页参数
+     * @return 字典类型分页结果
      */
     @SaCheckPermission("system:dict:list")
     @GetMapping("/list")
@@ -44,7 +48,10 @@ public class SysDictTypeController extends BaseController {
     }
 
     /**
-     * 导出字典类型列表
+     * 导出字典类型列表。
+     *
+     * @param dictType 查询条件
+     * @param response HTTP 响应
      */
     @Log(title = "字典类型", businessType = BusinessType.EXPORT)
     @SaCheckPermission("system:dict:export")
@@ -58,6 +65,7 @@ public class SysDictTypeController extends BaseController {
      * 查询字典类型详细
      *
      * @param dictId 字典ID
+     * @return 字典类型详情
      */
     @SaCheckPermission("system:dict:query")
     @GetMapping(value = "/{dictId}")
@@ -66,7 +74,10 @@ public class SysDictTypeController extends BaseController {
     }
 
     /**
-     * 新增字典类型
+     * 新增字典类型。
+     *
+     * @param dict 字典类型参数
+     * @return 操作结果
      */
     @SaCheckPermission("system:dict:add")
     @Log(title = "字典类型", businessType = BusinessType.INSERT)
@@ -81,7 +92,10 @@ public class SysDictTypeController extends BaseController {
     }
 
     /**
-     * 修改字典类型
+     * 修改字典类型。
+     *
+     * @param dict 字典类型参数
+     * @return 操作结果
      */
     @SaCheckPermission("system:dict:edit")
     @Log(title = "字典类型", businessType = BusinessType.UPDATE)
@@ -99,6 +113,7 @@ public class SysDictTypeController extends BaseController {
      * 删除字典类型
      *
      * @param dictIds 字典ID串
+     * @return 操作结果
      */
     @SaCheckPermission("system:dict:remove")
     @Log(title = "字典类型", businessType = BusinessType.DELETE)
@@ -109,7 +124,9 @@ public class SysDictTypeController extends BaseController {
     }
 
     /**
-     * 刷新字典缓存
+     * 刷新字典缓存。
+     *
+     * @return 操作结果
      */
     @SaCheckPermission("system:dict:remove")
     @Log(title = "字典类型", businessType = BusinessType.CLEAN)
@@ -121,7 +138,9 @@ public class SysDictTypeController extends BaseController {
     }
 
     /**
-     * 获取字典选择框列表
+     * 获取字典类型下拉选择列表。
+     *
+     * @return 字典类型列表
      */
     @GetMapping("/optionselect")
     public R<List<SysDictTypeVo>> optionselect() {

ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/controller/system/SysMenuController.java

@@ -39,7 +39,7 @@ public class SysMenuController extends BaseController {
     /**
      * 获取路由信息
      *
-     * @return 路由信息
+     * @return 当前用户可访问的路由信息
      */
     @GetMapping("/getRouters")
     public R<List<RouterVo>> getRouters() {
@@ -48,7 +48,10 @@ public class SysMenuController extends BaseController {
     }
 
     /**
-     * 获取菜单列表
+     * 查询菜单列表。
+     *
+     * @param menu 查询条件
+     * @return 菜单列表
      */
     @SaCheckRole(value = {
         SystemConstants.SUPER_ADMIN_ROLE_KEY,
@@ -64,6 +67,7 @@ public class SysMenuController extends BaseController {
      * 根据菜单编号获取详细信息
      *
      * @param menuId 菜单ID
+     * @return 菜单详情
      */
     @SaCheckRole(value = {
         SystemConstants.SUPER_ADMIN_ROLE_KEY,
@@ -75,7 +79,10 @@ public class SysMenuController extends BaseController {
     }
 
     /**
-     * 获取菜单下拉树列表
+     * 获取菜单下拉树列表。
+     *
+     * @param menu 查询条件
+     * @return 菜单树
      */
     @SaCheckPermission("system:menu:query")
     @GetMapping("/treeselect")
@@ -88,6 +95,7 @@ public class SysMenuController extends BaseController {
      * 加载对应角色菜单列表树
      *
      * @param roleId 角色ID
+     * @return 角色菜单树及选中节点
      */
     @SaCheckPermission("system:menu:query")
     @GetMapping(value = "/roleMenuTreeselect/{roleId}")
@@ -100,7 +108,10 @@ public class SysMenuController extends BaseController {
     }
 
     /**
-     * 新增菜单
+     * 新增菜单。
+     *
+     * @param menu 菜单参数
+     * @return 操作结果
      */
     @SaCheckRole(SystemConstants.SUPER_ADMIN_ROLE_KEY)
     @SaCheckPermission("system:menu:add")
@@ -119,7 +130,10 @@ public class SysMenuController extends BaseController {
     }
 
     /**
-     * 修改菜单
+     * 修改菜单。
+     *
+     * @param menu 菜单参数
+     * @return 操作结果
      */
     @SaCheckRole(SystemConstants.SUPER_ADMIN_ROLE_KEY)
     @SaCheckPermission("system:menu:edit")
@@ -143,6 +157,7 @@ public class SysMenuController extends BaseController {
      * 删除菜单
      *
      * @param menuId 菜单ID
+     * @return 操作结果
      */
     @SaCheckRole(SystemConstants.SUPER_ADMIN_ROLE_KEY)
     @SaCheckPermission("system:menu:remove")
@@ -171,6 +186,7 @@ public class SysMenuController extends BaseController {
      * 批量级联删除菜单
      *
      * @param menuIds 菜单ID串
+     * @return 操作结果
      */
     @SaCheckRole(SystemConstants.SUPER_ADMIN_ROLE_KEY)
     @SaCheckPermission("system:menu:remove")

ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/controller/system/SysNoticeController.java

@@ -32,7 +32,11 @@ public class SysNoticeController extends BaseController {
     private final DictService dictService;
 
     /**
-     * 获取通知公告列表
+     * 分页查询通知公告列表。
+     *
+     * @param notice 查询条件
+     * @param pageQuery 分页参数
+     * @return 公告分页结果
      */
     @SaCheckPermission("system:notice:list")
     @GetMapping("/list")
@@ -44,6 +48,7 @@ public class SysNoticeController extends BaseController {
      * 根据通知公告编号获取详细信息
      *
      * @param noticeId 公告ID
+     * @return 公告详情
      */
     @SaCheckPermission("system:notice:query")
     @GetMapping(value = "/{noticeId}")
@@ -52,7 +57,10 @@ public class SysNoticeController extends BaseController {
     }
 
     /**
-     * 新增通知公告
+     * 新增通知公告，并向在线用户广播公告摘要。
+     *
+     * @param notice 公告参数
+     * @return 操作结果
      */
     @SaCheckPermission("system:notice:add")
     @Log(title = "通知公告", businessType = BusinessType.INSERT)
@@ -69,7 +77,10 @@ public class SysNoticeController extends BaseController {
     }
 
     /**
-     * 修改通知公告
+     * 修改通知公告。
+     *
+     * @param notice 公告参数
+     * @return 操作结果
      */
     @SaCheckPermission("system:notice:edit")
     @Log(title = "通知公告", businessType = BusinessType.UPDATE)
@@ -83,6 +94,7 @@ public class SysNoticeController extends BaseController {
      * 删除通知公告
      *
      * @param noticeIds 公告ID串
+     * @return 操作结果
      */
     @SaCheckPermission("system:notice:remove")
     @Log(title = "通知公告", businessType = BusinessType.DELETE)

ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/controller/system/SysOssConfigController.java

@@ -38,7 +38,11 @@ public class SysOssConfigController extends BaseController {
     private final ISysOssConfigService ossConfigService;
 
     /**
-     * 查询对象存储配置列表
+     * 分页查询对象存储配置列表。
+     *
+     * @param bo 查询条件
+     * @param pageQuery 分页参数
+     * @return 配置分页数据
      */
     @SaCheckPermission("system:ossConfig:list")
     @GetMapping("/list")
@@ -47,9 +51,10 @@ public class SysOssConfigController extends BaseController {
     }
 
     /**
-     * 获取对象存储配置详细信息
+     * 获取单个对象存储配置详情。
      *
      * @param ossConfigId OSS配置ID
+     * @return 配置详情
      */
     @SaCheckPermission("system:ossConfig:list")
     @GetMapping("/{ossConfigId}")
@@ -59,7 +64,10 @@ public class SysOssConfigController extends BaseController {
     }
 
     /**
-     * 新增对象存储配置
+     * 新增对象存储配置。
+     *
+     * @param bo 配置信息
+     * @return 操作结果
      */
     @SaCheckPermission("system:ossConfig:add")
     @Log(title = "对象存储配置", businessType = BusinessType.INSERT)
@@ -70,7 +78,10 @@ public class SysOssConfigController extends BaseController {
     }
 
     /**
-     * 修改对象存储配置
+     * 修改对象存储配置。
+     *
+     * @param bo 配置信息
+     * @return 操作结果
      */
     @SaCheckPermission("system:ossConfig:edit")
     @Log(title = "对象存储配置", businessType = BusinessType.UPDATE)
@@ -81,9 +92,10 @@ public class SysOssConfigController extends BaseController {
     }
 
     /**
-     * 删除对象存储配置
+     * 批量删除对象存储配置。
      *
      * @param ossConfigIds OSS配置ID串
+     * @return 操作结果
      */
     @SaCheckPermission("system:ossConfig:remove")
     @Log(title = "对象存储配置", businessType = BusinessType.DELETE)
@@ -94,7 +106,10 @@ public class SysOssConfigController extends BaseController {
     }
 
     /**
-     * 状态修改
+     * 切换对象存储配置启用状态，并同步更新当前生效配置。
+     *
+     * @param bo 状态变更信息
+     * @return 操作结果
      */
     @SaCheckPermission("system:ossConfig:edit")
     @Log(title = "对象存储状态修改", businessType = BusinessType.UPDATE)

ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/controller/system/SysOssController.java

@@ -39,7 +39,11 @@ public class SysOssController extends BaseController {
     private final ISysOssService ossService;
 
     /**
-     * 查询OSS对象存储列表
+     * 分页查询 OSS 对象存储列表。
+     *
+     * @param bo 查询条件
+     * @param pageQuery 分页参数
+     * @return OSS 分页结果
      */
     @SaCheckPermission("system:oss:list")
     @GetMapping("/list")
@@ -51,6 +55,7 @@ public class SysOssController extends BaseController {
      * 查询OSS对象基于id串
      *
      * @param ossIds OSS对象ID串
+     * @return OSS 对象列表
      */
     @SaCheckPermission("system:oss:query")
     @GetMapping("/listByIds/{ossIds}")
@@ -64,6 +69,7 @@ public class SysOssController extends BaseController {
      * 上传OSS对象存储
      *
      * @param file 文件
+     * @return 上传结果
      */
     @SaCheckPermission("system:oss:upload")
     @Log(title = "OSS对象存储", businessType = BusinessType.INSERT)
@@ -81,6 +87,8 @@ public class SysOssController extends BaseController {
      * 下载OSS对象
      *
      * @param ossId OSS对象ID
+     * @param response HTTP 响应
+     * @throws IOException IO 异常
      */
     @SaCheckPermission("system:oss:download")
     @GetMapping("/download/{ossId}")
@@ -92,6 +100,7 @@ public class SysOssController extends BaseController {
      * 删除OSS对象存储
      *
      * @param ossIds OSS对象ID串
+     * @return 操作结果
      */
     @SaCheckPermission("system:oss:remove")
     @Log(title = "OSS对象存储", businessType = BusinessType.DELETE)

ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/controller/system/SysPostController.java

@@ -41,7 +41,11 @@ public class SysPostController extends BaseController {
     private final ISysDeptService deptService;
 
     /**
-     * 获取岗位列表
+     * 分页查询岗位列表。
+     *
+     * @param post 查询条件
+     * @param pageQuery 分页参数
+     * @return 岗位分页结果
      */
     @SaCheckPermission("system:post:list")
     @GetMapping("/list")
@@ -50,7 +54,10 @@ public class SysPostController extends BaseController {
     }
 
     /**
-     * 导出岗位列表
+     * 导出岗位列表。
+     *
+     * @param post 查询条件
+     * @param response HTTP 响应
      */
     @Log(title = "岗位管理", businessType = BusinessType.EXPORT)
     @SaCheckPermission("system:post:export")
@@ -64,6 +71,7 @@ public class SysPostController extends BaseController {
      * 根据岗位编号获取详细信息
      *
      * @param postId 岗位ID
+     * @return 岗位详情
      */
     @SaCheckPermission("system:post:query")
     @GetMapping(value = "/{postId}")
@@ -72,7 +80,10 @@ public class SysPostController extends BaseController {
     }
 
     /**
-     * 新增岗位
+     * 新增岗位。
+     *
+     * @param post 岗位参数
+     * @return 操作结果
      */
     @SaCheckPermission("system:post:add")
     @Log(title = "岗位管理", businessType = BusinessType.INSERT)
@@ -88,7 +99,10 @@ public class SysPostController extends BaseController {
     }
 
     /**
-     * 修改岗位
+     * 修改岗位。
+     *
+     * @param post 岗位参数
+     * @return 操作结果
      */
     @SaCheckPermission("system:post:edit")
     @Log(title = "岗位管理", businessType = BusinessType.UPDATE)
@@ -110,6 +124,7 @@ public class SysPostController extends BaseController {
      * 删除岗位
      *
      * @param postIds 岗位ID串
+     * @return 操作结果
      */
     @SaCheckPermission("system:post:remove")
     @Log(title = "岗位管理", businessType = BusinessType.DELETE)
@@ -123,6 +138,7 @@ public class SysPostController extends BaseController {
      *
      * @param postIds 岗位ID串
      * @param deptId  部门id
+     * @return 岗位列表
      */
     @SaCheckPermission("system:post:query")
     @GetMapping("/optionselect")
@@ -139,7 +155,10 @@ public class SysPostController extends BaseController {
     }
 
     /**
-     * 获取部门树列表
+     * 获取岗位筛选用的部门树。
+     *
+     * @param dept 部门查询条件
+     * @return 部门树列表
      */
     @SaCheckPermission("system:post:list")
     @GetMapping("/deptTree")

ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/controller/system/SysProfileController.java

@@ -45,7 +45,9 @@ public class SysProfileController extends BaseController {
     private final ISysOssService ossService;
 
     /**
-     * 个人信息
+     * 获取当前登录用户的个人中心信息。
+     *
+     * @return 用户信息、角色组和岗位组
      */
     @GetMapping
     public R<ProfileVo> profile() {
@@ -59,7 +61,10 @@ public class SysProfileController extends BaseController {
     }
 
     /**
-     * 修改用户信息
+     * 修改当前登录用户的个人资料。
+     *
+     * @param profile 个人资料参数
+     * @return 操作结果
      */
     @RepeatSubmit
     @Log(title = "个人信息", businessType = BusinessType.UPDATE)
@@ -85,6 +90,7 @@ public class SysProfileController extends BaseController {
      * 重置密码
      *
      * @param bo 新旧密码
+     * @return 操作结果
      */
     @RepeatSubmit
     @ApiEncrypt
@@ -110,6 +116,7 @@ public class SysProfileController extends BaseController {
      * 头像上传
      *
      * @param avatarfile 用户头像
+     * @return 头像上传结果
      */
     @RepeatSubmit
     @Log(title = "用户头像", businessType = BusinessType.UPDATE)

ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/controller/system/SysRoleController.java

@@ -42,7 +42,11 @@ public class SysRoleController extends BaseController {
     private final ISysDeptService deptService;
 
     /**
-     * 获取角色信息列表
+     * 分页查询角色列表。
+     *
+     * @param role 查询条件
+     * @param pageQuery 分页参数
+     * @return 角色分页结果
      */
     @SaCheckPermission("system:role:list")
     @GetMapping("/list")
@@ -51,7 +55,10 @@ public class SysRoleController extends BaseController {
     }
 
     /**
-     * 导出角色信息列表
+     * 导出角色信息列表。
+     *
+     * @param role 查询条件
+     * @param response HTTP 响应
      */
     @Log(title = "角色管理", businessType = BusinessType.EXPORT)
     @SaCheckPermission("system:role:export")
@@ -65,6 +72,7 @@ public class SysRoleController extends BaseController {
      * 根据角色编号获取详细信息
      *
      * @param roleId 角色ID
+     * @return 角色详情
      */
     @SaCheckPermission("system:role:query")
     @GetMapping(value = "/{roleId}")
@@ -74,7 +82,10 @@ public class SysRoleController extends BaseController {
     }
 
     /**
-     * 新增角色
+     * 新增角色。
+     *
+     * @param role 角色参数
+     * @return 操作结果
      */
     @SaCheckPermission("system:role:add")
     @Log(title = "角色管理", businessType = BusinessType.INSERT)
@@ -92,7 +103,10 @@ public class SysRoleController extends BaseController {
     }
 
     /**
-     * 修改保存角色
+     * 修改角色。
+     *
+     * @param role 角色参数
+     * @return 操作结果
      */
     @SaCheckPermission("system:role:edit")
     @Log(title = "角色管理", businessType = BusinessType.UPDATE)
@@ -115,7 +129,10 @@ public class SysRoleController extends BaseController {
     }
 
     /**
-     * 修改保存数据权限
+     * 修改角色数据权限。
+     *
+     * @param role 角色参数
+     * @return 操作结果
      */
     @SaCheckPermission("system:role:edit")
     @Log(title = "角色管理", businessType = BusinessType.UPDATE)
@@ -132,7 +149,10 @@ public class SysRoleController extends BaseController {
     }
 
     /**
-     * 状态修改
+     * 修改角色状态。
+     *
+     * @param role 角色参数
+     * @return 操作结果
      */
     @SaCheckPermission("system:role:edit")
     @Log(title = "角色管理", businessType = BusinessType.UPDATE)
@@ -152,6 +172,7 @@ public class SysRoleController extends BaseController {
      * 删除角色
      *
      * @param roleIds 角色ID串
+     * @return 操作结果
      */
     @SaCheckPermission("system:role:remove")
     @Log(title = "角色管理", businessType = BusinessType.DELETE)
@@ -164,6 +185,7 @@ public class SysRoleController extends BaseController {
      * 获取角色选择框列表
      *
      * @param roleIds 角色ID串
+     * @return 角色列表
      */
     @SaCheckPermission("system:role:query")
     @GetMapping("/optionselect")
@@ -172,7 +194,11 @@ public class SysRoleController extends BaseController {
     }
 
     /**
-     * 查询已分配用户角色列表
+     * 查询已分配用户角色列表。
+     *
+     * @param user 查询条件
+     * @param pageQuery 分页参数
+     * @return 用户分页结果
      */
     @SaCheckPermission("system:role:list")
     @GetMapping("/authUser/allocatedList")
@@ -181,7 +207,11 @@ public class SysRoleController extends BaseController {
     }
 
     /**
-     * 查询未分配用户角色列表
+     * 查询未分配用户角色列表。
+     *
+     * @param user 查询条件
+     * @param pageQuery 分页参数
+     * @return 用户分页结果
      */
     @SaCheckPermission("system:role:list")
     @GetMapping("/authUser/unallocatedList")
@@ -190,7 +220,10 @@ public class SysRoleController extends BaseController {
     }
 
     /**
-     * 取消授权用户
+     * 取消授权用户。
+     *
+     * @param userRole 用户角色关系
+     * @return 操作结果
      */
     @SaCheckPermission("system:role:edit")
     @Log(title = "角色管理", businessType = BusinessType.GRANT)
@@ -205,6 +238,7 @@ public class SysRoleController extends BaseController {
      *
      * @param roleId  角色ID
      * @param userIds 用户ID串
+     * @return 操作结果
      */
     @SaCheckPermission("system:role:edit")
     @Log(title = "角色管理", businessType = BusinessType.GRANT)
@@ -219,6 +253,7 @@ public class SysRoleController extends BaseController {
      *
      * @param roleId  角色ID
      * @param userIds 用户ID串
+     * @return 操作结果
      */
     @SaCheckPermission("system:role:edit")
     @Log(title = "角色管理", businessType = BusinessType.GRANT)
@@ -233,6 +268,7 @@ public class SysRoleController extends BaseController {
      * 获取对应角色部门树列表
      *
      * @param roleId 角色ID
+     * @return 角色部门树信息
      */
     @SaCheckPermission("system:role:list")
     @GetMapping(value = "/deptTree/{roleId}")

ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/controller/system/SysSocialController.java

@@ -28,7 +28,9 @@ public class SysSocialController extends BaseController {
     private final ISysSocialService socialUserService;
 
     /**
-     * 查询社会化关系列表
+     * 查询当前登录用户的社会化账号绑定列表。
+     *
+     * @return 绑定关系列表
      */
     @GetMapping("/list")
     public R<List<SysSocialVo>> list() {

ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/controller/system/SysUserController.java

@@ -59,7 +59,11 @@ public class SysUserController extends BaseController {
     private final ISysDeptService deptService;
 
     /**
-     * 获取用户列表
+     * 分页查询用户列表。
+     *
+     * @param user 用户查询条件
+     * @param pageQuery 分页参数
+     * @return 用户分页列表
      */
     @SaCheckPermission("system:user:list")
     @GetMapping("/list")
@@ -68,7 +72,10 @@ public class SysUserController extends BaseController {
     }
 
     /**
-     * 导出用户列表
+     * 导出符合条件的用户列表。
+     *
+     * @param user 用户查询条件
+     * @param response HTTP 响应
      */
     @Log(title = "用户管理", businessType = BusinessType.EXPORT)
     @SaCheckPermission("system:user:export")
@@ -93,7 +100,9 @@ public class SysUserController extends BaseController {
     }
 
     /**
-     * 获取导入模板
+     * 导出用户导入模板。
+     *
+     * @param response HTTP 响应
      */
     @PostMapping("/importTemplate")
     public void importTemplate(HttpServletResponse response) {
@@ -103,7 +112,7 @@ public class SysUserController extends BaseController {
     /**
      * 获取用户信息
      *
-     * @return 用户信息
+     * @return 当前登录用户信息、角色与权限集合
      */
     @GetMapping("/getInfo")
     public R<UserInfoVo> getInfo() {
@@ -124,6 +133,7 @@ public class SysUserController extends BaseController {
      * 根据用户编号获取详细信息
      *
      * @param userId 用户ID
+     * @return 用户详情、角色与岗位信息
      */
     @SaCheckPermission("system:user:query")
     @GetMapping(value = {"/", "/{userId}"})
@@ -150,7 +160,10 @@ public class SysUserController extends BaseController {
     }
 
     /**
-     * 新增用户
+     * 新增用户。
+     *
+     * @param user 用户新增参数
+     * @return 操作结果
      */
     @SaCheckPermission("system:user:add")
     @Log(title = "用户管理", businessType = BusinessType.INSERT)
@@ -170,7 +183,10 @@ public class SysUserController extends BaseController {
     }
 
     /**
-     * 修改用户
+     * 修改用户。
+     *
+     * @param user 用户编辑参数
+     * @return 操作结果
      */
     @SaCheckPermission("system:user:edit")
     @Log(title = "用户管理", businessType = BusinessType.UPDATE)
@@ -193,7 +209,8 @@ public class SysUserController extends BaseController {
     /**
      * 删除用户
      *
-     * @param userIds 角色ID串
+     * @param userIds 用户ID数组
+     * @return 操作结果
      */
     @SaCheckPermission("system:user:remove")
     @Log(title = "用户管理", businessType = BusinessType.DELETE)
@@ -210,6 +227,7 @@ public class SysUserController extends BaseController {
      *
      * @param userIds 用户ID串
      * @param deptId  部门ID
+     * @return 用户基础信息列表
      */
     @SaCheckPermission("system:user:query")
     @GetMapping("/optionselect")
@@ -219,7 +237,10 @@ public class SysUserController extends BaseController {
     }
 
     /**
-     * 重置密码
+     * 重置指定用户密码。
+     *
+     * @param user 用户参数
+     * @return 操作结果
      */
     @ApiEncrypt
     @SaCheckPermission("system:user:resetPwd")
@@ -234,7 +255,10 @@ public class SysUserController extends BaseController {
     }
 
     /**
-     * 状态修改
+     * 修改用户状态。
+     *
+     * @param user 用户参数
+     * @return 操作结果
      */
     @SaCheckPermission("system:user:edit")
     @Log(title = "用户管理", businessType = BusinessType.UPDATE)
@@ -250,6 +274,7 @@ public class SysUserController extends BaseController {
      * 根据用户编号获取授权角色
      *
      * @param userId 用户ID
+     * @return 用户及其可授权角色信息
      */
     @SaCheckPermission("system:user:query")
     @GetMapping("/authRole/{userId}")
@@ -268,6 +293,7 @@ public class SysUserController extends BaseController {
      *
      * @param userId  用户Id
      * @param roleIds 角色ID串
+     * @return 操作结果
      */
     @SaCheckPermission("system:user:edit")
     @Log(title = "用户管理", businessType = BusinessType.GRANT)
@@ -280,7 +306,10 @@ public class SysUserController extends BaseController {
     }
 
     /**
-     * 获取部门树列表
+     * 获取用户筛选用的部门树。
+     *
+     * @param dept 部门查询条件
+     * @return 部门树列表
      */
     @SaCheckPermission("system:user:list")
     @GetMapping("/deptTree")
@@ -289,7 +318,10 @@ public class SysUserController extends BaseController {
     }
 
     /**
-     * 获取部门下的所有用户信息
+     * 获取指定部门下的全部用户信息。
+     *
+     * @param deptId 部门ID
+     * @return 用户列表
      */
     @SaCheckPermission("system:user:list")
     @GetMapping("/list/dept/{deptId}")

ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/ISysPostService.java

@@ -35,7 +35,7 @@ public interface ISysPostService {
      * 查询用户所属岗位组
      *
      * @param userId 用户ID
-     * @return 岗位ID
+     * @return 岗位列表
      */
     List<SysPostVo> selectPostsByUserId(Long userId);
 
@@ -50,7 +50,7 @@ public interface ISysPostService {
      * 通过岗位ID查询岗位信息
      *
      * @param postId 岗位ID
-     * @return 角色对象信息
+     * @return 岗位信息
      */
     SysPostVo selectPostById(Long postId);
 
@@ -74,7 +74,7 @@ public interface ISysPostService {
      * 校验岗位名称
      *
      * @param post 岗位信息
-     * @return 结果
+     * @return 是否唯一
      */
     boolean checkPostNameUnique(SysPostBo post);
 
@@ -82,7 +82,7 @@ public interface ISysPostService {
      * 校验岗位编码
      *
      * @param post 岗位信息
-     * @return 结果
+     * @return 是否唯一
      */
     boolean checkPostCodeUnique(SysPostBo post);
 
@@ -90,7 +90,7 @@ public interface ISysPostService {
      * 通过岗位ID查询岗位使用数量
      *
      * @param postId 岗位ID
-     * @return 结果
+     * @return 绑定用户数量
      */
     long countUserPostById(Long postId);
 
@@ -98,7 +98,7 @@ public interface ISysPostService {
      * 通过部门ID查询岗位使用数量
      *
      * @param deptId 部门id
-     * @return 结果
+     * @return 岗位数量
      */
     long countPostByDeptId(Long deptId);
 
@@ -106,7 +106,7 @@ public interface ISysPostService {
      * 删除岗位信息
      *
      * @param postId 岗位ID
-     * @return 结果
+     * @return 影响行数
      */
     int deletePostById(Long postId);
 
@@ -114,7 +114,7 @@ public interface ISysPostService {
      * 批量删除岗位信息
      *
      * @param postIds 需要删除的岗位ID
-     * @return 结果
+     * @return 影响行数
      */
     int deletePostByIds(List<Long> postIds);
 
@@ -122,7 +122,7 @@ public interface ISysPostService {
      * 新增保存岗位信息
      *
      * @param bo 岗位信息
-     * @return 结果
+     * @return 影响行数
      */
     int insertPost(SysPostBo bo);
 
@@ -130,7 +130,7 @@ public interface ISysPostService {
      * 修改保存岗位信息
      *
      * @param bo 岗位信息
-     * @return 结果
+     * @return 影响行数
      */
     int updatePost(SysPostBo bo);
 }

ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/ISysRoleService.java

@@ -29,7 +29,7 @@ public interface ISysRoleService {
      * 根据条件查询角色数据
      *
      * @param role 角色信息
-     * @return 角色数据集合信息
+     * @return 角色列表
      */
     List<SysRoleVo> selectRoleList(SysRoleBo role);
 
@@ -92,7 +92,7 @@ public interface ISysRoleService {
      * 校验角色名称是否唯一
      *
      * @param role 角色信息
-     * @return 结果
+     * @return 是否唯一
      */
     boolean checkRoleNameUnique(SysRoleBo role);
 
@@ -100,7 +100,7 @@ public interface ISysRoleService {
      * 校验角色权限是否唯一
      *
      * @param role 角色信息
-     * @return 结果
+     * @return 是否唯一
      */
     boolean checkRoleKeyUnique(SysRoleBo role);
 
@@ -129,7 +129,7 @@ public interface ISysRoleService {
      * 通过角色ID查询角色使用数量
      *
      * @param roleId 角色ID
-     * @return 结果
+     * @return 绑定用户数量
      */
     long countUserRoleByRoleId(Long roleId);
 
@@ -137,7 +137,7 @@ public interface ISysRoleService {
      * 新增保存角色信息
      *
      * @param bo 角色信息
-     * @return 结果
+     * @return 影响行数
      */
     int insertRole(SysRoleBo bo);
 
@@ -145,7 +145,7 @@ public interface ISysRoleService {
      * 修改保存角色信息
      *
      * @param bo 角色信息
-     * @return 结果
+     * @return 影响行数
      */
     int updateRole(SysRoleBo bo);
 
@@ -154,7 +154,7 @@ public interface ISysRoleService {
      *
      * @param roleId 角色ID
      * @param status 角色状态
-     * @return 结果
+     * @return 影响行数
      */
     int updateRoleStatus(Long roleId, String status);
 
@@ -162,7 +162,7 @@ public interface ISysRoleService {
      * 修改数据权限信息
      *
      * @param bo 角色信息
-     * @return 结果
+     * @return 影响行数
      */
     int authDataScope(SysRoleBo bo);
 
@@ -170,7 +170,7 @@ public interface ISysRoleService {
      * 通过角色ID删除角色
      *
      * @param roleId 角色ID
-     * @return 结果
+     * @return 影响行数
      */
     int deleteRoleById(Long roleId);
 
@@ -178,7 +178,7 @@ public interface ISysRoleService {
      * 批量删除角色信息
      *
      * @param roleIds 需要删除的角色ID
-     * @return 结果
+     * @return 影响行数
      */
     int deleteRoleByIds(List<Long> roleIds);
 
@@ -186,7 +186,7 @@ public interface ISysRoleService {
      * 取消授权用户角色
      *
      * @param userRole 用户和角色关联信息
-     * @return 结果
+     * @return 影响行数
      */
     int deleteAuthUser(SysUserRole userRole);
 
@@ -195,7 +195,7 @@ public interface ISysRoleService {
      *
      * @param roleId  角色ID
      * @param userIds 需要取消授权的用户数据ID
-     * @return 结果
+     * @return 影响行数
      */
     int deleteAuthUsers(Long roleId, Long[] userIds);
 
@@ -204,7 +204,7 @@ public interface ISysRoleService {
      *
      * @param roleId  角色ID
      * @param userIds 需要删除的用户数据ID
-     * @return 结果
+     * @return 影响行数
      */
     int insertAuthUsers(Long roleId, Long[] userIds);
 

ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/ISysUserService.java

@@ -20,8 +20,8 @@ public interface ISysUserService {
      * 根据条件分页查询用户列表
      *
      * @param user      用户信息
-     * @param pageQuery 发呢也
-     * @return 用户信息
+     * @param pageQuery 分页参数
+     * @return 用户分页信息
      */
     TableDataInfo<SysUserVo> selectPageUserList(SysUserBo user, PageQuery pageQuery);
 
@@ -29,7 +29,7 @@ public interface ISysUserService {
      * 导出用户列表
      *
      * @param user 用户信息
-     * @return 用户信息集合信息
+     * @return 用户导出列表
      */
     List<SysUserExportVo> selectUserExportList(SysUserBo user);
 
@@ -37,8 +37,8 @@ public interface ISysUserService {
      * 根据条件分页查询已分配用户角色列表
      *
      * @param user      用户信息
-     * @param pageQuery 分页
-     * @return 用户信息集合信息
+      * @param pageQuery 分页
+     * @return 已分配角色的用户分页信息
      */
     TableDataInfo<SysUserVo> selectAllocatedList(SysUserBo user, PageQuery pageQuery);
 
@@ -47,7 +47,7 @@ public interface ISysUserService {
      *
      * @param user      用户信息
      * @param pageQuery 分页
-     * @return 用户信息集合信息
+     * @return 未分配角色的用户分页信息
      */
     TableDataInfo<SysUserVo> selectUnallocatedList(SysUserBo user, PageQuery pageQuery);
 
@@ -150,7 +150,7 @@ public interface ISysUserService {
      * 注册用户信息
      *
      * @param user 用户信息
-     * @return 结果
+     * @return 是否注册成功
      */
     boolean registerUser(SysUserBo user);
 
@@ -192,7 +192,7 @@ public interface ISysUserService {
      *
      * @param userId 用户ID
      * @param avatar 头像地址
-     * @return 结果
+     * @return 是否修改成功
      */
     boolean updateUserAvatar(Long userId, Long avatar);
 

ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/impl/SysClientServiceImpl.java

@@ -41,6 +41,9 @@ public class SysClientServiceImpl implements ISysClientService {
 
     /**
      * 查询客户端管理
+     *
+     * @param id 主键
+     * @return 客户端详情
      */
     @Override
     public SysClientVo queryById(Long id) {
@@ -51,6 +54,9 @@ public class SysClientServiceImpl implements ISysClientService {
 
     /**
      * 查询客户端管理
+     *
+     * @param clientId 客户端标识
+     * @return 客户端详情
      */
     @Cacheable(cacheNames = CacheNames.SYS_CLIENT, key = "#clientId")
     @Override
@@ -60,6 +66,10 @@ public class SysClientServiceImpl implements ISysClientService {
 
     /**
      * 查询客户端管理列表
+     *
+     * @param bo        查询条件
+     * @param pageQuery 分页参数
+     * @return 客户端分页列表
      */
     @Override
     public TableDataInfo<SysClientVo> queryPageList(SysClientBo bo, PageQuery pageQuery) {
@@ -71,6 +81,9 @@ public class SysClientServiceImpl implements ISysClientService {
 
     /**
      * 查询客户端管理列表
+     *
+     * @param bo 查询条件
+     * @return 客户端列表
      */
     @Override
     public List<SysClientVo> queryList(SysClientBo bo) {
@@ -78,6 +91,12 @@ public class SysClientServiceImpl implements ISysClientService {
         return baseMapper.selectVoList(lqw);
     }
 
+    /**
+     * 构造客户端列表查询条件。
+     *
+     * @param bo 客户端筛选条件
+     * @return 包含 clientId、clientKey、状态等条件的查询包装器
+     */
     private LambdaQueryWrapper<SysClient> buildQueryWrapper(SysClientBo bo) {
         LambdaQueryWrapper<SysClient> lqw = Wrappers.lambdaQuery();
         lqw.eq(StringUtils.isNotBlank(bo.getClientId()), SysClient::getClientId, bo.getClientId());
@@ -90,6 +109,9 @@ public class SysClientServiceImpl implements ISysClientService {
 
     /**
      * 新增客户端管理
+     *
+     * @param bo 客户端业务对象
+     * @return 新增成功返回 {@code true}
      */
     @Override
     public Boolean insertByBo(SysClientBo bo) {
@@ -108,6 +130,9 @@ public class SysClientServiceImpl implements ISysClientService {
 
     /**
      * 修改客户端管理
+     *
+     * @param bo 客户端业务对象
+     * @return 修改成功返回 {@code true}
      */
     @CacheEvict(cacheNames = CacheNames.SYS_CLIENT, key = "#bo.clientId")
     @Override
@@ -119,6 +144,10 @@ public class SysClientServiceImpl implements ISysClientService {
 
     /**
      * 修改状态
+     *
+     * @param clientId 客户端标识
+     * @param status   状态值
+     * @return 更新条数
      */
     @CacheEvict(cacheNames = CacheNames.SYS_CLIENT, key = "#clientId")
     @Override
@@ -131,6 +160,10 @@ public class SysClientServiceImpl implements ISysClientService {
 
     /**
      * 批量删除客户端管理
+     *
+     * @param ids     主键集合
+     * @param isValid 是否执行业务校验
+     * @return 删除成功返回 {@code true}
      */
     @CacheEvict(cacheNames = CacheNames.SYS_CLIENT, allEntries = true)
     @Override

ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/impl/SysConfigServiceImpl.java

@@ -103,6 +103,12 @@ public class SysConfigServiceImpl implements ISysConfigService, ConfigService {
         return baseMapper.selectVoList(lqw);
     }
 
+    /**
+     * 构造参数配置列表查询条件。
+     *
+     * @param bo 参数配置筛选条件
+     * @return 包含名称、键名、类型与时间区间的查询包装器
+     */
     private LambdaQueryWrapper<SysConfig> buildQueryWrapper(SysConfigBo bo) {
         Map<String, Object> params = bo.getParams();
         LambdaQueryWrapper<SysConfig> lqw = Wrappers.lambdaQuery();
@@ -214,7 +220,7 @@ public class SysConfigServiceImpl implements ISysConfigService, ConfigService {
      * 根据参数 key 获取 Map 类型的配置
      *
      * @param configKey 参数 key
-     * @return Dict 对象，如果配置为空或无法解析，返回空 Dict
+     * @return Dict 对象，如果配置为空或无法解析则返回空 Dict
      */
     @Override
     public Dict getConfigMap(String configKey) {
@@ -226,7 +232,7 @@ public class SysConfigServiceImpl implements ISysConfigService, ConfigService {
      * 根据参数 key 获取 Map 类型的配置列表
      *
      * @param configKey 参数 key
-     * @return Dict 列表，如果配置为空或无法解析，返回空列表
+     * @return Dict 列表，如果配置为空或无法解析则返回空列表
      */
     @Override
     public List<Dict> getConfigArrayMap(String configKey) {

ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/impl/SysDataScopeServiceImpl.java

@@ -21,6 +21,7 @@ import java.util.List;
  * <p>
  * 注意: 此Service内不允许调用标注`数据权限`注解的方法
  * 例如: deptMapper.selectList 此 selectList 方法标注了`数据权限`注解 会出现循环解析的问题
+ * 当前实现仅负责返回角色自定义部门范围以及部门树展开后的 id 串，供数据权限插件拼装 SQL 时使用。
  *
  * @author Lion Li
  */
@@ -35,7 +36,7 @@ public class SysDataScopeServiceImpl implements ISysDataScopeService {
      * 获取角色自定义权限
      *
      * @param roleId 角色Id
-     * @return 部门Id组
+     * @return 逗号分隔的部门 id 字符串，未配置时返回 `-1`
      */
     @Cacheable(cacheNames = CacheNames.SYS_ROLE_CUSTOM, key = "#roleId", condition = "#roleId != null")
     @Override
@@ -57,7 +58,7 @@ public class SysDataScopeServiceImpl implements ISysDataScopeService {
      * 获取部门及以下权限
      *
      * @param deptId 部门Id
-     * @return 部门Id组
+     * @return 当前部门及其子部门的逗号分隔 id 字符串，未查询到时返回 `-1`
      */
     @Cacheable(cacheNames = CacheNames.SYS_DEPT_AND_CHILD, key = "#deptId", condition = "#deptId != null")
     @Override

ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/impl/SysDeptServiceImpl.java

@@ -89,6 +89,12 @@ public class SysDeptServiceImpl implements ISysDeptService, DeptService {
         return buildDeptTreeSelect(depts);
     }
 
+    /**
+     * 构造部门列表查询条件。
+     *
+     * @param bo 部门筛选条件
+     * @return 包含树级过滤、状态、分类和时间区间的查询包装器
+     */
     private LambdaQueryWrapper<SysDept> buildQueryWrapper(SysDeptBo bo) {
         Map<String, Object> params = bo.getParams();
         LambdaQueryWrapper<SysDept> lqw = Wrappers.lambdaQuery();
@@ -169,6 +175,12 @@ public class SysDeptServiceImpl implements ISysDeptService, DeptService {
         return dept;
     }
 
+    /**
+     * 按部门主键集合查询部门基础信息。
+     *
+     * @param deptIds 部门主键集合
+     * @return 部门基础信息列表
+     */
     @Override
     public List<SysDeptVo> selectDeptByIds(List<Long> deptIds) {
         return baseMapper.selectDeptList(new LambdaQueryWrapper<SysDept>()

ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/impl/SysDictDataServiceImpl.java

@@ -59,6 +59,12 @@ public class SysDictDataServiceImpl implements ISysDictDataService {
         return baseMapper.selectVoList(lqw);
     }
 
+    /**
+     * 构造字典数据列表查询条件。
+     *
+     * @param bo 字典数据筛选条件
+     * @return 包含排序号、标签和字典类型条件的查询包装器
+     */
     private LambdaQueryWrapper<SysDictData> buildQueryWrapper(SysDictDataBo bo) {
         LambdaQueryWrapper<SysDictData> lqw = Wrappers.lambdaQuery();
         lqw.eq(bo.getDictSort() != null, SysDictData::getDictSort, bo.getDictSort());

ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/impl/SysDictTypeServiceImpl.java

@@ -74,6 +74,12 @@ public class SysDictTypeServiceImpl implements ISysDictTypeService, DictService
         return baseMapper.selectVoList(lqw);
     }
 
+    /**
+     * 构造字典类型列表查询条件。
+     *
+     * @param bo 字典类型筛选条件
+     * @return 包含名称、类型与创建时间区间的查询包装器
+     */
     private LambdaQueryWrapper<SysDictType> buildQueryWrapper(SysDictTypeBo bo) {
         Map<String, Object> params = bo.getParams();
         LambdaQueryWrapper<SysDictType> lqw = Wrappers.lambdaQuery();
@@ -224,7 +230,7 @@ public class SysDictTypeServiceImpl implements ISysDictTypeService, DictService
      * @param dictType  字典类型
      * @param dictValue 字典值
      * @param separator 分隔符
-     * @return 字典标签
+     * @return 转换后的字典标签，支持按分隔符批量转换
      */
     @Override
     public String getDictLabel(String dictType, String dictValue, String separator) {
@@ -248,7 +254,7 @@ public class SysDictTypeServiceImpl implements ISysDictTypeService, DictService
      * @param dictType  字典类型
      * @param dictLabel 字典标签
      * @param separator 分隔符
-     * @return 字典值
+     * @return 转换后的字典值，支持按分隔符批量转换
      */
     @Override
     public String getDictValue(String dictType, String dictLabel, String separator) {

ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/impl/SysLoginInfoServiceImpl.java

@@ -100,6 +100,12 @@ public class SysLoginInfoServiceImpl implements ISysLoginInfoService {
         insertLoginInfo(loginInfo);
     }
 
+    /**
+     * 将日志片段包装为统一的方括号格式。
+     *
+     * @param msg 日志片段内容
+     * @return 包装后的日志片段字符串
+     */
     private String getBlock(Object msg) {
         if (msg == null) {
             msg = "";

ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/impl/SysMenuServiceImpl.java

@@ -56,7 +56,8 @@ public class SysMenuServiceImpl implements ISysMenuService {
     /**
      * 查询系统菜单列表
      *
-     * @param menu 菜单信息
+     * @param menu   菜单筛选条件
+     * @param userId 当前查询的用户主键
      * @return 菜单列表
      */
     @Override
@@ -113,7 +114,7 @@ public class SysMenuServiceImpl implements ISysMenuService {
      * 根据用户ID查询菜单
      *
      * @param userId 用户ID
-     * @return 菜单列表
+     * @return 按树结构组织的菜单列表
      */
     @Override
     public List<SysMenu> selectMenuTreeByUserId(Long userId) {
@@ -309,7 +310,6 @@ public class SysMenuServiceImpl implements ISysMenuService {
      * 批量删除菜单管理信息
      *
      * @param menuIds 菜单ID串
-     * @return 结果
      */
     @Override
     @Transactional(rollbackFor = Exception.class)

ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/impl/SysNoticeServiceImpl.java

@@ -71,6 +71,12 @@ public class SysNoticeServiceImpl implements ISysNoticeService {
         return baseMapper.selectVoList(lqw);
     }
 
+    /**
+     * 构造公告列表查询条件。
+     *
+     * @param bo 公告筛选条件
+     * @return 包含标题、类型、创建人和排序条件的查询包装器
+     */
     private LambdaQueryWrapper<SysNotice> buildQueryWrapper(SysNoticeBo bo) {
         LambdaQueryWrapper<SysNotice> lqw = Wrappers.lambdaQuery();
         lqw.like(StringUtils.isNotBlank(bo.getNoticeTitle()), SysNotice::getNoticeTitle, bo.getNoticeTitle());

ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/impl/SysOperLogServiceImpl.java

@@ -66,6 +66,12 @@ public class SysOperLogServiceImpl implements ISysOperLogService {
         return TableDataInfo.build(page);
     }
 
+    /**
+     * 构造操作日志查询条件。
+     *
+     * @param operLog 操作日志筛选条件
+     * @return 包含业务类型、状态、操作人和时间区间的查询包装器
+     */
     private LambdaQueryWrapper<SysOperLog> buildQueryWrapper(SysOperLogBo operLog) {
         Map<String, Object> params = operLog.getParams();
         return new LambdaQueryWrapper<SysOperLog>()

ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/impl/SysOssConfigServiceImpl.java

@@ -60,11 +60,24 @@ public class SysOssConfigServiceImpl implements ISysOssConfigService {
         }
     }
 
+    /**
+     * 查询对象存储配置详情。
+     *
+     * @param ossConfigId 配置主键
+     * @return 对象存储配置详情
+     */
     @Override
     public SysOssConfigVo queryById(Long ossConfigId) {
         return baseMapper.selectVoById(ossConfigId);
     }
 
+    /**
+     * 分页查询对象存储配置列表。
+     *
+     * @param bo        配置筛选条件
+     * @param pageQuery 分页参数
+     * @return 配置分页结果
+     */
     @Override
     public TableDataInfo<SysOssConfigVo> queryPageList(SysOssConfigBo bo, PageQuery pageQuery) {
         LambdaQueryWrapper<SysOssConfig> lqw = buildQueryWrapper(bo);
@@ -73,6 +86,12 @@ public class SysOssConfigServiceImpl implements ISysOssConfigService {
     }
 
 
+    /**
+     * 构造对象存储配置列表查询条件。
+     *
+     * @param bo 配置筛选条件
+     * @return 包含配置标识、桶名称和状态条件的查询包装器
+     */
     private LambdaQueryWrapper<SysOssConfig> buildQueryWrapper(SysOssConfigBo bo) {
         LambdaQueryWrapper<SysOssConfig> lqw = Wrappers.lambdaQuery();
         lqw.eq(StringUtils.isNotBlank(bo.getConfigKey()), SysOssConfig::getConfigKey, bo.getConfigKey());
@@ -82,6 +101,12 @@ public class SysOssConfigServiceImpl implements ISysOssConfigService {
         return lqw;
     }
 
+    /**
+     * 新增对象存储配置并刷新缓存。
+     *
+     * @param bo 配置业务对象
+     * @return 新增成功返回 {@code true}
+     */
     @Override
     public Boolean insertByBo(SysOssConfigBo bo) {
         SysOssConfig config = MapstructUtils.convert(bo, SysOssConfig.class);
@@ -95,6 +120,12 @@ public class SysOssConfigServiceImpl implements ISysOssConfigService {
         return flag;
     }
 
+    /**
+     * 更新对象存储配置并刷新缓存。
+     *
+     * @param bo 配置业务对象
+     * @return 更新成功返回 {@code true}
+     */
     @Override
     public Boolean updateByBo(SysOssConfigBo bo) {
         SysOssConfig config = MapstructUtils.convert(bo, SysOssConfig.class);
@@ -116,6 +147,8 @@ public class SysOssConfigServiceImpl implements ISysOssConfigService {
 
     /**
      * 保存前的数据校验
+     *
+     * @param entity 待保存的对象存储配置实体
      */
     private void validEntityBeforeSave(SysOssConfig entity) {
         if (StringUtils.isNotEmpty(entity.getConfigKey())
@@ -124,6 +157,13 @@ public class SysOssConfigServiceImpl implements ISysOssConfigService {
         }
     }
 
+    /**
+     * 删除对象存储配置并同步清理缓存。
+     *
+     * @param ids     主键集合
+     * @param isValid 是否执行业务校验
+     * @return 删除成功返回 {@code true}
+     */
     @Override
     public Boolean deleteWithValidByIds(Collection<Long> ids, Boolean isValid) {
         if (isValid) {
@@ -146,6 +186,9 @@ public class SysOssConfigServiceImpl implements ISysOssConfigService {
 
     /**
      * 判断configKey是否唯一
+     *
+     * @param sysOssConfig 对象存储配置实体
+     * @return 唯一返回 {@code true}
      */
     private boolean checkConfigKeyUnique(SysOssConfig sysOssConfig) {
         long ossConfigId = ObjectUtils.notNull(sysOssConfig.getOssConfigId(), -1L);
@@ -160,6 +203,9 @@ public class SysOssConfigServiceImpl implements ISysOssConfigService {
 
     /**
      * 启用禁用状态
+     *
+     * @param bo 配置业务对象
+     * @return 更新条数
      */
     @Override
     @Transactional(rollbackFor = Exception.class)

ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/impl/SysOssServiceImpl.java

@@ -119,6 +119,12 @@ public class SysOssServiceImpl implements ISysOssService, OssService {
         return StringUtils.joinComma(list);
     }
 
+    /**
+     * 根据逗号分隔的文件主键列表查询文件传输对象集合。
+     *
+     * @param ossIds 逗号分隔的文件主键字符串
+     * @return 文件传输对象列表
+     */
     @Override
     public List<OssDTO> selectByIds(String ossIds) {
         List<OssDTO> list = new ArrayList<>();
@@ -137,6 +143,12 @@ public class SysOssServiceImpl implements ISysOssService, OssService {
         return list;
     }
 
+    /**
+     * 构造 OSS 文件列表查询条件。
+     *
+     * @param bo 文件筛选条件
+     * @return 包含文件名、后缀、归属服务和创建时间区间的查询包装器
+     */
     private LambdaQueryWrapper<SysOss> buildQueryWrapper(SysOssBo bo) {
         Map<String, Object> params = bo.getParams();
         LambdaQueryWrapper<SysOss> lqw = Wrappers.lambdaQuery();
@@ -233,6 +245,16 @@ public class SysOssServiceImpl implements ISysOssService, OssService {
         return buildResultEntity(originalfileName, suffix, storage.getConfigKey(), uploadResult, ext1);
     }
 
+    /**
+     * 组装上传结果并持久化文件元数据。
+     *
+     * @param originalfileName 原始文件名
+     * @param suffix           文件后缀
+     * @param configKey        存储配置标识
+     * @param uploadResult     上传结果
+     * @param ext1             扩展属性对象
+     * @return 持久化后的文件信息视图
+     */
     @NotNull
     private SysOssVo buildResultEntity(String originalfileName, String suffix, String configKey, UploadResult uploadResult, SysOssExt ext1) {
         SysOss oss = new SysOss();

ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/impl/SysPermissionServiceImpl.java

@@ -62,6 +62,12 @@ public class SysPermissionServiceImpl implements ISysPermissionService, Permissi
         return perms;
     }
 
+    /**
+     * 按权限标识汇总具备数据权限的角色集合。
+     *
+     * @param roles 角色传输对象列表
+     * @return key 为权限标识、value 为拥有该权限的角色主键列表
+     */
     @Override
     public Map<String, List<Long>> getDataScopeRoleMap(List<RoleDTO> roles) {
         if (CollUtil.isEmpty(roles)) {

ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/impl/SysRoleServiceImpl.java

@@ -77,6 +77,12 @@ public class SysRoleServiceImpl implements ISysRoleService, RoleService {
         return baseMapper.selectRoleList(this.buildQueryWrapper(role));
     }
 
+    /**
+     * 构造角色列表查询条件。
+     *
+     * @param bo 角色筛选条件
+     * @return 包含名称、权限字符、状态和创建时间区间的查询包装器
+     */
     private Wrapper<SysRole> buildQueryWrapper(SysRoleBo bo) {
         Map<String, Object> params = bo.getParams();
         LambdaQueryWrapper<SysRole> wrapper = Wrappers.lambdaQuery();

ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/impl/SysSensitiveServiceImpl.java

@@ -19,6 +19,10 @@ public class SysSensitiveServiceImpl implements SensitiveService {
 
     /**
      * 是否脱敏
+     *
+     * @param roleKey 允许查看原文的角色标识列表
+     * @param perms   允许查看原文的权限标识列表
+     * @return 需要脱敏返回 {@code true}
      */
     @Override
     public boolean isSensitive(String[] roleKey, String[] perms) {

ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/impl/SysSocialServiceImpl.java

@@ -29,6 +29,9 @@ public class SysSocialServiceImpl implements ISysSocialService {
 
     /**
      * 查询社会化关系
+     *
+     * @param id 主键
+     * @return 社会化绑定详情
      */
     @Override
     public SysSocialVo queryById(String id) {
@@ -37,6 +40,9 @@ public class SysSocialServiceImpl implements ISysSocialService {
 
     /**
      * 授权列表
+     *
+     * @param bo 查询条件
+     * @return 社会化授权关系列表
      */
     @Override
     public List<SysSocialVo> queryList(SysSocialBo bo) {
@@ -47,6 +53,12 @@ public class SysSocialServiceImpl implements ISysSocialService {
         return baseMapper.selectVoList(lqw);
     }
 
+    /**
+     * 按用户主键查询其绑定的社会化授权列表。
+     *
+     * @param userId 用户主键
+     * @return 用户已绑定的社会化授权列表
+     */
     @Override
     public List<SysSocialVo> queryListByUserId(Long userId) {
         return baseMapper.selectVoList(new LambdaQueryWrapper<SysSocial>().eq(SysSocial::getUserId, userId));
@@ -55,6 +67,9 @@ public class SysSocialServiceImpl implements ISysSocialService {
 
     /**
      * 新增社会化关系
+     *
+     * @param bo 业务对象
+     * @return 新增成功返回 {@code true}
      */
     @Override
     public Boolean insertByBo(SysSocialBo bo) {
@@ -73,6 +88,9 @@ public class SysSocialServiceImpl implements ISysSocialService {
 
     /**
      * 更新社会化关系
+     *
+     * @param bo 业务对象
+     * @return 更新成功返回 {@code true}
      */
     @Override
     public Boolean updateByBo(SysSocialBo bo) {
@@ -83,6 +101,8 @@ public class SysSocialServiceImpl implements ISysSocialService {
 
     /**
      * 保存前的数据校验
+     *
+     * @param entity 待保存的社会化关系实体
      */
     private void validEntityBeforeSave(SysSocial entity) {
         //TODO 做一些数据校验,如唯一约束
@@ -91,6 +111,9 @@ public class SysSocialServiceImpl implements ISysSocialService {
 
     /**
      * 删除社会化关系
+     *
+     * @param id 主键
+     * @return 删除成功返回 {@code true}
      */
     @Override
     public Boolean deleteWithValidById(Long id) {

ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/service/impl/SysUserServiceImpl.java

@@ -56,6 +56,13 @@ public class SysUserServiceImpl implements ISysUserService, UserService {
     private final SysUserRoleMapper userRoleMapper;
     private final SysUserPostMapper userPostMapper;
 
+    /**
+     * 分页查询用户列表。
+     *
+     * @param user      用户筛选条件
+     * @param pageQuery 分页参数
+     * @return 用户分页结果
+     */
     @Override
     public TableDataInfo<SysUserVo> selectPageUserList(SysUserBo user, PageQuery pageQuery) {
         Page<SysUserVo> page = baseMapper.selectPageUserList(pageQuery.build(), this.buildQueryWrapper(user));
@@ -74,6 +81,12 @@ public class SysUserServiceImpl implements ISysUserService, UserService {
         return baseMapper.selectUserExportList(user, deptIds);
     }
 
+    /**
+     * 构造用户列表查询条件。
+     *
+     * @param user 用户筛选条件
+     * @return 叠加部门、状态、时间区间等条件的查询包装器
+     */
     private Wrapper<SysUser> buildQueryWrapper(SysUserBo user) {
         Map<String, Object> params = user.getParams();
         LambdaQueryWrapper<SysUser> wrapper = Wrappers.lambdaQuery();

ruoyi-modules/ruoyi-workflow/src/main/java/org/dromara/workflow/common/constant/FlowConstant.java

@@ -24,52 +24,52 @@ public interface FlowConstant {
     String INITIATOR_DEPT_ID = "initiatorDeptId";
 
     /**
-     * 流程分类Id转名称
+     * 流程分类 ID 转名称的翻译标识。
      */
     String CATEGORY_ID_TO_NAME = "category_id_to_name";
 
     /**
-     * 流程分类名称
+     * 流程分类名称缓存键。
      */
     String FLOW_CATEGORY_NAME = "flow_category_name#30d";
 
     /**
-     * 默认租户OA申请分类id
+     * 默认租户 OA 申请分类 ID。
      */
     Long FLOW_CATEGORY_ID = 100L;
 
     /**
-     * 是否为申请人提交常量
+     * 申请人提交动作标识。
      */
     String SUBMIT = "submit";
 
     /**
-     * 抄送常量
+     * 抄送列表流程变量名。
      */
     String FLOW_COPY_LIST = "flowCopyList";
 
     /**
-     * 消息类型常量
+     * 消息类型流程变量名。
      */
     String MESSAGE_TYPE = "messageType";
 
     /**
-     * 消息通知常量
+     * 消息通知内容流程变量名。
      */
     String MESSAGE_NOTICE = "messageNotice";
 
     /**
-     * 任务状态
+     * 任务状态字典类型编码。
      */
     String WF_TASK_STATUS = "wf_task_status";
 
     /**
-     * 自动通过
+     * 自动通过变量标识。
      */
     String AUTO_PASS = "autoPass";
 
     /**
-     * 业务编码
+     * 业务编码流程变量名。
      */
     String BUSINESS_CODE = "businessCode";
 

ruoyi-modules/ruoyi-workflow/src/main/java/org/dromara/workflow/common/enums/ButtonPermissionEnum.java

@@ -57,8 +57,19 @@ public enum ButtonPermissionEnum implements NodeExtEnum {
      */
     FILE("是否能上传附件", "file", true);
 
+    /**
+     * 按钮展示名称。
+     */
     private final String label;
+
+    /**
+     * 按钮权限值。
+     */
     private final String value;
+
+    /**
+     * 是否默认开启。
+     */
     private final boolean selected;
 
 }

ruoyi-modules/ruoyi-workflow/src/main/java/org/dromara/workflow/common/enums/CopySettingEnum.java

@@ -12,8 +12,20 @@ import lombok.Getter;
 @AllArgsConstructor
 public enum CopySettingEnum implements NodeExtEnum {
     ;
+
+    /**
+     * 展示名称。
+     */
     private final String label;
+
+    /**
+     * 配置值。
+     */
     private final String value;
+
+    /**
+     * 是否默认选中。
+     */
     private final boolean selected;
 
 }

ruoyi-modules/ruoyi-workflow/src/main/java/org/dromara/workflow/common/enums/MessageTypeEnum.java

@@ -9,7 +9,7 @@ import java.util.function.Function;
 import java.util.stream.Collectors;
 
 /**
- * 消息类型枚举
+ * 消息类型枚举，定义流程通知支持的消息通道。
  *
  * @author may
  */
@@ -32,15 +32,21 @@ public enum MessageTypeEnum {
      */
     SMS_MESSAGE("3", "短信");
 
+    /**
+     * 消息类型编码。
+     */
     private final String code;
 
+    /**
+     * 消息类型描述。
+     */
     private final String desc;
 
     private static final Map<String, MessageTypeEnum> MESSAGE_TYPE_ENUM_MAP = Arrays.stream(values())
         .collect(Collectors.toConcurrentMap(MessageTypeEnum::getCode, Function.identity()));
 
     /**
-     * 根据消息类型 code 获取 MessageTypeEnum
+     * 根据消息类型编码获取枚举实例。
      *
      * @param code 消息类型code
      * @return MessageTypeEnum

ruoyi-modules/ruoyi-workflow/src/main/java/org/dromara/workflow/common/enums/NodeExtEnum.java

@@ -1,28 +1,28 @@
 package org.dromara.workflow.common.enums;
 
 /**
- * 节点扩展属性枚举
+ * 节点扩展属性枚举通用接口，约束扩展选项的展示名、值和默认勾选状态。
  *
  * @author AprilWind
  */
 public interface NodeExtEnum {
 
     /**
-     * 选项label
+     * 获取选项展示名称。
      *
      * @return 选项label
      */
     String getLabel();
 
     /**
-     * 选项值
+     * 获取选项值。
      *
      * @return 选项值
      */
     String getValue();
 
     /**
-     * 是否默认选中
+     * 是否默认选中。
      *
      * @return 是否默认选中
      */

ruoyi-modules/ruoyi-workflow/src/main/java/org/dromara/workflow/common/enums/TaskAssigneeEnum.java

@@ -43,7 +43,14 @@ public enum TaskAssigneeEnum {
      */
     SPEL("SpEL表达式", "");
 
+    /**
+     * 类型描述。
+     */
     private final String desc;
+
+    /**
+     * 类型编码前缀。
+     */
     private final String code;
 
     /**
@@ -85,10 +92,7 @@ public enum TaskAssigneeEnum {
     }
 
     /**
-     * 获取所有办理人类型的描述列表
-     * <p>
-     * 获取当前枚举类所有项的描述字段列表，通常用于展示选择项。
-     * </p>
+     * 获取所有办理人类型的描述列表，通常用于前端展示选择项。
      *
      * @return List<String> 返回所有办理人类型的描述列表
      */
@@ -99,10 +103,8 @@ public enum TaskAssigneeEnum {
     }
 
     /**
-     * 获取所有办理人类型的代码列表
-     * <p>
-     * 获取当前枚举类所有项的代码字段列表，通常用于程序内部逻辑的判断。
-     * </p>
+    /**
+     * 获取所有办理人类型的代码列表，通常用于程序内部逻辑判断。
      *
      * @return List<String> 返回所有办理人类型的代码列表
      */
@@ -113,7 +115,7 @@ public enum TaskAssigneeEnum {
     }
 
     /**
-     * 判断当前办理人类型是否需要调用部门服务（deptService）
+     * 判断当前办理人类型是否需要调用部门服务。
      *
      * @return 如果类型是 USER、DEPT 或 POST，则返回 true；否则返回 false
      */

ruoyi-modules/ruoyi-workflow/src/main/java/org/dromara/workflow/common/enums/TaskOperationEnum.java

@@ -9,7 +9,7 @@ import java.util.function.Function;
 import java.util.stream.Collectors;
 
 /**
- * 任务操作类型枚举
+ * 任务操作类型枚举，定义流程任务支持的运行时操作。
  *
  * @author may
  */
@@ -37,14 +37,24 @@ public enum TaskOperationEnum {
      */
     REDUCTION_SIGNATURE("reductionSignature", "减签");
 
+    /**
+     * 操作编码，供接口与前端交互使用。
+     */
     private final String code;
+
+    /**
+     * 操作描述。
+     */
     private final String desc;
 
     private static final Map<String, TaskOperationEnum> CODE_MAP = Arrays.stream(values())
         .collect(Collectors.toConcurrentMap(TaskOperationEnum::getCode, Function.identity()));
 
     /**
-     * 根据 code 获取枚举
+     * 根据 code 获取枚举实例。
+     *
+     * @param code 操作编码
+     * @return 对应的枚举实例
      */
     public static TaskOperationEnum getByCode(String code) {
         return CODE_MAP.get(code);

ruoyi-modules/ruoyi-workflow/src/main/java/org/dromara/workflow/common/enums/TaskStatusEnum.java

@@ -83,7 +83,7 @@ public enum TaskStatusEnum {
     private final String status;
 
     /**
-     * 描述
+     * 状态描述。
      */
     private final String desc;
 
@@ -91,9 +91,10 @@ public enum TaskStatusEnum {
         .collect(Collectors.toConcurrentMap(TaskStatusEnum::getStatus, TaskStatusEnum::getDesc));
 
     /**
-     * 任务业务状态
+     * 根据状态编码获取任务业务状态描述。
      *
      * @param status 状态
+     * @return 状态描述
      */
     public static String findByStatus(String status) {
         // 从缓存中直接获取描述

ruoyi-modules/ruoyi-workflow/src/main/java/org/dromara/workflow/common/enums/VariablesEnum.java

@@ -4,7 +4,7 @@ import lombok.AllArgsConstructor;
 import lombok.Getter;
 
 /**
- * 变量枚举
+ * 节点扩展变量枚举，占位用于后续补充可配置变量定义。
  *
  * @author AprilWind
  */
@@ -12,8 +12,20 @@ import lombok.Getter;
 @AllArgsConstructor
 public enum VariablesEnum implements NodeExtEnum {
     ;
+
+    /**
+     * 展示名称。
+     */
     private final String label;
+
+    /**
+     * 变量值。
+     */
     private final String value;
+
+    /**
+     * 是否选中。
+     */
     private final boolean selected;
 
 }

ruoyi-modules/ruoyi-workflow/src/main/java/org/dromara/workflow/config/WarmFlowConfig.java

@@ -4,7 +4,7 @@ import org.dromara.workflow.common.ConditionalOnEnable;
 import org.springframework.context.annotation.Configuration;
 
 /**
- * warmFlow配置
+ * WarmFlow 工作流配置入口，在工作流开关开启时注册相关组件。
  *
  * @author may
  */

ruoyi-modules/ruoyi-workflow/src/main/java/org/dromara/workflow/controller/FlwCategoryController.java

@@ -38,7 +38,10 @@ public class FlwCategoryController extends BaseController {
     private final IFlwCategoryService flwCategoryService;
 
     /**
-     * 查询流程分类列表
+     * 查询流程分类列表。
+     *
+     * @param bo 查询条件
+     * @return 流程分类列表
      */
     @SaCheckPermission("workflow:category:list")
     @GetMapping("/list")
@@ -48,7 +51,10 @@ public class FlwCategoryController extends BaseController {
     }
 
     /**
-     * 导出流程分类列表
+     * 导出流程分类列表。
+     *
+     * @param bo 查询条件
+     * @param response 响应流
      */
     @SaCheckPermission("workflow:category:export")
     @Log(title = "流程分类", businessType = BusinessType.EXPORT)
@@ -59,9 +65,10 @@ public class FlwCategoryController extends BaseController {
     }
 
     /**
-     * 获取流程分类详细信息
+     * 获取单个流程分类详情。
      *
      * @param categoryId 主键
+     * @return 流程分类详情
      */
     @SaCheckPermission("workflow:category:query")
     @GetMapping("/{categoryId}")
@@ -70,7 +77,10 @@ public class FlwCategoryController extends BaseController {
     }
 
     /**
-     * 新增流程分类
+     * 新增流程分类，并校验分类名称唯一性。
+     *
+     * @param category 分类信息
+     * @return 操作结果
      */
     @SaCheckPermission("workflow:category:add")
     @Log(title = "流程分类", businessType = BusinessType.INSERT)
@@ -84,7 +94,10 @@ public class FlwCategoryController extends BaseController {
     }
 
     /**
-     * 修改流程分类
+     * 修改流程分类，并校验名称唯一及父子关系合法性。
+     *
+     * @param category 分类信息
+     * @return 操作结果
      */
     @SaCheckPermission("workflow:category:edit")
     @Log(title = "流程分类", businessType = BusinessType.UPDATE)
@@ -101,9 +114,10 @@ public class FlwCategoryController extends BaseController {
     }
 
     /**
-     * 删除流程分类
+     * 删除流程分类，删除前校验默认分类、子节点和绑定流程定义。
      *
      * @param categoryId 主键
+     * @return 操作结果
      */
     @SaCheckPermission("workflow:category:remove")
     @Log(title = "流程分类", businessType = BusinessType.DELETE)
@@ -122,9 +136,10 @@ public class FlwCategoryController extends BaseController {
     }
 
     /**
-     * 获取流程分类树列表
+     * 获取流程分类树列表，用于流程定义选择分类节点。
      *
      * @param categoryBo 流程分类
+     * @return 流程分类树
      */
     @GetMapping("/categoryTree")
     public R<List<Tree<String>>> categoryTree(FlowCategoryBo categoryBo) {

ruoyi-modules/ruoyi-workflow/src/main/java/org/dromara/workflow/controller/FlwDefinitionController.java

@@ -39,10 +39,11 @@ public class FlwDefinitionController extends BaseController {
     private final IFlwDefinitionService flwDefinitionService;
 
     /**
-     * 查询流程定义列表
+     * 分页查询流程定义列表。
      *
-     * @param flowDefinition 参数
-     * @param pageQuery      分页
+     * @param flowDefinition 查询条件
+     * @param pageQuery      分页参数
+     * @return 流程定义分页数据
      */
     @GetMapping("/list")
     public TableDataInfo<FlowDefinitionVo> list(FlowDefinition flowDefinition, PageQuery pageQuery) {
@@ -50,10 +51,11 @@ public class FlwDefinitionController extends BaseController {
     }
 
     /**
-     * 查询未发布的流程定义列表
+     * 分页查询未发布的流程定义列表。
      *
-     * @param flowDefinition 参数
-     * @param pageQuery      分页
+     * @param flowDefinition 查询条件
+     * @param pageQuery      分页参数
+     * @return 未发布流程定义分页数据
      */
     @GetMapping("/unPublishList")
     public TableDataInfo<FlowDefinitionVo> unPublishList(FlowDefinition flowDefinition, PageQuery pageQuery) {
@@ -61,9 +63,10 @@ public class FlwDefinitionController extends BaseController {
     }
 
     /**
-     * 获取流程定义详细信息
+     * 获取流程定义详细信息。
      *
      * @param id 流程定义id
+     * @return 流程定义详情
      */
     @GetMapping(value = "/{id}")
     public R<Definition> getInfo(@PathVariable Long id) {
@@ -71,9 +74,10 @@ public class FlwDefinitionController extends BaseController {
     }
 
     /**
-     * 新增流程定义
+     * 新增流程定义并执行格式校验。
      *
-     * @param flowDefinition 参数
+     * @param flowDefinition 流程定义信息
+     * @return 操作结果
      */
     @Log(title = "流程定义", businessType = BusinessType.INSERT)
     @PostMapping
@@ -84,9 +88,10 @@ public class FlwDefinitionController extends BaseController {
     }
 
     /**
-     * 修改流程定义
+     * 修改流程定义。
      *
-     * @param flowDefinition 参数
+     * @param flowDefinition 流程定义信息
+     * @return 操作结果
      */
     @Log(title = "流程定义", businessType = BusinessType.UPDATE)
     @PutMapping
@@ -97,9 +102,10 @@ public class FlwDefinitionController extends BaseController {
     }
 
     /**
-     * 发布流程定义
+     * 发布流程定义，使其进入可用状态。
      *
      * @param id 流程定义id
+     * @return 发布结果
      */
     @Log(title = "流程定义", businessType = BusinessType.INSERT)
     @PutMapping("/publish/{id}")
@@ -109,9 +115,10 @@ public class FlwDefinitionController extends BaseController {
     }
 
     /**
-     * 取消发布流程定义
+     * 取消发布流程定义。
      *
      * @param id 流程定义id
+     * @return 操作结果
      */
     @Log(title = "流程定义", businessType = BusinessType.INSERT)
     @PutMapping("/unPublish/{id}")
@@ -122,7 +129,10 @@ public class FlwDefinitionController extends BaseController {
     }
 
     /**
-     * 删除流程定义
+     * 批量删除流程定义。
+     *
+     * @param ids 流程定义ID集合
+     * @return 操作结果
      */
     @Log(title = "流程定义", businessType = BusinessType.DELETE)
     @DeleteMapping("/{ids}")
@@ -131,9 +141,10 @@ public class FlwDefinitionController extends BaseController {
     }
 
     /**
-     * 复制流程定义
+     * 复制一份流程定义，便于快速创建相似流程。
      *
      * @param id 流程定义id
+     * @return 复制结果
      */
     @Log(title = "流程定义", businessType = BusinessType.INSERT)
     @PostMapping("/copy/{id}")
@@ -144,10 +155,11 @@ public class FlwDefinitionController extends BaseController {
     }
 
     /**
-     * 导入流程定义
+     * 通过文件导入流程定义。
      *
      * @param file     文件
      * @param category 分类
+     * @return 导入结果
      */
     @Log(title = "流程定义", businessType = BusinessType.IMPORT)
     @PostMapping("/importDef")
@@ -156,7 +168,7 @@ public class FlwDefinitionController extends BaseController {
     }
 
     /**
-     * 导出流程定义
+     * 导出流程定义文件。
      *
      * @param id       流程定义id
      * @param response 响应
@@ -169,9 +181,10 @@ public class FlwDefinitionController extends BaseController {
     }
 
     /**
-     * 获取流程定义JSON字符串
+     * 获取流程定义 JSON 字符串。
      *
      * @param id 流程定义id
+     * @return 流程定义 JSON
      */
     @GetMapping("/xmlString/{id}")
     public R<String> xmlString(@PathVariable Long id) {
@@ -179,10 +192,12 @@ public class FlwDefinitionController extends BaseController {
     }
 
     /**
-     * 激活/挂起流程定义
+    /**
+     * 激活或挂起流程定义。
      *
      * @param id     流程定义id
      * @param active 激活/挂起
+     * @return 处理结果
      */
     @RepeatSubmit()
     @PutMapping("/active/{id}")

ruoyi-modules/ruoyi-workflow/src/main/java/org/dromara/workflow/controller/FlwInstanceController.java

@@ -40,10 +40,11 @@ public class FlwInstanceController extends BaseController {
     private final IFlwInstanceService flwInstanceService;
 
     /**
-     * 查询正在运行的流程实例列表
+     * 分页查询正在运行的流程实例。
      *
      * @param flowInstanceBo 流程实例
      * @param pageQuery      分页
+     * @return 正在运行的流程实例分页数据
      */
     @GetMapping("/pageByRunning")
     public TableDataInfo<FlowInstanceVo> selectRunningInstanceList(FlowInstanceBo flowInstanceBo, PageQuery pageQuery) {
@@ -51,10 +52,11 @@ public class FlwInstanceController extends BaseController {
     }
 
     /**
-     * 查询已结束的流程实例列表
+     * 分页查询已结束的流程实例。
      *
      * @param flowInstanceBo 流程实例
      * @param pageQuery      分页
+     * @return 已结束的流程实例分页数据
      */
     @GetMapping("/pageByFinish")
     public TableDataInfo<FlowInstanceVo> selectFinishInstanceList(FlowInstanceBo flowInstanceBo, PageQuery pageQuery) {
@@ -62,9 +64,10 @@ public class FlwInstanceController extends BaseController {
     }
 
     /**
-     * 根据业务id查询流程实例详细信息
+     * 根据业务 id 查询流程实例详细信息。
      *
      * @param businessId 业务id
+     * @return 流程实例详情
      */
     @GetMapping("/getInfo/{businessId}")
     public R<FlowInstanceVo> getInfo(@PathVariable Long businessId) {
@@ -72,9 +75,10 @@ public class FlwInstanceController extends BaseController {
     }
 
     /**
-     * 按照业务id删除流程实例
+     * 按业务 id 批量删除流程实例。
      *
      * @param businessIds 业务id
+     * @return 操作结果
      */
     @DeleteMapping("/deleteByBusinessIds/{businessIds}")
     @Log(title = "流程实例管理", businessType = BusinessType.DELETE)
@@ -83,9 +87,10 @@ public class FlwInstanceController extends BaseController {
     }
 
     /**
-     * 按照实例id删除流程实例
+     * 按实例 id 批量删除流程实例。
      *
      * @param instanceIds 实例id
+     * @return 操作结果
      */
     @DeleteMapping("/deleteByInstanceIds/{instanceIds}")
     @Log(title = "流程实例管理", businessType = BusinessType.DELETE)
@@ -94,9 +99,10 @@ public class FlwInstanceController extends BaseController {
     }
 
     /**
-     * 按照实例id删除已完成得流程实例
+     * 按实例 id 批量删除已完成的流程实例。
      *
      * @param instanceIds 实例id
+     * @return 操作结果
      */
     @DeleteMapping("/deleteHisByInstanceIds/{instanceIds}")
     @Log(title = "流程实例管理", businessType = BusinessType.DELETE)
@@ -105,9 +111,10 @@ public class FlwInstanceController extends BaseController {
     }
 
     /**
-     * 撤销流程
+     * 撤销当前申请人发起的流程。
      *
      * @param bo 参数
+     * @return 操作结果
      */
     @RepeatSubmit()
     @PutMapping("/cancelProcessApply")
@@ -117,10 +124,11 @@ public class FlwInstanceController extends BaseController {
     }
 
     /**
-     * 激活/挂起流程实例
+     * 激活或挂起流程实例。
      *
      * @param id     流程实例id
      * @param active 激活/挂起
+     * @return 处理结果
      */
     @RepeatSubmit()
     @PutMapping("/active/{id}")
@@ -130,10 +138,11 @@ public class FlwInstanceController extends BaseController {
     }
 
     /**
-     * 获取当前登陆人发起的流程实例
+     * 获取当前登录人发起的流程实例列表。
      *
      * @param flowInstanceBo 参数
      * @param pageQuery      分页
+     * @return 当前用户发起的流程实例分页数据
      */
     @GetMapping("/pageByCurrent")
     public TableDataInfo<FlowInstanceVo> selectCurrentInstanceList(FlowInstanceBo flowInstanceBo, PageQuery pageQuery) {
@@ -141,9 +150,10 @@ public class FlwInstanceController extends BaseController {
     }
 
     /**
-     * 获取流程图，流程记录
+     * 获取流程图和流程记录，用于展示实例流转轨迹。
      *
      * @param businessId 业务id
+     * @return 流程图与历史节点信息
      */
     @GetMapping("/flowHisTaskList/{businessId}")
     public R<Map<String, Object>> flowHisTaskList(@PathVariable String businessId) {
@@ -151,9 +161,10 @@ public class FlwInstanceController extends BaseController {
     }
 
     /**
-     * 获取流程变量
+     * 获取流程变量。
      *
      * @param instanceId 流程实例id
+     * @return 流程变量
      */
     @GetMapping("/instanceVariable/{instanceId}")
     public R<Map<String, Object>> instanceVariable(@PathVariable Long instanceId) {
@@ -161,9 +172,10 @@ public class FlwInstanceController extends BaseController {
     }
 
     /**
-     * 修改流程变量
+     * 修改流程变量。
      *
      * @param bo 参数
+     * @return 操作结果
      */
     @RepeatSubmit()
     @PutMapping("/updateVariable")
@@ -173,9 +185,10 @@ public class FlwInstanceController extends BaseController {
     }
 
     /**
-     * 作废流程
+     * 作废流程实例。
      *
      * @param bo 参数
+     * @return 处理结果
      */
     @Log(title = "流程实例管理", businessType = BusinessType.INSERT)
     @RepeatSubmit()

ruoyi-modules/ruoyi-workflow/src/main/java/org/dromara/workflow/controller/FlwSpelController.java

@@ -23,7 +23,7 @@ import org.springframework.web.bind.annotation.*;
 import java.util.List;
 
 /**
- * 流程spel表达式定义
+ * 流程 SpEL 表达式定义控制器，负责表达式规则的增删改查。
  *
  * @author Michelle.Chung
  * @date 2025-07-04
@@ -38,7 +38,11 @@ public class FlwSpelController extends BaseController {
     private final IFlwSpelService flwSpelService;
 
     /**
-     * 查询流程spel表达式定义列表
+     * 分页查询流程 SpEL 表达式定义列表。
+     *
+     * @param bo 查询条件
+     * @param pageQuery 分页参数
+     * @return 表达式分页数据
      */
     @SaCheckPermission("workflow:spel:list")
     @GetMapping("/list")
@@ -47,9 +51,10 @@ public class FlwSpelController extends BaseController {
     }
 
     /**
-     * 获取流程spel表达式定义详细信息
+     * 获取流程 SpEL 表达式定义详情。
      *
      * @param id 主键
+     * @return 表达式详情
      */
     @SaCheckPermission("workflow:spel:query")
     @GetMapping("/{id}")
@@ -58,7 +63,11 @@ public class FlwSpelController extends BaseController {
     }
 
     /**
-     * 新增流程spel表达式定义
+    /**
+     * 新增流程 SpEL 表达式定义。
+     *
+     * @param bo 表达式信息
+     * @return 操作结果
      */
     @SaCheckPermission("workflow:spel:add")
     @Log(title = "流程spel表达式定义", businessType = BusinessType.INSERT)
@@ -69,7 +78,10 @@ public class FlwSpelController extends BaseController {
     }
 
     /**
-     * 修改流程spel表达式定义
+     * 修改流程 SpEL 表达式定义。
+     *
+     * @param bo 表达式信息
+     * @return 操作结果
      */
     @SaCheckPermission("workflow:spel:edit")
     @Log(title = "流程spel表达式定义", businessType = BusinessType.UPDATE)
@@ -80,9 +92,10 @@ public class FlwSpelController extends BaseController {
     }
 
     /**
-     * 删除流程spel表达式定义
+     * 批量删除流程 SpEL 表达式定义。
      *
      * @param ids 主键串
+     * @return 操作结果
      */
     @SaCheckPermission("workflow:spel:remove")
     @Log(title = "流程spel表达式定义", businessType = BusinessType.DELETE)

ruoyi-modules/ruoyi-workflow/src/main/java/org/dromara/workflow/controller/FlwTaskController.java

@@ -38,9 +38,10 @@ public class FlwTaskController extends BaseController {
     private final IFlwTaskService flwTaskService;
 
     /**
-     * 启动任务
+     * 启动流程任务。
      *
      * @param startProcessBo 启动流程参数
+     * @return 启动结果及后续流程信息
      */
     @Log(title = "任务管理", businessType = BusinessType.INSERT)
     @RepeatSubmit()
@@ -51,9 +52,10 @@ public class FlwTaskController extends BaseController {
     }
 
     /**
-     * 办理任务
+     * 办理当前任务节点。
      *
      * @param completeTaskBo 办理任务参数
+     * @return 操作结果
      */
     @Log(title = "任务管理", businessType = BusinessType.INSERT)
     @RepeatSubmit()
@@ -63,10 +65,11 @@ public class FlwTaskController extends BaseController {
     }
 
     /**
-     * 查询当前用户的待办任务
+     * 查询当前用户的待办任务。
      *
      * @param flowTaskBo 参数
      * @param pageQuery  分页
+     * @return 待办任务分页数据
      */
     @GetMapping("/pageByTaskWait")
     public TableDataInfo<FlowTaskVo> pageByTaskWait(FlowTaskBo flowTaskBo, PageQuery pageQuery) {
@@ -74,22 +77,24 @@ public class FlwTaskController extends BaseController {
     }
 
     /**
-     * 查询当前用户的已办任务
+     * 查询当前用户的已办任务。
      *
      * @param flowTaskBo 参数
      * @param pageQuery  分页
+     * @return 已办任务分页数据
      */
-
     @GetMapping("/pageByTaskFinish")
     public TableDataInfo<FlowHisTaskVo> pageByTaskFinish(FlowTaskBo flowTaskBo, PageQuery pageQuery) {
         return flwTaskService.pageByTaskFinish(flowTaskBo, pageQuery);
     }
 
     /**
-     * 查询待办任务
+    /**
+     * 查询全部待办任务。
      *
      * @param flowTaskBo 参数
      * @param pageQuery  分页
+     * @return 待办任务分页数据
      */
     @GetMapping("/pageByAllTaskWait")
     public TableDataInfo<FlowTaskVo> pageByAllTaskWait(FlowTaskBo flowTaskBo, PageQuery pageQuery) {
@@ -97,10 +102,11 @@ public class FlwTaskController extends BaseController {
     }
 
     /**
-     * 查询已办任务
+     * 查询全部已办任务。
      *
      * @param flowTaskBo 参数
      * @param pageQuery  分页
+     * @return 已办任务分页数据
      */
     @GetMapping("/pageByAllTaskFinish")
     public TableDataInfo<FlowHisTaskVo> pageByAllTaskFinish(FlowTaskBo flowTaskBo, PageQuery pageQuery) {
@@ -108,10 +114,11 @@ public class FlwTaskController extends BaseController {
     }
 
     /**
-     * 查询当前用户的抄送
+     * 查询当前用户收到的抄送任务。
      *
      * @param flowTaskBo 参数
      * @param pageQuery  分页
+     * @return 抄送任务分页数据
      */
     @GetMapping("/pageByTaskCopy")
     public TableDataInfo<FlowTaskVo> pageByTaskCopy(FlowTaskBo flowTaskBo, PageQuery pageQuery) {
@@ -119,9 +126,11 @@ public class FlwTaskController extends BaseController {
     }
 
     /**
-     * 根据taskId查询代表任务
+    /**
+     * 根据任务 id 查询任务详情。
      *
      * @param taskId 任务id
+     * @return 任务详情
      */
     @GetMapping("/getTask/{taskId}")
     public R<FlowTaskVo> getTask(@PathVariable Long taskId) {
@@ -129,9 +138,11 @@ public class FlwTaskController extends BaseController {
     }
 
     /**
-     * 获取下一节点信息
+    /**
+     * 获取流程下一节点信息。
      *
      * @param bo 参数
+     * @return 下一节点列表
      */
     @PostMapping("/getNextNodeList")
     public R<List<FlowNode>> getNextNodeList(@RequestBody FlowNextNodeBo bo) {
@@ -139,9 +150,11 @@ public class FlwTaskController extends BaseController {
     }
 
     /**
-     * 终止任务
+    /**
+     * 终止流程任务。
      *
      * @param bo 参数
+     * @return 处理结果
      */
     @Log(title = "任务管理", businessType = BusinessType.INSERT)
     @RepeatSubmit()
@@ -151,10 +164,11 @@ public class FlwTaskController extends BaseController {
     }
 
     /**
-     * 任务操作
+     * 执行任务操作，例如委派、转办、加签或减签。
      *
      * @param bo            参数
      * @param taskOperation 操作类型，委派 delegateTask、转办 transferTask、加签 addSignature、减签 reductionSignature
+     * @return 操作结果
      */
     @Log(title = "任务管理", businessType = BusinessType.UPDATE)
     @RepeatSubmit
@@ -164,10 +178,11 @@ public class FlwTaskController extends BaseController {
     }
 
     /**
-     * 修改任务办理人
+     * 批量修改任务办理人。
      *
      * @param taskIdList 任务id
      * @param userId     办理人id
+     * @return 操作结果
      */
     @Log(title = "任务管理", businessType = BusinessType.UPDATE)
     @RepeatSubmit()
@@ -177,9 +192,10 @@ public class FlwTaskController extends BaseController {
     }
 
     /**
-     * 驳回审批
+     * 驳回审批到前置节点。
      *
      * @param bo 参数
+     * @return 操作结果
      */
     @Log(title = "任务管理", businessType = BusinessType.INSERT)
     @RepeatSubmit()
@@ -189,10 +205,11 @@ public class FlwTaskController extends BaseController {
     }
 
     /**
-     * 获取可驳回的前置节点
+     * 获取当前任务可驳回的前置节点。
      *
      * @param taskId       任务id
      * @param nowNodeCode  当前节点
+     * @return 可驳回节点列表
      */
     @GetMapping("/getBackTaskNode/{taskId}/{nowNodeCode}")
     public R<List<Node>> getBackTaskNode(@PathVariable Long taskId, @PathVariable String nowNodeCode) {
@@ -200,9 +217,11 @@ public class FlwTaskController extends BaseController {
     }
 
     /**
-     * 获取当前任务的所有办理人
+    /**
+     * 获取当前任务的所有办理人。
      *
      * @param taskId 任务id
+     * @return 办理人列表
      */
     @GetMapping("/currentTaskAllUser/{taskId}")
     public R<List<UserDTO>> currentTaskAllUser(@PathVariable Long taskId) {
@@ -210,7 +229,7 @@ public class FlwTaskController extends BaseController {
     }
 
     /**
-     * 催办任务
+     * 催办任务。
      *
      * @param bo 参数
      * @return 结果
@@ -220,6 +239,4 @@ public class FlwTaskController extends BaseController {
     public R<Void> urgeTask(@RequestBody FlowUrgeTaskBo bo) {
         return toAjax(flwTaskService.urgeTask(bo));
     }
-
-
 }

ruoyi-modules/ruoyi-workflow/src/main/java/org/dromara/workflow/controller/TestLeaveController.java

@@ -25,7 +25,7 @@ import org.springframework.web.bind.annotation.*;
 import java.util.List;
 
 /**
- * 请假
+ * 请假示例控制器，演示业务单据与流程引擎联动的典型用法。
  *
  * @author may
  * @date 2023-07-21
@@ -40,7 +40,11 @@ public class TestLeaveController extends BaseController {
     private final ITestLeaveService testLeaveService;
 
     /**
-     * 查询请假列表
+     * 分页查询请假列表。
+     *
+     * @param bo 查询条件
+     * @param pageQuery 分页参数
+     * @return 请假分页数据
      */
     @SaCheckPermission("workflow:leave:list")
     @GetMapping("/list")
@@ -49,7 +53,11 @@ public class TestLeaveController extends BaseController {
     }
 
     /**
-     * 导出请假列表
+    /**
+     * 导出请假列表。
+     *
+     * @param bo 查询条件
+     * @param response 响应流
      */
     @SaCheckPermission("workflow:leave:export")
     @Log(title = "请假", businessType = BusinessType.EXPORT)
@@ -60,9 +68,10 @@ public class TestLeaveController extends BaseController {
     }
 
     /**
-     * 获取请假详细信息
+     * 获取请假单详情。
      *
      * @param id 主键
+     * @return 请假详情
      */
     @SaCheckPermission("workflow:leave:query")
     @GetMapping("/{id}")
@@ -72,7 +81,10 @@ public class TestLeaveController extends BaseController {
     }
 
     /**
-     * 新增请假
+     * 新增请假单。
+     *
+     * @param bo 请假信息
+     * @return 新增后的请假单
      */
     @SaCheckPermission("workflow:leave:add")
     @Log(title = "请假", businessType = BusinessType.INSERT)
@@ -83,7 +95,10 @@ public class TestLeaveController extends BaseController {
     }
 
     /**
-     * 提交请假并提交流程
+     * 提交请假单并同步发起流程。
+     *
+     * @param bo 请假信息
+     * @return 提交后的请假单
      */
     @SaCheckPermission("workflow:leave:add")
     @Log(title = "请假", businessType = BusinessType.INSERT)
@@ -94,7 +109,10 @@ public class TestLeaveController extends BaseController {
     }
 
     /**
-     * 修改请假
+     * 修改请假单。
+     *
+     * @param bo 请假信息
+     * @return 修改后的请假单
      */
     @SaCheckPermission("workflow:leave:edit")
     @Log(title = "请假", businessType = BusinessType.UPDATE)
@@ -105,9 +123,10 @@ public class TestLeaveController extends BaseController {
     }
 
     /**
-     * 删除请假
+     * 批量删除请假单。
      *
      * @param ids 主键串
+     * @return 操作结果
      */
     @SaCheckPermission("workflow:leave:remove")
     @Log(title = "请假", businessType = BusinessType.DELETE)

ruoyi-modules/ruoyi-workflow/src/main/java/org/dromara/workflow/domain/bo/FlowCancelBo.java

@@ -8,7 +8,7 @@ import java.io.Serial;
 import java.io.Serializable;
 
 /**
- * 撤销任务请求对象
+ * 撤销流程请求对象。
  *
  * @author may
  */

ruoyi-modules/ruoyi-workflow/src/main/java/org/dromara/workflow/domain/bo/FlowCopyBo.java

@@ -7,7 +7,7 @@ import java.io.Serializable;
 
 
 /**
- * 抄送
+ * 流程抄送请求对象。
  *
  * @author may
  */

ruoyi-modules/ruoyi-workflow/src/main/java/org/dromara/workflow/domain/bo/FlowInstanceBo.java

@@ -7,7 +7,7 @@ import java.io.Serializable;
 import java.util.List;
 
 /**
- * 流程实例请求对象
+ * 流程实例查询条件对象。
  *
  * @author may
  */

ruoyi-modules/ruoyi-workflow/src/main/java/org/dromara/workflow/domain/bo/FlowInvalidBo.java

@@ -8,7 +8,7 @@ import java.io.Serial;
 import java.io.Serializable;
 
 /**
- * 作废请求对象
+ * 作废流程请求对象。
  *
  * @author may
  */

ruoyi-modules/ruoyi-workflow/src/main/java/org/dromara/workflow/domain/bo/FlowNextNodeBo.java

@@ -9,7 +9,7 @@ import java.util.Map;
 import java.util.Objects;
 
 /**
- * 下一节点信息
+ * 查询下一节点信息的请求对象。
  *
  * @author may
  */
@@ -28,6 +28,11 @@ public class FlowNextNodeBo implements Serializable {
      */
     private Map<String, Object> variables;
 
+    /**
+     * 获取流程变量并自动剔除空值。
+     *
+     * @return 流程变量
+     */
     public Map<String, Object> getVariables() {
         if (variables == null) {
             variables = new HashMap<>(16);

ruoyi-modules/ruoyi-workflow/src/main/java/org/dromara/workflow/domain/vo/ButtonPermissionVo.java

@@ -6,7 +6,7 @@ import java.io.Serial;
 import java.io.Serializable;
 
 /**
- * 按钮权限
+ * 按钮权限视图对象。
  *
  * @author may
  * @date 2025-02-28
@@ -32,9 +32,18 @@ public class ButtonPermissionVo implements Serializable {
      */
     private Boolean show;
 
+    /**
+     * 无参构造方法。
+     */
     public ButtonPermissionVo() {
     }
 
+    /**
+     * 使用按钮编码和显示状态构造按钮权限对象。
+     *
+     * @param code 按钮编码
+     * @param show 是否显示
+     */
     public ButtonPermissionVo(String code, Boolean show) {
         this.code = code;
         this.show = show;

ruoyi-modules/ruoyi-workflow/src/main/java/org/dromara/workflow/domain/vo/FlowCopyVo.java

@@ -8,7 +8,7 @@ import java.io.Serial;
 import java.io.Serializable;
 
 /**
- * 抄送对象
+ * 流程抄送视图对象。
  *
  * @author AprilWind
  */
@@ -29,6 +29,11 @@ public class FlowCopyVo implements Serializable {
     @Translation(type = TransConstant.USER_ID_TO_NICKNAME, mapper = "userId")
     private String nickName;
 
+    /**
+     * 使用用户 ID 构造抄送对象。
+     *
+     * @param userId 用户ID
+     */
     public FlowCopyVo(Long userId) {
         this.userId = userId;
     }

ruoyi-modules/ruoyi-workflow/src/main/java/org/dromara/workflow/domain/vo/FlowInstanceVo.java

@@ -8,13 +8,16 @@ import org.dromara.workflow.common.constant.FlowConstant;
 import java.util.Date;
 
 /**
- * 流程实例视图
+ * 流程实例视图对象。
  *
  * @author may
  */
 @Data
 public class FlowInstanceVo {
 
+    /**
+     * 流程实例ID。
+     */
     private Long id;
 
     /**

ruoyi-modules/ruoyi-workflow/src/main/java/org/dromara/workflow/domain/vo/FlowTaskVo.java

@@ -14,7 +14,7 @@ import java.util.List;
 import java.util.Map;
 
 /**
- * 任务视图
+ * 流程任务视图对象。
  *
  * @author may
  */
@@ -24,6 +24,9 @@ public class FlowTaskVo implements Serializable {
     @Serial
     private static final long serialVersionUID = 1L;
 
+    /**
+     * 任务ID。
+     */
     private Long id;
 
     /**
@@ -207,6 +210,11 @@ public class FlowTaskVo implements Serializable {
     private String businessTitle;
     //业务扩展信息结束
 
+    /**
+     * 获取友好格式的创建时间。
+     *
+     * @return 格式化后的创建时间
+     */
     public String getCreateTime() {
         return DateUtils.formatFriendlyTime(createTime);
     }

ruoyi-modules/ruoyi-workflow/src/main/java/org/dromara/workflow/handler/WorkflowPermissionHandler.java

@@ -34,6 +34,8 @@ public class WorkflowPermissionHandler implements PermissionHandler {
      * 办理人权限标识，比如用户，角色，部门等，用于校验是否有权限办理任务
      * 后续在{@link FlowParams#getPermissionFlag}  中获取
      * 返回当前用户权限集合
+     *
+     * @return 当前用户权限集合
      */
     @Override
     public List<String> permissions() {
@@ -51,7 +53,10 @@ public class WorkflowPermissionHandler implements PermissionHandler {
     }
 
     /**
-     * 转换办理人，比如设计器中预设了能办理的人，如果其中包含角色或者部门id等，可以通过此接口进行转换成用户id
+     * 将预设办理人转换为实际用户 ID 列表。
+     *
+     * @param permissions 预设权限标识列表
+     * @return 用户 ID 列表
      */
     @Override
     public List<String> convertPermissions(List<String> permissions) {

ruoyi-modules/ruoyi-workflow/src/main/java/org/dromara/workflow/listener/WorkflowGlobalListener.java

@@ -37,7 +37,7 @@ import java.util.Map;
 import java.util.Set;
 
 /**
- * 全局任务办理监听
+ * 工作流全局监听器，处理任务流转中的扩展变量、消息和事件发布。
  *
  * @author may
  */
@@ -55,7 +55,7 @@ public class WorkflowGlobalListener implements GlobalListener {
     private final UserService userService;
 
     /**
-     * 创建监听器，任务创建时执行
+     * 任务创建回调，当前预留扩展。
      *
      * @param listenerVariable 监听器变量
      */
@@ -65,7 +65,7 @@ public class WorkflowGlobalListener implements GlobalListener {
     }
 
     /**
-     * 开始监听器，任务开始办理时执行
+     * 任务开始办理时解析节点扩展配置。
      *
      * @param listenerVariable 监听器变量
      */
@@ -98,7 +98,7 @@ public class WorkflowGlobalListener implements GlobalListener {
     }
 
     /**
-     * 分派监听器，动态修改代办任务信息
+     * 任务分派时动态调整办理权限。
      *
      * @param listenerVariable 监听器变量
      */
@@ -166,7 +166,7 @@ public class WorkflowGlobalListener implements GlobalListener {
     }
 
     /**
-     * 完成监听器，当前任务完成后执行
+     * 任务完成后发布流程事件并处理抄送和通知。
      *
      * @param listenerVariable 监听器变量
      */

ruoyi-modules/ruoyi-workflow/src/main/java/org/dromara/workflow/rule/SpelRuleComponent.java

@@ -25,7 +25,10 @@ public class SpelRuleComponent {
     private final DeptService deptService;
 
     /**
-     * 通过发起人部门id获取部门负责人
+     * 通过发起人部门 ID 获取部门负责人。
+     *
+     * @param initiatorDeptId 发起人部门 ID
+     * @return 部门负责人用户 ID
      */
     public Long selectDeptLeaderById(Long initiatorDeptId) {
         Long leaderId = deptService.selectDeptLeaderById(initiatorDeptId);

ruoyi-modules/ruoyi-workflow/src/main/java/org/dromara/workflow/service/IFlwDefinitionService.java

@@ -39,7 +39,7 @@ public interface IFlwDefinitionService {
      * 发布流程定义
      *
      * @param id 流程定义id
-     * @return 结果
+     * @return 是否发布成功
      */
     boolean publish(Long id);
 
@@ -57,7 +57,7 @@ public interface IFlwDefinitionService {
      *
      * @param file     文件
      * @param category 分类
-     * @return 结果
+     * @return 是否导入成功
      */
     boolean importJson(MultipartFile file, String category);
 
@@ -65,7 +65,7 @@ public interface IFlwDefinitionService {
      * 删除流程定义
      *
      * @param ids 流程定义id
-     * @return 结果
+     * @return 是否删除成功
      */
     boolean removeDef(List<Long> ids);
 

ruoyi-modules/ruoyi-workflow/src/main/java/org/dromara/workflow/service/IFlwInstanceService.java

@@ -38,7 +38,7 @@ public interface IFlwInstanceService {
     TableDataInfo<FlowInstanceVo> selectFinishInstanceList(FlowInstanceBo flowInstanceBo, PageQuery pageQuery);
 
     /**
-     * 根据业务id查询流程实例详细信息
+     * 根据业务 id 查询流程实例详情，返回业务侧展示所需信息。
      *
      * @param businessId 业务id
      * @return 结果
@@ -46,7 +46,7 @@ public interface IFlwInstanceService {
     FlowInstanceVo queryByBusinessId(Long businessId);
 
     /**
-     * 按照业务id查询流程实例
+     * 按业务 id 查询底层流程实例实体。
      *
      * @param businessId 业务id
      * @return 结果
@@ -54,7 +54,7 @@ public interface IFlwInstanceService {
     FlowInstance selectInstByBusinessId(String businessId);
 
     /**
-     * 按照实例id查询流程实例
+     * 按实例 id 查询单个流程实例实体。
      *
      * @param instanceId 实例id
      * @return 结果
@@ -62,7 +62,7 @@ public interface IFlwInstanceService {
     FlowInstance selectInstById(Long instanceId);
 
     /**
-     * 按照实例id查询流程实例
+     * 按实例 id 集合批量查询流程实例。
      *
      * @param instanceIds 实例id
      * @return 结果
@@ -111,7 +111,7 @@ public interface IFlwInstanceService {
     TableDataInfo<FlowInstanceVo> selectCurrentInstanceList(FlowInstanceBo instanceBo, PageQuery pageQuery);
 
     /**
-     * 获取流程图,流程记录
+     * 获取流程图及历史办理记录，供前端展示流转轨迹。
      *
      * @param businessId 业务id
      * @return 结果
@@ -127,7 +127,7 @@ public interface IFlwInstanceService {
     void updateStatus(Long instanceId, String status);
 
     /**
-     * 获取流程变量
+     * 获取指定实例当前持有的流程变量。
      *
      * @param instanceId 实例id
      * @return 结果
@@ -135,7 +135,7 @@ public interface IFlwInstanceService {
     Map<String, Object> instanceVariable(Long instanceId);
 
     /**
-     * 更新流程变量
+     * 更新流程变量，支持在运行中修正流程上下文数据。
      *
      * @param bo 参数
      * @return 结果
@@ -143,7 +143,7 @@ public interface IFlwInstanceService {
     boolean updateVariable(FlowVariableBo bo);
 
     /**
-     * 设置流程变量
+     * 为指定流程实例设置变量集合。
      *
      * @param instanceId 实例id
      * @param variable   流程变量
@@ -151,7 +151,7 @@ public interface IFlwInstanceService {
     void setVariable(Long instanceId, Map<String, Object> variable);
 
     /**
-     * 按任务id查询实例
+     * 按任务 id 反查所属流程实例。
      *
      * @param taskId 任务id
      * @return 结果

ruoyi-modules/ruoyi-workflow/src/main/java/org/dromara/workflow/service/IFlwSpelService.java

@@ -12,7 +12,7 @@ import java.util.List;
 import java.util.Map;
 
 /**
- * 流程spel表达式定义Service接口
+ * 流程 SpEL 表达式定义服务接口，负责表达式规则管理与动态指派解析。
  *
  * @author Michelle.Chung
  * @date 2025-07-04
@@ -20,7 +20,7 @@ import java.util.Map;
 public interface IFlwSpelService {
 
     /**
-     * 查询流程spel表达式定义
+     * 根据主键查询流程 SpEL 表达式定义。
      *
      * @param id 主键
      * @return 流程spel表达式定义
@@ -37,7 +37,7 @@ public interface IFlwSpelService {
     TableDataInfo<FlowSpelVo> queryPageList(FlowSpelBo bo, PageQuery pageQuery);
 
     /**
-     * 查询符合条件的流程spel表达式定义列表
+     * 查询符合条件的流程 SpEL 表达式定义列表。
      *
      * @param bo 查询条件
      * @return 流程spel表达式定义列表
@@ -45,7 +45,7 @@ public interface IFlwSpelService {
     List<FlowSpelVo> queryList(FlowSpelBo bo);
 
     /**
-     * 新增流程spel表达式定义
+     * 新增流程 SpEL 表达式定义。
      *
      * @param bo 流程spel表达式定义
      * @return 是否新增成功
@@ -53,7 +53,7 @@ public interface IFlwSpelService {
     Boolean insertByBo(FlowSpelBo bo);
 
     /**
-     * 修改流程spel表达式定义
+     * 修改流程 SpEL 表达式定义。
      *
      * @param bo 流程spel表达式定义
      * @return 是否修改成功
@@ -70,7 +70,7 @@ public interface IFlwSpelService {
     Boolean deleteWithValidByIds(Collection<Long> ids, Boolean isValid);
 
     /**
-     * 查询spel并返回任务指派的列表，支持分页
+     * 按任务指派条件解析 SpEL，并返回可用办理人列表。
      *
      * @param taskQuery 查询条件
      * @return 办理人

ruoyi-modules/ruoyi-workflow/src/main/java/org/dromara/workflow/service/IFlwTaskService.java

@@ -51,7 +51,7 @@ public interface IFlwTaskService {
      *
      * @param flowTaskBo 参数
      * @param pageQuery  分页
-     * @return 结果
+     * @return 当前用户待办任务分页结果
      */
     TableDataInfo<FlowTaskVo> pageByTaskWait(FlowTaskBo flowTaskBo, PageQuery pageQuery);
 
@@ -60,7 +60,7 @@ public interface IFlwTaskService {
      *
      * @param flowTaskBo 参数
      * @param pageQuery  分页
-     * @return 结果
+     * @return 当前用户已办任务分页结果
      */
     TableDataInfo<FlowHisTaskVo> pageByTaskFinish(FlowTaskBo flowTaskBo, PageQuery pageQuery);
 
@@ -69,7 +69,7 @@ public interface IFlwTaskService {
      *
      * @param flowTaskBo 参数
      * @param pageQuery  分页
-     * @return 结果
+     * @return 当前租户待办任务分页结果
      */
     TableDataInfo<FlowTaskVo> pageByAllTaskWait(FlowTaskBo flowTaskBo, PageQuery pageQuery);
 
@@ -78,7 +78,7 @@ public interface IFlwTaskService {
      *
      * @param flowTaskBo 参数
      * @param pageQuery  分页
-     * @return 结果
+     * @return 当前租户已办任务分页结果
      */
     TableDataInfo<FlowHisTaskVo> pageByAllTaskFinish(FlowTaskBo flowTaskBo, PageQuery pageQuery);
 
@@ -87,7 +87,7 @@ public interface IFlwTaskService {
      *
      * @param flowTaskBo 参数
      * @param pageQuery  分页
-     * @return 结果
+     * @return 当前用户抄送分页结果
      */
     TableDataInfo<FlowTaskVo> pageByTaskCopy(FlowTaskBo flowTaskBo, PageQuery pageQuery);
 
@@ -129,7 +129,7 @@ public interface IFlwTaskService {
      * 按照任务id查询任务
      *
      * @param taskIdList 任务id
-     * @return 结果
+     * @return 任务列表
      */
     List<FlowTask> selectByIdList(List<Long> taskIdList);
 
@@ -137,7 +137,7 @@ public interface IFlwTaskService {
      * 按照任务id查询任务
      *
      * @param taskId 任务id
-     * @return 结果
+     * @return 任务详情
      */
     FlowTaskVo selectById(Long taskId);
 
@@ -145,7 +145,7 @@ public interface IFlwTaskService {
      * 获取下一节点信息
      *
      * @param bo 参数
-     * @return 结果
+     * @return 下一节点列表
      */
     List<FlowNode> getNextNodeList(FlowNextNodeBo bo);
 
@@ -153,7 +153,7 @@ public interface IFlwTaskService {
      * 按照任务id查询任务
      *
      * @param taskId 任务id
-     * @return 结果
+     * @return 历史任务详情
      */
     FlowHisTask selectHisTaskById(Long taskId);
 
@@ -161,7 +161,7 @@ public interface IFlwTaskService {
      * 按照实例id查询任务
      *
      * @param instanceId 流程实例id
-     * @return 结果
+     * @return 任务列表
      */
     List<FlowTask> selectByInstId(Long instanceId);
 
@@ -169,7 +169,7 @@ public interface IFlwTaskService {
      * 按照实例id查询任务
      *
      * @param instanceIds 列表
-     * @return 结果
+     * @return 任务列表
      */
     List<FlowTask> selectByInstIds(List<Long> instanceIds);
 
@@ -194,7 +194,7 @@ public interface IFlwTaskService {
      * 获取当前任务的所有办理人
      *
      * @param taskIds 任务id
-     * @return 结果
+     * @return 办理人列表
      */
     List<UserDTO> currentTaskAllUser(List<Long> taskIds);
 
@@ -211,7 +211,7 @@ public interface IFlwTaskService {
      * 催办任务
      *
      * @param bo 参数
-     * @return 结果
+     * @return 是否催办成功
      */
     boolean urgeTask(FlowUrgeTaskBo bo);
 }

ruoyi-modules/ruoyi-workflow/src/main/java/org/dromara/workflow/service/ITestLeaveService.java

@@ -8,7 +8,7 @@ import org.dromara.workflow.domain.vo.TestLeaveVo;
 import java.util.List;
 
 /**
- * 请假Service接口
+ * 请假示例服务接口，定义请假单查询、维护与流程发起能力。
  *
  * @author may
  * @date 2023-07-21
@@ -16,37 +16,59 @@ import java.util.List;
 public interface ITestLeaveService {
 
     /**
-     * 查询请假
+     * 根据主键查询请假单。
+     *
+     * @param id 主键
+     * @return 请假详情
      */
     TestLeaveVo queryById(Long id);
 
     /**
-     * 查询请假列表
+     * 分页查询请假列表。
+     *
+     * @param bo 查询条件
+     * @param pageQuery 分页参数
+     * @return 请假分页数据
      */
     TableDataInfo<TestLeaveVo> queryPageList(TestLeaveBo bo, PageQuery pageQuery);
 
     /**
-     * 查询请假列表
+     * 查询符合条件的请假列表。
+     *
+     * @param bo 查询条件
+     * @return 请假列表
      */
     List<TestLeaveVo> queryList(TestLeaveBo bo);
 
     /**
-     * 新增请假
+     * 新增请假单。
+     *
+     * @param bo 请假信息
+     * @return 新增结果
      */
     TestLeaveVo insertByBo(TestLeaveBo bo);
 
     /**
-     * 提交请假并发起流程
+     * 提交请假单并发起审批流程。
+     *
+     * @param bo 请假信息
+     * @return 提交结果
      */
     TestLeaveVo submitAndFlowStart(TestLeaveBo bo);
 
     /**
-     * 修改请假
+     * 修改请假单。
+     *
+     * @param bo 请假信息
+     * @return 修改结果
      */
     TestLeaveVo updateByBo(TestLeaveBo bo);
 
     /**
-     * 校验并批量删除请假信息
+     * 校验并批量删除请假信息。
+     *
+     * @param ids 主键集合
+     * @return 删除结果
      */
     Boolean deleteWithValidByIds(List<Long> ids);
 }

ruoyi-modules/ruoyi-workflow/src/main/java/org/dromara/workflow/service/impl/CategoryNameTranslationImpl.java

@@ -24,6 +24,13 @@ public class CategoryNameTranslationImpl implements TranslationInterface<String>
 
     private final IFlwCategoryService flwCategoryService;
 
+    /**
+     * 将流程分类 ID 翻译为分类名称。
+     *
+     * @param key 分类 ID
+     * @param other 额外参数
+     * @return 分类名称
+     */
     @Override
     public String translation(Object key, String other) {
         return flwCategoryService.selectCategoryNameById(Convert.toLong(key));

ruoyi-modules/ruoyi-workflow/src/main/java/org/dromara/workflow/service/impl/FlwCategoryServiceImpl.java

@@ -161,6 +161,12 @@ public class FlwCategoryServiceImpl implements IFlwCategoryService, CategoryServ
             .eq(FlowCategory::getParentId, categoryId));
     }
 
+    /**
+     * 构建流程分类查询条件。
+     *
+     * @param bo 查询条件
+     * @return 查询条件包装器
+     */
     private LambdaQueryWrapper<FlowCategory> buildQueryWrapper(FlowCategoryBo bo) {
         LambdaQueryWrapper<FlowCategory> lqw = Wrappers.lambdaQuery();
         lqw.eq(FlowCategory::getDelFlag, SystemConstants.NORMAL);

ruoyi-modules/ruoyi-workflow/src/main/java/org/dromara/workflow/service/impl/FlwChartExtServiceImpl.java

@@ -260,7 +260,7 @@ public class FlwChartExtServiceImpl implements ChartExtService {
      * 根据流程实例ID获取历史任务列表
      *
      * @param instanceId 流程实例ID
-     * @return 历史任务列表
+     * @return 按更新时间倒序排列的审批历史任务列表
      */
     public List<FlowHisTask> getHisTaskGroupedByNode(Long instanceId) {
         LambdaQueryWrapper<FlowHisTask> wrapper = Wrappers.lambdaQuery();

ruoyi-modules/ruoyi-workflow/src/main/java/org/dromara/workflow/service/impl/FlwDefinitionServiceImpl.java

@@ -93,6 +93,12 @@ public class FlwDefinitionServiceImpl implements IFlwDefinitionService {
         return new TableDataInfo<>(list, page.getTotal());
     }
 
+    /**
+     * 构造流程定义分页查询条件。
+     *
+     * @param flowDefinition 页面传入的流程定义筛选条件
+     * @return 叠加流程编码、名称、分类以及排序条件后的查询包装器
+     */
     private LambdaQueryWrapper<FlowDefinition> buildQueryWrapper(FlowDefinition flowDefinition) {
         LambdaQueryWrapper<FlowDefinition> wrapper = Wrappers.lambdaQuery();
         wrapper.like(StringUtils.isNotBlank(flowDefinition.getFlowCode()), FlowDefinition::getFlowCode, flowDefinition.getFlowCode());
@@ -109,6 +115,7 @@ public class FlwDefinitionServiceImpl implements IFlwDefinitionService {
      * 发布流程定义
      *
      * @param id 流程定义id
+     * @return 发布成功返回 {@code true}
      */
     @Override
     @Transactional(rollbackFor = Exception.class)
@@ -132,7 +139,9 @@ public class FlwDefinitionServiceImpl implements IFlwDefinitionService {
     /**
      * 导入流程定义
      *
-     * @param file 文件
+     * @param file     流程定义 Json 文件
+     * @param category 导入后绑定的流程分类
+     * @return 导入成功返回 {@code true}
      */
     @Override
     @Transactional(rollbackFor = Exception.class)
@@ -152,7 +161,7 @@ public class FlwDefinitionServiceImpl implements IFlwDefinitionService {
      * 导出流程定义
      *
      * @param id       流程定义id
-     * @param response 响应
+     * @param response HTTP 响应对象，用于输出定义 Json 内容
      * @throws IOException 异常
      */
     @Override
@@ -171,6 +180,7 @@ public class FlwDefinitionServiceImpl implements IFlwDefinitionService {
      * 删除流程定义
      *
      * @param ids 流程定义id
+     * @return 删除成功返回 {@code true}
      */
     @Override
     @Transactional(rollbackFor = Exception.class)

ruoyi-modules/ruoyi-workflow/src/main/java/org/dromara/workflow/service/impl/FlwInstanceServiceImpl.java

@@ -80,6 +80,7 @@ public class FlwInstanceServiceImpl implements IFlwInstanceService {
      *
      * @param flowInstanceBo 流程实例
      * @param pageQuery      分页
+     * @return 当前符合条件的运行中流程实例分页结果
      */
     @Override
     public TableDataInfo<FlowInstanceVo> selectRunningInstanceList(FlowInstanceBo flowInstanceBo, PageQuery pageQuery) {
@@ -94,6 +95,7 @@ public class FlwInstanceServiceImpl implements IFlwInstanceService {
      *
      * @param flowInstanceBo 流程实例
      * @param pageQuery      分页
+     * @return 当前符合条件的已结束流程实例分页结果
      */
     @Override
     public TableDataInfo<FlowInstanceVo> selectFinishInstanceList(FlowInstanceBo flowInstanceBo, PageQuery pageQuery) {
@@ -179,6 +181,7 @@ public class FlwInstanceServiceImpl implements IFlwInstanceService {
      * 根据业务id查询流程实例
      *
      * @param businessId 业务id
+     * @return 对应的流程实例，不存在时返回 {@code null}
      */
     @Override
     public FlowInstance selectInstByBusinessId(String businessId) {
@@ -189,6 +192,7 @@ public class FlwInstanceServiceImpl implements IFlwInstanceService {
      * 按照实例id查询流程实例
      *
      * @param instanceId 实例id
+     * @return 实例详情，不存在时返回 {@code null}
      */
     @Override
     public FlowInstance selectInstById(Long instanceId) {
@@ -199,6 +203,7 @@ public class FlwInstanceServiceImpl implements IFlwInstanceService {
      * 按照实例id查询流程实例
      *
      * @param instanceIds 实例id
+     * @return 实例列表
      */
     @Override
     public List<FlowInstance> selectInstListByIdList(List<Long> instanceIds) {
@@ -209,6 +214,7 @@ public class FlwInstanceServiceImpl implements IFlwInstanceService {
      * 按照业务id删除流程实例
      *
      * @param businessIds 业务id
+     * @return 删除成功返回 {@code true}，未找到实例时返回 {@code false}
      */
     @Override
     @Transactional(rollbackFor = Exception.class)
@@ -225,6 +231,7 @@ public class FlwInstanceServiceImpl implements IFlwInstanceService {
      * 按照实例id删除流程实例
      *
      * @param instanceIds 实例id
+     * @return 删除成功返回 {@code true}，未找到实例时返回 {@code false}
      */
     @Override
     @Transactional(rollbackFor = Exception.class)
@@ -259,6 +266,7 @@ public class FlwInstanceServiceImpl implements IFlwInstanceService {
      * 按照实例id删除已完成的流程实例
      *
      * @param instanceIds 实例id
+     * @return 删除成功返回 {@code true}，未找到实例时返回 {@code false}
      */
     @Override
     @Transactional(rollbackFor = Exception.class)
@@ -298,6 +306,7 @@ public class FlwInstanceServiceImpl implements IFlwInstanceService {
      * 撤销流程
      *
      * @param bo 参数
+     * @return 撤销成功返回 {@code true}
      */
     @Override
     @Transactional(rollbackFor = Exception.class)
@@ -328,6 +337,7 @@ public class FlwInstanceServiceImpl implements IFlwInstanceService {
      *
      * @param instanceBo 流程实例
      * @param pageQuery  分页
+     * @return 当前登录人发起的流程实例分页结果
      */
     @Override
     public TableDataInfo<FlowInstanceVo> selectCurrentInstanceList(FlowInstanceBo instanceBo, PageQuery pageQuery) {
@@ -341,6 +351,7 @@ public class FlwInstanceServiceImpl implements IFlwInstanceService {
      * 获取流程图,流程记录
      *
      * @param businessId 业务id
+     * @return 包含流程记录列表和实例 id 的结果集
      */
     @Override
     public Map<String, Object> flowHisTaskList(String businessId) {
@@ -410,6 +421,7 @@ public class FlwInstanceServiceImpl implements IFlwInstanceService {
      * 获取流程变量
      *
      * @param instanceId 实例id
+     * @return 变量明细列表及原始变量字符串
      */
     @Override
     public Map<String, Object> instanceVariable(Long instanceId) {
@@ -428,6 +440,7 @@ public class FlwInstanceServiceImpl implements IFlwInstanceService {
      * 设置流程变量
      *
      * @param bo 参数
+     * @return 更新成功返回 {@code true}
      */
     @Override
     @Transactional(rollbackFor = Exception.class)
@@ -465,6 +478,7 @@ public class FlwInstanceServiceImpl implements IFlwInstanceService {
      * 按任务id查询实例
      *
      * @param taskId 任务id
+     * @return 任务关联的流程实例，运行中任务不存在时回退查询历史任务
      */
     @Override
     public FlowInstance selectByTaskId(Long taskId) {
@@ -484,6 +498,7 @@ public class FlwInstanceServiceImpl implements IFlwInstanceService {
      * 作废流程
      *
      * @param bo 参数
+     * @return 作废成功返回 {@code true}
      */
     @Override
     @Transactional(rollbackFor = Exception.class)

ruoyi-modules/ruoyi-workflow/src/main/java/org/dromara/workflow/service/impl/FlwNodeExtServiceImpl.java

@@ -275,6 +275,9 @@ public class FlwNodeExtServiceImpl implements NodeExtService, IFlwNodeExtService
 
     /**
      * 按逗号分割字符串，但保留 #{...} 表达式和字符串常量中的逗号
+     *
+     * @param str 原始配置字符串
+     * @return 智能分割后的片段列表
      */
     private static List<String> spelSmartSplit(String str) {
         List<String> result = new ArrayList<>();
@@ -347,6 +350,14 @@ public class FlwNodeExtServiceImpl implements NodeExtService, IFlwNodeExtService
         return result;
     }
 
+    /**
+     * 判断指定位置的下一个字符是否匹配预期字符。
+     *
+     * @param str      原始字符串
+     * @param index    当前索引
+     * @param expected 期望匹配的字符
+     * @return 匹配成功返回 {@code true}
+     */
     private static boolean checkNext(String str, int index, char expected) {
         return index + 1 < str.length() && str.charAt(index + 1) == expected;
     }

ruoyi-modules/ruoyi-workflow/src/main/java/org/dromara/workflow/service/impl/FlwSpelServiceImpl.java

@@ -80,6 +80,12 @@ public class FlwSpelServiceImpl implements IFlwSpelService {
         return baseMapper.selectVoList(lqw);
     }
 
+    /**
+     * 组装 SpEL 表达式列表查询条件。
+     *
+     * @param bo 页面筛选参数
+     * @return 包含排序和筛选条件的查询包装器
+     */
     private LambdaQueryWrapper<FlowSpel> buildQueryWrapper(FlowSpelBo bo) {
         Map<String, Object> params = bo.getParams();
         LambdaQueryWrapper<FlowSpel> lqw = Wrappers.lambdaQuery();
@@ -125,6 +131,8 @@ public class FlwSpelServiceImpl implements IFlwSpelService {
 
     /**
      * 保存前的数据校验
+     *
+     * @param entity 待保存的 SpEL 表达式实体
      */
     private void validEntityBeforeSave(FlowSpel entity){
         if (StringUtils.isNotBlank(entity.getViewSpel())) {

ruoyi-modules/ruoyi-workflow/src/main/java/org/dromara/workflow/service/impl/FlwTaskAssigneeServiceImpl.java

@@ -119,7 +119,11 @@ public class FlwTaskAssigneeServiceImpl implements IFlwTaskAssigneeService, Hand
     }
 
     /**
-     * 根据任务办理类型查询对应的数据
+     * 根据办理人类型查询右侧候选数据。
+     *
+     * @param type 办理人类型
+     * @param taskQuery 查询条件
+     * @return 办理人数据
      */
     private TaskAssigneeDTO fetchTaskAssigneeData(TaskAssigneeEnum type, TaskAssigneeBody taskQuery) {
         return switch (type) {
@@ -132,7 +136,10 @@ public class FlwTaskAssigneeServiceImpl implements IFlwTaskAssigneeService, Hand
     }
 
     /**
-     * 根据任务办理类型获取部门数据
+     * 根据办理人类型获取部门树数据源。
+     *
+     * @param type 办理人类型
+     * @return 部门列表
      */
     private List<DeptDTO> fetchDeptData(TaskAssigneeEnum type) {
         if (type.needsDeptService()) {
@@ -159,7 +166,10 @@ public class FlwTaskAssigneeServiceImpl implements IFlwTaskAssigneeService, Hand
     }
 
     /**
-     * 构建部门树状结构
+     * 构建设计器左侧部门树。
+     *
+     * @param depts 部门列表
+     * @return 部门树构建器
      */
     private TreeFunDto<DeptDTO> buildDeptTree(List<DeptDTO> depts) {
         return new TreeFunDto<>(depts)
@@ -169,7 +179,11 @@ public class FlwTaskAssigneeServiceImpl implements IFlwTaskAssigneeService, Hand
     }
 
     /**
-     * 构建任务办理人数据
+     * 构建设计器右侧办理人列表数据。
+     *
+     * @param dto 办理人数据
+     * @param type 办理人类型
+     * @return 办理人列表构建器
      */
     private HandlerFunDto<TaskAssigneeDTO.TaskHandler> buildHandlerData(TaskAssigneeDTO dto, TaskAssigneeEnum type) {
         return new HandlerFunDto<>(dto.getList(), dto.getTotal())

ruoyi-modules/ruoyi-workflow/src/main/java/org/dromara/workflow/service/impl/FlwTaskServiceImpl.java

@@ -97,6 +97,7 @@ public class FlwTaskServiceImpl implements IFlwTaskService {
      * 启动任务
      *
      * @param startProcessBo 启动流程参数
+     * @return 启动后的流程实例标识与首个任务标识
      */
     @Override
     @Transactional(rollbackFor = Exception.class)
@@ -171,6 +172,9 @@ public class FlwTaskServiceImpl implements IFlwTaskService {
 
     /**
      * 生成业务编号，如果已有则直接返回已有值
+     *
+     * @param bizExt 流程业务扩展信息
+     * @return 可用于流程实例展示的业务编号
      */
     private String generateBusinessCode(FlowInstanceBizExt bizExt) {
         if (StringUtils.isBlank(bizExt.getBusinessCode())) {
@@ -198,6 +202,7 @@ public class FlwTaskServiceImpl implements IFlwTaskService {
      * 办理任务
      *
      * @param completeTaskBo 办理任务参数
+     * @return 办理成功返回 {@code true}
      */
     @Override
     @Transactional(rollbackFor = Exception.class)
@@ -294,6 +299,7 @@ public class FlwTaskServiceImpl implements IFlwTaskService {
      *
      * @param assigneeMap  处理人
      * @param variablesMap 变量
+     * @return 追加流程状态前缀后的处理人变量映射
      */
     private Map<String, Object> setPopAssigneeMap(Map<String, Object> assigneeMap, Map<String, Object> variablesMap) {
         Map<String, Object> map = new HashMap<>();
@@ -367,6 +373,7 @@ public class FlwTaskServiceImpl implements IFlwTaskService {
      *
      * @param flowTaskBo 参数
      * @param pageQuery  分页
+     * @return 当前登录人的待办任务分页结果
      */
     @Override
     public TableDataInfo<FlowTaskVo> pageByTaskWait(FlowTaskBo flowTaskBo, PageQuery pageQuery) {
@@ -380,6 +387,7 @@ public class FlwTaskServiceImpl implements IFlwTaskService {
      *
      * @param flowTaskBo 参数
      * @param pageQuery  分页
+     * @return 当前登录人的已办任务分页结果
      */
     @Override
     public TableDataInfo<FlowHisTaskVo> pageByTaskFinish(FlowTaskBo flowTaskBo, PageQuery pageQuery) {
@@ -392,6 +400,7 @@ public class FlwTaskServiceImpl implements IFlwTaskService {
      *
      * @param flowTaskBo 参数
      * @param pageQuery  分页
+     * @return 全部待办任务分页结果
      */
     @Override
     public TableDataInfo<FlowTaskVo> pageByAllTaskWait(FlowTaskBo flowTaskBo, PageQuery pageQuery) {
@@ -423,6 +432,7 @@ public class FlwTaskServiceImpl implements IFlwTaskService {
      *
      * @param flowTaskBo 参数
      * @param pageQuery  分页
+     * @return 全部已办任务分页结果
      */
     @Override
     public TableDataInfo<FlowHisTaskVo> pageByAllTaskFinish(FlowTaskBo flowTaskBo, PageQuery pageQuery) {
@@ -435,6 +445,7 @@ public class FlwTaskServiceImpl implements IFlwTaskService {
      *
      * @param flowTaskBo 参数
      * @param pageQuery  分页
+     * @return 当前登录人收到的抄送分页结果
      */
     @Override
     public TableDataInfo<FlowTaskVo> pageByTaskCopy(FlowTaskBo flowTaskBo, PageQuery pageQuery) {
@@ -442,6 +453,12 @@ public class FlwTaskServiceImpl implements IFlwTaskService {
         return TableDataInfo.build(page);
     }
 
+    /**
+     * 解析查询条件中的分类及其子分类编码集合。
+     *
+     * @param flowTaskBo 任务筛选条件
+     * @return 分类 id 字符串集合，未指定分类时返回 {@code null}
+     */
     private List<String> categoryIds(FlowTaskBo flowTaskBo) {
         if (StringUtils.isNotBlank(flowTaskBo.getCategory())) {
             List<Long> categoryIds = flwCategoryMapper.selectCategoryIdsByParentId(Convert.toLong(flowTaskBo.getCategory()));
@@ -454,6 +471,7 @@ public class FlwTaskServiceImpl implements IFlwTaskService {
      * 驳回任务
      *
      * @param bo 参数
+     * @return 驳回成功返回 {@code true}
      */
     @Override
     @Transactional(rollbackFor = Exception.class)
@@ -497,6 +515,7 @@ public class FlwTaskServiceImpl implements IFlwTaskService {
      *
      * @param taskId      任务id
      * @param nowNodeCode 当前节点
+     * @return 当前任务允许驳回的节点列表
      */
     @Override
     public List<Node> getBackTaskNode(Long taskId, String nowNodeCode) {
@@ -544,6 +563,7 @@ public class FlwTaskServiceImpl implements IFlwTaskService {
      * 终止任务
      *
      * @param bo 参数
+     * @return 终止成功返回 {@code true}
      */
     @Override
     @Transactional(rollbackFor = Exception.class)
@@ -569,6 +589,7 @@ public class FlwTaskServiceImpl implements IFlwTaskService {
      * 按照任务id查询任务
      *
      * @param taskIdList 任务id
+     * @return 任务列表
      */
     @Override
     public List<FlowTask> selectByIdList(List<Long> taskIdList) {
@@ -579,6 +600,7 @@ public class FlwTaskServiceImpl implements IFlwTaskService {
      * 按照任务id查询任务
      *
      * @param taskId 任务id
+     * @return 任务详情视图，不存在时返回 {@code null}
      */
     @Override
     public FlowTaskVo selectById(Long taskId) {
@@ -631,6 +653,7 @@ public class FlwTaskServiceImpl implements IFlwTaskService {
      * 获取下一节点信息
      *
      * @param bo 参数
+     * @return 当前任务在给定变量下可流转到的下一审批节点列表
      */
     @Override
     public List<FlowNode> getNextNodeList(FlowNextNodeBo bo) {
@@ -691,6 +714,7 @@ public class FlwTaskServiceImpl implements IFlwTaskService {
      * 按照实例id查询任务
      *
      * @param instanceId 流程实例id
+     * @return 运行中的任务列表
      */
     @Override
     public List<FlowTask> selectByInstId(Long instanceId) {
@@ -701,6 +725,7 @@ public class FlwTaskServiceImpl implements IFlwTaskService {
      * 按照实例id查询任务
      *
      * @param instanceIds 流程实例id
+     * @return 运行中的任务列表
      */
     @Override
     public List<FlowTask> selectByInstIds(List<Long> instanceIds) {
@@ -724,6 +749,7 @@ public class FlwTaskServiceImpl implements IFlwTaskService {
      *
      * @param bo            参数
      * @param taskOperation 操作类型，委派 delegateTask、转办 transferTask、加签 addSignature、减签 reductionSignature
+     * @return 操作成功返回 {@code true}
      */
     @Override
     @Transactional(rollbackFor = Exception.class)

ruoyi-modules/ruoyi-workflow/src/main/java/org/dromara/workflow/service/impl/TestLeaveServiceImpl.java

@@ -67,6 +67,9 @@ public class TestLeaveServiceImpl implements ITestLeaveService {
 
     /**
      * 查询请假
+     *
+     * @param id 主键
+     * @return 请假详情
      */
     @Override
     public TestLeaveVo queryById(Long id) {
@@ -75,6 +78,10 @@ public class TestLeaveServiceImpl implements ITestLeaveService {
 
     /**
      * 查询请假列表
+     *
+     * @param bo        查询条件
+     * @param pageQuery 分页参数
+     * @return 请假分页列表
      */
     @Override
     public TableDataInfo<TestLeaveVo> queryPageList(TestLeaveBo bo, PageQuery pageQuery) {
@@ -85,6 +92,9 @@ public class TestLeaveServiceImpl implements ITestLeaveService {
 
     /**
      * 查询请假列表
+     *
+     * @param bo 查询条件
+     * @return 请假列表
      */
     @Override
     public List<TestLeaveVo> queryList(TestLeaveBo bo) {
@@ -92,6 +102,12 @@ public class TestLeaveServiceImpl implements ITestLeaveService {
         return baseMapper.selectVoList(lqw);
     }
 
+    /**
+     * 构造请假列表查询条件。
+     *
+     * @param bo 查询参数
+     * @return 包含请假类型、天数区间和排序条件的查询包装器
+     */
     private LambdaQueryWrapper<TestLeave> buildQueryWrapper(TestLeaveBo bo) {
         LambdaQueryWrapper<TestLeave> lqw = Wrappers.lambdaQuery();
         lqw.eq(StringUtils.isNotBlank(bo.getLeaveType()), TestLeave::getLeaveType, bo.getLeaveType());
@@ -103,6 +119,9 @@ public class TestLeaveServiceImpl implements ITestLeaveService {
 
     /**
      * 新增请假
+     *
+     * @param bo 请假业务对象
+     * @return 新增后的请假详情
      */
     @Override
     public TestLeaveVo insertByBo(TestLeaveBo bo) {
@@ -121,6 +140,12 @@ public class TestLeaveServiceImpl implements ITestLeaveService {
         return MapstructUtils.convert(add, TestLeaveVo.class);
     }
 
+    /**
+     * 提交请假并同步发起审批流程。
+     *
+     * @param bo 请假业务对象
+     * @return 已落库并完成流程提交的请假详情
+     */
     @Transactional(rollbackFor = Exception.class)
     @Override
     public TestLeaveVo submitAndFlowStart(TestLeaveBo bo) {
@@ -154,6 +179,9 @@ public class TestLeaveServiceImpl implements ITestLeaveService {
 
     /**
      * 修改请假
+     *
+     * @param bo 请假业务对象
+     * @return 更新后的请假详情
      */
     @Override
     public TestLeaveVo updateByBo(TestLeaveBo bo) {
@@ -164,6 +192,9 @@ public class TestLeaveServiceImpl implements ITestLeaveService {
 
     /**
      * 批量删除请假
+     *
+     * @param ids 主键集合
+     * @return 删除成功返回 {@code true}
      */
     @Override
     @Transactional(rollbackFor = Exception.class)

ruoyi-modules/ruoyi-workflow/src/main/java/org/dromara/workflow/service/impl/WorkflowServiceImpl.java

@@ -53,6 +53,7 @@ public class WorkflowServiceImpl implements WorkflowService {
      * 获取当前流程状态
      *
      * @param taskId 任务id
+     * @return 任务关联流程实例的业务状态，未查询到时返回空字符串
      */
     @Override
     public String getBusinessStatusByTaskId(Long taskId) {
@@ -64,6 +65,7 @@ public class WorkflowServiceImpl implements WorkflowService {
      * 获取当前流程状态
      *
      * @param businessId 业务id
+     * @return 业务单据对应的流程状态，未查询到时返回空字符串
      */
     @Override
     public String getBusinessStatus(String businessId) {
@@ -86,6 +88,7 @@ public class WorkflowServiceImpl implements WorkflowService {
      * 获取流程变量
      *
      * @param instanceId 流程实例id
+     * @return 实例变量信息
      */
     @Override
     public Map<String, Object> instanceVariable(Long instanceId) {
@@ -108,6 +111,7 @@ public class WorkflowServiceImpl implements WorkflowService {
      * 启动流程
      *
      * @param startProcess 参数
+     * @return 启动后的流程实例和首个任务信息
      */
     @Override
     public StartProcessReturnDTO startWorkFlow(StartProcessDTO startProcess) {
@@ -120,6 +124,7 @@ public class WorkflowServiceImpl implements WorkflowService {
      * completeTask.getVariables().put("ignore", true);
      *
      * @param completeTask 参数
+     * @return 办理成功返回 {@code true}
      */
     @Override
     public boolean completeTask(CompleteTaskDTO completeTask) {
@@ -131,6 +136,7 @@ public class WorkflowServiceImpl implements WorkflowService {
      *
      * @param taskId  任务ID
      * @param message 办理意见
+     * @return 办理成功返回 {@code true}
      */
     @Override
     public boolean completeTask(Long taskId, String message) {
@@ -146,6 +152,7 @@ public class WorkflowServiceImpl implements WorkflowService {
      * 启动流程并办理第一个任务
      *
      * @param startProcess 参数
+     * @return 首节点办理成功返回 {@code true}
      */
     @Override
     @Transactional(rollbackFor = Exception.class)