OCT REM: 1. 修正代码警告

src/main/java/com/cmhi/magent/annotation/AutoExternString.java

@@ -3,7 +3,6 @@ package com.cmhi.magent.annotation;
 import com.cmhi.magent.annotation.impl.AutoExternStringJsonProcess;
 import com.cmhi.magent.common.NoneEnum;
 import com.cmhi.magent.common.UtilsFormatType;
-import com.fasterxml.jackson.databind.annotation.JsonSerialize;
 
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;

src/main/java/com/cmhi/magent/annotation/OperationLogAnnotation.java

@@ -29,7 +29,7 @@ import java.lang.annotation.Target;
  * </ul>
  * </p>
  *
- * @author
+ * @author huangxin@cmhi.chinamobile.com
  * @version 1.0.0
  * @since 2025-01-07
  */

src/main/java/com/cmhi/magent/annotation/impl/AutoExternStringJsonProcess.java

@@ -180,10 +180,9 @@ public class AutoExternStringJsonProcess extends JsonSerializer<Number> implemen
      * @param serializerProvider 序列化器提供者
      * @param property           目标字段
      * @return 配置化的序列化器实例
-     * @throws JsonMappingException 如果发生映射错误
      */
     @Override
-    public JsonSerializer<?> createContextual(SerializerProvider serializerProvider, BeanProperty property) throws JsonMappingException {
+    public JsonSerializer<?> createContextual(SerializerProvider serializerProvider, BeanProperty property) {
         if (property != null) {
             // 检查字段是否存在 @AutoExternString 注解
             AutoExternString annotation = property.getAnnotation(AutoExternString.class);

src/main/java/com/cmhi/magent/common/UtilsFormatType.java

@@ -17,7 +17,7 @@ import com.cmhi.magent.misc.MessageUtil;
  * <h2>枚举值说明</h2>
  * <ul>
  *     <li>{@link #FORMAT_BYTES}：按字节计算机单位格式化（基于 1024 计算）。</li>
- *     <li>{@link #FORMAT_BYTESDecimal}：按字节网络单位格式化（基于 1000 计算）。</li>
+ *     <li>{@link #FORMAT_BYTESDECIMAL}：按字节网络单位格式化（基于 1000 计算）。</li>
  *     <li>{@link #FORMAT_ENUM}：将值转换为枚举字符串。</li>
  *     <li>{@link #FORMAT_NONE}：使用 DES 对称加密。</li>
  * </ul>

src/main/java/com/cmhi/magent/config/CommonConfigure.java

@@ -126,9 +126,10 @@ public class CommonConfigure {
      * @return 默认的语言区域 {@link Locale}
      */
     public Locale getDefaultLocale() {
+        final int localSegment = 2;
         // 按下划线分割
         String[] parts = locale.split("_");
-        if (2 == parts.length) {
+        if (localSegment == parts.length) {
             return new Locale(parts[0], parts[1]);
         }
         // 如果格式不正确，则返回系统默认 Locale.CHINA

src/main/java/com/cmhi/magent/config/ObjectMapperProvider.java

@@ -2,6 +2,7 @@ package com.cmhi.magent.config;
 
 import com.fasterxml.jackson.databind.ObjectMapper;
 import lombok.Setter;
+import org.jetbrains.annotations.NotNull;
 import org.springframework.context.ApplicationContext;
 import org.springframework.context.ApplicationContextAware;
 import org.springframework.stereotype.Component;
@@ -39,7 +40,7 @@ public class ObjectMapperProvider implements ApplicationContextAware {
      * @param applicationContext Spring 应用上下文对象。
      */
     @Override
-    public void setApplicationContext(ApplicationContext applicationContext) {
+    public void setApplicationContext(@NotNull ApplicationContext applicationContext) {
         setContext(applicationContext);
     }
 

src/main/java/com/cmhi/magent/misc/HelperUtils.java

@@ -206,7 +206,7 @@ public class HelperUtils {
         if (request == null) {
             return "{}";
         }
-        Map<String, String> headers     = new HashMap<>();
+        Map<String, String> headers     = new HashMap<>(32);
         Enumeration<String> headerNames = request.getHeaderNames();
         while (headerNames.hasMoreElements()) {
             String name = headerNames.nextElement();

src/main/java/com/cmhi/magent/pojo/po/IfInterfaceInfo.java

@@ -2,7 +2,6 @@ package com.cmhi.magent.pojo.po;
 
 import com.cmhi.magent.annotation.AutoExternString;
 import com.cmhi.magent.common.UtilsFormatType;
-import com.fasterxml.jackson.annotation.JsonBackReference;
 import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.Data;
 import oshi.hardware.NetworkIF;

src/main/java/com/cmhi/magent/pojo/po/NetworkInfo.java

@@ -1,7 +1,5 @@
 package com.cmhi.magent.pojo.po;
 
-import com.cmhi.magent.annotation.AutoExternString;
-import com.cmhi.magent.common.UtilsFormatType;
 import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.Data;
 

src/main/java/com/cmhi/magent/pojo/vo/VersionResp.java

@@ -12,7 +12,7 @@ import lombok.NoArgsConstructor;
 
 /**
  * 版本信息响应类 {@code VersionResp}。
- *
+ * <p>
  * 用于封装版本信息查询接口的响应结果，继承自 {@link BaseRespStatus}，包含状态码、消息以及版本的详细信息。
  *
  * <p>
@@ -60,7 +60,7 @@ public class VersionResp extends BaseRespStatus {
 
     /**
      * 版本信息内容。
-     *
+     * <p>
      * 表示当前系统或模块的版本详情信息，包括版本号、发布日期以及描述信息。
      */
     @Schema(description = "版本信息内容，包括版本号、发布日期以及描述信息")

src/main/java/com/cmhi/magent/service/PlatformApiService.java

@@ -3,6 +3,27 @@ package com.cmhi.magent.service;
 import com.cmhi.magent.pojo.po.RegisterAgent;
 import com.fasterxml.jackson.core.JsonProcessingException;
 
+/**
+ * PlatformApiService 接口定义了与平台 API 通信的核心服务功能。
+ * <p>
+ * 该接口包含与平台交互的关键操作，具体实现类负责与平台进行数据交互。
+ * </p>
+ *
+ * @author huangxin@cmhi.chinamobile.com
+ * @version 1.0.0
+ * @since 2025-01-07
+ */
 public interface PlatformApiService {
+
+    /**
+     * 注册代理（Agent）。
+     * <p>
+     * 该方法用于将代理实例注册到平台，并返回平台生成的响应结果。
+     * </p>
+     *
+     * @param agent 包含代理注册信息的 {@link RegisterAgent} 对象
+     * @return 平台返回的结果，通常为一个 JSON 格式的字符串
+     * @throws JsonProcessingException 如果在处理 JSON 时发生错误
+     */
     String registerAgent(RegisterAgent agent) throws JsonProcessingException;
 }

src/main/java/com/cmhi/magent/service/impl/PlatformApiServiceImpl.java

@@ -8,11 +8,45 @@ import jakarta.annotation.Resource;
 import org.springframework.stereotype.Service;
 import org.springframework.web.reactive.function.client.WebClient;
 
+/**
+ * PlatformApiServiceImpl 是 {@link PlatformApiService} 的具体实现类。
+ * <p>
+ * 该类使用 {@link WebClient} 与平台 API 进行交互，提供了注册代理的功能。
+ * </p>
+ *
+ * <ul>
+ * <li>通过 WebClient 实现 HTTP 调用。</li>
+ * <li>在 JSON 序列化时使用辅助工具类 {@link HelperUtils}。</li>
+ * <li>提供了同步模式下的 API 调用。</li>
+ * </ul>
+ *
+ * @author huangxin@cmhi.chinamobile.com
+ * @version 1.0.0
+ * @since 2025-01-07
+ */
 @Service
 public class PlatformApiServiceImpl implements PlatformApiService {
+
+    /**
+     * 用于与平台 API 通信的 WebClient 实例。
+     * <p>
+     * 该实例通过 Spring 注解 {@code @Resource} 注入，支持异步和响应式调用。
+     * </p>
+     */
     @Resource
     private WebClient webClient;
 
+    /**
+     * 注册代理（Agent）。
+     * <p>
+     * 通过向平台 API 提供的注册接口（"/register"）发送 POST 请求，完成代理的注册操作。
+     * 请求体为转换为 JSON 格式的 {@link RegisterAgent} 对象。
+     * </p>
+     *
+     * @param agent 包含代理注册信息的 {@link RegisterAgent} 实例
+     * @return 平台返回的注册结果，通常为 JSON 格式的字符串
+     * @throws JsonProcessingException 如果在将 {@link RegisterAgent} 对象序列化为 JSON 时发生错误
+     */
     @Override
     public String registerAgent(RegisterAgent agent) throws JsonProcessingException {
         return webClient.post().uri("/register")            // 相对 URL

src/main/java/com/cmhi/magent/validation/valids/ValidHttpMethod.java

@@ -33,7 +33,7 @@ import java.lang.annotation.Target;
  * 该实现通常包含自定义逻辑，确保输入值属于预定义的 HTTP 方法集合。
  * </p>
  *
- * @author
+ * @author huangxin@cmhi.chinamobile.com
  * @version 1.0.0
  * @since 2025-01-07
  */

src/main/java/com/cmhi/magent/validation/valids/ValidPageSize.java

@@ -41,7 +41,7 @@ import java.lang.annotation.Target;
  * </pre>
  * </p>
  *
- * @author
+ * @author huangxin@cmhi.chinamobile.com
  * @version 1.0.0
  * @since 2025-01-07
  */