docs: 添加 Javadoc

config/application-prod.yml.example

@@ -26,9 +26,9 @@ app:
     # 是否开启 S3 文件存储服务
     enabled: true
     # S3 服务端点（若使用非 AWS 提供的 S3 兼容 API，请添加该配置）
-#    endpoint: https://endpoint.s3.service
+    # endpoint: https://endpoint.s3.service
     # S3 服务区域（详情请见 S3 服务提供商）
-#    region: apac
+    # region: apac
     # 公开域名
     public-host: https://s3.my.app
     # 是否开启 Path Style
@@ -64,8 +64,8 @@ app:
     # 允许的请求头列表
     allowed-headers: Content-Type
     # 允许的请求方法列表（Ref org.springframework.http.HttpMethod）
-    # 2025.11.6注
-    #   由于 Spring 解析问题，在此处使用小写的情况下会导致在请求头中存在 Origin 时出现 Invalid CORS Request 的问题，请务必使用大写
+    #   Spring HttpMethod 并非 enum class，因此在此处使用小写请求方式会导致在请求头中存在 Origin 时出现 Invalid
+    #   CORS Request 的问题，请务必使用大写
     allowed-methods:
       - GET
       - POST

src/main/java/com/onixbyte/helix/config/WebFluxConfig.java

@@ -1,57 +0,0 @@
-package com.onixbyte.helix.config;
-
-import org.springframework.context.annotation.Bean;
-import org.springframework.context.annotation.Configuration;
-import org.springframework.web.reactive.function.client.WebClient;
-
-/**
- * Configuration class for Spring WebFlux reactive web components.
- * <p>
- * This configuration class provides beans for reactive web programming components within the Helix
- * application. It configures WebClient instances and other reactive web-related components that
- * enable non-blocking, asynchronous HTTP communication with external services.
- * <p>
- * The configuration supports:
- * <ul>
- *   <li>Reactive HTTP client configuration</li>
- *   <li>Non-blocking I/O operations</li>
- *   <li>Asynchronous request/response handling</li>
- * </ul>
- *
- * @author zihluwang
- * @since 1.0.0
- * @see WebClient
- * @see Configuration
- */
-@Configuration
-public class WebFluxConfig {
-
-    /**
-     * Creates a reactive WebClient for HTTP communication with external services.
-     * <p>
-     * This method configures a {@link WebClient} instance that provides a modern, reactive approach
-     * to HTTP client operations. The WebClient supports non-blocking I/O and is built on top of
-     * Reactor Netty, making it suitable for high-performance, scalable applications.
-     * <p>
-     * The client is configured with default settings and can be used throughout the application for
-     * making HTTP requests to external APIs, microservices, or other web resources in a reactive,
-     * non-blocking manner.
-     * <p>
-     * Key features:
-     * <ul>
-     *   <li>Non-blocking I/O operations</li>
-     *   <li>Reactive streams support</li>
-     *   <li>Built-in support for JSON serialisation/deserialisation</li>
-     *   <li>Configurable timeouts and retry mechanisms</li>
-     * </ul>
-     *
-     * @return a configured {@link WebClient} instance for reactive HTTP operations
-     * @see WebClient
-     * @see WebClient.Builder
-     */
-    @Bean
-    public WebClient webClient() {
-        return WebClient.builder()
-                .build();
-    }
-}

src/main/java/com/onixbyte/helix/controller/AssetController.java

@@ -13,11 +13,10 @@ import org.springframework.web.bind.annotation.*;
 import org.springframework.web.multipart.MultipartFile;
 
 /**
- * REST controller for file storage operations. Provides endpoints for uploading, downloading, and
- * deleting assets using the configured storage service.
+ * This controller provides entry points that manipulates assets.
  *
  * @author zihluwang
- * @since 1.0.0
+ * @author siujamo
  */
 @RestController
 @RequestMapping("/assets")

src/main/java/com/onixbyte/helix/controller/AuthController.java

@@ -17,6 +17,12 @@ import org.springframework.web.bind.annotation.*;
 
 import java.time.Duration;
 
+/**
+ * This controller provides entry points making user authorised.
+ *
+ * @author zihluwang
+ * @author siujamo
+ */
 @RestController
 @RequestMapping("/auth")
 public class AuthController {
@@ -57,11 +63,21 @@ public class AuthController {
                 .body(userService.getDetail(user));
     }
 
+    /**
+     * Get whether the registration function is enabled.
+     *
+     * @return {@code true} if registration function is enabled, otherwise {@code false}
+     */
     @GetMapping("/register-enabled")
     public boolean getRegisterEnabled() {
         return authService.getRegisterEnabled();
     }
 
+    /**
+     * Perform log out.
+     *
+     * @return a response that remove the authentication from cookie
+     */
     @GetMapping("/logout")
     public ResponseEntity<Void> logout() {
         var cookie = authService.buildCookie(TokenConstant.TOKEN_NAME, "", Duration.ZERO);

src/main/java/com/onixbyte/helix/controller/AuthorityController.java

@@ -7,12 +7,15 @@ import com.onixbyte.helix.domain.web.request.QueryAuthorityRequest;
 import com.onixbyte.helix.service.AuthorityService;
 import org.springframework.data.domain.Page;
 import org.springframework.data.domain.PageRequest;
-import org.springframework.http.ResponseEntity;
 import org.springframework.validation.annotation.Validated;
 import org.springframework.web.bind.annotation.*;
 
-import java.util.List;
-
+/**
+ * This controller provides entry points for manipulate authorities.
+ *
+ * @author zihluwang
+ * @author siujamo
+ */
 @RestController
 @RequestMapping("/authorities")
 public class AuthorityController {
@@ -23,6 +26,14 @@ public class AuthorityController {
         this.authorityService = authorityService;
     }
 
+    /**
+     * Get authorities by page.
+     *
+     * @param pageNum  current page num
+     * @param pageSize page size
+     * @param request  query parameters
+     * @return a page contains authority data of the specified page
+     */
     @GetMapping
     public Page<Authority> getAuthorities(
             @RequestParam(required = false, defaultValue = "1") Integer pageNum,
@@ -33,11 +44,23 @@ public class AuthorityController {
         return authorityService.getAuthorities(pageRequest, request);
     }
 
+    /**
+     * Add an authority.
+     *
+     * @param request authority specs
+     * @return created authority
+     */
     @PostMapping
     public Authority addAuthority(@Validated @RequestBody AddAuthorityRequest request) {
         return authorityService.addAuthority(request);
     }
 
+    /**
+     * Edit an authority.
+     *
+     * @param request authority specs
+     * @return edited authority
+     */
     @PutMapping
     public Authority editAuthority(@Validated @RequestBody EditAuthorityRequest request) {
         return authorityService.editAuthority(request);

src/main/java/com/onixbyte/helix/controller/CaptchaController.java

@@ -10,6 +10,12 @@ import org.springframework.web.bind.annotation.RestController;
 
 import java.util.Optional;
 
+/**
+ * This controller provides entry points to get captcha images.
+ *
+ * @author zihluwang
+ * @author siujamo
+ */
 @RestController
 @RequestMapping("/captcha")
 public class CaptchaController {
@@ -21,6 +27,11 @@ public class CaptchaController {
         this.captchaService = captchaService;
     }
 
+    /**
+     * Get captcha image and captcha uuid.
+     *
+     * @return captcha response, contains the uuid of the captcha and image BASE64
+     */
     @GetMapping
     public ResponseEntity<CaptchaResponse> getCaptcha() {
         var captchaTuple = captchaService.buildCaptcha();

src/main/java/com/onixbyte/helix/controller/DepartmentController.java

@@ -10,6 +10,12 @@ import org.springframework.web.bind.annotation.RestController;
 
 import java.util.List;
 
+/**
+ * This controller provides entry points that manipulates departments.
+ *
+ * @author zihluwang
+ * @author siujamo
+ */
 @RestController
 @RequestMapping("/departments")
 public class DepartmentController {

src/main/java/com/onixbyte/helix/controller/ExceptionController.java

@@ -13,22 +13,10 @@ import java.time.LocalDateTime;
 import java.util.stream.Collectors;
 
 /**
- * Global exception handler for the Helix application.
- * <p>
- * This controller advice provides centralised exception handling across all controllers in
- * the application. It intercepts exceptions thrown during request processing and converts them into
- * appropriate HTTP responses with standardised error formats.
- * <p>
- * The controller handles various types of exceptions including:
- * <ul>
- *   <li>Business logic exceptions ({@link BizException})</li>
- *   <li>Bean validation constraint violations ({@link ConstraintViolationException})</li>
- * </ul>
- * <p>
- * All error responses are formatted consistently using {@link BizExceptionResponse} to provide a
- * uniform API error structure for client applications.
+ * This controller advise will catch some business exception which produced when performing actions.
  *
  * @author zihluwang
+ * @author siujamo
  * @see BizException
  * @see BizExceptionResponse
  * @see RestControllerAdvice

src/main/java/com/onixbyte/helix/controller/MenuController.java

@@ -10,6 +10,12 @@ import org.springframework.web.bind.annotation.RestController;
 
 import java.util.List;
 
+/**
+ * This controller provides entry points to manipulate menus.
+ *
+ * @author zihluwang
+ * @author siujamo
+ */
 @RestController
 @RequestMapping("/menus")
 public class MenuController {
@@ -21,6 +27,11 @@ public class MenuController {
         this.menuService = menuService;
     }
 
+    /**
+     * Get menu tree.
+     *
+     * @return available menu tree for the current user
+     */
     @GetMapping
     public List<TreeNode<Menu>> getMenuTree() {
         return menuService.getMenuTree();

src/main/java/com/onixbyte/helix/controller/PositionController.java

@@ -11,6 +11,12 @@ import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RequestParam;
 import org.springframework.web.bind.annotation.RestController;
 
+/**
+ * This controller provides entry points to manipulate positions.
+ *
+ * @author zihluwang
+ * @author siujamo
+ */
 @RestController
 @RequestMapping("/positions")
 public class PositionController {
@@ -22,6 +28,13 @@ public class PositionController {
         this.positionService = positionService;
     }
 
+    /**
+     * Get position data paginated.
+     *
+     * @param pageNum  current page num
+     * @param pageSize page size
+     * @return paginated position data
+     */
     @GetMapping
     public Page<Position> getPositions(
             @RequestParam(required = false, defaultValue = "1") Integer pageNum,

src/main/java/com/onixbyte/helix/controller/RoleController.java

@@ -13,6 +13,12 @@ import org.springframework.http.ResponseEntity;
 import org.springframework.validation.annotation.Validated;
 import org.springframework.web.bind.annotation.*;
 
+/**
+ * This controller provides entry points to manipulate roles.
+ *
+ * @author zihluwang
+ * @author siujamo
+ */
 @RestController
 @RequestMapping("/roles")
 public class RoleController {

src/main/java/com/onixbyte/helix/controller/SettingController.java

@@ -1,11 +1,14 @@
 package com.onixbyte.helix.controller;
 
-import com.onixbyte.helix.domain.entity.Setting;
-import org.springframework.web.bind.annotation.GetMapping;
-import org.springframework.web.bind.annotation.PathVariable;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RestController;
 
+/**
+ * This controller provides entry points to manipulate settings.
+ *
+ * @author zihluwang
+ * @author siujamo
+ */
 @RestController
 @RequestMapping
 public class SettingController {

src/main/java/com/onixbyte/helix/controller/UserController.java

@@ -1,9 +1,10 @@
 package com.onixbyte.helix.controller;
 
 import com.onixbyte.helix.domain.web.request.AddUserRequest;
+import com.onixbyte.helix.domain.web.request.EditUserRequest;
 import com.onixbyte.helix.domain.web.request.QueryUserRequest;
 import com.onixbyte.helix.domain.web.request.ResetPasswordRequest;
-import com.onixbyte.helix.domain.web.request.EditUserRequest;
+import com.onixbyte.helix.domain.web.response.ActionResponse;
 import com.onixbyte.helix.domain.web.response.UserDetailResponse;
 import com.onixbyte.helix.service.UserService;
 import org.springframework.beans.factory.annotation.Autowired;
@@ -15,6 +16,12 @@ import org.springframework.security.access.prepost.PreAuthorize;
 import org.springframework.validation.annotation.Validated;
 import org.springframework.web.bind.annotation.*;
 
+/**
+ * This controller provides entry points to manipulate users.
+ *
+ * @author zihluwang
+ * @author siujamo
+ */
 @RestController
 @RequestMapping("/users")
 public class UserController {
@@ -56,29 +63,53 @@ public class UserController {
         return userService.getUserDetailByUserId(userId);
     }
 
+    /**
+     * Add a new user.
+     *
+     * @param request user to be added
+     * @return added user
+     */
     @PostMapping
     @PreAuthorize("hasAnyAuthority('system:user:write')")
     public UserDetailResponse addUser(@Validated @RequestBody AddUserRequest request) {
         return userService.addUser(request);
     }
 
+    /**
+     * Edit a user.
+     *
+     * @param request user to be edited
+     * @return edited user
+     */
     @PutMapping
     public ResponseEntity<Void> editUser(@Validated @RequestBody EditUserRequest request) {
         userService.updateUser(request);
         return ResponseEntity.ok(null);
     }
 
+    /**
+     * Reset user's password.
+     *
+     * @param request reset password request, contains ID of the user and new password
+     * @return action response
+     */
     @PreAuthorize("hasAnyAuthority('system:user:reset-password')")
     @PatchMapping("/reset-password")
-    public ResponseEntity<Void> resetPassword(@Validated @RequestBody ResetPasswordRequest request) {
+    public ActionResponse resetPassword(@Validated @RequestBody ResetPasswordRequest request) {
         userService.resetPassword(request);
-        return ResponseEntity.ok(null);
+        return ActionResponse.success("密码修改成功");
     }
 
+    /**
+     * Delete a user.
+     *
+     * @param userId ID of the user to be deleted
+     * @return action response
+     */
     @PreAuthorize("hasAnyAuthority('system:user:write')")
     @DeleteMapping("/{userId:\\d+}")
-    public ResponseEntity<Void> deleteUser(@PathVariable Long userId) {
+    public ActionResponse deleteUser(@PathVariable Long userId) {
         userService.deleteUser(userId);
-        return ResponseEntity.ok(null);
+        return ActionResponse.success("删除成功");
     }
 }

src/main/java/com/onixbyte/helix/domain/web/response/ActionResponse.java

@@ -0,0 +1,15 @@
+package com.onixbyte.helix.domain.web.response;
+
+public record ActionResponse(
+        String message,
+        boolean success
+) {
+
+    public static ActionResponse success(String message) {
+        return new ActionResponse(message, true);
+    }
+
+    public static ActionResponse failed(String message) {
+        return new ActionResponse(message, false);
+    }
+}