Merge pull request #17 from vnobo/dev

Update Angular & Express dependencies to their latest versions

boot/oauth2/src/main/java/com/plate/auth/commons/base/AbstractDatabase.java

@@ -7,33 +7,114 @@
 import org.springframework.jdbc.core.simple.JdbcClient;
 
 /**
- * @author <a href="https://github.com/vnobo">Alex bob</a>
+ * AbstractDatabase serves as an abstract base class for database-related services within the application.
+ * It centralizes common database connection and setup logic by providing initialized instances
+ * of JDBC clients and templates, along with a ConversionService, ready for extension by concrete service implementations.
+ * This class extends AbstractService which ensures additional initialization steps are performed after bean properties are set.
+ *
+ * <p>This abstract class autowires the following dependencies:</p>
+ * <ul>
+ *   <li>{@link JdbcClient}: For low-level JDBC operations.</li>
+ *   <li>{@link JdbcTemplate}: Simplifies JDBC operations with a template design pattern.</li>
+ *   <li>{@link NamedParameterJdbcTemplate}: Extends JdbcTemplate to use named parameters instead of traditional placeholders.</li>
+ *   <li>{@link ConversionService}: Handles conversion between different types when binding parameters or reading results.</li>
+ * </ul>
+ *
+ * <p>Subclasses should implement specific database interaction logic tailored to their needs,
+ * leveraging the provided database access tools.</p>
+ *
+ * <p>Usage Note:</p>
+ * <pre>
+ * {@code
+ * public class MyDatabaseService extends AbstractDatabase {
+ *     // Implement your service methods here
+ *     // Access JDBC tools using `this.jdbcTemplate`, `this.namedParameterJdbcTemplate`, etc.
+ * }
+ * }</pre>
  */
 public abstract class AbstractDatabase extends AbstractService {
 
+    /**
+     * The JDBC client instance used for executing SQL statements and managing
+     * database connections within the service. This field is populated by Spring's
+     * dependency injection through the {@link #setJdbcClient(JdbcClient)} method.
+     * It serves as the primary interface for interacting with the underlying database.
+     */
     protected JdbcClient jdbcClient;
+    /**
+     * JDBC template instance utilized for executing SQL commands and queries against the database.
+     * This field is automatically wired by the Spring framework through the {@link #setJdbcTemplate(JdbcTemplate)} method,
+     * which injects a configured {@link JdbcTemplate} capable of efficient data access operations.
+     */
     protected JdbcTemplate jdbcTemplate;
+    /**
+     * Instance of NamedParameterJdbcTemplate used for executing SQL queries with named parameters.
+     * This field is automatically wired by the Spring framework, facilitating safer and more convenient
+     * parameter binding in SQL statements compared to traditional positional parameters.
+     */
     protected NamedParameterJdbcTemplate namedParameterJdbcTemplate;
+    /**
+     * Conversion service used for type conversion operations within the application.
+     * This service facilitates binding of parameters and reading of results from the database,
+     * ensuring seamless communication between different data types.
+     */
     protected ConversionService conversionService;
 
+    /**
+     * Sets the JDBC client instance for the service.
+     * This method is automatically called by the Spring framework to inject the JDBC client dependency.
+     *
+     * @param jdbcClient The JDBC client used for executing SQL statements and managing database connections.
+     */
     @Autowired
     public void setJdbcClient(JdbcClient jdbcClient) {
         this.jdbcClient = jdbcClient;
     }
 
+    /**
+     * Sets the ConversionService instance to be used by the service.
+     * This method is automatically invoked by the Spring framework during bean initialization to inject the ConversionService dependency.
+     *
+     * @param conversionService The ConversionService responsible for type conversion operations within the application,
+     *                          facilitating binding of parameters and reading of results from the database.
+     */
     @Autowired
     public void setConversionService(ConversionService conversionService) {
         this.conversionService = conversionService;
     }
+
+    /**
+     * Sets the JdbcTemplate instance for the service.
+     * This method is automatically invoked by the Spring framework's dependency injection to provide the JdbcTemplate bean,
+     * enabling the service to execute SQL commands and queries efficiently.
+     *
+     * @param jdbcTemplate The JdbcTemplate that simplifies JDBC operations and provides high-level data access functions.
+     */
     @Autowired
     public void setJdbcTemplate(JdbcTemplate jdbcTemplate) {
         this.jdbcTemplate = jdbcTemplate;
     }
+
+    /**
+     * Sets the NamedParameterJdbcTemplate instance for the service.
+     * This method is automatically called by the Spring framework to inject the NamedParameterJdbcTemplate dependency,
+     * which allows for executing SQL queries with named parameters.
+     *
+     * @param namedParameterJdbcTemplate The NamedParameterJdbcTemplate used for executing parameterized SQL statements
+     *                                   with named parameters, providing a more convenient and safer way to bind query variables.
+     */
     @Autowired
     public void setNamedParameterJdbcTemplate(NamedParameterJdbcTemplate namedParameterJdbcTemplate) {
         this.namedParameterJdbcTemplate = namedParameterJdbcTemplate;
     }
 
+    /**
+     * Callback method that is invoked by the Spring container once all properties
+     * of this Bean have been set. This method is part of the lifecycle interface
+     * for beans that need to react once all their properties have been initialized.
+     * It calls the superclass's {@code afterPropertiesSet} method to ensure
+     * any additional setup defined there is also executed.
+     */
     @Override
     public void afterPropertiesSet() {
         super.afterPropertiesSet();

boot/oauth2/src/main/java/com/plate/auth/commons/base/AbstractService.java

@@ -4,22 +4,66 @@
 import lombok.extern.log4j.Log4j2;
 import org.springframework.beans.factory.InitializingBean;
 import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.jdbc.core.JdbcTemplate;
+import org.springframework.jdbc.core.namedparam.NamedParameterJdbcTemplate;
 
 /**
- * @author <a href="https://github.com/vnobo">Alex bob</a>
+ * AbstractService serves as a foundation for implementing service layers within an application,
+ * encapsulating common functionality and providing a structure for dependency injection and initialization.
+ * It integrates with Spring Framework features, ensuring that services are properly set up and ready to use.
+ *
+ * <p>This abstract class offers the following core functionalities:</p>
+ * <ul>
+ *   <li>Automatically configures an {@link ObjectMapper} instance for JSON serialization/deserialization.</li>
+ *   <li>Implements {@link InitializingBean} to define initialization logic after all properties are set.</li>
+ *   <li>Logs debug information upon initialization, indicating the specific service class being initialized.</li>
+ * </ul>
+ *
+ * <p>Subclasses should extend this class and may override {@link #afterPropertiesSet()}
+ * to include custom initialization steps, ensuring they call `super.afterPropertiesSet()` to maintain base behavior.</p>
+ *
+ * <p>Dependencies like {@link JdbcTemplate}, {@link NamedParameterJdbcTemplate}, and {@link ConversionService}
+ * can be injected via respective setter methods (not shown directly here), following Spring's dependency injection principles.</p>
  */
 @Log4j2
 public abstract class AbstractService implements InitializingBean {
 
+    /**
+     * Provides an instance of {@link ObjectMapper} configured for JSON serialization and deserialization.
+     * This object is essential for converting Java objects to and from JSON format.
+     * It is automatically configured and injected into subclasses of {@link AbstractService},
+     * ensuring that service layers have the capability to handle JSON data processing consistently.
+     * <p>
+     * Subclasses can utilize this {@code objectMapper} directly to perform JSON operations without needing
+     * to manage the configuration themselves.
+     */
     protected ObjectMapper objectMapper;
 
+    /**
+     * Sets the {@link ObjectMapper} instance to be used for JSON serialization and deserialization.
+     * This method is typically called by the Spring framework to inject a pre-configured ObjectMapper bean.
+     *
+     * @param objectMapper The ObjectMapper instance to be set, which should be configured for the application's needs.
+     */
     @Autowired
     public void setObjectMapper(ObjectMapper objectMapper) {
         this.objectMapper = objectMapper;
     }
 
+    /**
+     * Invoked by the Spring IoC container after all properties
+     * of this bean have been set. This method is an implementation
+     * of the {@link InitializingBean} interface, allowing for custom
+     * initialization logic to be executed at the appropriate time
+     * in the bean lifecycle. It logs a debug message indicating
+     * the name of the initializing provider class.
+     * <p>
+     * Subclasses may override this method but should call
+     * `super.afterPropertiesSet()` to maintain the base
+     * class's initialization behavior.
+     */
     @Override
     public void afterPropertiesSet() {
-        log.debug("Initializing provider names: {}",this.getClass().getName());
+        log.debug("Initializing provider names: {}", this.getClass().getName());
     }
 }

boot/oauth2/src/main/java/com/plate/auth/commons/base/BaseEntity.java

@@ -8,29 +8,41 @@
 import java.io.Serializable;
 
 /**
- * @author <a href="https://github.com/vnobo">Alex bob</a>
+ * Represents the base entity definition with common functionality shared across all entities.
+ * This interface extends {@link Serializable} and {@link Persistable}, ensuring entities can be serialized
+ * and have basic persistence-related operations defined.
+ *
+ * <p>{@code BaseEntity} introduces a default method to set a code value and overrides the `isNew` method
+ * to determine if an entity instance is new (typically based on the absence of an identifier).
+ * It also suggests a flexible way to handle entity identifiers through the `setCode` method.
+ *
+ * <h3>Key Methods:</h3>
+ * <ul>
+ *   <li>{@link #setCode(String)}: Assigns a code value to the entity, allowing customization of how codes are handled.</li>
+ *   <li>{@link #isNew()}: Determines whether the entity instance represents a new record that needs to be persisted.</li>
+ * </ul>
+ *
+ * @param <T> The type of the identifier for this entity.
  */
 public interface BaseEntity<T> extends Serializable, Persistable<T> {
 
     /**
-     * 设置代码值。
-     * <p>
-     * 此方法提供了一个接口来为相关对象设置一个代码值。具体的实现可能会根据实际需求来决定如何处理这个代码值。
-     * 由于这是一个默认方法，它为接口的实现提供了一种灵活的方式来处理代码值，而不需要强制实现这个方法。
+     * Assigns a code to the entity.
      *
-     * @param code 要设置的代码值。这个参数允许调用者指定一个代码值，该值可以是任何字符串，具体的含义和使用方式取决于实现。
+     * This method is intended to set a unique code identifier for an entity. The implementation should define
+     * how the `code` parameter is utilized, as the current implementation is a placeholder.
+     *
+     * @param code The code value to be assigned to the entity. The nature of this code is dependent on the
+     *             business logic or system requirements where this interface is implemented.
      */
     default void setCode(String code) {
-        //todo 方法体为空，具体的实现可能需要根据实际需求来决定如何处理code参数。
+        //todo
     }
 
     /**
-     * 判断当前对象是否为新对象，即是否具有ID。
-     * 如果对象尚未分配ID，则将其视为新对象，并生成一个新的ID。
-     * 此方法用于标识对象是否已存在于持久化存储中，如果没有ID，则认为是新对象需要进行持久化操作。
-     *
-     * @return 如果对象是新对象（没有ID），则返回true；否则返回false。
-     */
+     * Determines whether the entity instance represents a new record that has not yet been persisted.
+     * This method checks if the entity's identifier ({@code getId}) is empty to assess its novelty.
+     * If the entity is deemed new, it assigns a new unique code*/
     @Override
     @JsonIgnore
     default boolean isNew() {

boot/oauth2/src/main/java/com/plate/auth/commons/converters/CollectionConverters.java

@@ -17,21 +17,59 @@
 import java.util.Collection;
 
 /**
- * @author <a href="https://github.com/vnobo">Alex bob</a>
+ * CollectionConverters is a Spring configuration class that provides converters to facilitate
+ * the serialization and deserialization of {@link Collection} objects into and from JSON strings,
+ * primarily for database storage and retrieval operations. This class registers these converters
+ * to be automatically applied within the Spring context where applicable.
+ *
+ * <p>The converters encapsulated within this class are:</p>
+ * <ul>
+ *   <li>{@link CollectionAttributeConverter}: A JPA AttributeConverter to convert collections to/from JSON strings.</li>
+ *   <li>{@link CollectionReadConverter}: A Spring Data MongoDB converter to read JSON strings into collections.</li>
+ *   <li>{@link CollectionWriteConverter}: A Spring Data MongoDB converter to write collections into JSON strings.</li>
+ * </ul>
+ *
+ * <p>These converters leverage {@link ContextUtils#OBJECT_MAPPER} for JSON processing.</p>
+ *
+ * <p><strong>Note:</strong> This class implements {@link InitializingBean} to log an initialization message.</p>
  */
 @Log4j2
 @Configuration(proxyBeanMethods = false)
 public class CollectionConverters implements InitializingBean {
 
+    /**
+     * Invoked by the containing {@code BeanFactory} after it has set all bean properties
+     * and satisfied all dependencies for this bean. This method allows the bean instance
+     * to perform initialization only possible when all bean properties have been set
+     * and to throw an exception in the event of misconfiguration.
+     * <p>
+     * This implementation logs a message indicating the initialization of
+     * {@code CollectionConverters}, which provides converters for handling
+     * {@link Collection} serialization and deserialization within a Spring context.
+     */
     @Override
     public void afterPropertiesSet() {
         log.info("Initializing converter [CollectionConverters]...");
     }
 
+    /**
+     * A converter class designed to facilitate the persistence of {@link Collection} objects into a database and their retrieval back into Java objects.
+     * This converter serializes collections to JSON strings when persisting into a database column and deserializes them back into collections when loading from the database.
+     * It is annotated to be automatically applied by JPA for any {@link Collection} fields marked with the appropriate JPA annotations.
+     */
     @Component
     @jakarta.persistence.Converter(autoApply = true)
     public static class CollectionAttributeConverter implements AttributeConverter<Collection<?>, String> {
 
+        /**
+         * Converts a given Collection object into a JSON formatted string suitable for storage in a database column.
+         * This method utilizes the OBJECT_MAPPER from ContextUtils to serialize the Collection.
+         *
+         * @param source The Collection object to be converted. Must not be null.
+         * @return A JSON string representation of the input Collection.
+         * @throws JsonException If the serialization process encounters a JsonProcessingException,
+         *                      indicating a failure to convert the Collection to a JSON string.
+         */
         @Override
         public String convertToDatabaseColumn(@NonNull Collection<?> source) {
             try {
@@ -43,6 +81,13 @@ public String convertToDatabaseColumn(@NonNull Collection<?> source) {
 
         }
 
+        /**
+         * Converts a JSON string, retrieved from a database column, back into the original Collection object.
+         * This method uses the OBJECT_MAPPER from ContextUtils to deserialize the JSON string into a Collection of the appropriate type.
+         *
+         * @param value The JSON string representation of the Collection that was stored in the database. Must not be null.
+         * @return The deserialized Collection object that the input string represents.
+         */
         @Override
         public Collection<?> convertToEntityAttribute(String value) {
             try {
@@ -55,10 +100,36 @@ public Collection<?> convertToEntityAttribute(String value) {
         }
     }
 
+    /**
+     * A converter class designed to facilitate the deserialization of JSON strings into Collection objects.
+     * This class is annotated as a Spring component and specifically designated as a reading converter,
+     * enabling it to be auto-detected and utilized within Spring's data access framework.
+     * It leverages Jackson's `ObjectMapper` to parse JSON strings into collections of arbitrary types.
+     *
+     * <p>Usage Note:
+     * The converter expects the input string to be formatted as a valid JSON array.
+     * If the source string fails to deserialize due to invalid JSON format,
+     * a {@link JsonException} is thrown, providing a descriptive error message.</p>
+     *
+     * @see Converter Interface that this class implements for type conversion.
+     * @see Component Spring annotation marking this class as a managed bean.
+     * @see ReadingConverter Spring Data MongoDB annotation indicating this is a read converter.
+     */
     @Component
     @ReadingConverter
     public static class CollectionReadConverter implements Converter<String, Collection<?>> {
 
+        /**
+         * Converts a JSON formatted string into a Collection object.
+         * This method utilizes the Jackson ObjectMapper to deserialize the input string into a Collection type,
+         * inferred through a TypeReference.
+         *
+         * @param source The JSON string that needs to be converted into a Collection.
+         *               It must be a valid JSON structure that can be mapped to a Collection type.
+         * @return A Collection object deserialized from the input JSON string.
+         * @throws JsonException If an error occurs during the JSON processing, a JsonException is thrown
+         *                      with a specific error message detailing the failure.
+         */
         @Override
         public Collection<?> convert(@NonNull String source) {
             try {
@@ -71,6 +142,23 @@ public Collection<?> convert(@NonNull String source) {
         }
     }
 
+    /**
+     * A converter class designed to transform collections into their JSON string representation.
+     * This class is annotated as a Spring component and designated as a writing converter,
+     * facilitating its integration within Spring's data binding and conversion infrastructure.
+     * It utilizes the Jackson Object Mapper for the conversion process.
+     *
+     * <p>Upon invocation of the {@link #convert(Collection)} method, the source collection is serialized
+     * into a JSON string. If any exception occurs during the serialization, a custom {@link JsonException}
+     * is thrown, encapsulating the original error message to provide a clearer indication of the issue.</p>
+     *
+     * @implNote The conversion relies on the static reference to `ContextUtils.OBJECT_MAPPER`,
+     * expecting that the `ContextUtils` class provides a pre-configured instance of `ObjectMapper`.
+     *
+     * @see Converter
+     * @see WritingConverter
+     * @see JsonProcessingException
+     */
     @Component
     @WritingConverter
     public static class CollectionWriteConverter implements Converter<Collection<?>, String> {