【代码评审】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>
+ * @see <a href="https://docmee.cn/open-platform/api">PPT 生成 API</a>
- * * 对接文多多：<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)
@@ -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 请求
      */
+    // 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>
+ * @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) {
@@ -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)
@@ -192,9 +195,7 @@ public class XunfeiPptApi {
      */
     public CreateResponse create(MultipartFile file, String fileName) {
         CreatePptRequest request = CreatePptRequest.builder()
-                .file(file)
+                .file(file).fileName(fileName).build();
-                .fileName(fileName)
-                .build();
         return create(request);
     }
 
@@ -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)
@@ -245,7 +245,6 @@ public class XunfeiPptApi {
      */
     public CreateResponse createPptByOutline(CreatePptByOutlineRequest request) {
         SignatureInfo signInfo = getSignature();
-
         return this.webClient.post()
                 .uri("/createPptByOutline")
                 .header("appId", signInfo.appId)
@@ -267,7 +266,6 @@ public class XunfeiPptApi {
      */
     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,6 +447,7 @@ public class XunfeiPptApi {
             }
             return (int) (donePages * 100.0 / totalPages);
         }
+
     }
 
     /**
@@ -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;
@@ -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 {
             }
         }
     }
+
 }

yudao-module-ai/yudao-spring-boot-starter-ai/src/test/java/cn/iocoder/yudao/framework/ai/ppt/wdd/WddPptApiTests.java

@@ -9,7 +9,6 @@ import reactor.core.publisher.Flux;
 import java.util.Map;
 import java.util.Objects;
 
-
 /**
  * {@link WddPptApi} 集成测试
  *
@@ -19,11 +18,9 @@ public class WddPptApiTests {
 
     private final WddPptApi wddPptApi = new WddPptApi("https://docmee.cn");
 
+    private final String token = ""; // API Token
 
-    private final String token = "";
+    @Test
-
-
-    @Test //获取token
     @Disabled
     public void testCreateApiToken() {
         // 准备参数
@@ -35,8 +32,10 @@ public class WddPptApiTests {
         System.out.println(token);
     }
 
-
+    /**
-    @Test // 创建任务
+     * 创建任务
+     */
+    @Test
     @Disabled
     public void testCreateTask() {
         WddPptApi.ApiResponse apiResponse = wddPptApi.createTask(token, 1, "dify 介绍", null);
@@ -47,7 +46,8 @@ public class WddPptApiTests {
     @Test // 创建大纲
     @Disabled
     public void testGenerateOutlineRequest() {
-        WddPptApi.CreateOutlineRequest request = new WddPptApi.CreateOutlineRequest("1901539019628613632", "medium", null, null, null, null);
+        WddPptApi.CreateOutlineRequest request = new WddPptApi.CreateOutlineRequest(
+                "1901539019628613632", "medium", null, null, null, null);
         // 调用
         Flux<Map<String, Object>> flux = wddPptApi.createOutline(token, request);
         StringBuffer contentBuffer = new StringBuffer();
@@ -61,13 +61,16 @@ public class WddPptApiTests {
         }).then().block();
         // 打印结果
         System.out.println(contentBuffer);
-
     }
 
-    @Test // 修改大纲
+    /**
+     * 修改大纲
+     */
+    @Test
     @Disabled
     public void testUpdateOutlineRequest() {
-        WddPptApi.UpdateOutlineRequest request = new WddPptApi.UpdateOutlineRequest("1901539019628613632", TEST_OUT_LINE_CONTENT, "精简一点，三个章节即可");
+        WddPptApi.UpdateOutlineRequest request = new WddPptApi.UpdateOutlineRequest(
+                "1901539019628613632", TEST_OUT_LINE_CONTENT, "精简一点，三个章节即可");
         // 调用
         Flux<Map<String, Object>> flux = wddPptApi.updateOutline(token, request);
         StringBuffer contentBuffer = new StringBuffer();
@@ -84,11 +87,15 @@ public class WddPptApiTests {
 
     }
 
-    @Test // 获取 PPT 模版分页
+    /**
+     * 获取 PPT 模版分页
+     */
+    @Test
     @Disabled
     public void testGetPptTemplatePage() {
         // 准备参数
-        WddPptApi.TemplateQueryRequest.Filter filter = new WddPptApi.TemplateQueryRequest.Filter(1, null, null, null);
+        WddPptApi.TemplateQueryRequest.Filter filter = new WddPptApi.TemplateQueryRequest.Filter(
+                1, null, null, null);
         WddPptApi.TemplateQueryRequest request = new WddPptApi.TemplateQueryRequest(1, 10, filter);
         // 调用
         WddPptApi.PagePptTemplateInfo pptTemplatePage = wddPptApi.getTemplatePage(token, request);
@@ -96,8 +103,10 @@ public class WddPptApiTests {
         System.out.println(pptTemplatePage);
     }
 
-
+    /**
-    @Test // 生成 PPT
+     * 生成 PPT
+     */
+    @Test
     @Disabled
     public void testGeneratePptx() {
         // 准备参数
@@ -108,7 +117,6 @@ public class WddPptApiTests {
         System.out.println(pptInfo);
     }
 
-
     private final String TEST_OUT_LINE_CONTENT = """
             # Dify：新一代AI应用开发平台
             

yudao-module-ai/yudao-spring-boot-starter-ai/src/test/java/cn/iocoder/yudao/framework/ai/ppt/xunfei/XunfeiPptApiTests.java

@@ -1,6 +1,7 @@
 package cn.iocoder.yudao.framework.ai.ppt.xunfei;
 
-import cn.iocoder.yudao.framework.ai.core.model.xunfei.api.XunfeiPptApi;
+import cn.hutool.core.io.FileUtil;
+import cn.iocoder.yudao.framework.ai.core.model.xinghuo.api.XunfeiPptApi;
 import cn.iocoder.yudao.framework.common.util.json.JsonUtils;
 import org.junit.jupiter.api.Disabled;
 import org.junit.jupiter.api.Test;
@@ -8,8 +9,6 @@ import org.springframework.mock.web.MockMultipartFile;
 import org.springframework.web.multipart.MultipartFile;
 
 import java.io.File;
-import java.io.FileInputStream;
-import java.io.IOException;
 
 /**
  * {@link XunfeiPptApi} 集成测试
@@ -24,7 +23,10 @@ public class XunfeiPptApiTests {
 
     private final XunfeiPptApi xunfeiPptApi = new XunfeiPptApi(XunfeiPptApi.BASE_URL, APP_ID, API_SECRET);
 
-    @Test // 获取PPT模板列表
+    /**
+     * 获取 PPT 模板列表
+     */
+    @Test
     @Disabled
     public void testGetTemplatePage() {
         // 调用方法
@@ -48,7 +50,10 @@ public class XunfeiPptApiTests {
         }
     }
 
-    @Test // 创建大纲（通过文本）
+    /**
+     * 创建大纲（通过文本）
+     */
+    @Test
     @Disabled
     public void testCreateOutline() {
         XunfeiPptApi.CreateResponse response = getCreateResponse();
@@ -68,15 +73,19 @@ public class XunfeiPptApiTests {
         }
     }
 
-    // 创建大纲（通过文本）
+    /**
+     * 创建大纲（通过文本）
+     * @return 创建大纲响应
+     */
     private XunfeiPptApi.CreateResponse getCreateResponse() {
-        // 准备参数
         String param = "智能体平台 Dify 介绍";
-        // 调用方法
         return xunfeiPptApi.createOutline(param);
     }
 
-    @Test // 通过大纲创建PPT（完整参数）
+    /**
+     * 通过大纲创建 PPT（完整参数）
+     */
+    @Test
     @Disabled
     public void testCreatePptByOutlineWithFullParams() {
         // 创建大纲对象
@@ -95,7 +104,10 @@ public class XunfeiPptApiTests {
         }
     }
 
-    @Test // 检查PPT生成进度
+    /**
+     * 检查 PPT 生成进度
+     */
+    @Test
     @Disabled
     public void testCheckProgress() {
         // 准备参数 - 使用之前创建 PPT 时返回的 sid
@@ -141,7 +153,10 @@ public class XunfeiPptApiTests {
         }
     }
 
-    @Test // 轮询检查PPT生成进度直到完成
+    /**
+     * 轮询检查 PPT 生成进度直到完成
+     */
+    @Test
     @Disabled
     public void testPollCheckProgress() throws InterruptedException {
         // 准备参数 - 使用之前创建 PP T时返回的 sid
@@ -193,7 +208,10 @@ public class XunfeiPptApiTests {
         }
     }
 
-    @Test // 直接创建PPT（通过文本）
+    /**
+     * 直接创建 PPT（通过文本）
+     */
+    @Test
     @Disabled
     public void testCreatePptByText() {
         // 准备参数
@@ -215,9 +233,12 @@ public class XunfeiPptApiTests {
         }
     }
 
-    @Test // 直接创建PPT（通过文件）
+    /**
+     * 直接创建 PPT（通过文件）
+     */
+    @Test
     @Disabled
-    public void testCreatePptByFile() throws IOException {
+    public void testCreatePptByFile() {
         // 准备参数
         File file = new File("src/test/resources/test.txt"); // 请确保此文件存在
         MultipartFile multipartFile = convertFileToMultipartFile(file);
@@ -238,9 +259,12 @@ public class XunfeiPptApiTests {
         }
     }
 
-    @Test // 直接创建PPT（完整参数）
+    /**
+     * 直接创建 PPT（完整参数）
+     */
+    @Test
     @Disabled
-    public void testCreatePptWithFullParams() throws IOException {
+    public void testCreatePptWithFullParams() {
         // 准备参数
         String query = "合肥天气趋势分析，包括近 5 年的气温变化、降水量变化、极端天气事件，以及对城市生活的影响";
 
@@ -287,14 +311,8 @@ public class XunfeiPptApiTests {
     /**
      * 将 File 转换为 MultipartFile
      */
-    private MultipartFile convertFileToMultipartFile(File file) throws IOException {
+    private MultipartFile convertFileToMultipartFile(File file) {
-        FileInputStream input = new FileInputStream(file);
+        return new MockMultipartFile("file", file.getName(), "text/plain", FileUtil.readBytes(file));
-        return new MockMultipartFile(
-                "file",
-                file.getName(),
-                "text/plain",
-                input.readAllBytes()
-        );
     }
 
 }