update 增加多个方法的注释以提升代码可读性

ruoyi-common/ruoyi-common-core/src/main/java/org/dromara/common/core/enums/FormatsType.java

@@ -135,6 +135,12 @@ public enum FormatsType {
      */
     private final String timeFormat;
 
+    /**
+     * 根据字符串内容匹配时间格式类型。
+     *
+     * @param str 字符串内容
+     * @return 时间格式类型
+     */
     public static FormatsType getFormatsType(String str) {
         for (FormatsType value : values()) {
             if (StringUtils.contains(str, value.getTimeFormat())) {

ruoyi-common/ruoyi-common-core/src/main/java/org/dromara/common/core/utils/SpringUtils.java

@@ -60,6 +60,11 @@ public final class SpringUtils extends SpringUtil {
         return getApplicationContext();
     }
 
+    /**
+     * 当前是否启用虚拟线程。
+     *
+     * @return true 启用 false 未启用
+     */
     public static boolean isVirtual() {
         return Threading.VIRTUAL.isActive(getBean(Environment.class));
     }

ruoyi-common/ruoyi-common-core/src/main/java/org/dromara/common/core/utils/ip/AddressUtils.java

@@ -21,6 +21,12 @@ public class AddressUtils {
     // 内网地址
     public static final String LOCAL_ADDRESS = "内网IP";
 
+    /**
+     * 根据 IP 查询真实地址。
+     *
+     * @param ip IP 地址
+     * @return 真实地址
+     */
     public static String getRealAddressByIP(String ip) {
         // 处理空串并过滤HTML标签
         ip = HtmlUtil.cleanHtmlTag(StringUtils.blankToDefault(ip,""));

ruoyi-common/ruoyi-common-excel/src/main/java/org/dromara/common/excel/core/CellMergeHandler.java

@@ -33,6 +33,13 @@ public class CellMergeHandler {
         this.hasTitle = hasTitle;
         this.rowIndex = hasTitle ? rowIndex : 0;
     }
+
+    /**
+     * 计算需要合并的单元格区域。
+     *
+     * @param rows 数据行
+     * @return 单元格合并区域列表
+     */
     @SneakyThrows
     public List<CellRangeAddress> handle(List<?> rows) {
         // 如果入参为空集合则返回空集

ruoyi-common/ruoyi-common-excel/src/main/java/org/dromara/common/excel/utils/ExcelWriterWrapper.java

@@ -22,38 +22,95 @@ import java.util.function.Supplier;
  */
 public record ExcelWriterWrapper<T>(ExcelWriter excelWriter) {
 
+    /**
+     * 写出集合数据到指定工作表。
+     *
+     * @param data       数据集合
+     * @param writeSheet 工作表
+     */
     public void write(Collection<T> data, WriteSheet writeSheet) {
         excelWriter.write(data, writeSheet);
     }
 
+    /**
+     * 通过数据提供器写出集合数据到指定工作表。
+     *
+     * @param supplier   数据提供器
+     * @param writeSheet 工作表
+     */
     public void write(Supplier<Collection<T>> supplier, WriteSheet writeSheet) {
         excelWriter.write(supplier.get(), writeSheet);
     }
 
+    /**
+     * 写出集合数据到指定工作表和表格。
+     *
+     * @param data       数据集合
+     * @param writeSheet 工作表
+     * @param writeTable 表格
+     */
     public void write(Collection<T> data, WriteSheet writeSheet, WriteTable writeTable) {
         excelWriter.write(data, writeSheet, writeTable);
     }
 
+    /**
+     * 通过数据提供器写出集合数据到指定工作表和表格。
+     *
+     * @param supplier   数据提供器
+     * @param writeSheet 工作表
+     * @param writeTable 表格
+     */
     public void write(Supplier<Collection<T>> supplier, WriteSheet writeSheet, WriteTable writeTable) {
         excelWriter.write(supplier.get(), writeSheet, writeTable);
     }
 
+    /**
+     * 填充数据到指定工作表。
+     *
+     * @param data       填充数据
+     * @param writeSheet 工作表
+     */
     public void fill(Object data, WriteSheet writeSheet) {
         excelWriter.fill(data, writeSheet);
     }
 
+    /**
+     * 按填充配置填充数据到指定工作表。
+     *
+     * @param data       填充数据
+     * @param fillConfig 填充配置
+     * @param writeSheet 工作表
+     */
     public void fill(Object data, FillConfig fillConfig, WriteSheet writeSheet) {
         excelWriter.fill(data, fillConfig, writeSheet);
     }
 
+    /**
+     * 通过数据提供器填充数据到指定工作表。
+     *
+     * @param supplier   数据提供器
+     * @param writeSheet 工作表
+     */
     public void fill(Supplier<Object> supplier, WriteSheet writeSheet) {
         excelWriter.fill(supplier, writeSheet);
     }
 
+    /**
+     * 通过数据提供器按填充配置填充数据到指定工作表。
+     *
+     * @param supplier   数据提供器
+     * @param fillConfig 填充配置
+     * @param writeSheet 工作表
+     */
     public void fill(Supplier<Object> supplier, FillConfig fillConfig, WriteSheet writeSheet) {
         excelWriter.fill(supplier, fillConfig, writeSheet);
     }
 
+    /**
+     * 获取写出上下文。
+     *
+     * @return 写出上下文
+     */
     public WriteContext writeContext() {
         return excelWriter.writeContext();
     }
@@ -70,34 +127,82 @@ public record ExcelWriterWrapper<T>(ExcelWriter excelWriter) {
 
     // -------------------------------- sheet start
 
+    /**
+     * 创建工作表。
+     *
+     * @param sheetNo   工作表编号
+     * @param sheetName 工作表名称
+     * @return 工作表
+     */
     public static WriteSheet buildSheet(Integer sheetNo, String sheetName) {
         return sheetBuilder(sheetNo, sheetName).build();
     }
 
+    /**
+     * 创建工作表。
+     *
+     * @param sheetNo 工作表编号
+     * @return 工作表
+     */
     public static WriteSheet buildSheet(Integer sheetNo) {
         return sheetBuilder(sheetNo).build();
     }
 
+    /**
+     * 创建工作表。
+     *
+     * @param sheetName 工作表名称
+     * @return 工作表
+     */
     public static WriteSheet buildSheet(String sheetName) {
         return sheetBuilder(sheetName).build();
     }
 
+    /**
+     * 创建工作表。
+     *
+     * @return 工作表
+     */
     public static WriteSheet buildSheet() {
         return sheetBuilder().build();
     }
 
+    /**
+     * 创建工作表构造器。
+     *
+     * @param sheetNo   工作表编号
+     * @param sheetName 工作表名称
+     * @return 工作表构造器
+     */
     public static ExcelWriterSheetBuilder sheetBuilder(Integer sheetNo, String sheetName) {
         return FesodSheet.writerSheet(sheetNo, sheetName);
     }
 
+    /**
+     * 创建工作表构造器。
+     *
+     * @param sheetNo 工作表编号
+     * @return 工作表构造器
+     */
     public static ExcelWriterSheetBuilder sheetBuilder(Integer sheetNo) {
         return FesodSheet.writerSheet(sheetNo);
     }
 
+    /**
+     * 创建工作表构造器。
+     *
+     * @param sheetName 工作表名称
+     * @return 工作表构造器
+     */
     public static ExcelWriterSheetBuilder sheetBuilder(String sheetName) {
         return FesodSheet.writerSheet(sheetName);
     }
 
+    /**
+     * 创建工作表构造器。
+     *
+     * @return 工作表构造器
+     */
     public static ExcelWriterSheetBuilder sheetBuilder() {
         return FesodSheet.writerSheet();
     }
@@ -106,18 +211,40 @@ public record ExcelWriterWrapper<T>(ExcelWriter excelWriter) {
 
     // -------------------------------- table start
 
+    /**
+     * 创建表格。
+     *
+     * @param tableNo 表格编号
+     * @return 表格
+     */
     public static WriteTable buildTable(Integer tableNo) {
         return tableBuilder(tableNo).build();
     }
 
+    /**
+     * 创建表格。
+     *
+     * @return 表格
+     */
     public static WriteTable buildTable() {
         return tableBuilder().build();
     }
 
+    /**
+     * 创建表格构造器。
+     *
+     * @param tableNo 表格编号
+     * @return 表格构造器
+     */
     public static ExcelWriterTableBuilder tableBuilder(Integer tableNo) {
         return FesodSheet.writerTable(tableNo);
     }
 
+    /**
+     * 创建表格构造器。
+     *
+     * @return 表格构造器
+     */
     public static ExcelWriterTableBuilder tableBuilder() {
         return FesodSheet.writerTable();
     }

ruoyi-common/ruoyi-common-json/src/main/java/org/dromara/common/json/enhance/JsonEnhancementContext.java

@@ -16,15 +16,33 @@ public class JsonEnhancementContext {
 
     private final Map<String, Object> attributes = new LinkedHashMap<>();
 
+    /**
+     * 构造响应增强上下文。
+     *
+     * @param jsonMapper JSON 映射器
+     */
     public JsonEnhancementContext(JsonMapper jsonMapper) {
         this.jsonMapper = jsonMapper;
     }
 
+    /**
+     * 获取上下文属性。
+     *
+     * @param key 属性键
+     * @param <T> 属性值类型
+     * @return 属性值
+     */
     @SuppressWarnings("unchecked")
     public <T> T getAttribute(String key) {
         return (T) attributes.get(key);
     }
 
+    /**
+     * 设置上下文属性。
+     *
+     * @param key   属性键
+     * @param value 属性值
+     */
     public void setAttribute(String key, Object value) {
         attributes.put(key, value);
     }

ruoyi-common/ruoyi-common-json/src/main/java/org/dromara/common/json/enhance/JsonFieldContext.java

@@ -9,6 +9,13 @@ import java.lang.annotation.Annotation;
  */
 public record JsonFieldContext(Object owner, String propertyName, AnnotatedMember member, Object value) {
 
+    /**
+     * 获取字段上的指定注解。
+     *
+     * @param annotationType 注解类型
+     * @param <A>            注解类型
+     * @return 注解对象
+     */
     public <A extends Annotation> A getAnnotation(Class<A> annotationType) {
         return member == null ? null : member.getAnnotation(annotationType);
     }

ruoyi-common/ruoyi-common-json/src/main/java/org/dromara/common/json/enhance/JsonValueEnhancer.java

@@ -31,6 +31,12 @@ public class JsonValueEnhancer {
 
     private final Map<Class<?>, List<PropertyMetadata>> propertyCache = new ConcurrentHashMap<>();
 
+    /**
+     * 构造统一响应增强器。
+     *
+     * @param jsonMapper JSON 映射器
+     * @param processors 字段处理器列表
+     */
     public JsonValueEnhancer(JsonMapper jsonMapper, List<JsonFieldProcessor> processors) {
         this.jsonMapper = jsonMapper;
         List<JsonFieldProcessor> sortedProcessors = new ArrayList<>(processors);
@@ -38,6 +44,12 @@ public class JsonValueEnhancer {
         this.processors = Collections.unmodifiableList(sortedProcessors);
     }
 
+    /**
+     * 增强响应对象。
+     *
+     * @param body 响应对象
+     * @return 增强后的响应对象
+     */
     public Object enhance(Object body) {
         if (body == null || body instanceof JsonNode || processors.isEmpty()) {
             return body;
@@ -45,6 +57,12 @@ public class JsonValueEnhancer {
         return enhanceTree(body);
     }
 
+    /**
+     * 判断消息转换器是否支持响应增强。
+     *
+     * @param converterType 消息转换器类型
+     * @return true 支持 false 不支持
+     */
     public boolean supports(Class<?> converterType) {
         return !processors.isEmpty()
             && !ByteArrayHttpMessageConverter.class.isAssignableFrom(converterType)

ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/core/domain/DataPermissionAccess.java

@@ -18,6 +18,11 @@ public record DataPermissionAccess(Set<String> perms, Set<String> roleKeys) impl
 
     public static final DataPermissionAccess EMPTY = new DataPermissionAccess(Set.of(), Set.of());
 
+    /**
+     * 是否存在数据权限约束。
+     *
+     * @return true 存在权限约束 false 不存在权限约束
+     */
     public boolean constrained() {
         return CollUtil.isNotEmpty(perms) || CollUtil.isNotEmpty(roleKeys);
     }

ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/core/mapper/LambdaCrudChainWrapper.java

@@ -40,6 +40,11 @@ public class LambdaCrudChainWrapper<T, V> extends AbstractLambdaWrapper<T, Lambd
     private final List<String> sqlSet;
     private SharedString sqlSelect = new SharedString();
 
+    /**
+     * 构造 Mapper 级 Lambda CRUD 链式包装器。
+     *
+     * @param crudMapper Mapper 对象
+     */
     public LambdaCrudChainWrapper(BaseMapperPlus<T, V> crudMapper) {
         this.crudMapper = crudMapper;
         super.setEntityClass(crudMapper.currentModelClass());
@@ -47,6 +52,22 @@ public class LambdaCrudChainWrapper<T, V> extends AbstractLambdaWrapper<T, Lambd
         this.sqlSet = new ArrayList<>();
     }
 
+    /**
+     * 构造 Mapper 级 Lambda CRUD 链式包装器实例。
+     *
+     * @param crudMapper          Mapper 对象
+     * @param entity              实体对象
+     * @param entityClass         实体类型
+     * @param sqlSelect           查询字段 SQL 片段
+     * @param sqlSet              更新 set SQL 片段集合
+     * @param paramNameSeq        参数名称序列
+     * @param paramNameValuePairs 参数名称与参数值映射
+     * @param mergeSegments       查询条件表达式
+     * @param paramAlias          参数别名
+     * @param lastSql             SQL 尾部片段
+     * @param sqlComment          SQL 注释片段
+     * @param sqlFirst            SQL 起始片段
+     */
     LambdaCrudChainWrapper(BaseMapperPlus<T, V> crudMapper, T entity, Class<T> entityClass, SharedString sqlSelect,
                            List<String> sqlSet, AtomicInteger paramNameSeq, Map<String, Object> paramNameValuePairs,
                            MergeSegments mergeSegments, SharedString paramAlias, SharedString lastSql,
@@ -65,6 +86,13 @@ public class LambdaCrudChainWrapper<T, V> extends AbstractLambdaWrapper<T, Lambd
         this.sqlFirst = sqlFirst;
     }
 
+    /**
+     * 按条件选择查询字段。
+     *
+     * @param condition 是否选择字段
+     * @param columns   查询字段集合
+     * @return this
+     */
     @Override
     public LambdaCrudChainWrapper<T, V> select(boolean condition, List<SFunction<T, ?>> columns) {
         if (condition && CollectionUtils.isNotEmpty(columns)) {
@@ -73,16 +101,36 @@ public class LambdaCrudChainWrapper<T, V> extends AbstractLambdaWrapper<T, Lambd
         return typedThis;
     }
 
+    /**
+     * 选择查询字段。
+     *
+     * @param columns 查询字段
+     * @return this
+     */
     @SafeVarargs
     public final LambdaCrudChainWrapper<T, V> select(SFunction<T, ?>... columns) {
         return select(true, CollectionUtils.toList(columns));
     }
 
+    /**
+     * 按条件选择查询字段。
+     *
+     * @param condition 是否选择字段
+     * @param columns   查询字段
+     * @return this
+     */
     @SafeVarargs
     public final LambdaCrudChainWrapper<T, V> select(boolean condition, SFunction<T, ?>... columns) {
         return select(condition, CollectionUtils.toList(columns));
     }
 
+    /**
+     * 按字段过滤条件选择查询字段。
+     *
+     * @param entityClass 实体类型
+     * @param predicate   字段过滤条件
+     * @return this
+     */
     @Override
     public LambdaCrudChainWrapper<T, V> select(Class<T> entityClass, Predicate<TableFieldInfo> predicate) {
         if (entityClass == null) {
@@ -95,11 +143,25 @@ public class LambdaCrudChainWrapper<T, V> extends AbstractLambdaWrapper<T, Lambd
         return typedThis;
     }
 
+    /**
+     * 获取查询字段 SQL 片段。
+     *
+     * @return 查询字段 SQL 片段
+     */
     @Override
     public String getSqlSelect() {
         return sqlSelect.getStringValue();
     }
 
+    /**
+     * 按条件设置更新字段。
+     *
+     * @param condition 是否设置该字段
+     * @param column    字段
+     * @param val       字段值
+     * @param mapping   参数映射
+     * @return this
+     */
     @Override
     public LambdaCrudChainWrapper<T, V> set(boolean condition, SFunction<T, ?> column, Object val, String mapping) {
         return maybeDo(condition, () -> {
@@ -130,11 +192,27 @@ public class LambdaCrudChainWrapper<T, V> extends AbstractLambdaWrapper<T, Lambd
         return set(org.dromara.common.core.utils.StringUtils.isNotBlank(value), column, value);
     }
 
+    /**
+     * 按条件设置自定义 SQL 更新片段。
+     *
+     * @param condition 是否设置该片段
+     * @param setSql    SQL 更新片段
+     * @param params    SQL 片段参数
+     * @return this
+     */
     @Override
     public LambdaCrudChainWrapper<T, V> setSql(boolean condition, String setSql, Object... params) {
         return maybeDo(condition && StringUtils.isNotBlank(setSql), () -> sqlSet.add(formatSqlMaybeWithParam(setSql, params)));
     }
 
+    /**
+     * 按条件设置字段自增。
+     *
+     * @param condition 是否设置该字段
+     * @param column    字段
+     * @param val       自增值
+     * @return this
+     */
     @Override
     public LambdaCrudChainWrapper<T, V> setIncrBy(boolean condition, SFunction<T, ?> column, Number val) {
         return maybeDo(condition, () -> {
@@ -144,6 +222,14 @@ public class LambdaCrudChainWrapper<T, V> extends AbstractLambdaWrapper<T, Lambd
         });
     }
 
+    /**
+     * 按条件设置字段自减。
+     *
+     * @param condition 是否设置该字段
+     * @param column    字段
+     * @param val       自减值
+     * @return this
+     */
     @Override
     public LambdaCrudChainWrapper<T, V> setDecrBy(boolean condition, SFunction<T, ?> column, Number val) {
         return maybeDo(condition, () -> {
@@ -153,6 +239,11 @@ public class LambdaCrudChainWrapper<T, V> extends AbstractLambdaWrapper<T, Lambd
         });
     }
 
+    /**
+     * 获取更新 set SQL 片段。
+     *
+     * @return 更新 set SQL 片段
+     */
     @Override
     public String getSqlSet() {
         if (CollectionUtils.isEmpty(sqlSet)) {
@@ -170,14 +261,36 @@ public class LambdaCrudChainWrapper<T, V> extends AbstractLambdaWrapper<T, Lambd
         return typedThis;
     }
 
+    /**
+     * 添加 FIND_IN_SET 条件。
+     *
+     * @param value  匹配值
+     * @param column 字段
+     * @return this
+     */
     public LambdaCrudChainWrapper<T, V> findInSet(Object value, SFunction<T, ?> column) {
         return findInSet(true, value, column);
     }
 
+    /**
+     * 添加 FIND_IN_SET 条件。
+     *
+     * @param condition 是否添加该条件
+     * @param value     匹配值
+     * @param column    字段
+     * @return this
+     */
     public LambdaCrudChainWrapper<T, V> findInSet(boolean condition, Object value, SFunction<T, ?> column) {
         return findInSet(condition, value, columnToString(column));
     }
 
+    /**
+     * 值不为空时添加 FIND_IN_SET 条件。
+     *
+     * @param value  匹配值
+     * @param column 字段
+     * @return this
+     */
     public LambdaCrudChainWrapper<T, V> findInSetIfPresent(Object value, SFunction<T, ?> column) {
         return findInSet(value != null, value, column);
     }
@@ -382,6 +495,11 @@ public class LambdaCrudChainWrapper<T, V> extends AbstractLambdaWrapper<T, Lambd
         return crudMapper.update(entity, typedThis);
     }
 
+    /**
+     * 创建新的链式包装器实例。
+     *
+     * @return 新的链式包装器实例
+     */
     @Override
     protected LambdaCrudChainWrapper<T, V> instance() {
         return new LambdaCrudChainWrapper<>(crudMapper, getEntity(), getEntityClass(), null, null, paramNameSeq,
@@ -389,6 +507,9 @@ public class LambdaCrudChainWrapper<T, V> extends AbstractLambdaWrapper<T, Lambd
             SharedString.emptyString());
     }
 
+    /**
+     * 清空当前 Wrapper 状态。
+     */
     @Override
     public void clear() {
         super.clear();

ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/core/page/PageQuery.java

@@ -114,11 +114,22 @@ public class PageQuery implements Serializable {
         return list;
     }
 
+    /**
+     * 获取当前页起始行号。
+     *
+     * @return 起始行号
+     */
     @JsonIgnore
     public Integer getFirstNum() {
         return (pageNum - 1) * pageSize;
     }
 
+    /**
+     * 构造分页查询对象。
+     *
+     * @param pageSize 分页大小
+     * @param pageNum  当前页码
+     */
     public PageQuery(Integer pageSize, Integer pageNum) {
         this.pageSize = pageSize;
         this.pageNum = pageNum;

ruoyi-common/ruoyi-common-oss/src/main/java/org/dromara/common/oss/config/OssClientConfig.java

@@ -149,10 +149,22 @@ public class OssClientConfig implements Config<OssClientConfig, OssClientConfig.
         return Optional.ofNullable(prefix);
     }
 
+    /**
+     * 根据 OSS 配置属性构建客户端配置。
+     *
+     * @param properties OSS 配置属性
+     * @return 客户端配置
+     */
     public static OssClientConfig formProperties(OssProperties properties) {
         return formPropertiesBuilder(properties).build();
     }
 
+    /**
+     * 根据 OSS 配置属性构建客户端配置构造器。
+     *
+     * @param properties OSS 配置属性
+     * @return 客户端配置构造器
+     */
     public static OssClientConfigBuilder formPropertiesBuilder(OssProperties properties) {
         String regionString = properties.getRegion();
         Region region = Region.US_EAST_1;

ruoyi-common/ruoyi-common-oss/src/main/java/org/dromara/common/oss/enums/AccessPolicy.java

@@ -47,6 +47,12 @@ public enum AccessPolicy {
      */
     private final ObjectCannedACL objectCannedACL;
 
+    /**
+     * 根据策略类型查找访问策略。
+     *
+     * @param type 策略类型
+     * @return 访问策略
+     */
     public static AccessPolicy formType(String type) {
         return Arrays.stream(values())
             .filter(policy -> policy.getType().toString().equals(type))

ruoyi-common/ruoyi-common-oss/src/main/java/org/dromara/common/oss/exception/S3StorageException.java

@@ -12,34 +12,86 @@ public class S3StorageException extends RuntimeException {
     @Serial
     private static final long serialVersionUID = 1L;
 
+    /**
+     * 使用异常消息构造 S3 对象存储异常。
+     *
+     * @param message 异常消息
+     */
     public S3StorageException(String message) {
         super(message);
     }
 
+    /**
+     * 使用异常消息和原因构造 S3 对象存储异常。
+     *
+     * @param message 异常消息
+     * @param cause   异常原因
+     */
     public S3StorageException(String message, Throwable cause) {
         super(message, cause);
     }
 
+    /**
+     * 使用异常原因构造 S3 对象存储异常。
+     *
+     * @param cause 异常原因
+     */
     public S3StorageException(Throwable cause) {
         super(cause);
     }
 
+    /**
+     * 使用完整异常参数构造 S3 对象存储异常。
+     *
+     * @param message            异常消息
+     * @param cause              异常原因
+     * @param enableSuppression  是否启用抑制
+     * @param writableStackTrace 是否写入堆栈
+     */
     public S3StorageException(String message, Throwable cause, boolean enableSuppression, boolean writableStackTrace) {
         super(message, cause, enableSuppression, writableStackTrace);
     }
 
+    /**
+     * 创建 S3 对象存储异常。
+     *
+     * @param message 异常消息
+     * @return S3 对象存储异常
+     */
     public static S3StorageException form(String message) {
         return new S3StorageException(message);
     }
 
+    /**
+     * 创建 S3 对象存储异常。
+     *
+     * @param message 异常消息
+     * @param cause   异常原因
+     * @return S3 对象存储异常
+     */
     public static S3StorageException form(String message, Throwable cause) {
         return new S3StorageException(message, cause);
     }
 
+    /**
+     * 创建 S3 对象存储异常。
+     *
+     * @param cause 异常原因
+     * @return S3 对象存储异常
+     */
     public static S3StorageException form(Throwable cause) {
         return new S3StorageException(cause);
     }
 
+    /**
+     * 创建 S3 对象存储异常。
+     *
+     * @param message            异常消息
+     * @param cause              异常原因
+     * @param enableSuppression  是否启用抑制
+     * @param writableStackTrace 是否写入堆栈
+     * @return S3 对象存储异常
+     */
     public static S3StorageException form(String message, Throwable cause, boolean enableSuppression, boolean writableStackTrace) {
         return new S3StorageException(message, cause, enableSuppression, writableStackTrace);
     }

ruoyi-common/ruoyi-common-oss/src/main/java/org/dromara/common/oss/model/HandleAsyncResult.java

@@ -15,30 +15,72 @@ public record HandleAsyncResult<T>(
         Throwable error
 ) {
 
+    /**
+     * 获取异步处理结果。
+     *
+     * @return 异步处理结果
+     */
     public Optional<T> getResult() {
         return Optional.ofNullable(result);
     }
 
+    /**
+     * 获取异步处理异常。
+     *
+     * @return 异步处理异常
+     */
     public Optional<Throwable> getError() {
         return Optional.ofNullable(error);
     }
 
+    /**
+     * 是否处理成功。
+     *
+     * @return true 成功 false 失败
+     */
     public boolean isSuccess() {
         return getError().isEmpty();
     }
 
+    /**
+     * 是否处理失败。
+     *
+     * @return true 失败 false 成功
+     */
     public boolean isFailure() {
         return getError().isPresent();
     }
 
+    /**
+     * 构建异步处理结果。
+     *
+     * @param result 结果
+     * @param error  异常
+     * @param <T>    结果类型
+     * @return 异步处理结果
+     */
     public static <T> HandleAsyncResult<T> of(T result, Throwable error) {
         return new HandleAsyncResult<T>(result, error);
     }
 
+    /**
+     * 构建成功的异步处理结果。
+     *
+     * @param result 结果
+     * @param <T>    结果类型
+     * @return 异步处理结果
+     */
     public static <T> HandleAsyncResult<T> success(T result) {
         return new HandleAsyncResult<T>(result, null);
     }
 
+    /**
+     * 构建失败的异步处理结果。
+     *
+     * @param error 异常
+     * @param <T>   结果类型
+     * @return 异步处理结果
+     */
     public static <T> HandleAsyncResult<T> failure(Throwable error) {
         return new HandleAsyncResult<T>(null, error);
     }

ruoyi-common/ruoyi-common-oss/src/main/java/org/dromara/common/oss/model/PutObjectResult.java

@@ -16,6 +16,15 @@ public record PutObjectResult(
         long size
 ) {
 
+    /**
+     * 构建文件上传结果。
+     *
+     * @param url  文件地址
+     * @param key  文件标识
+     * @param eTag 文件 ETag
+     * @param size 文件大小
+     * @return 文件上传结果
+     */
     public static PutObjectResult form(String url, String key, String eTag, long size) {
         return new PutObjectResult(url, key, eTag, size);
     }

ruoyi-modules/ruoyi-gen/src/main/java/org/dromara/gen/util/template/PathNamedTemplate.java

@@ -48,14 +48,35 @@ public class PathNamedTemplate implements Template {
         return delegate.render(bindingMap);
     }
 
+    /**
+     * 构建带路径名称的模板。
+     *
+     * @param pathName 路径名称
+     * @param delegate 模板对象
+     * @return 带路径名称的模板
+     */
     public static PathNamedTemplate form(String pathName, Template delegate) {
         return new PathNamedTemplate(pathName, delegate);
     }
 
+    /**
+     * 根据模板引擎和路径名称构建模板。
+     *
+     * @param templateEngine 模板引擎
+     * @param pathName       路径名称
+     * @return 带路径名称的模板
+     */
     public static PathNamedTemplate form(TemplateEngine templateEngine,String pathName) {
         return new PathNamedTemplate(pathName,templateEngine.getTemplate(pathName));
     }
 
+    /**
+     * 根据模板引擎和路径名称集合构建模板映射。
+     *
+     * @param templateEngine 模板引擎
+     * @param pathNames      路径名称集合
+     * @return 模板映射
+     */
     public static Map<String, PathNamedTemplate> form(TemplateEngine templateEngine, Set<String> pathNames) {
         Map<String, PathNamedTemplate> result = new HashMap<>();
         for (String pathName : pathNames) {

ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/domain/SysUser.java

@@ -104,10 +104,20 @@ public class SysUser extends BaseEntity {
     private String remark;
 
 
+    /**
+     * 使用用户ID构造系统用户对象。
+     *
+     * @param userId 用户ID
+     */
     public SysUser(Long userId) {
         this.userId = userId;
     }
 
+    /**
+     * 判断当前用户是否为超级管理员。
+     *
+     * @return true 是超级管理员 false 不是超级管理员
+     */
     public boolean isSuperAdmin() {
         return SystemConstants.SUPER_ADMIN_USER_ID.equals(this.userId);
     }

ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/domain/bo/SysRoleBo.java

@@ -88,6 +88,11 @@ public class SysRoleBo implements Serializable {
      */
     private Long[] deptIds;
 
+    /**
+     * 判断当前角色是否为超级管理员角色。
+     *
+     * @return true 是超级管理员角色 false 不是超级管理员角色
+     */
     public boolean isSuperAdmin() {
         return SystemConstants.SUPER_ADMIN_ROLE_ID.equals(this.roleId);
     }

ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/domain/bo/SysUserBo.java

@@ -133,6 +133,11 @@ public class SysUserBo implements Serializable {
      */
     private Map<String, Object> params = new HashMap<>();
 
+    /**
+     * 判断当前用户是否为超级管理员。
+     *
+     * @return true 是超级管理员 false 不是超级管理员
+     */
     public boolean isSuperAdmin() {
         return SystemConstants.SUPER_ADMIN_USER_ID.equals(this.userId);
     }

ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/domain/vo/SysRoleVo.java

@@ -93,6 +93,11 @@ public class SysRoleVo implements Serializable {
      */
     private boolean flag = false;
 
+    /**
+     * 判断当前角色是否为超级管理员角色。
+     *
+     * @return true 是超级管理员角色 false 不是超级管理员角色
+     */
     public boolean isSuperAdmin() {
         return SystemConstants.SUPER_ADMIN_ROLE_ID.equals(this.roleId);
     }

ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/mapper/SysUserMapper.java

@@ -165,6 +165,12 @@ public interface SysUserMapper extends BaseMapperPlus<SysUser, SysUserVo>, MPJBa
     })
     int updateById(@Param(Constants.ENTITY) SysUser user);
 
+    /**
+     * 构建用户与角色关联查询条件
+     *
+     * @param user 查询条件
+     * @return 用户角色关联查询包装器
+     */
     default MPJLambdaWrapper<SysUser> buildUserRoleJoinWrapper(SysUserBo user) {
         return JoinWrappers.lambda("u", SysUser.class)
             .distinct()

ruoyi-modules/ruoyi-system/src/main/java/org/dromara/system/runner/SystemApplicationRunner.java

@@ -19,6 +19,11 @@ public class SystemApplicationRunner implements ApplicationRunner {
 
     private final ISysOssConfigService ossConfigService;
 
+    /**
+     * 应用启动后初始化 OSS 配置缓存。
+     *
+     * @param args 启动参数
+     */
     @Override
     public void run(ApplicationArguments args) throws Exception {
         ossConfigService.init();

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

@@ -110,7 +110,7 @@ public interface ISysMenuService {
     /**
      * 是否存在菜单子节点
      *
-     * @param menuIds 菜单ID串
+     * @param menuIds 菜单ID列表
      * @return 结果 true 存在 false 不存在
      */
     boolean hasChildByMenuId(Collection<Long> menuIds);
@@ -150,8 +150,7 @@ public interface ISysMenuService {
     /**
      * 批量删除菜单管理信息
      *
-     * @param menuIds 菜单ID串
+     * @param menuIds 菜单ID列表
-     * @return 结果
      */
     void deleteMenuById(Collection<Long> menuIds);
 

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

@@ -110,7 +110,7 @@ public class SysMenuServiceImpl implements ISysMenuService {
     }
 
     /**
-     * 根据用户ID查询菜单
+     * 根据用户ID查询菜单树信息
      *
      * @param userId 用户ID
      * @return 按树结构组织的菜单列表
@@ -251,7 +251,7 @@ public class SysMenuServiceImpl implements ISysMenuService {
     /**
      * 是否存在菜单子节点
      *
-     * @param menuIds 菜单ID串
+     * @param menuIds 菜单ID列表
      * @return 结果
      */
     @Override
@@ -337,7 +337,7 @@ public class SysMenuServiceImpl implements ISysMenuService {
     }
 
     /**
-     * 校验路由名称是否唯一
+     * 校验路由组合是否唯一
      *
      * @param menuBo 菜单信息
      * @return 结果