docs(common): refine shared metadata

dc3-common/dc3-common-log/src/main/java/io/github/pnoker/common/annotation/LogsTypeEnum.java

@@ -20,11 +20,14 @@ package io.github.pnoker.common.annotation;
 import lombok.Getter;
 
 /**
- * Enumeration representing different types of log levels used in the DC3 IoT Platform.
- * Provides standardized log levels for consistent logging across the platform: - INFO:
- * General information messages - WARN: Warning messages indicating potential issues -
- * DEBUG: Detailed debug information for development/troubleshooting - ERROR: Error
- * messages for critical issues and failures
+ * Enumeration of log levels used by the DC3 IoT Platform.
+ *
+ * <ul>
+ *   <li>{@link #INFO}: general information messages</li>
+ *   <li>{@link #WARN}: warning messages indicating potential issues</li>
+ *   <li>{@link #DEBUG}: detailed information for development and troubleshooting</li>
+ *   <li>{@link #ERROR}: error messages for failures</li>
+ * </ul>
  *
  * @author pnoker
  * @version 2025.9.0

dc3-common/dc3-common-repository/src/main/java/io/github/pnoker/common/entity/query/PointValueQuery.java

@@ -93,13 +93,13 @@ public class PointValueQuery implements Serializable {
     /**
      * Enable flag to filter active/inactive points
      */
-    @Schema(description = "Enable flag: 0=enabled, 1=disabled")
+    @Schema(description = "Enable flag enum (ENABLE or DISABLE)")
     private EnableFlagEnum enableFlag;
 
     /**
      * Optional lower bound for create_time filtering (time range feature).
      */
-    @Schema(description = "create time from")
+    @Schema(description = "Start time for querying point values")
     private java.time.LocalDateTime createTimeFrom;
 
     /**
@@ -107,7 +107,7 @@ public class PointValueQuery implements Serializable {
      * createTimeFrom = now - rangeHours. Retained for backward compatibility; new callers
      * should set {@link #rangeKey}.
      */
-    @Schema(description = "range hours")
+    @Schema(description = "Fallback rolling time range in hours")
     private Integer rangeHours;
 
     /**
@@ -116,7 +116,7 @@ public class PointValueQuery implements Serializable {
      * {@code 24h}, {@code 7d}, {@code 30d}). Takes precedence over {@link #rangeHours}
      * when both are supplied.
      */
-    @Schema(description = "range key")
+    @Schema(description = "Preset time range key: today, 24h, 7d, or 30d")
     private String rangeKey;
 
 }

dc3-common/dc3-common-repository/src/main/java/io/github/pnoker/common/entity/query/WindowAggregateRequest.java

@@ -17,6 +17,7 @@
 
 package io.github.pnoker.common.entity.query;
 
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.AllArgsConstructor;
 import lombok.Builder;
 import lombok.Getter;
@@ -38,6 +39,7 @@ import java.time.LocalDateTime;
  * @version 2026.5.21
  * @since 2026.5.21
  */
+@Schema(description = "Window aggregation request")
 @Getter
 @Setter
 @Builder
@@ -46,16 +48,22 @@ import java.time.LocalDateTime;
 @AllArgsConstructor
 public class WindowAggregateRequest {
 
+    @Schema(description = "Tenant ID")
     private Long tenantId;
 
+    @Schema(description = "Device ID")
     private Long deviceId;
 
+    @Schema(description = "Point ID")
     private Long pointId;
 
+    @Schema(description = "Aggregate function: AVG, MIN, MAX, SUM, or COUNT", example = "AVG")
     private String function;
 
+    @Schema(description = "Inclusive start time")
     private LocalDateTime from;
 
+    @Schema(description = "Exclusive end time")
     private LocalDateTime to;
 
 }