【代码评审】AI：PPT API 的接入

yudao-module-ai/yudao-spring-boot-starter-ai/src/main/java/cn/iocoder/yudao/framework/ai/core/model/wenduoduo/api/WddPptApi.java

@@ -24,11 +24,11 @@ import java.util.Objects;
 import java.util.function.Function;
 import java.util.function.Predicate;
 
+// TODO @新：要不改成 WenDuoDuoPptApi
 /**
  * 文多多 API
- * <p>
- * <p>
- * * 对接文多多：<a href="https://docmee.cn/open-platform/api">PPT 生成 API</a>
+ *
+ * @see <a href="https://docmee.cn/open-platform/api">PPT 生成 API</a>
  *
  * @author xiaoxin
  */
@@ -49,14 +49,15 @@ public class WddPptApi {
                 sink.error(new IllegalStateException("[wdd-api] 调用失败！"));
             });
 
+    // TODO @新：是不是不用 baseUrl 哈
     public WddPptApi(String baseUrl) {
         this.webClient = WebClient.builder()
                 .baseUrl(baseUrl)
+                // TODO @新：建议，token 作为 defaultHeader
                 .defaultHeaders((headers) -> headers.setContentType(MediaType.APPLICATION_JSON))
                 .build();
     }
 
-
     /**
      * 创建 token
      *
@@ -81,7 +82,7 @@ public class WddPptApi {
                 .block();
     }
 
-
+    // TODO @xin：是不是给个 API 连接，这样 type、content、files 都不用写注释太细了
     /**
      * 创建任务
      *
@@ -122,7 +123,6 @@ public class WddPptApi {
                 formData.add("file", file.getResource());
             }
         }
-
         return this.webClient.post()
                 .uri("/api/ppt/v2/createTask")
                 .header("token", token)
@@ -162,7 +162,7 @@ public class WddPptApi {
     }
 
     /**
-     * 分页查询PPT模板
+     * 分页查询 PPT 模板
      *
      * @param token   令牌
      * @param request 请求体
@@ -214,7 +214,7 @@ public class WddPptApi {
     }
 
     /**
-     * 生成PPT
+     * 生成 PPT
      *
      * @return PPT信息
      */
@@ -243,9 +243,11 @@ public class WddPptApi {
             String uid,
             Integer limit
     ) {
+
         public CreateTokenRequest(String apiKey) {
             this(apiKey, null, null);
         }
+
     }
 
     /**
@@ -256,8 +258,7 @@ public class WddPptApi {
             Integer code,
             String message,
             Map<String, Object> data
-    ) {
-    }
+    ) { }
 
     /**
      * 创建任务
@@ -267,8 +268,7 @@ public class WddPptApi {
             Integer type,
             String content,
             List<MultipartFile> files
-    ) {
-    }
+    ) { }
 
     /**
      * 生成大纲内容请求
@@ -281,8 +281,7 @@ public class WddPptApi {
             String audience,
             String lang,
             String prompt
-    ) {
-    }
+    ) { }
 
     /**
      * 修改大纲内容请求
@@ -292,21 +291,20 @@ public class WddPptApi {
             String id,
             String markdown,
             String question
-    ) {
-    }
+    ) { }
 
     /**
-     * 生成PPT请求
+     * 生成 PPT 请求
      */
+    // TODO @新：要不按照 PptCreateRequest 这样的风格
     @JsonInclude(value = JsonInclude.Include.NON_NULL)
     public record CreatePptRequest(
             String id,
             String templateId,
             String markdown
-    ) {
-    }
-
+    ) { }
 
+    // TODO @新：要不写下类注释
     @JsonInclude(value = JsonInclude.Include.NON_NULL)
     public record PptInfo(
             String id,
@@ -325,36 +323,35 @@ public class WddPptApi {
             LocalDateTime createTime,
             String createUser,
             String updateUser
-    ) {
-    }
-
+    ) { }
 
+    // TODO @新：要不写下类注释
     @JsonInclude(value = JsonInclude.Include.NON_NULL)
     public record TemplateQueryRequest(
             int page,
             int size,
             Filter filters
     ) {
+
         @JsonInclude(value = JsonInclude.Include.NON_NULL)
         public record Filter(
                 int type,
                 String category,
                 String style,
                 String themeColor
-        ) {
-        }
+        ) { }
+
     }
 
-
+    // TODO @新：要不写下类注释
     @JsonInclude(value = JsonInclude.Include.NON_NULL)
     public record PagePptTemplateInfo(
             List<PptTemplateInfo> data,
             String total
-    ) {
-
-    }
+    ) {}
 
 
+    // TODO @新：要不写下类注释
     @JsonInclude(value = JsonInclude.Include.NON_NULL)
     public record PptTemplateInfo(
             String id,
@@ -383,7 +380,6 @@ public class WddPptApi {
             LocalDateTime createTime,
             String createUser,
             String updateUser
-    ) {
-    }
+    ) { }
 
 }

yudao-module-ai/yudao-spring-boot-starter-ai/src/main/java/cn/iocoder/yudao/framework/ai/core/model/xinghuo/api/XunfeiPptApi.java

@@ -1,4 +1,4 @@
-package cn.iocoder.yudao.framework.ai.core.model.xunfei.api;
+package cn.iocoder.yudao.framework.ai.core.model.xinghuo.api;
 
 import cn.iocoder.yudao.framework.common.util.json.JsonUtils;
 import com.fasterxml.jackson.annotation.JsonInclude;
@@ -28,10 +28,11 @@ import java.util.Map;
 import java.util.function.Function;
 import java.util.function.Predicate;
 
+// TODO @新：要不改成 XunFeiPptApi
 /**
- * 讯飞智能PPT生成 API
- * <p>
- * 对接讯飞：<a href="https://www.xfyun.cn/doc/spark/PPTv2.html">智能 PPT 生成 API</a>
+ * 讯飞智能 PPT 生成 API
+ *
+ * @see <a href="https://www.xfyun.cn/doc/spark/PPTv2.html">智能 PPT 生成 API</a>
  *
  * @author xiaoxin
  */
@@ -52,7 +53,9 @@ public class XunfeiPptApi {
                 sink.error(new IllegalStateException("[xunfei-ppt-api] 调用失败！"));
             });
 
+    // TODO @新：是不是不用 baseUrl 哈
     public XunfeiPptApi(String baseUrl, String appId, String apiSecret) {
+        // TODO @新：建议，增加 defaultheaders，例如说 appid 之类的；或者每个请求，通过 headers customer 处理。
         this.webClient = WebClient.builder()
                 .baseUrl(baseUrl)
                 .build();
@@ -82,6 +85,7 @@ public class XunfeiPptApi {
      */
     private String generateSignature(String appId, String apiSecret, long timestamp) {
         try {
+            // TODO @新：使用 hutool 简化
             String auth = md5(appId + timestamp);
             return hmacSHA1Encrypt(auth, apiSecret);
         } catch (NoSuchAlgorithmException | InvalidKeyException e) {
@@ -120,7 +124,7 @@ public class XunfeiPptApi {
     }
 
     /**
-     * 获取PPT模板列表
+     * 获取 PPT 模板列表
      *
      * @param style    风格，如"商务"
      * @param pageSize 每页数量
@@ -130,8 +134,8 @@ public class XunfeiPptApi {
         SignatureInfo signInfo = getSignature();
         Map<String, Object> requestBody = new HashMap<>();
         requestBody.put("style", style);
-        requestBody.put("pageSize", pageSize != null ? pageSize.toString() : "10");
-
+        // TODO @新：可以使用 ObjUtil.defaultIfNull
+        requestBody.put("pageSize", pageSize != null ? pageSize : 10);
         return this.webClient.post()
                 .uri("/template/list")
                 .header("appId", signInfo.appId)
@@ -155,7 +159,6 @@ public class XunfeiPptApi {
         SignatureInfo signInfo = getSignature();
         MultiValueMap<String, Object> formData = new LinkedMultiValueMap<>();
         formData.add("query", query);
-
         return this.webClient.post()
                 .uri("/createOutline")
                 .header("appId", signInfo.appId)
@@ -171,7 +174,7 @@ public class XunfeiPptApi {
 
 
     /**
-     * 直接创建PPT（简化版 - 通过文本）
+     * 直接创建 PPT（简化版 - 通过文本）
      *
      * @param query 查询文本
      * @return 创建响应
@@ -184,7 +187,7 @@ public class XunfeiPptApi {
     }
 
     /**
-     * 直接创建PPT（简化版 - 通过文件）
+     * 直接创建 PPT（简化版 - 通过文件）
      *
      * @param file     文件
      * @param fileName 文件名
@@ -192,14 +195,12 @@ public class XunfeiPptApi {
      */
     public CreateResponse create(MultipartFile file, String fileName) {
         CreatePptRequest request = CreatePptRequest.builder()
-                .file(file)
-                .fileName(fileName)
-                .build();
+                .file(file).fileName(fileName).build();
         return create(request);
     }
 
     /**
-     * 直接创建PPT（完整版）
+     * 直接创建 PPT（完整版）
      *
      * @param request 请求参数
      * @return 创建响应
@@ -207,7 +208,6 @@ public class XunfeiPptApi {
     public CreateResponse create(CreatePptRequest request) {
         SignatureInfo signInfo = getSignature();
         MultiValueMap<String, Object> formData = buildCreateFormData(request);
-
         return this.webClient.post()
                 .uri("/create")
                 .header("appId", signInfo.appId)
@@ -223,7 +223,7 @@ public class XunfeiPptApi {
 
 
     /**
-     * 通过大纲创建PPT（简化版）
+     * 通过大纲创建 PPT（简化版）
      *
      * @param outline 大纲内容
      * @param query   查询文本
@@ -238,14 +238,13 @@ public class XunfeiPptApi {
     }
 
     /**
-     * 通过大纲创建PPT（完整版）
+     * 通过大纲创建 PPT（完整版）
      *
      * @param request 请求参数
      * @return 创建响应
      */
     public CreateResponse createPptByOutline(CreatePptByOutlineRequest request) {
         SignatureInfo signInfo = getSignature();
-
         return this.webClient.post()
                 .uri("/createPptByOutline")
                 .header("appId", signInfo.appId)
@@ -260,14 +259,13 @@ public class XunfeiPptApi {
     }
 
     /**
-     * 检查PPT生成进度
+     * 检查 PPT 生成进度
      *
-     * @param sid 任务ID
+     * @param sid 任务 ID
      * @return 进度响应
      */
     public ProgressResponse checkProgress(String sid) {
         SignatureInfo signInfo = getSignature();
-
         return this.webClient.get()
                 .uri(uriBuilder -> uriBuilder
                         .path("/progress")
@@ -290,8 +288,7 @@ public class XunfeiPptApi {
             String appId,
             String timestamp,
             String signature
-    ) {
-    }
+    ) { }
 
     /**
      * 模板列表响应
@@ -303,8 +300,7 @@ public class XunfeiPptApi {
             String desc,
             Integer count,
             TemplatePageData data
-    ) {
-    }
+    ) { }
 
     /**
      * 模板列表数据
@@ -314,8 +310,7 @@ public class XunfeiPptApi {
             String total,
             List<TemplateInfo> records,
             Integer pageNum
-    ) {
-    }
+    ) { }
 
     /**
      * 模板信息
@@ -329,8 +324,7 @@ public class XunfeiPptApi {
             String industry,
             String style,
             String detailImage
-    ) {
-    }
+    ) { }
 
     /**
      * 创建响应
@@ -342,8 +336,7 @@ public class XunfeiPptApi {
             String desc,
             Integer count,
             CreateResponseData data
-    ) {
-    }
+    ) { }
 
     /**
      * 创建响应数据
@@ -355,8 +348,7 @@ public class XunfeiPptApi {
             String title,
             String subTitle,
             OutlineData outline
-    ) {
-    }
+    ) { }
 
     /**
      * 大纲数据结构
@@ -367,6 +359,7 @@ public class XunfeiPptApi {
             String subTitle,
             List<Chapter> chapters
     ) {
+
         /**
          * 章节结构
          */
@@ -375,14 +368,15 @@ public class XunfeiPptApi {
                 String chapterTitle,
                 List<ChapterContent> chapterContents
         ) {
+
             /**
              * 章节内容
              */
             @JsonInclude(value = JsonInclude.Include.NON_NULL)
             public record ChapterContent(
                     String chapterTitle
-            ) {
-            }
+            ) { }
+
         }
 
         /**
@@ -403,8 +397,7 @@ public class XunfeiPptApi {
             int code,
             String desc,
             ProgressResponseData data
-    ) {
-    }
+    ) { }
 
     /**
      * 进度响应数据
@@ -414,6 +407,7 @@ public class XunfeiPptApi {
             int process,
             String pptId,
             String pptUrl,
+            // TODO @新：字段注释，去掉
             String pptStatus,         // PPT构建状态：building（构建中），done（已完成），build_failed（生成失败）
             String aiImageStatus,     // ai配图状态：building（构建中），done（已完成）
             String cardNoteStatus,    // 演讲备注状态：building（构建中），done（已完成）
@@ -421,6 +415,7 @@ public class XunfeiPptApi {
             Integer totalPages,       // 生成PPT的总页数
             Integer donePages         // 生成PPT的完成页数
     ) {
+
         /**
          * 是否全部完成
          *
@@ -452,10 +447,11 @@ public class XunfeiPptApi {
             }
             return (int) (donePages * 100.0 / totalPages);
         }
+
     }
 
     /**
-     * 通过大纲创建PPT请求参数
+     * 通过大纲创建 PPT 请求参数
      */
     @JsonInclude(value = JsonInclude.Include.NON_NULL)
     public record CreatePptByOutlineRequest(
@@ -473,6 +469,7 @@ public class XunfeiPptApi {
             Boolean isFigure,            // 是否自动配图
             String aiImage               // ai配图类型：normal、advanced
     ) {
+
         /**
          * 创建构建器
          *
@@ -482,10 +479,12 @@ public class XunfeiPptApi {
             return new Builder();
         }
 
+        // TODO @新：这个可以用 lombok 简化么？
         /**
          * 构建器类
          */
         public static class Builder {
+
             private String query;
             private String outlineSid;
             private OutlineData outline;
@@ -575,7 +574,7 @@ public class XunfeiPptApi {
     }
 
     /**
-     * 构建创建PPT的表单数据
+     * 构建创建 PPT 的表单数据
      *
      * @param request 请求参数
      * @return 表单数据
@@ -586,7 +585,6 @@ public class XunfeiPptApi {
         if (request.query() != null) {
             formData.add("query", request.query());
         }
-
         if (request.file() != null) {
             try {
                 formData.add("file", new ByteArrayResource(request.file().getBytes()) {
@@ -600,47 +598,37 @@ public class XunfeiPptApi {
                 throw new IllegalStateException("[xunfei-ppt-api] 文件处理失败", e);
             }
         }
-
+        // TODO @新：要不搞个 MapUtil.addIfPresent 方法？
         if (request.fileUrl() != null) {
             formData.add("fileUrl", request.fileUrl());
         }
-
         if (request.fileName() != null) {
             formData.add("fileName", request.fileName());
         }
-
         if (request.templateId() != null) {
             formData.add("templateId", request.templateId());
         }
-
         if (request.businessId() != null) {
             formData.add("businessId", request.businessId());
         }
-
         if (request.author() != null) {
             formData.add("author", request.author());
         }
-
         if (request.isCardNote() != null) {
             formData.add("isCardNote", request.isCardNote().toString());
         }
-
         if (request.search() != null) {
             formData.add("search", request.search().toString());
         }
-
         if (request.language() != null) {
             formData.add("language", request.language());
         }
-
         if (request.isFigure() != null) {
             formData.add("isFigure", request.isFigure().toString());
         }
-
         if (request.aiImage() != null) {
             formData.add("aiImage", request.aiImage());
         }
-
         return formData;
     }
 
@@ -662,6 +650,7 @@ public class XunfeiPptApi {
             Boolean isFigure,            // 是否自动配图
             String aiImage               // ai配图类型：normal、advanced
     ) {
+
         /**
          * 创建构建器
          *
@@ -675,6 +664,7 @@ public class XunfeiPptApi {
          * 构建器类
          */
         public static class Builder {
+
             private String query;
             private MultipartFile file;
             private String fileUrl;
@@ -688,6 +678,8 @@ public class XunfeiPptApi {
             private Boolean isFigure;
             private String aiImage;
 
+            // TODO @新：这个可以用 lombok 简化么？
+
             public Builder query(String query) {
                 this.query = query;
                 return this;
@@ -763,4 +755,5 @@ public class XunfeiPptApi {
             }
         }
     }
-} 
+
+}