sync: cherry-pick changes from feature/3.0.x

Author: loong10k

src/main/java/com/faceplusplus/spring/boot/FaceppApiAddress.java

@@ -1,21 +1,33 @@
 package com.faceplusplus.spring.boot;
 
 /**
- * 声网相关的常量
+ * Constants used across the Face++ SDK for API endpoints, recording identifiers,
+ * and storage path configuration.
+ *
+ * @author [@Loong Wan](https://github.com/loong10k)
+ * @since 3.0.0
+ * @see FaceppApiAddress
  */
 public interface FaceppConstant {
 
-    // 获取频道内的所有用户
-    // https://api.agora.io/dev/v1/channel/user/{appid}/{channelName}
+    /**
+     * URL template for retrieving all users within a channel.
+     * Placeholders: {0} = appId, {1} = channelName.
+     */
     String URL_CHANNEL_USER = "https://api.agora.io/dev/v1/channel/user/{0}/{1}";
 
-    // 用户禁封
-    // https://api.agora.io/dev/v1/kicking-rule
+    /**
+     * URL for user-ban rule management.
+     */
     String URL_RULE = "https://api.agora.io/dev/v1/kicking-rule";
 
-    // 录制请求的uid
+    /**
+     * Default UID used for recording requests.
+     */
     String RECORDING_UID = "10";
 
-    // 存储位置 /video/{{yyyy-MM-dd}}
+    /**
+     * Root directory for video file storage (pattern: video/{yyyy-MM-dd}).
+     */
     String VEIDO_PAHT = "video";
 }

src/main/java/com/faceplusplus/spring/boot/FaceppConstant.java

@@ -15,8 +15,22 @@
  */
 package com.faceplusplus.spring.boot;
 
+/**
+ * Async-capable operations for face detection, analysis, comparison, search, and skin analysis.
+ * Extends {@link FaceppFaceOperations} inheriting all synchronous face operation methods.
+ *
+ * @author [@Loong Wan](https://github.com/loong10k)
+ * @since 3.0.0
+ * @see FaceppFaceOperations
+ * @see FaceppTemplate
+ */
 public class FaceppFaceAsyncOperations extends FaceppFaceOperations {
 
+	/**
+	 * Constructs a new {@code FaceppFaceAsyncOperations} bound to the given template.
+	 *
+	 * @param faceppTemplate the template providing access to SDK configuration and HTTP client
+	 */
 	public FaceppFaceAsyncOperations(FaceppTemplate faceppTemplate) {
 		super(faceppTemplate);
 	}

src/main/java/com/faceplusplus/spring/boot/FaceppFaceAsyncOperations.java

@@ -24,20 +24,34 @@
 import java.util.Map;
 import java.util.function.Consumer;
 
+/**
+ * Async-capable operations for FaceSet management, including asynchronous
+ * add/remove face operations and task status queries.
+ *
+ * @author [@Loong Wan](https://github.com/loong10k)
+ * @since 3.0.0
+ * @see FaceppFacesetOperations
+ * @see FaceppTemplate
+ */
 public class FaceppFacesetAsyncOperations extends FaceppFacesetOperations {
 
+	/**
+	 * Constructs a new {@code FaceppFacesetAsyncOperations} bound to the given template.
+	 *
+	 * @param faceppTemplate the template providing access to SDK configuration and HTTP client
+	 */
 	public FaceppFacesetAsyncOperations(FaceppTemplate faceppTemplate) {
 		super(faceppTemplate);
 	}
 
 	/**
-	 * 1、人脸库管理相关接口 > 添加人脸（异步） API
-	 * 为一个已经创建的 FaceSet 添加人脸标识 face_token。一个 FaceSet 最多存储1,000个 face_token。
-	 * 注意：2017年8月16日后，一个 FaceSet 能够存储的 face_token 数量将从 1000 提升至 10000。
-	 * API：https://console.faceplusplus.com.cn/documents/40622166
-	 * @param facesetToken FaceSet的标识
-	 * @param faceTokens 人脸标识 face_token 组成的字符串，可以是一个或者多个，用逗号分隔。最多不超过5个face_token
-	 * @return 操作结果
+	 * Asynchronously adds face tokens to a FaceSet identified by its token.
+	 *
+	 * @param facesetToken the FaceSet identifier
+	 * @param faceTokens   array of face tokens to add (max 5)
+	 * @param consumer     callback to receive the response
+	 * @throws IOException if the HTTP request fails
+	 * @see FaceppApiAddress#FACE_ADD_ASYNC
 	 */
 	public void asyncAddFaceWithToken(String facesetToken, String[] faceTokens, Consumer<FaceAddResponse> consumer) throws IOException {
 		String reqUrl = FaceppApiAddress.FACE_ADD_ASYNC.getUrl();
@@ -51,13 +65,13 @@ public void asyncAddFaceWithToken(String facesetToken, String[] faceTokens, Cons
 	}
 
 	/**
-	 * 2、人脸库管理相关接口 > 添加人脸（异步） API
-	 * 为一个已经创建的 FaceSet 添加人脸标识 face_token。一个 FaceSet 最多存储1,000个 face_token。
-	 * 注意：2017年8月16日后，一个 FaceSet 能够存储的 face_token 数量将从 1000 提升至 10000。
-	 * API：https://console.faceplusplus.com.cn/documents/40622166
-	 * @param outerId 用户提供的FaceSet标识
-	 * @param faceTokens 人脸标识 face_token 组成的字符串，可以是一个或者多个，用逗号分隔。最多不超过5个face_token
-	 * @return 操作结果
+	 * Asynchronously adds face tokens to a FaceSet identified by its outer_id.
+	 *
+	 * @param outerId    the user-defined FaceSet identifier
+	 * @param faceTokens array of face tokens to add (max 5)
+	 * @param consumer   callback to receive the response
+	 * @throws IOException if the HTTP request fails
+	 * @see FaceppApiAddress#FACE_ADD_ASYNC
 	 */
 	public void asyncAddFaceWithOuterId(String outerId, String[] faceTokens, Consumer<FaceAddResponse> consumer) throws IOException {
 		String reqUrl = FaceppApiAddress.FACE_ADD_ASYNC.getUrl();
@@ -71,13 +85,13 @@ public void asyncAddFaceWithOuterId(String outerId, String[] faceTokens, Consume
 	}
 
 	/**
-	 * 3、人脸库管理相关接口 > 删除人脸（异步） API
-	 * 移除一个FaceSet中的某些或者全部face_token
-	 * API：https://console.faceplusplus.com.cn/documents/4888399
-	 * @param facesetToken FaceSet的标识
-	 * @param faceTokens 需要移除的人脸标识字符串，可以是一个或者多个face_token组成，用逗号分隔。最多不能超过1,000个face_token
-	 * 注：face_tokens字符串传入“RemoveAllFaceTokens”则会移除FaceSet内所有的face_token
-	 * @return 操作结果
+	 * Asynchronously removes face tokens from a FaceSet identified by its token.
+	 *
+	 * @param facesetToken the FaceSet identifier
+	 * @param faceTokens   array of face tokens to remove
+	 * @param consumer     callback to receive the response
+	 * @throws IOException if the HTTP request fails
+	 * @see FaceppApiAddress#FACE_REMOVE_ASYNC
 	 */
 	public void asyncRemoveFaceByToken(String facesetToken, String[] faceTokens, Consumer<FaceRemoveResponse> consumer) throws IOException {
 		String reqUrl = FaceppApiAddress.FACE_REMOVE_ASYNC.getUrl();
@@ -91,13 +105,13 @@ public void asyncRemoveFaceByToken(String facesetToken, String[] faceTokens, Con
 	}
 
 	/**
-	 * 4、人脸库管理相关接口 > 删除人脸（异步） API
-	 * 移除一个FaceSet中的某些或者全部face_token
-	 * API：https://console.faceplusplus.com.cn/documents/40622169
-	 * @param outerId 用户提供的FaceSet标识
-	 * @param faceTokens 需要移除的人脸标识字符串，可以是一个或者多个face_token组成，用逗号分隔。最多不能超过1,000个face_token
-	 * 注：face_tokens字符串传入“RemoveAllFaceTokens”则会移除FaceSet内所有的face_token
-	 * @return 操作结果
+	 * Asynchronously removes face tokens from a FaceSet identified by its outer_id.
+	 *
+	 * @param outerId    the user-defined FaceSet identifier
+	 * @param faceTokens array of face tokens to remove
+	 * @param consumer   callback to receive the response
+	 * @throws IOException if the HTTP request fails
+	 * @see FaceppApiAddress#FACE_REMOVE_ASYNC
 	 */
 	public void asyncRemoveFaceByOuterId(String outerId, String[] faceTokens, Consumer<FaceRemoveResponse> consumer) throws IOException {
 		String reqUrl = FaceppApiAddress.FACE_REMOVE_ASYNC.getUrl();
@@ -111,12 +125,12 @@ public void asyncRemoveFaceByOuterId(String outerId, String[] faceTokens, Consum
 	}
 
 	/**
-	 * 5、人脸库管理相关接口 > 添加/删除人脸结果查询 API
-	 * 查询之前调用的异步添加/删除人脸请求，异步任务当前的状态
-	 * 注意：2017年8月16日后，一个 FaceSet 能够存储的 face_token 数量将从 1000 提升至 10000。
-	 * API：https://console.faceplusplus.com.cn/documents/40622157
-	 * @param taskId 异步任务的唯一标识
-	 * @return 操作结果
+	 * Queries the status of an asynchronous add/remove face task.
+	 *
+	 * @param taskId the unique identifier of the async task
+	 * @return the task status response
+	 * @throws IOException if the HTTP request fails
+	 * @see FaceppApiAddress#FACE_STATUS_ASYNC
 	 */
 	public FaceStatusResponse getFaceStatusByTaskId(String taskId) throws IOException {
 		String reqUrl = FaceppApiAddress.FACE_STATUS_ASYNC.getUrl();