新增北向接口前端使用文档 (#349)

* [frontend] 北向接口API文档增加新接口内容

* [app-platform] 新增北向接口修改接口注解内容

* [frontend] 北向接口API文档兼容旧接口内容

* [app-platform] 老版北向接口修改接口注解内容

* [app-platform] 新ws北向接口修改接口路径

* [frontend] 合并两套前端北向接口组件

* [frontend] x86环境不显示apiKey鉴权相关内容

* [app-platform] 代码格式化

* [app-platform] 代码格式化

* [app-platform] 检视意见修改

---------

Co-authored-by: 陈潇文 <chenxiaowen17@huawei.com>

Author: Msquittto

app-builder/jane/plugins/aipp-plugin/src/main/java/modelengine/fit/jober/aipp/controller/AppChatController.java

@@ -63,7 +63,7 @@ public AppChatController(Authenticator authenticator, AppChatService appChatServ
      * @throws AippTaskNotFoundException 任务不存在异常
      */
     @CarverSpan(value = "operation.appChat.app.chat")
-    @PostMapping(value = "/app_chat", description = "会话接口，传递会话信息")
+    @PostMapping(path = "/app_chat", description = "会话接口，传递会话信息", summary = "会话接口")
     public Choir<Object> chat(HttpClassicServerRequest httpRequest, @PathVariable("tenant_id") String tenantId,
             @RequestBody CreateAppChatRequest body) throws AippTaskNotFoundException {
         // todo 等多版本整改上线，在app domain结构中获取多模态的配置信息 当前临时方案是放在请求的headers里

app-builder/plugins/aipp-northbound/src/main/java/modelengine/fit/jade/aipp/northbound/controller/AippLogController.java

@@ -50,7 +50,8 @@ public AippLogController(Authenticator authenticator, AippLogServiceAdapter aipp
      * @param appId 表示应用 id 的 {@link String}。
      * @return 表示会话历史记录的 {@link Rsp}{@code <}{@link List}{@code <}{@link AippInstLogData}{@code >>}。
      */
-    @GetMapping(path = "/app/{app_id}/chat/{chat_id}", description = "指定chatId查询实例历史记录（查询最近10个实例）")
+    @GetMapping(path = "/app/{app_id}/chat/{chat_id}", summary = "查询会话历史记录",
+            description = "指定 chatId 查询实例历史记录（查询最近 10 个实例）。")
     public Rsp<List<AippInstLogData>> queryChatRecentChatLog(HttpClassicServerRequest httpRequest,
             @PathVariable("tenant_id") String tenantId, @PathVariable("app_id") String appId,
             @PathVariable("chat_id") String chatId) {

app-builder/plugins/aipp-northbound/src/main/java/modelengine/fit/jade/aipp/northbound/controller/AppBuilderAppController.java

@@ -88,7 +88,7 @@ public Rsp<RangedResultSet<AppMetadata>> list(HttpClassicServerRequest httpReque
      * @param appId 表示待查询应用的唯一标识符的 {@link String}。
      * @return 表示应用配置详情的 {@link Rsp}{@code <}{@link AppBuilderAppDto}{@code >}。
      */
-    @GetMapping(value = "/{appId}/config", summary = "查询应用配置详情",
+    @GetMapping(path = "/{appId}/config", summary = "查询应用配置详情",
             description = "该接口可以通过待查询应用的唯一标识符来查询指定应用的配置详情。")
     public Rsp<AppBuilderAppDto> query(HttpClassicServerRequest httpRequest,
             @PathVariable("tenantId") @Property(description = "租户的唯一标识符") String tenantId,

app-builder/plugins/aipp-northbound/src/main/java/modelengine/fit/jade/aipp/northbound/controller/AppChatController.java

@@ -78,7 +78,7 @@ public AppChatController(Authenticator authenticator, AppChatServiceAdapter appC
      * @return 表示会话的 sse 流的 {@link Choir}。
      */
     @CarverSpan(value = "operation.appChat.app.chat")
-    @PostMapping(value = "/apps/{appId}", summary = "发送对话消息",
+    @PostMapping(path = "/apps/{appId}", summary = "发送对话消息",
             description = "该接口向大模型发送一个问题信息，并开启一个对话。支持 SSE 和 Websocket 两种流式调用方式。")
     public Choir<Object> chat(HttpClassicServerRequest httpRequest,
             @PathVariable("tenantId") @Property(description = "租户的唯一标识符") String tenantId,

app-builder/plugins/aipp-northbound/src/main/java/modelengine/fit/jade/aipp/northbound/controller/UserFeedbackController.java

@@ -13,6 +13,7 @@
 import modelengine.fit.http.annotation.RequestBody;
 import modelengine.fit.http.annotation.RequestMapping;
 import modelengine.fit.jane.common.controller.AbstractController;
+import modelengine.fit.jane.common.response.Rsp;
 import modelengine.fit.jane.task.gateway.Authenticator;
 import modelengine.fitframework.annotation.Component;
 import modelengine.jade.app.engine.base.dto.UsrFeedbackDto;
@@ -45,9 +46,11 @@ public UserFeedbackController(Authenticator authenticator, UsrFeedbackService us
      *
      * @param usrFeedbackDto 表示用户反馈消息体的 {@link UsrFeedbackDto}。
      */
-    @PostMapping("/feedback")
-    public void createUsrFeedback(@RequestBody UsrFeedbackDto usrFeedbackDto) {
-        usrFeedbackService.create(usrFeedbackDto);
+    @PostMapping(path = "/feedback", summary = "创建用户反馈记录",
+            description = "该接口用于创建用户对一个对话实例的反馈记录。")
+    public Rsp<Void> createUsrFeedback(@RequestBody UsrFeedbackDto usrFeedbackDto) {
+        this.usrFeedbackService.create(usrFeedbackDto);
+        return Rsp.ok();
     }
 
     /**
@@ -56,20 +59,23 @@ public void createUsrFeedback(@RequestBody UsrFeedbackDto usrFeedbackDto) {
      * @param usrFeedbackDto 表示用户反馈消息体的 {@link UsrFeedbackDto}。
      * @param instanceId 表示对话实例 Id 的 {@link String}。
      */
-    @PatchMapping("/feedback/{instanceId}")
-    public void updateUsrFeedback(@PathVariable("instanceId") String instanceId,
+    @PatchMapping(path = "/feedback/{instanceId}", summary = "更新用户反馈记录",
+            description = "该接口用于更新用户对一个对话实例反馈记录。")
+    public Rsp<Void> updateUsrFeedback(@PathVariable("instanceId") String instanceId,
             @RequestBody UsrFeedbackDto usrFeedbackDto) {
-        usrFeedbackService.updateOne(instanceId, usrFeedbackDto);
+        this.usrFeedbackService.updateOne(instanceId, usrFeedbackDto);
+        return Rsp.ok();
     }
 
     /**
-     * 通过 LogId 获取对话信息列表。
+     * 通过 logId 查询用户反馈记录
      *
      * @param instanceId 表示对话实例 Id 的 {@link String}。
-     * @return 表示对话信息的 {@link UsrFeedbackDto}。
+     * @return 表示反馈记录的 {@link UsrFeedbackDto}。
      */
-    @GetMapping("/feedback/{instanceId}")
-    public UsrFeedbackDto getAllAnswerByInstanceId(@PathVariable("instanceId") String instanceId) {
-        return usrFeedbackService.getUsrFeedbackByInstanceId(instanceId);
+    @GetMapping(path = "/feedback/{instanceId}", summary = "查询用户反馈记录",
+            description = "该接口可以通过待查询实例的唯一标识符来查询实例的反馈记录。")
+    public Rsp<UsrFeedbackDto> getAllAnswerByInstanceId(@PathVariable("instanceId") String instanceId) {
+        return Rsp.ok(this.usrFeedbackService.getUsrFeedbackByInstanceId(instanceId));
     }
 }

app-builder/plugins/aipp-northbound/src/main/java/modelengine/fit/jade/aipp/northbound/websocket/controller/AppStreamController.java

@@ -49,7 +49,7 @@
  * @author 曹嘉美
  * @since 2024-07-23
  */
-@WebSocketEndpoint(path = "/v1/chat")
+@WebSocketEndpoint(path = "/api/app/v1/chat")
 @Component
 public class AppStreamController extends AbstractController {
     private static final String METHOD = "appChat";