docs 补充项目注释

pom.xml

@@ -155,18 +155,21 @@
                 <scope>import</scope>
             </dependency>
 
+            <!-- 接口文档 -->
             <dependency>
                 <groupId>org.springdoc</groupId>
                 <artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
                 <version>${springdoc.version}</version>
             </dependency>
 
+            <!-- JavaDoc 运行时读取 -->
             <dependency>
                 <groupId>com.github.therapi</groupId>
                 <artifactId>therapi-runtime-javadoc</artifactId>
                 <version>${therapi-javadoc.version}</version>
             </dependency>
 
+            <!-- lombok -->
             <dependency>
                 <groupId>org.projectlombok</groupId>
                 <artifactId>lombok</artifactId>
@@ -194,30 +197,35 @@
                 <version>${dynamic-ds.version}</version>
             </dependency>
 
+            <!-- MyBatis 核心 -->
             <dependency>
                 <groupId>org.mybatis</groupId>
                 <artifactId>mybatis</artifactId>
                 <version>${mybatis.version}</version>
             </dependency>
 
+            <!-- MyBatis Plus 启动器 -->
             <dependency>
                 <groupId>com.baomidou</groupId>
                 <artifactId>mybatis-plus-spring-boot4-starter</artifactId>
                 <version>${mybatis-plus.version}</version>
             </dependency>
 
+            <!-- MyBatis Plus JSqlParser 支持 -->
             <dependency>
                 <groupId>com.baomidou</groupId>
                 <artifactId>mybatis-plus-jsqlparser</artifactId>
                 <version>${mybatis-plus.version}</version>
             </dependency>
 
+            <!-- MyBatis Plus 注解 -->
             <dependency>
                 <groupId>com.baomidou</groupId>
                 <artifactId>mybatis-plus-annotation</artifactId>
                 <version>${mybatis-plus.version}</version>
             </dependency>
 
+            <!-- MyBatis Plus Join -->
             <dependency>
                 <groupId>com.github.yulichang</groupId>
                 <artifactId>mybatis-plus-join-boot-starter</artifactId>
@@ -256,11 +264,13 @@
                 <version>${sms4j.version}</version>
             </dependency>
 
+            <!-- Spring Boot Admin 服务端 -->
             <dependency>
                 <groupId>de.codecentric</groupId>
                 <artifactId>spring-boot-admin-starter-server</artifactId>
                 <version>${spring-boot-admin.version}</version>
             </dependency>
+            <!-- Spring Boot Admin 客户端 -->
             <dependency>
                 <groupId>de.codecentric</groupId>
                 <artifactId>spring-boot-admin-starter-client</artifactId>
@@ -274,6 +284,7 @@
                 <version>${redisson.version}</version>
             </dependency>
 
+            <!-- 分布式锁 -->
             <dependency>
                 <groupId>com.baomidou</groupId>
                 <artifactId>lock4j-redisson-spring-boot-starter</artifactId>
@@ -286,23 +297,27 @@
                 <artifactId>snail-job-client-starter</artifactId>
                 <version>${snailjob.version}</version>
             </dependency>
+            <!-- SnailJob 重试核心 -->
             <dependency>
                 <groupId>com.aizuda</groupId>
                 <artifactId>snail-job-client-retry-core</artifactId>
                 <version>${snailjob.version}</version>
             </dependency>
+            <!-- SnailJob 任务核心 -->
             <dependency>
                 <groupId>com.aizuda</groupId>
                 <artifactId>snail-job-client-job-core</artifactId>
                 <version>${snailjob.version}</version>
             </dependency>
 
+            <!-- Snail AI Agent 启动器 -->
             <dependency>
                 <groupId>com.aizuda</groupId>
                 <artifactId>snail-ai-agent-starter</artifactId>
                 <version>${snailai.version}</version>
             </dependency>
 
+            <!-- Snail AI OpenAPI 启动器 -->
             <dependency>
                 <groupId>com.aizuda</groupId>
                 <artifactId>snail-ai-openapi-starter</artifactId>
@@ -316,6 +331,7 @@
                 <version>${bouncycastle.version}</version>
             </dependency>
 
+            <!-- Mapstruct Plus -->
             <dependency>
                 <groupId>io.github.linpeilie</groupId>
                 <artifactId>mapstruct-plus-spring-boot-starter</artifactId>
@@ -328,30 +344,35 @@
                 <artifactId>warm-flow-mybatis-plus-sb3-starter</artifactId>
                 <version>${warm-flow.version}</version>
             </dependency>
+            <!-- Warm-Flow UI 插件 -->
             <dependency>
                 <groupId>org.dromara.warm</groupId>
                 <artifactId>warm-flow-plugin-ui-sb-web</artifactId>
                 <version>${warm-flow.version}</version>
             </dependency>
 
+            <!-- mqtt客户端 -->
             <dependency>
                 <groupId>org.dromara.mica-mqtt</groupId>
                 <artifactId>mica-mqtt-client-spring-boot-starter</artifactId>
                 <version>${mica-mqtt.version}</version>
             </dependency>
 
+            <!-- Easy-Es 搜索引擎 -->
             <dependency>
                 <groupId>org.dromara.easy-es</groupId>
                 <artifactId>easy-es-boot-starter</artifactId>
                 <version>${easy-es.version}</version>
             </dependency>
 
+            <!-- Elasticsearch Java 客户端 -->
             <dependency>
                 <groupId>co.elastic.clients</groupId>
                 <artifactId>elasticsearch-java</artifactId>
                 <version>${elasticsearch-client.version}</version>
             </dependency>
 
+            <!-- Elasticsearch REST 客户端 -->
             <dependency>
                 <groupId>org.elasticsearch.client</groupId>
                 <artifactId>elasticsearch-rest-client</artifactId>
@@ -372,36 +393,42 @@
                 <version>${ip2region.version}</version>
             </dependency>
 
+            <!-- fastjson -->
             <dependency>
                 <groupId>com.alibaba</groupId>
                 <artifactId>fastjson</artifactId>
                 <version>${fastjson.version}</version>
             </dependency>
 
+            <!-- 系统模块 -->
             <dependency>
                 <groupId>org.dromara</groupId>
                 <artifactId>ruoyi-system</artifactId>
                 <version>${revision}</version>
             </dependency>
 
+            <!-- 调度任务模块 -->
             <dependency>
                 <groupId>org.dromara</groupId>
                 <artifactId>ruoyi-job</artifactId>
                 <version>${revision}</version>
             </dependency>
 
+            <!-- AI业务模块 -->
             <dependency>
                 <groupId>org.dromara</groupId>
                 <artifactId>ruoyi-ai</artifactId>
                 <version>${revision}</version>
             </dependency>
 
+            <!-- 代码生成模块 -->
             <dependency>
                 <groupId>org.dromara</groupId>
                 <artifactId>ruoyi-gen</artifactId>
                 <version>${revision}</version>
             </dependency>
 
+            <!-- demo模块 -->
             <dependency>
                 <groupId>org.dromara</groupId>
                 <artifactId>ruoyi-demo</artifactId>
@@ -426,10 +453,15 @@
     </dependencyManagement>
 
     <modules>
+        <!-- web服务入口 -->
         <module>ruoyi-admin</module>
+        <!-- common 通用模块 -->
         <module>ruoyi-common</module>
+        <!-- 扩展模块 -->
         <module>ruoyi-extend</module>
+        <!-- 业务模块 -->
         <module>ruoyi-modules</module>
+        <!-- api模块 -->
         <module>ruoyi-api</module>
     </modules>
     <packaging>pom</packaging>

ruoyi-admin/pom.xml

@@ -50,36 +50,43 @@
             <artifactId>ruoyi-common-doc</artifactId>
         </dependency>
 
+        <!-- 授权认证 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-social</artifactId>
         </dependency>
 
+        <!-- 邮件服务 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-mail</artifactId>
         </dependency>
 
+        <!-- mcp模块 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-mcp</artifactId>
         </dependency>
 
+        <!-- api模块 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-api</artifactId>
         </dependency>
 
+        <!-- 系统模块 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-system</artifactId>
         </dependency>
 
+        <!-- 调度任务模块 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-job</artifactId>
         </dependency>
 
+        <!-- AI业务模块 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-ai</artifactId>
@@ -97,11 +104,13 @@
             <artifactId>ruoyi-workflow</artifactId>
         </dependency>
 
+        <!-- Spring Boot Admin 客户端 -->
         <dependency>
             <groupId>de.codecentric</groupId>
             <artifactId>spring-boot-admin-starter-client</artifactId>
         </dependency>
 
+        <!-- 单元测试 -->
         <dependency>
             <groupId>org.springframework.boot</groupId>
             <artifactId>spring-boot-starter-test</artifactId>

ruoyi-api/pom.xml

@@ -16,6 +16,7 @@
     </description>
 
     <dependencies>
+        <!-- 核心模块 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-core</artifactId>

ruoyi-api/src/main/java/org/dromara/system/api/domain/PushPayloadDTO.java

@@ -54,6 +54,15 @@ public class PushPayloadDTO implements Serializable {
      */
     private Long timestamp;
 
+    /**
+     * 构建推送消息体，缺省消息类型与来源时使用系统默认值。
+     *
+     * @param type 消息类型
+     * @param source 消息来源
+     * @param message 文本消息
+     * @param data 扩展数据
+     * @return 推送消息体
+     */
     public static PushPayloadDTO of(String type, String source, String message, Object data) {
         PushPayloadDTO payload = new PushPayloadDTO();
         payload.setType(StringUtils.defaultIfBlank(type, PushTypeEnum.MESSAGE.getType()));
@@ -64,6 +73,15 @@ public class PushPayloadDTO implements Serializable {
         return payload;
     }
 
+    /**
+     * 通过枚举值构建推送消息体。
+     *
+     * @param type 消息类型枚举
+     * @param source 消息来源枚举
+     * @param message 文本消息
+     * @param data 扩展数据
+     * @return 推送消息体
+     */
     public static PushPayloadDTO of(PushTypeEnum type, PushSourceEnum source, String message, Object data) {
         return of(
             type == null ? null : type.getType(),
@@ -73,6 +91,16 @@ public class PushPayloadDTO implements Serializable {
         );
     }
 
+    /**
+     * 构建带前端跳转路径的推送消息体。
+     *
+     * @param type 消息类型枚举
+     * @param source 消息来源枚举
+     * @param message 文本消息
+     * @param data 扩展数据
+     * @param path 前端跳转路径
+     * @return 推送消息体
+     */
     public static PushPayloadDTO of(PushTypeEnum type, PushSourceEnum source, String message, Object data, String path) {
         PushPayloadDTO payload = of(type, source, message, data);
         payload.setPath(path);

ruoyi-common/pom.xml

@@ -16,29 +16,53 @@
     </description>
 
     <modules>
+        <!-- common依赖项 -->
         <module>ruoyi-common-bom</module>
+        <!-- 授权认证 -->
         <module>ruoyi-common-social</module>
+        <!-- 核心模块 -->
         <module>ruoyi-common-core</module>
+        <!-- 接口模块 -->
         <module>ruoyi-common-doc</module>
+        <!-- excel -->
         <module>ruoyi-common-excel</module>
+        <!-- 调度模块 -->
         <module>ruoyi-common-job</module>
+        <!-- 日志记录 -->
         <module>ruoyi-common-log</module>
+        <!-- 邮件服务 -->
         <module>ruoyi-common-mail</module>
+        <!-- 数据库服务 -->
         <module>ruoyi-common-mybatis</module>
+        <!-- OSS -->
         <module>ruoyi-common-oss</module>
+        <!-- 缓存服务 -->
         <module>ruoyi-common-redis</module>
+        <!-- satoken -->
         <module>ruoyi-common-satoken</module>
+        <!-- 安全模块 -->
         <module>ruoyi-common-security</module>
+        <!-- 短信模块 -->
         <module>ruoyi-common-sms</module>
+        <!-- ES搜索引擎服务 -->
         <module>ruoyi-common-elasticsearch</module>
+        <!-- web服务 -->
         <module>ruoyi-common-web</module>
+        <!-- 翻译模块 -->
         <module>ruoyi-common-translation</module>
+        <!-- 脱敏模块 -->
         <module>ruoyi-common-sensitive</module>
+        <!-- 序列化模块 -->
         <module>ruoyi-common-json</module>
+        <!-- 数据库加解密模块 -->
         <module>ruoyi-common-encrypt</module>
+        <!-- 消息推送模块 -->
         <module>ruoyi-common-push</module>
+        <!-- mqtt模块 -->
         <module>ruoyi-common-mqtt</module>
+        <!-- ai模块 -->
         <module>ruoyi-common-ai</module>
+        <!-- mcp模块 -->
         <module>ruoyi-common-mcp</module>
     </modules>
 

ruoyi-common/ruoyi-common-ai/pom.xml

@@ -17,16 +17,19 @@
 
     <dependencies>
 
+        <!-- 核心模块 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-core</artifactId>
         </dependency>
 
+        <!-- Snail AI Agent 启动器 -->
         <dependency>
             <groupId>com.aizuda</groupId>
             <artifactId>snail-ai-agent-starter</artifactId>
         </dependency>
 
+        <!-- Snail AI OpenAPI 启动器 -->
         <dependency>
             <groupId>com.aizuda</groupId>
             <artifactId>snail-ai-openapi-starter</artifactId>

ruoyi-common/ruoyi-common-core/pom.xml

@@ -34,6 +34,7 @@
             <artifactId>spring-boot-starter-validation</artifactId>
         </dependency>
 
+        <!-- AOP 切面 -->
         <dependency>
             <groupId>org.springframework.boot</groupId>
             <artifactId>spring-boot-starter-aspectj</artifactId>
@@ -51,21 +52,25 @@
             <artifactId>jakarta.servlet-api</artifactId>
         </dependency>
 
+        <!-- Hutool 核心工具 -->
         <dependency>
             <groupId>cn.hutool</groupId>
             <artifactId>hutool-core</artifactId>
         </dependency>
 
+        <!-- Hutool HTTP 工具 -->
         <dependency>
             <groupId>cn.hutool</groupId>
             <artifactId>hutool-http</artifactId>
         </dependency>
 
+        <!-- Hutool 扩展工具 -->
         <dependency>
             <groupId>cn.hutool</groupId>
             <artifactId>hutool-extra</artifactId>
         </dependency>
 
+        <!-- lombok -->
         <dependency>
             <groupId>org.projectlombok</groupId>
             <artifactId>lombok</artifactId>
@@ -77,12 +82,14 @@
             <artifactId>spring-boot-configuration-processor</artifactId>
         </dependency>
 
+        <!-- Spring Boot 配置迁移 -->
         <dependency>
             <groupId>org.springframework.boot</groupId>
             <artifactId>spring-boot-properties-migrator</artifactId>
             <scope>runtime</scope>
         </dependency>
 
+        <!-- Mapstruct Plus -->
         <dependency>
             <groupId>io.github.linpeilie</groupId>
             <artifactId>mapstruct-plus-spring-boot-starter</artifactId>

ruoyi-common/ruoyi-common-core/src/main/java/org/dromara/common/core/validate/dicts/DictPattern.java

@@ -33,8 +33,14 @@ public @interface DictPattern {
      */
     String message() default "字典值无效";
 
+    /**
+     * Bean Validation 分组。
+     */
     Class<?>[] groups() default {};
 
+    /**
+     * Bean Validation 负载信息。
+     */
     Class<? extends Payload>[] payload() default {};
 
 }

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

@@ -32,16 +32,32 @@ public @interface EnumPattern {
      */
     String fieldName();
 
+    /**
+     * 校验失败时返回的错误消息。
+     */
     String message() default "输入值不在枚举范围内";
 
+    /**
+     * Bean Validation 分组。
+     */
     Class<?>[] groups() default {};
 
+    /**
+     * Bean Validation 负载信息。
+     */
     Class<? extends Payload>[] payload() default {};
 
+    /**
+     * 支持在同一元素上重复声明多个枚举校验规则。
+     */
     @Documented
     @Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE})
     @Retention(RUNTIME)
     @interface List {
+
+        /**
+         * 重复声明的枚举校验规则集合。
+         */
         EnumPattern[] value();
     }
 

ruoyi-common/ruoyi-common-core/src/main/java/org/dromara/common/core/xss/Xss.java

@@ -17,10 +17,19 @@ import java.lang.annotation.Target;
 @Constraint(validatedBy = {XssValidator.class})
 public @interface Xss {
 
+    /**
+     * 校验失败时返回的错误消息。
+     */
     String message() default "不允许任何脚本运行";
 
+    /**
+     * Bean Validation 分组。
+     */
     Class<?>[] groups() default {};
 
+    /**
+     * Bean Validation 负载信息。
+     */
     Class<? extends Payload>[] payload() default {};
 
 }

ruoyi-common/ruoyi-common-doc/pom.xml

@@ -16,26 +16,31 @@
     </description>
 
     <dependencies>
+        <!-- 核心模块 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-core</artifactId>
         </dependency>
 
+        <!-- Web 服务器抽象 -->
         <dependency>
             <groupId>org.springframework.boot</groupId>
             <artifactId>spring-boot-web-server</artifactId>
         </dependency>
 
+        <!-- 接口文档 -->
         <dependency>
             <groupId>org.springdoc</groupId>
             <artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
         </dependency>
 
+        <!-- JavaDoc 运行时读取 -->
         <dependency>
             <groupId>com.github.therapi</groupId>
             <artifactId>therapi-runtime-javadoc</artifactId>
         </dependency>
 
+        <!-- Jackson Kotlin 模块 -->
         <dependency>
             <groupId>com.fasterxml.jackson.module</groupId>
             <artifactId>jackson-module-kotlin</artifactId>

ruoyi-common/ruoyi-common-elasticsearch/pom.xml

@@ -16,6 +16,7 @@
     </description>
 
     <dependencies>
+        <!-- Easy-Es 搜索引擎 -->
         <dependency>
             <groupId>org.dromara.easy-es</groupId>
             <artifactId>easy-es-boot-starter</artifactId>

ruoyi-common/ruoyi-common-encrypt/pom.xml

@@ -17,26 +17,31 @@
 
     <dependencies>
 
+        <!-- 核心模块 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-core</artifactId>
         </dependency>
 
+        <!-- 加密包引入 -->
         <dependency>
             <groupId>org.bouncycastle</groupId>
             <artifactId>bcpkix-jdk18on</artifactId>
         </dependency>
 
+        <!-- Hutool 加密工具 -->
         <dependency>
             <groupId>cn.hutool</groupId>
             <artifactId>hutool-crypto</artifactId>
         </dependency>
 
+        <!-- Spring WebMVC -->
         <dependency>
             <groupId>org.springframework</groupId>
             <artifactId>spring-webmvc</artifactId>
         </dependency>
 
+        <!-- MyBatis Plus 启动器 -->
         <dependency>
             <groupId>com.baomidou</groupId>
             <artifactId>mybatis-plus-spring-boot4-starter</artifactId>

ruoyi-common/ruoyi-common-excel/pom.xml

@@ -16,11 +16,13 @@
     </description>
 
     <dependencies>
+        <!-- 序列化模块 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-json</artifactId>
         </dependency>
 
+        <!-- excel -->
         <dependency>
             <groupId>org.apache.fesod</groupId>
             <artifactId>fesod-sheet</artifactId>

ruoyi-common/ruoyi-common-job/pom.xml

@@ -17,6 +17,7 @@
 
     <dependencies>
 
+        <!-- Spring Boot 自动配置 -->
         <dependency>
             <groupId>org.springframework.boot</groupId>
             <artifactId>spring-boot-autoconfigure</artifactId>
@@ -27,16 +28,19 @@
             <groupId>com.aizuda</groupId>
             <artifactId>snail-job-client-starter</artifactId>
         </dependency>
+        <!-- SnailJob 任务核心 -->
         <dependency>
             <groupId>com.aizuda</groupId>
             <artifactId>snail-job-client-job-core</artifactId>
         </dependency>
 
+        <!-- lombok -->
         <dependency>
             <groupId>org.projectlombok</groupId>
             <artifactId>lombok</artifactId>
         </dependency>
 
+        <!-- 核心模块 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-core</artifactId>

ruoyi-common/ruoyi-common-job/src/main/java/org/dromara/common/job/config/SnailJobConfig.java

@@ -24,6 +24,11 @@ import org.springframework.scheduling.annotation.EnableScheduling;
 @EnableSnailJob
 public class SnailJobConfig {
 
+    /**
+     * Snail Job 客户端启动时挂载远程日志 appender。
+     *
+     * @param event 客户端启动事件
+     */
     @EventListener(SnailClientStartingEvent.class)
     public void onStarting(SnailClientStartingEvent event) {
         LoggerContext lc = (LoggerContext) LoggerFactory.getILoggerFactory();

ruoyi-common/ruoyi-common-json/pom.xml

@@ -16,11 +16,13 @@
     </description>
 
     <dependencies>
+        <!-- 核心模块 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-core</artifactId>
         </dependency>
 
+        <!-- Jackson 序列化 -->
         <dependency>
             <groupId>org.springframework.boot</groupId>
             <artifactId>spring-boot-starter-jackson</artifactId>

ruoyi-common/ruoyi-common-json/src/main/java/org/dromara/common/json/config/JsonEnhancementConfig.java

@@ -14,6 +14,13 @@ import java.util.List;
 @AutoConfiguration
 public class JsonEnhancementConfig {
 
+    /**
+     * 创建 JSON 字段增强处理器入口。
+     *
+     * @param jsonMapper JSON 映射器
+     * @param processors 字段处理器集合
+     * @return JSON 值增强器
+     */
     @Bean
     public JsonValueEnhancer jsonValueEnhancer(JsonMapper jsonMapper, List<JsonFieldProcessor> processors) {
         return new JsonValueEnhancer(jsonMapper, processors);

ruoyi-common/ruoyi-common-json/src/main/java/org/dromara/common/json/validate/JsonPattern.java

@@ -26,8 +26,14 @@ public @interface JsonPattern {
      */
     String message() default "不是有效的 JSON 格式";
 
+    /**
+     * Bean Validation 分组。
+     */
     Class<?>[] groups() default {};
 
+    /**
+     * Bean Validation 负载信息。
+     */
     Class<? extends Payload>[] payload() default {};
 
 }

ruoyi-common/ruoyi-common-log/pom.xml

@@ -17,16 +17,19 @@
 
     <dependencies>
 
+        <!-- satoken -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-satoken</artifactId>
         </dependency>
 
+        <!-- 序列化模块 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-json</artifactId>
         </dependency>
 
+        <!-- api模块 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-api</artifactId>

ruoyi-common/ruoyi-common-mail/pom.xml

@@ -16,15 +16,18 @@
     </description>
 
     <dependencies>
+        <!-- 核心模块 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-core</artifactId>
         </dependency>
 
+        <!-- 邮件接口 -->
         <dependency>
             <groupId>jakarta.mail</groupId>
             <artifactId>jakarta.mail-api</artifactId>
         </dependency>
+        <!-- 邮件实现 -->
         <dependency>
             <groupId>org.eclipse.angus</groupId>
             <artifactId>jakarta.mail</artifactId>

ruoyi-common/ruoyi-common-mcp/pom.xml

@@ -16,16 +16,19 @@
     </description>
 
     <dependencies>
+        <!-- 核心模块 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-core</artifactId>
         </dependency>
 
+        <!-- MCP 服务端 -->
         <dependency>
             <groupId>org.springframework.ai</groupId>
             <artifactId>spring-ai-starter-mcp-server-webmvc</artifactId>
         </dependency>
 
+        <!-- MCP 客户端 -->
         <dependency>
             <groupId>org.springframework.ai</groupId>
             <artifactId>spring-ai-starter-mcp-client</artifactId>

ruoyi-common/ruoyi-common-mcp/src/main/java/org/dromara/common/mcp/core/McpResourceReadResult.java

@@ -14,6 +14,13 @@ public record McpResourceReadResult(
     List<McpSchema.ResourceContents> contents
 ) {
 
+    /**
+     * 将 MCP SDK 资源读取结果转换为带服务端名称的项目结果对象。
+     *
+     * @param serverName MCP 服务端名称
+     * @param result MCP SDK 资源读取结果
+     * @return MCP 资源读取结果
+     */
     public static McpResourceReadResult of(String serverName, McpSchema.ReadResourceResult result) {
         return new McpResourceReadResult(serverName, result.contents());
     }

ruoyi-common/ruoyi-common-mcp/src/main/java/org/dromara/common/mcp/core/McpToolCallResult.java

@@ -16,6 +16,13 @@ public record McpToolCallResult(
     Object structuredContent
 ) {
 
+    /**
+     * 将 MCP SDK 工具调用结果转换为带服务端名称的项目结果对象。
+     *
+     * @param serverName MCP 服务端名称
+     * @param result MCP SDK 工具调用结果
+     * @return MCP 工具调用结果
+     */
     public static McpToolCallResult of(String serverName, McpSchema.CallToolResult result) {
         return new McpToolCallResult(
             serverName,

ruoyi-common/ruoyi-common-mqtt/pom.xml

@@ -16,16 +16,19 @@
     </description>
 
     <dependencies>
+        <!-- 核心模块 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-core</artifactId>
         </dependency>
 
+        <!-- 序列化模块 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-json</artifactId>
         </dependency>
 
+        <!-- mqtt客户端 -->
         <dependency>
             <groupId>org.dromara.mica-mqtt</groupId>
             <artifactId>mica-mqtt-client-spring-boot-starter</artifactId>

ruoyi-common/ruoyi-common-mqtt/src/main/java/org/dromara/common/mqtt/config/MqttAutoConfiguration.java

@@ -31,11 +31,22 @@ import java.util.concurrent.TimeUnit;
 @ConditionalOnProperty(value = "mqtt.client.enabled", havingValue = "true")
 public class MqttAutoConfiguration {
 
+    /**
+     * 创建 MQTT 客户端连接监听器。
+     *
+     * @param mqttClientCreator MQTT 客户端创建器
+     * @return MQTT 客户端连接监听器
+     */
     @Bean
     public MqttClientConnectListener mqttClientConnectListener(MqttClientCreator mqttClientCreator) {
         return new MqttClientConnectListener(mqttClientCreator);
     }
 
+    /**
+     * 创建 MQTT 全局消息监听器。
+     *
+     * @return MQTT 全局消息监听器
+     */
     @Bean
     public MqttClientGlobalMessageListener mqttClientGlobalMessageListener() {
         return new MqttClientGlobalMessageListener();

ruoyi-common/ruoyi-common-mybatis/pom.xml

@@ -16,16 +16,19 @@
     </description>
 
     <dependencies>
+        <!-- 核心模块 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-core</artifactId>
         </dependency>
 
+        <!-- satoken -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-satoken</artifactId>
         </dependency>
 
+        <!-- api模块 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-api</artifactId>
@@ -37,16 +40,19 @@
             <artifactId>dynamic-datasource-spring-boot4-starter</artifactId>
         </dependency>
 
+        <!-- MyBatis Plus 启动器 -->
         <dependency>
             <groupId>com.baomidou</groupId>
             <artifactId>mybatis-plus-spring-boot4-starter</artifactId>
         </dependency>
 
+        <!-- MyBatis Plus JSqlParser 支持 -->
         <dependency>
             <groupId>com.baomidou</groupId>
             <artifactId>mybatis-plus-jsqlparser</artifactId>
         </dependency>
 
+        <!-- MyBatis Plus Join -->
         <dependency>
             <groupId>com.github.yulichang</groupId>
             <artifactId>mybatis-plus-join-boot-starter</artifactId>

ruoyi-common/ruoyi-common-mybatis/src/main/java/com/github/yulichang/injector/MPJSqlInjector.java

@@ -143,6 +143,12 @@ public class MPJSqlInjector extends DefaultSqlInjector {
         TableHelper.init(modelClass, supplier.get());
     }
 
+    /**
+     * 兼容旧版泛型解析逻辑，提取 Mapper 绑定的实体类型。
+     *
+     * @param mapperClass Mapper 类型
+     * @return Mapper 泛型中的实体类型，无法解析时返回 null
+     */
     @SuppressWarnings("IfStatementWithIdenticalBranches")
     protected Class<?> extractModelClassOld(Class<?> mapperClass) {
         Type[] types = mapperClass.getGenericInterfaces();

ruoyi-common/ruoyi-common-mybatis/src/main/java/org/dromara/common/mybatis/config/MybatisPlusConfig.java

@@ -32,6 +32,11 @@ import org.springframework.transaction.annotation.EnableTransactionManagement;
 @PropertySource(value = "classpath:common-mybatis.yml", factory = YmlPropertySourceFactory.class)
 public class MybatisPlusConfig {
 
+    /**
+     * 组装 MyBatis-Plus 核心拦截器链。
+     *
+     * @return MyBatis-Plus 拦截器
+     */
     @Bean
     public MybatisPlusInterceptor mybatisPlusInterceptor() {
         MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();

ruoyi-common/ruoyi-common-oss/pom.xml

@@ -16,11 +16,13 @@
     </description>
 
     <dependencies>
+        <!-- 序列化模块 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-json</artifactId>
         </dependency>
 
+        <!-- 缓存服务 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-redis</artifactId>

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

@@ -31,6 +31,21 @@ public record GetObjectResult(
         Map<String, String> metadata
 ) {
 
+    /**
+     * 构建文件对象获取结果。
+     *
+     * @param key 对象 Key
+     * @param eTag 对象 ETag
+     * @param lastModified 最后修改时间
+     * @param size 对象大小
+     * @param contentType 内容类型
+     * @param contentDisposition 内容处置方式
+     * @param contentRange 内容范围
+     * @param contentEncoding 内容编码
+     * @param contentLanguage 内容语言
+     * @param metadata 自定义元数据
+     * @return 文件对象获取结果
+     */
     public static GetObjectResult form(String key, String eTag, LocalDateTime lastModified, long size
             , String contentType, String contentDisposition, String contentRange, String contentEncoding, String contentLanguage
             , Map<String, String> metadata) {

ruoyi-common/ruoyi-common-push/pom.xml

@@ -16,26 +16,32 @@
     </description>
 
     <dependencies>
+        <!-- 核心模块 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-core</artifactId>
         </dependency>
+        <!-- 缓存服务 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-redis</artifactId>
         </dependency>
+        <!-- satoken -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-satoken</artifactId>
         </dependency>
+        <!-- 序列化模块 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-json</artifactId>
         </dependency>
+        <!-- api模块 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-api</artifactId>
         </dependency>
+        <!-- WebSocket 服务 -->
         <dependency>
             <groupId>org.springframework.boot</groupId>
             <artifactId>spring-boot-starter-websocket</artifactId>

ruoyi-common/ruoyi-common-redis/pom.xml

@@ -22,6 +22,7 @@
             <artifactId>ruoyi-common-core</artifactId>
         </dependency>
 
+        <!-- 序列化模块 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-json</artifactId>
@@ -33,32 +34,38 @@
             <artifactId>redisson-spring-boot-starter</artifactId>
         </dependency>
 
+        <!-- Redisson 缓存 -->
         <dependency>
             <groupId>org.redisson</groupId>
             <artifactId>redisson-spring-cache</artifactId>
             <version>${redisson.version}</version>
         </dependency>
 
+        <!-- 分布式锁 -->
         <dependency>
             <groupId>com.baomidou</groupId>
             <artifactId>lock4j-redisson-spring-boot-starter</artifactId>
         </dependency>
 
+        <!-- 本地缓存 -->
         <dependency>
             <groupId>com.github.ben-manes.caffeine</groupId>
             <artifactId>caffeine</artifactId>
         </dependency>
 
+        <!-- Jackson Databind -->
         <dependency>
             <groupId>tools.jackson.core</groupId>
             <artifactId>jackson-databind</artifactId>
         </dependency>
 
+        <!-- Hutool 加密工具 -->
         <dependency>
             <groupId>cn.hutool</groupId>
             <artifactId>hutool-crypto</artifactId>
         </dependency>
 
+        <!-- Sa-Token 核心 -->
         <dependency>
             <groupId>cn.dev33</groupId>
             <artifactId>sa-token-core</artifactId>

ruoyi-common/ruoyi-common-redis/src/main/java/org/dromara/common/redis/annotation/RepeatSubmit.java

@@ -19,6 +19,9 @@ public @interface RepeatSubmit {
      */
     int interval() default 5000;
 
+    /**
+     * 重复提交间隔时间单位。
+     */
     TimeUnit timeUnit() default TimeUnit.MILLISECONDS;
 
     /**

ruoyi-common/ruoyi-common-redis/src/main/java/org/dromara/common/redis/aspectj/RateLimiterAspect.java

@@ -50,6 +50,12 @@ public class RateLimiterAspect {
     private final ParameterNameDiscoverer pnd = new DefaultParameterNameDiscoverer();
 
 
+    /**
+     * 在限流注解方法执行前扣减令牌，令牌不足时阻断请求。
+     *
+     * @param point 切点信息
+     * @param rateLimiter 限流注解配置
+     */
     @Before("@annotation(rateLimiter)")
     public void doBefore(JoinPoint point, RateLimiter rateLimiter) {
         int time = rateLimiter.time();

ruoyi-common/ruoyi-common-redis/src/main/java/org/dromara/common/redis/config/IdempotentConfig.java

@@ -13,6 +13,11 @@ import org.springframework.data.redis.connection.RedisConfiguration;
 @AutoConfiguration(after = RedisConfiguration.class)
 public class IdempotentConfig {
 
+    /**
+     * 创建重复提交切面。
+     *
+     * @return 重复提交切面
+     */
     @Bean
     public RepeatSubmitAspect repeatSubmitAspect() {
         return new RepeatSubmitAspect();

ruoyi-common/ruoyi-common-redis/src/main/java/org/dromara/common/redis/config/RateLimiterConfig.java

@@ -6,12 +6,19 @@ import org.springframework.context.annotation.Bean;
 import org.springframework.data.redis.connection.RedisConfiguration;
 
 /**
+ * 限流功能配置。
+ *
  * @author guangxin
  * @date 2023/1/18
  */
 @AutoConfiguration(after = RedisConfiguration.class)
 public class RateLimiterConfig {
 
+    /**
+     * 创建限流切面。
+     *
+     * @return 限流切面
+     */
     @Bean
     public RateLimiterAspect rateLimiterAspect() {
         return new RateLimiterAspect();

ruoyi-common/ruoyi-common-satoken/pom.xml

@@ -13,6 +13,7 @@
 
     <dependencies>
 
+        <!-- 核心模块 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-core</artifactId>
@@ -24,6 +25,7 @@
             <artifactId>ruoyi-common-redis</artifactId>
         </dependency>
 
+        <!-- api模块 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-api</artifactId>
@@ -53,6 +55,7 @@
             </exclusions>
         </dependency>
 
+        <!-- 本地缓存 -->
         <dependency>
             <groupId>com.github.ben-manes.caffeine</groupId>
             <artifactId>caffeine</artifactId>

ruoyi-common/ruoyi-common-security/pom.xml

@@ -16,6 +16,7 @@
     </description>
 
     <dependencies>
+        <!-- satoken -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-satoken</artifactId>

ruoyi-common/ruoyi-common-sensitive/pom.xml

@@ -16,6 +16,7 @@
     </description>
 
     <dependencies>
+        <!-- 序列化模块 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-json</artifactId>

ruoyi-common/ruoyi-common-sensitive/src/main/java/org/dromara/common/sensitive/config/SensitiveConfig.java

@@ -10,6 +10,11 @@ import org.springframework.context.annotation.Bean;
 @AutoConfiguration
 public class SensitiveConfig {
 
+    /**
+     * 创建脱敏 JSON 字段处理器。
+     *
+     * @return 脱敏 JSON 字段处理器
+     */
     @Bean
     public SensitiveJsonFieldProcessor sensitiveJsonFieldProcessor() {
         return new SensitiveJsonFieldProcessor();

ruoyi-common/ruoyi-common-sensitive/src/main/java/org/dromara/common/sensitive/core/SensitiveStrategy.java

@@ -105,8 +105,16 @@ public enum SensitiveStrategy {
 
     //可自行添加其他脱敏策略
 
+    /**
+     * 当前策略对应的脱敏函数。
+     */
     private final Function<String, String> desensitizer;
 
+    /**
+     * 获取当前策略对应的脱敏函数。
+     *
+     * @return 脱敏函数
+     */
     public Function<String, String> desensitizer() {
         return desensitizer;
     }

ruoyi-common/ruoyi-common-sms/pom.xml

@@ -17,6 +17,7 @@
 
     <dependencies>
 
+        <!-- 短信模块 -->
         <dependency>
             <groupId>org.dromara.sms4j</groupId>
             <artifactId>sms4j-spring-boot-starter</artifactId>

ruoyi-common/ruoyi-common-sms/src/main/java/org/dromara/common/sms/config/SmsAutoConfiguration.java

@@ -16,6 +16,11 @@ import org.springframework.context.annotation.Primary;
 @AutoConfiguration(after = {DataRedisAutoConfiguration.class})
 public class SmsAutoConfiguration {
 
+    /**
+     * 创建 sms4j 使用的短信缓存访问对象。
+     *
+     * @return 短信缓存访问对象
+     */
     @Primary
     @Bean
     public SmsDao smsDao() {

ruoyi-common/ruoyi-common-social/pom.xml

@@ -16,16 +16,19 @@
     </description>
 
     <dependencies>
+        <!-- 授权认证 -->
         <dependency>
             <groupId>me.zhyd.oauth</groupId>
             <artifactId>JustAuth</artifactId>
         </dependency>
 
+        <!-- 序列化模块 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-json</artifactId>
         </dependency>
 
+        <!-- 缓存服务 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-redis</artifactId>

ruoyi-common/ruoyi-common-translation/pom.xml

@@ -17,11 +17,13 @@
 
     <dependencies>
 
+        <!-- 序列化模块 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-json</artifactId>
         </dependency>
 
+        <!-- api模块 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-api</artifactId>

ruoyi-common/ruoyi-common-translation/src/main/java/org/dromara/common/translation/config/TranslationConfig.java

@@ -15,6 +15,12 @@ import java.util.List;
 @AutoConfiguration
 public class TranslationConfig {
 
+    /**
+     * 创建翻译 JSON 字段处理器。
+     *
+     * @param list 翻译实现集合
+     * @return 翻译 JSON 字段处理器
+     */
     @Bean
     public TranslationJsonFieldProcessor translationJsonFieldProcessor(List<TranslationInterface<?>> list) {
         return new TranslationJsonFieldProcessor(list);

ruoyi-common/ruoyi-common-web/pom.xml

@@ -16,6 +16,7 @@
     </description>
 
     <dependencies>
+        <!-- 序列化模块 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-json</artifactId>
@@ -38,16 +39,19 @@
             <artifactId>spring-boot-starter-jetty</artifactId>
         </dependency>
 
+        <!-- 监控端点 -->
         <dependency>
             <groupId>org.springframework.boot</groupId>
             <artifactId>spring-boot-starter-actuator</artifactId>
         </dependency>
 
+        <!-- 图形验证码 -->
         <dependency>
             <groupId>cn.hutool</groupId>
             <artifactId>hutool-captcha</artifactId>
         </dependency>
 
+        <!-- Hutool 加密工具 -->
         <dependency>
             <groupId>cn.hutool</groupId>
             <artifactId>hutool-crypto</artifactId>

ruoyi-extend/pom.xml

@@ -12,8 +12,11 @@
     <packaging>pom</packaging>
 
     <modules>
+        <!-- 监控服务 -->
         <module>ruoyi-monitor-admin</module>
+        <!-- Snail AI 服务端 -->
         <module>ruoyi-snailai-server</module>
+        <!-- SnailJob 服务端 -->
         <module>ruoyi-snailjob-server</module>
     </modules>
 

ruoyi-extend/ruoyi-monitor-admin/pom.xml

@@ -35,16 +35,19 @@
             <artifactId>spring-boot-starter-security</artifactId>
         </dependency>
 
+        <!-- Spring Boot Admin 服务端 -->
         <dependency>
             <groupId>de.codecentric</groupId>
             <artifactId>spring-boot-admin-starter-server</artifactId>
         </dependency>
 
+        <!-- Spring Boot Admin 客户端 -->
         <dependency>
             <groupId>de.codecentric</groupId>
             <artifactId>spring-boot-admin-starter-client</artifactId>
         </dependency>
 
+        <!-- lombok -->
         <dependency>
             <groupId>org.projectlombok</groupId>
             <artifactId>lombok</artifactId>

ruoyi-extend/ruoyi-snailai-server/pom.xml

@@ -12,12 +12,14 @@
     <artifactId>ruoyi-snailai-server</artifactId>
 
     <dependencies>
+        <!-- Snail AI 服务端 -->
         <dependency>
             <groupId>com.aizuda</groupId>
             <artifactId>snail-ai-starter</artifactId>
             <version>${snailai.version}</version>
         </dependency>
 
+        <!-- Spring Boot Admin 客户端 -->
         <dependency>
             <groupId>de.codecentric</groupId>
             <artifactId>spring-boot-admin-starter-client</artifactId>

ruoyi-extend/ruoyi-snailai-server/src/main/java/com/aizuda/snail/ai/starter/filter/ActuatorAuthFilter.java

@@ -13,11 +13,22 @@ import java.io.IOException;
 import java.nio.charset.StandardCharsets;
 import java.util.Base64;
 
+/**
+ * Actuator Basic Auth 认证过滤器。
+ *
+ * @author Lion Li
+ */
 public class ActuatorAuthFilter implements Filter {
 
     private final String username;
     private final String password;
 
+    /**
+     * 创建 Actuator 认证过滤器。
+     *
+     * @param username 认证用户名
+     * @param password 认证密码
+     */
     public ActuatorAuthFilter(String username, String password) {
         this.username = username;
         this.password = password;

ruoyi-extend/ruoyi-snailai-server/src/main/java/com/aizuda/snail/ai/starter/filter/SecurityConfig.java

@@ -18,6 +18,11 @@ public class SecurityConfig {
     @Value("${spring.boot.admin.client.password}")
     private String password;
 
+    /**
+     * 注册 Actuator Basic Auth 过滤器。
+     *
+     * @return Actuator 过滤器注册对象
+     */
     @Bean
     public FilterRegistrationBean<ActuatorAuthFilter> actuatorFilterRegistrationBean() {
         FilterRegistrationBean<ActuatorAuthFilter> registrationBean = new FilterRegistrationBean<>();

ruoyi-extend/ruoyi-snailjob-server/pom.xml

@@ -12,6 +12,7 @@
     <artifactId>ruoyi-snailjob-server</artifactId>
 
     <dependencies>
+        <!-- SnailJob 服务端 -->
         <dependency>
             <groupId>com.aizuda</groupId>
             <artifactId>snail-job-server-starter</artifactId>
@@ -24,12 +25,14 @@
             </exclusions>
         </dependency>
 
+        <!-- Scala 运行库 -->
         <dependency>
             <groupId>org.scala-lang</groupId>
             <artifactId>scala-library</artifactId>
             <version>2.13.9</version>
         </dependency>
 
+        <!-- Spring Boot Admin 客户端 -->
         <dependency>
             <groupId>de.codecentric</groupId>
             <artifactId>spring-boot-admin-starter-client</artifactId>

ruoyi-extend/ruoyi-snailjob-server/src/main/java/com/aizuda/snailjob/server/starter/filter/ActuatorAuthFilter.java

@@ -8,11 +8,22 @@ import java.io.IOException;
 import java.nio.charset.StandardCharsets;
 import java.util.Base64;
 
+/**
+ * Actuator Basic Auth 认证过滤器。
+ *
+ * @author Lion Li
+ */
 public class ActuatorAuthFilter implements Filter {
 
     private final String username;
     private final String password;
 
+    /**
+     * 创建 Actuator 认证过滤器。
+     *
+     * @param username 认证用户名
+     * @param password 认证密码
+     */
     public ActuatorAuthFilter(String username, String password) {
         this.username = username;
         this.password = password;

ruoyi-extend/ruoyi-snailjob-server/src/main/java/com/aizuda/snailjob/server/starter/filter/SecurityConfig.java

@@ -18,6 +18,11 @@ public class SecurityConfig {
     @Value("${spring.boot.admin.client.password}")
     private String password;
 
+    /**
+     * 注册 Actuator Basic Auth 过滤器。
+     *
+     * @return Actuator 过滤器注册对象
+     */
     @Bean
     public FilterRegistrationBean<ActuatorAuthFilter> actuatorFilterRegistrationBean() {
         FilterRegistrationBean<ActuatorAuthFilter> registrationBean = new FilterRegistrationBean<>();

ruoyi-modules/pom.xml

@@ -16,11 +16,17 @@
     </description>
 
     <modules>
+        <!-- demo模块 -->
         <module>ruoyi-demo</module>
+        <!-- 代码生成模块 -->
         <module>ruoyi-gen</module>
+        <!-- 调度任务模块 -->
         <module>ruoyi-job</module>
+        <!-- 系统模块 -->
         <module>ruoyi-system</module>
+        <!-- 工作流模块 -->
         <module>ruoyi-workflow</module>
+        <!-- AI业务模块 -->
         <module>ruoyi-ai</module>
     </modules>
 

ruoyi-modules/ruoyi-ai/pom.xml

@@ -17,22 +17,27 @@
 
     <dependencies>
 
+        <!-- 核心模块 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-core</artifactId>
         </dependency>
+        <!-- api模块 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-api</artifactId>
         </dependency>
+        <!-- ai模块 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-ai</artifactId>
         </dependency>
+        <!-- satoken -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-satoken</artifactId>
         </dependency>
+        <!-- web服务 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-web</artifactId>

ruoyi-modules/ruoyi-demo/pom.xml

@@ -23,86 +23,103 @@
             <artifactId>ruoyi-common-core</artifactId>
         </dependency>
 
+        <!-- api模块 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-api</artifactId>
         </dependency>
 
+        <!-- 接口模块 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-doc</artifactId>
         </dependency>
 
+        <!-- 短信模块 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-sms</artifactId>
         </dependency>
 
+        <!-- 邮件服务 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-mail</artifactId>
         </dependency>
 
+        <!-- 缓存服务 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-redis</artifactId>
         </dependency>
 
+        <!-- 数据库服务 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-mybatis</artifactId>
         </dependency>
 
+        <!-- 日志记录 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-log</artifactId>
         </dependency>
 
+        <!-- excel -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-excel</artifactId>
         </dependency>
 
+        <!-- 安全模块 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-security</artifactId>
         </dependency>
 
+        <!-- web服务 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-web</artifactId>
         </dependency>
 
+        <!-- 翻译模块 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-translation</artifactId>
         </dependency>
 
+        <!-- 脱敏模块 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-sensitive</artifactId>
         </dependency>
 
+        <!-- 数据库加解密模块 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-encrypt</artifactId>
         </dependency>
 
+        <!-- ES搜索引擎服务 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-elasticsearch</artifactId>
         </dependency>
 
+        <!-- 消息推送模块 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-push</artifactId>
         </dependency>
 
+        <!-- mqtt模块 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-mqtt</artifactId>
         </dependency>
 
+        <!-- mcp模块 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-mcp</artifactId>

ruoyi-modules/ruoyi-demo/src/main/java/org/dromara/demo/controller/MqttController.java

@@ -36,22 +36,45 @@ public class MqttController {
     @Autowired
     private MqttClientTemplate client;
 
+    /**
+     * 发布一条 MQTT 测试消息。
+     *
+     * @return 是否发送成功
+     */
     @GetMapping("/send")
     public boolean send() {
         client.publish("/test/client", "测试测试".getBytes(StandardCharsets.UTF_8));
         return true;
     }
 
+    /**
+     * 订阅 QoS0 测试主题并打印原始消息。
+     *
+     * @param topic 消息主题
+     * @param payload 消息内容
+     */
     @MqttClientSubscribe("/test/#")
     public void subQos0(String topic, byte[] payload) {
         log.info("topic:{} payload:{}", topic, new String(payload, StandardCharsets.UTF_8));
     }
 
+    /**
+     * 订阅 QoS1 测试主题并打印原始消息。
+     *
+     * @param topic 消息主题
+     * @param payload 消息内容
+     */
     @MqttClientSubscribe(value = "/qos1/#", qos = MqttQoS.QOS1)
     public void subQos1(String topic, byte[] payload) {
         log.info("topic:{} payload:{}", topic, new String(payload, StandardCharsets.UTF_8));
     }
 
+    /**
+     * 订阅带产品和设备占位符的注册主题。
+     *
+     * @param topic 消息主题
+     * @param payload 消息内容
+     */
     @MqttClientSubscribe("/sys/${productKey}/${deviceName}/thing/sub/register")
     public void thingSubRegister(String topic, byte[] payload) {
         // 1.3.8 开始支持，@MqttClientSubscribe 注解支持 ${} 变量替换，会默认替换成 +
@@ -59,6 +82,13 @@ public class MqttController {
         log.info("topic:{} payload:{}", topic, new String(payload, StandardCharsets.UTF_8));
     }
 
+    /**
+     * 订阅 JSON 测试主题并演示自定义反序列化。
+     *
+     * @param topic 消息主题
+     * @param message MQTT 原始消息
+     * @param data 反序列化后的演示数据
+     */
     @MqttClientSubscribe(
         value = "/test/json",
         deserialize = MqttJsonDeserializer.class // 2.4.5 开始支持 自定义序列化，默认 json 序列化

ruoyi-modules/ruoyi-demo/src/main/java/org/dromara/demo/domain/TestDemoEncrypt.java

@@ -6,6 +6,11 @@ import org.dromara.common.encrypt.enums.AlgorithmType;
 import lombok.Data;
 import lombok.EqualsAndHashCode;
 
+/**
+ * 测试加密字段实体。
+ *
+ * @author Lion Li
+ */
 @Data
 @EqualsAndHashCode(callSuper = true)
 @TableName("test_demo")

ruoyi-modules/ruoyi-demo/src/main/java/org/dromara/demo/esmapper/DocumentMapper.java

@@ -3,5 +3,10 @@ package org.dromara.demo.esmapper;
 import org.dromara.demo.domain.Document;
 import org.dromara.easyes.core.kernel.BaseEsMapper;
 
+/**
+ * Easy-Es 文档 Mapper。
+ *
+ * @author Lion Li
+ */
 public interface DocumentMapper extends BaseEsMapper<Document> {
 }

ruoyi-modules/ruoyi-gen/pom.xml

@@ -22,21 +22,25 @@
             <artifactId>ruoyi-common-core</artifactId>
         </dependency>
 
+        <!-- 接口模块 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-doc</artifactId>
         </dependency>
 
+        <!-- 数据库服务 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-mybatis</artifactId>
         </dependency>
 
+        <!-- web服务 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-web</artifactId>
         </dependency>
 
+        <!-- 日志记录 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-log</artifactId>
@@ -48,12 +52,14 @@
             <artifactId>velocity-engine-core</artifactId>
         </dependency>
 
+        <!-- AnyLine Spring JDBC 环境 -->
         <dependency>
             <groupId>org.anyline</groupId>
             <artifactId>anyline-environment-spring-data-jdbc</artifactId>
             <version>${anyline.version}</version>
         </dependency>
 
+        <!-- AnyLine MySQL 驱动 -->
         <dependency>
             <groupId>org.anyline</groupId>
             <artifactId>anyline-data-jdbc-mysql</artifactId>

ruoyi-modules/ruoyi-job/pom.xml

@@ -23,6 +23,7 @@
             <artifactId>ruoyi-common-json</artifactId>
         </dependency>
 
+        <!-- 调度模块 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-job</artifactId>

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

@@ -22,6 +22,13 @@ import java.math.BigDecimal;
 @JobExecutor(name = "alipayBillTask")
 public class AlipayBillTask {
 
+    /**
+     * 执行支付宝账单模拟任务，并将结果写入工作流上下文。
+     *
+     * @param jobArgs 任务执行参数
+     * @return 执行结果
+     * @throws InterruptedException 任务被中断时抛出
+     */
     public ExecuteResult jobExecute(JobArgs jobArgs) throws InterruptedException {
         // 设置清算日期
         String settlementDate = (String) jobArgs.getWfContext().get("settlementDate");

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

@@ -21,6 +21,13 @@ import java.math.BigDecimal;
 @JobExecutor(name = "summaryBillTask")
 public class SummaryBillTask {
 
+    /**
+     * 汇总工作流上下文中的微信与支付宝账单金额。
+     *
+     * @param jobArgs 任务执行参数
+     * @return 汇总执行结果
+     * @throws InterruptedException 任务被中断时抛出
+     */
     public ExecuteResult jobExecute(JobArgs jobArgs) throws InterruptedException {
         // 获得微信账单
         BigDecimal wechatAmount = BigDecimal.valueOf(0);

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

@@ -23,6 +23,12 @@ public class TestBroadcastJob {
     @Value("${snail-job.port}")
     private int clientPort;
 
+    /**
+     * 执行广播任务示例，随机模拟成功或失败。
+     *
+     * @param jobArgs 任务执行参数
+     * @return 执行结果
+     */
     public ExecuteResult jobExecute(JobArgs jobArgs) {
         int randomInt = RandomUtil.randomInt(100);
         log.info("随机数: {}", randomInt);

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

@@ -26,6 +26,13 @@ import java.util.stream.IntStream;
 @JobExecutor(name = "testMapJobAnnotation")
 public class TestMapJobAnnotation {
 
+    /**
+     * 根 Map 任务，将示例数据拆分为多个分片任务。
+     *
+     * @param mapArgs Map 任务参数
+     * @param mapHandler 分片调度处理器
+     * @return 分片调度结果
+     */
     @MapExecutor
     public ExecuteResult doJobMapExecute(MapArgs mapArgs, MapHandler mapHandler) {
         // 生成1~200数值并分片
@@ -39,6 +46,12 @@ public class TestMapJobAnnotation {
         return mapHandler.doMap(partition, "doCalc");
     }
 
+    /**
+     * 执行单个分片的累加计算。
+     *
+     * @param mapArgs 分片任务参数
+     * @return 分片计算结果
+     */
     @MapExecutor(taskName = "doCalc")
     public ExecuteResult doCalc(MapArgs mapArgs) {
         List<Integer> sourceList = (List<Integer>) mapArgs.getMapResult();

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

@@ -28,6 +28,13 @@ import java.util.stream.IntStream;
 @JobExecutor(name = "testMapReduceAnnotation1")
 public class TestMapReduceAnnotation1 {
 
+    /**
+     * 根 Map 任务，将示例数据拆分为多个分片任务。
+     *
+     * @param mapArgs Map 任务参数
+     * @param mapHandler 分片调度处理器
+     * @return 分片调度结果
+     */
     @MapExecutor
     public ExecuteResult rootMapExecute(MapArgs mapArgs, MapHandler mapHandler) {
         int partitionSize = 50;
@@ -40,6 +47,12 @@ public class TestMapReduceAnnotation1 {
         return mapHandler.doMap(partition, "doCalc");
     }
 
+    /**
+     * 执行单个分片的累加计算。
+     *
+     * @param mapArgs 分片任务参数
+     * @return 分片计算结果
+     */
     @MapExecutor(taskName = "doCalc")
     public ExecuteResult doCalc(MapArgs mapArgs) {
         List<Integer> sourceList = (List<Integer>) mapArgs.getMapResult();
@@ -51,6 +64,12 @@ public class TestMapReduceAnnotation1 {
         return ExecuteResult.success(partitionTotal);
     }
 
+    /**
+     * 汇总所有 Map 分片的计算结果。
+     *
+     * @param reduceArgs Reduce 任务参数
+     * @return 汇总结果
+     */
     @ReduceExecutor
     public ExecuteResult reduceExecute(ReduceArgs reduceArgs) {
         int reduceTotal = reduceArgs.getMapResult().stream().mapToInt(i -> Integer.parseInt((String) i)).sum();

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

@@ -17,6 +17,12 @@ import org.springframework.stereotype.Component;
 @JobExecutor(name = "testStaticShardingJob")
 public class TestStaticShardingJob {
 
+    /**
+     * 执行静态分片任务示例。
+     *
+     * @param jobArgs 任务执行参数
+     * @return 执行结果
+     */
     public ExecuteResult jobExecute(JobArgs jobArgs) {
         String jobParams = Convert.toStr(jobArgs.getJobParams());
         SnailJobLog.LOCAL.info("开始执行分片任务,参数:{}", jobParams);

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

@@ -22,6 +22,13 @@ import java.math.BigDecimal;
 @JobExecutor(name = "wechatBillTask")
 public class WechatBillTask {
 
+    /**
+     * 执行微信账单模拟任务，并将结果写入工作流上下文。
+     *
+     * @param jobArgs 任务执行参数
+     * @return 执行结果
+     * @throws InterruptedException 任务被中断时抛出
+     */
     public ExecuteResult jobExecute(JobArgs jobArgs) throws InterruptedException {
         // 从上下文中获得清算日期并设置，如果上下文中清算日期
         // 是sysdate设置为当前日期；否则取管理页面设置的值

ruoyi-modules/ruoyi-system/pom.xml

@@ -22,21 +22,25 @@
             <artifactId>ruoyi-common-core</artifactId>
         </dependency>
 
+        <!-- api模块 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-api</artifactId>
         </dependency>
 
+        <!-- 接口模块 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-doc</artifactId>
         </dependency>
 
+        <!-- 数据库服务 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-mybatis</artifactId>
         </dependency>
 
+        <!-- 翻译模块 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-translation</artifactId>
@@ -48,6 +52,7 @@
             <artifactId>ruoyi-common-oss</artifactId>
         </dependency>
 
+        <!-- 日志记录 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-log</artifactId>
@@ -65,26 +70,31 @@
             <artifactId>ruoyi-common-sms</artifactId>
         </dependency>
 
+        <!-- 安全模块 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-security</artifactId>
         </dependency>
 
+        <!-- web服务 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-web</artifactId>
         </dependency>
 
+        <!-- 脱敏模块 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-sensitive</artifactId>
         </dependency>
 
+        <!-- 数据库加解密模块 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-encrypt</artifactId>
         </dependency>
 
+        <!-- 消息推送模块 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-push</artifactId>

ruoyi-modules/ruoyi-workflow/pom.xml

@@ -18,63 +18,84 @@
 
     <dependencies>
 
+        <!-- 消息推送模块 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-push</artifactId>
         </dependency>
 
+        <!-- 接口模块 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-doc</artifactId>
         </dependency>
 
+        <!-- 邮件服务 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-mail</artifactId>
         </dependency>
 
+        <!-- 短信模块 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-sms</artifactId>
         </dependency>
 
+        <!-- 数据库服务 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-mybatis</artifactId>
         </dependency>
+
+        <!-- web服务 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-web</artifactId>
         </dependency>
+
+        <!-- 日志记录 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-log</artifactId>
         </dependency>
+
+        <!-- excel -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-excel</artifactId>
         </dependency>
+
+        <!-- 翻译模块 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-translation</artifactId>
         </dependency>
+
+        <!-- 安全模块 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-common-security</artifactId>
         </dependency>
+
+        <!-- api模块 -->
         <dependency>
             <groupId>org.dromara</groupId>
             <artifactId>ruoyi-api</artifactId>
         </dependency>
+
+        <!-- Warm-Flow 工作流引擎 -->
         <dependency>
             <groupId>org.dromara.warm</groupId>
             <artifactId>warm-flow-mybatis-plus-sb3-starter</artifactId>
         </dependency>
+
+        <!-- Warm-Flow UI 插件 -->
         <dependency>
             <groupId>org.dromara.warm</groupId>
             <artifactId>warm-flow-plugin-ui-sb-web</artifactId>
         </dependency>
+
     </dependencies>
 
 </project>
-