feat(compat): 补齐文档草案接口兼容入口

common-agent-agent/src/main/java/com/bruce/agent/controller/AgentDefinitionController.java

@@ -8,6 +8,7 @@ import com.bruce.agent.dto.response.AgentDefinitionResponse;
 import com.bruce.agent.service.IAgentDefinitionService;
 import com.bruce.common.domain.model.RequestResult;
 import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.PathVariable;
 import org.springframework.web.bind.annotation.PostMapping;
@@ -18,6 +19,7 @@ import org.springframework.web.bind.annotation.RestController;
 
 import java.util.List;
 
+@Slf4j
 @RestController
 @RequestMapping("/api/agents")
 @RequiredArgsConstructor
@@ -55,4 +57,15 @@ public class AgentDefinitionController {
                                                  @RequestBody AgentChatRequest request) {
         return RequestResult.success(agentDefinitionService.chat(agentId, request));
     }
+
+    /**
+     * 兼容前端实现文档中的运行入口路径。
+     */
+    @PostMapping("/{agentId}/runs")
+    public RequestResult<AgentChatResponse> run(@PathVariable("agentId") Long agentId,
+                                                @RequestBody AgentChatRequest request) {
+        log.info("Agent运行入口开始，agentId={}, messageCount={}",
+                agentId, request.getMessages() == null ? 0 : request.getMessages().size());
+        return RequestResult.success(agentDefinitionService.chat(agentId, request));
+    }
 }

common-agent-agent/src/main/java/com/bruce/agent/controller/AgentSessionController.java

@@ -48,6 +48,24 @@ public class AgentSessionController {
         return RequestResult.success(agentSessionService.getDetailById(id));
     }
 
+    /**
+     * 兼容前端实现文档中的资源化会话详情路径。
+     */
+    @GetMapping("/{sessionId}")
+    public RequestResult<AgentSessionDetailVO> detailByPath(@PathVariable("sessionId") Long sessionId) {
+        log.info("Agent会话详情按路径查询开始，sessionId={}", sessionId);
+        return RequestResult.success(agentSessionService.getDetailById(sessionId));
+    }
+
+    /**
+     * 兼容前端实现文档中的 Agent 会话列表路径。
+     */
+    @GetMapping("/agents/{agentId}/sessions")
+    public RequestResult<List<AgentSessionDetailVO>> sessionsByAgent(@PathVariable("agentId") Long agentId) {
+        log.info("Agent会话列表查询开始，agentId={}", agentId);
+        return RequestResult.success(agentSessionService.listByAgentId(agentId));
+    }
+
     @GetMapping("/{sessionId}/messages")
     public RequestResult<List<AgentMessageVO>> messages(@PathVariable("sessionId") Long sessionId) {
         log.info("Agent消息列表查询开始，sessionId={}", sessionId);

common-agent-agent/src/test/java/com/bruce/agent/controller/AgentCompatControllerTests.java

@@ -0,0 +1,121 @@
+package com.bruce.agent.controller;
+
+import com.bruce.agent.dto.response.AgentChatResponse;
+import com.bruce.agent.service.IAgentDefinitionService;
+import com.bruce.agent.service.IAgentMessageService;
+import com.bruce.agent.service.IAgentSessionService;
+import com.bruce.agent.service.IAgentWorkspaceService;
+import com.bruce.agent.vo.AgentSessionDetailVO;
+import com.bruce.common.handler.GlobalExceptionHandler;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.InjectMocks;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+import org.springframework.http.MediaType;
+import org.springframework.test.web.servlet.MockMvc;
+import org.springframework.test.web.servlet.setup.MockMvcBuilders;
+
+import java.util.List;
+
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.when;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
+
+/**
+ * 验证 Agent 文档草案兼容路径。
+ */
+@ExtendWith(MockitoExtension.class)
+class AgentCompatControllerTests {
+
+    private MockMvc mockMvc;
+
+    @Mock
+    private IAgentDefinitionService agentDefinitionService;
+
+    @Mock
+    private IAgentSessionService agentSessionService;
+
+    @Mock
+    private IAgentMessageService agentMessageService;
+
+    @Mock
+    private IAgentWorkspaceService agentWorkspaceService;
+
+    @InjectMocks
+    private AgentDefinitionController agentDefinitionController;
+
+    @InjectMocks
+    private AgentSessionController agentSessionController;
+
+    @BeforeEach
+    void setUp() {
+        mockMvc = MockMvcBuilders.standaloneSetup(agentDefinitionController, agentSessionController)
+                .setControllerAdvice(new GlobalExceptionHandler())
+                .build();
+    }
+
+    @Test
+    void agentRunCompatShouldReturnChatResponse() throws Exception {
+        AgentChatResponse response = new AgentChatResponse();
+        response.setAgentId(1001L);
+        response.setAgentCode("presale_agent");
+        response.setAnswer("这是兼容运行入口返回的答案");
+        response.setModelRequestId("req-1001");
+
+        when(agentDefinitionService.chat(org.mockito.ArgumentMatchers.eq(1001L), any())).thenReturn(response);
+
+        mockMvc.perform(post("/api/agents/1001/runs")
+                        .contentType(MediaType.APPLICATION_JSON)
+                        .content("""
+                                {
+                                  "messages": [
+                                    {
+                                      "role": "user",
+                                      "content": "请总结合同重点"
+                                    }
+                                  ],
+                                  "ragEnabled": true
+                                }
+                                """))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.resultcode").value("0"))
+                .andExpect(jsonPath("$.data.agentCode").value("presale_agent"))
+                .andExpect(jsonPath("$.data.modelRequestId").value("req-1001"));
+    }
+
+    @Test
+    void sessionsCompatShouldReturnStructuredSessionList() throws Exception {
+        AgentSessionDetailVO session = new AgentSessionDetailVO();
+        session.setId(2001L);
+        session.setAgentId(1001L);
+        session.setSessionCode("session_001");
+        session.setStatus("ACTIVE");
+
+        when(agentSessionService.listByAgentId(1001L)).thenReturn(List.of(session));
+
+        mockMvc.perform(get("/api/agent-sessions/agents/1001/sessions"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.resultcode").value("0"))
+                .andExpect(jsonPath("$.data[0].sessionCode").value("session_001"));
+    }
+
+    @Test
+    void sessionDetailCompatShouldReturnStructuredDetail() throws Exception {
+        AgentSessionDetailVO session = new AgentSessionDetailVO();
+        session.setId(2001L);
+        session.setSessionCode("session_001");
+        session.setStatus("ACTIVE");
+
+        when(agentSessionService.getDetailById(2001L)).thenReturn(session);
+
+        mockMvc.perform(get("/api/agent-sessions/2001"))
+                .andExpect(status().isOk())
+                .andExpect(jsonPath("$.resultcode").value("0"))
+                .andExpect(jsonPath("$.data.sessionCode").value("session_001"));
+    }
+}