[FEAT] AI 멘토 질문 및 답변 스트리밍 API 구현

src/main/java/com/mr/domain/mentor/controller/MentorController.java

@@ -1,16 +1,23 @@
 package com.mr.domain.mentor.controller;
 
+import com.mr.domain.mentor.dto.req.MentorQuestionRequestDTO;
 import com.mr.domain.mentor.dto.res.MentorMessageHistoryResponseDTO;
+import com.mr.domain.mentor.service.MentorQuestionService;
 import com.mr.domain.mentor.service.MentorService;
+import com.mr.domain.mentor.service.MentorStreamingService;
 import com.mr.global.apipayload.ApiResponse;
 import com.mr.global.security.SecurityUtil;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
+import org.springframework.http.MediaType;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RestController;
+import org.springframework.web.servlet.mvc.method.annotation.SseEmitter;
 
 @RestController
 @RequiredArgsConstructor
@@ -19,6 +26,8 @@
 public class MentorController {
 
     private final MentorService mentorService;
+    private final MentorQuestionService mentorQuestionService;
+    private final MentorStreamingService mentorStreamingService;
 
     @GetMapping("/{analysisId}/mentor/messages")
     @Operation(
@@ -31,4 +40,20 @@ public ApiResponse<MentorMessageHistoryResponseDTO> getMessageHistory(
         Long userId = SecurityUtil.getCurrentUserId();
         return ApiResponse.onSuccess(mentorService.getMessageHistory(userId, analysisId));
     }
+
+    @PostMapping(
+            value = "/{analysisId}/mentor/messages",
+            consumes = MediaType.APPLICATION_JSON_VALUE,
+            produces = MediaType.TEXT_EVENT_STREAM_VALUE
+    )
+    @Operation(summary = "AI 멘토 질문 전송 API", description = "질문을 저장하고 Gemini 답변을 SSE로 실시간 전송합니다.")
+    public SseEmitter sendQuestion(
+            @PathVariable Long analysisId,
+            @RequestBody MentorQuestionRequestDTO request
+    ) {
+        Long userId = SecurityUtil.getCurrentUserId();
+        MentorQuestionService.PreparedQuestion prepared =
+                mentorQuestionService.prepare(userId, analysisId, request.content());
+        return mentorStreamingService.stream(prepared);
+    }
 }

src/main/java/com/mr/domain/mentor/dto/req/MentorQuestionRequestDTO.java

@@ -0,0 +1,4 @@
+package com.mr.domain.mentor.dto.req;
+
+public record MentorQuestionRequestDTO(String content) {
+}

src/main/java/com/mr/domain/mentor/dto/res/MentorStreamEventDTO.java

@@ -0,0 +1,42 @@
+package com.mr.domain.mentor.dto.res;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.mr.domain.mentor.entity.MentorMessage;
+import com.mr.domain.mentor.entity.enums.MessageRole;
+import java.time.LocalDateTime;
+
+public final class MentorStreamEventDTO {
+
+    private MentorStreamEventDTO() {
+    }
+
+    public record Start(Long analysisId, Long mentorChatSessionId, Message userMessage) {
+    }
+
+    public record Chunk(String content) {
+    }
+
+    public record Complete(Message assistantMessage) {
+    }
+
+    public record Error(String code, String message) {
+    }
+
+    public record Message(Long mentorMessageId, MessageRole role, JsonNode referencesJson,
+                          String content, LocalDateTime createdAt) {
+
+        public static Message user(MentorMessage message) {
+            return new Message(message.getId(), message.getRole(), null, message.getContent(), message.getCreatedAt());
+        }
+
+        public static Message assistant(MentorMessage message, JsonNode referencesJson) {
+            return new Message(
+                    message.getId(),
+                    message.getRole(),
+                    referencesJson,
+                    message.getContent(),
+                    message.getCreatedAt()
+            );
+        }
+    }
+}

src/main/java/com/mr/domain/mentor/entity/MentorChatSession.java

@@ -8,7 +8,10 @@
 import com.mr.global.entity.BaseTimeEntity;
 import jakarta.persistence.*;
 
+import java.time.Duration;
 import java.time.LocalDateTime;
+import java.util.Objects;
+import java.util.UUID;
 import lombok.AccessLevel;
 import lombok.Getter;
 import lombok.NoArgsConstructor;
@@ -57,6 +60,12 @@ public class MentorChatSession extends BaseTimeEntity {
     @Column(name = "last_message_at")
     private LocalDateTime lastMessageAt;
 
+    @Column(name = "generation_token", length = 36)
+    private String generationToken;
+
+    @Column(name = "generation_started_at")
+    private LocalDateTime generationStartedAt;
+
     @Column(name = "question_count", nullable = false)
     private Integer questionCount;
 
@@ -108,12 +117,56 @@ public void updateLastMessageAt() {
         this.lastMessageAt = LocalDateTime.now();
     }
 
-    // TODO: 질문 횟수 3회 제한(MENTOR_429_01) 체크는 질문 전송 API 구현 시 추가
     public void increaseQuestionCount() {
         validateActive();
         this.questionCount += 1;
     }
 
+    public String startGenerating(Duration staleAfter) {
+        if (this.status == MentorChatStatus.GENERATING && !isStale(staleAfter)) {
+            throw new GeneralException(MentorErrorStatus.MENTOR_RESPONSE_IN_PROGRESS);
+        }
+        if (this.status != MentorChatStatus.ACTIVE && this.status != MentorChatStatus.GENERATING) {
+            throw new GeneralException(MentorErrorStatus.MENTOR_SESSION_NOT_ACTIVE);
+        }
+        if (this.questionCount >= 3) {
+            throw new GeneralException(MentorErrorStatus.MENTOR_QUESTION_LIMIT_EXCEEDED);
+        }
+        this.status = MentorChatStatus.GENERATING;
+        this.generationToken = UUID.randomUUID().toString();
+        this.generationStartedAt = LocalDateTime.now();
+        return this.generationToken;
+    }
+
+    public void completeGenerating(String expectedToken) {
+        if (this.status != MentorChatStatus.GENERATING
+                || !Objects.equals(this.generationToken, expectedToken)) {
+            throw new GeneralException(MentorErrorStatus.MENTOR_SESSION_NOT_ACTIVE);
+        }
+        this.questionCount += 1;
+        this.lastMessageAt = LocalDateTime.now();
+        this.status = MentorChatStatus.ACTIVE;
+        clearGeneration();
+    }
+
+    public void failGenerating(String expectedToken) {
+        if (this.status == MentorChatStatus.GENERATING
+                && Objects.equals(this.generationToken, expectedToken)) {
+            this.status = MentorChatStatus.ACTIVE;
+            clearGeneration();
+        }
+    }
+
+    private boolean isStale(Duration staleAfter) {
+        return this.generationStartedAt == null
+                || this.generationStartedAt.isBefore(LocalDateTime.now().minus(staleAfter));
+    }
+
+    private void clearGeneration() {
+        this.generationToken = null;
+        this.generationStartedAt = null;
+    }
+
     private void validateActive() {
         if (this.status != MentorChatStatus.ACTIVE) {
             throw new GeneralException(MentorErrorStatus.MENTOR_SESSION_NOT_ACTIVE);

src/main/java/com/mr/domain/mentor/entity/enums/MentorChatStatus.java

@@ -2,6 +2,7 @@
 
 public enum MentorChatStatus {
     ACTIVE,
+    GENERATING,
     CLOSED,
     DISABLED
 }

src/main/java/com/mr/domain/mentor/exception/MentorErrorStatus.java

@@ -9,11 +9,17 @@
 @AllArgsConstructor
 public enum MentorErrorStatus implements BaseCode {
 
-    // 400_01/02는 스펙상 질문 전송 검증용으로 예약됨
+    MENTOR_QUESTION_REQUIRED(HttpStatus.BAD_REQUEST, "MENTOR_400_01", "질문 내용을 입력해주세요."),
+    MENTOR_QUESTION_TOO_LONG(HttpStatus.BAD_REQUEST, "MENTOR_400_02", "질문은 500자 이하로 입력해주세요."),
     MENTOR_INVALID_REQUEST(HttpStatus.BAD_REQUEST, "MENTOR_400_03", "필수 정보가 누락되었습니다."),
 
     MENTOR_ACCESS_DENIED(HttpStatus.FORBIDDEN, "MENTOR_403_01", "해당 대화에 접근할 수 없습니다."),
+    MENTOR_ANALYSIS_NOT_COMPLETED(HttpStatus.CONFLICT, "MENTOR_409_01", "분석 완료 후 질문할 수 있습니다."),
+    MENTOR_RESPONSE_IN_PROGRESS(HttpStatus.CONFLICT, "MENTOR_409_02", "이미 AI 멘토 답변을 생성하고 있습니다."),
     MENTOR_SESSION_NOT_ACTIVE(HttpStatus.CONFLICT, "MENTOR_409_02", "활성 상태의 세션에서만 질문할 수 있습니다."),
+    MENTOR_QUESTION_LIMIT_EXCEEDED(HttpStatus.TOO_MANY_REQUESTS, "MENTOR_429_01", "질문 가능 횟수를 초과했습니다."),
+    MENTOR_RESPONSE_GENERATION_FAILED(HttpStatus.INTERNAL_SERVER_ERROR, "AI_500_02", "AI 멘토 답변 생성에 실패했습니다."),
+    MENTOR_MESSAGE_SAVE_FAILED(HttpStatus.INTERNAL_SERVER_ERROR, "MENTOR_500_02", "멘토 대화 저장에 실패했습니다."),
     ;
 
     private final HttpStatus status;

src/main/java/com/mr/domain/mentor/repository/MentorChatSessionRepository.java

@@ -0,0 +1,18 @@
+package com.mr.domain.mentor.repository;
+
+import com.mr.domain.mentor.entity.MentorChatSession;
+import jakarta.persistence.LockModeType;
+import java.util.Optional;
+import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.data.jpa.repository.Lock;
+import org.springframework.data.jpa.repository.Query;
+import org.springframework.data.repository.query.Param;
+
+public interface MentorChatSessionRepository extends JpaRepository<MentorChatSession, Long> {
+
+    Optional<MentorChatSession> findByAnalysisId(Long analysisId);
+
+    @Lock(LockModeType.PESSIMISTIC_WRITE)
+    @Query("select session from MentorChatSession session where session.id = :sessionId")
+    Optional<MentorChatSession> findByIdForUpdate(@Param("sessionId") Long sessionId);
+}

src/main/java/com/mr/domain/mentor/repository/MentorMessageRepository.java

@@ -7,4 +7,6 @@
 public interface MentorMessageRepository extends JpaRepository<MentorMessage, Long> {
 
     List<MentorMessage> findByMentorChatSessionAnalysisIdOrderByCreatedAtAscIdAsc(Long analysisId);
+
+    List<MentorMessage> findTop10ByMentorChatSessionAnalysisIdOrderByCreatedAtDescIdDesc(Long analysisId);
 }

src/main/java/com/mr/domain/mentor/service/MentorQuestionService.java

@@ -0,0 +1,149 @@
+package com.mr.domain.mentor.service;
+
+import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.mr.domain.analysis.entity.Analysis;
+import com.mr.domain.analysis.entity.AnalysisReport;
+import com.mr.domain.analysis.entity.enums.AnalysisStatus;
+import com.mr.domain.analysis.entity.enums.LlmStatus;
+import com.mr.domain.analysis.exception.AnalysisErrorStatus;
+import com.mr.domain.analysis.repository.AnalysisReportRepository;
+import com.mr.domain.analysis.repository.AnalysisRepository;
+import com.mr.domain.mentor.dto.res.MentorStreamEventDTO;
+import com.mr.domain.mentor.entity.MentorChatSession;
+import com.mr.domain.mentor.entity.MentorMessage;
+import com.mr.domain.mentor.exception.MentorErrorStatus;
+import com.mr.domain.mentor.repository.MentorChatSessionRepository;
+import com.mr.domain.mentor.repository.MentorMessageRepository;
+import com.mr.global.apipayload.exception.GeneralException;
+import java.time.Duration;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Objects;
+import lombok.RequiredArgsConstructor;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+@Service
+@RequiredArgsConstructor
+public class MentorQuestionService {
+
+    private static final Duration STALE_GENERATION_AFTER = Duration.ofMinutes(2);
+    private static final String REFERENCES_JSON =
+            "{\"sourceFields\":[\"analysis.raw_result_json\",\"analysis_report.content\"]}";
+
+    private final AnalysisRepository analysisRepository;
+    private final AnalysisReportRepository analysisReportRepository;
+    private final MentorChatSessionRepository sessionRepository;
+    private final MentorMessageRepository messageRepository;
+    private final ObjectMapper objectMapper;
+
+    @Transactional
+    public PreparedQuestion prepare(Long userId, Long analysisId, String content) {
+        validateContent(content);
+
+        Analysis analysis = analysisRepository.findByIdForUpdate(analysisId)
+                .orElseThrow(() -> new GeneralException(AnalysisErrorStatus.ANALYSIS_NOT_FOUND));
+        validateOwner(analysis, userId);
+        if (analysis.getStatus() != AnalysisStatus.COMPLETED) {
+            throw new GeneralException(MentorErrorStatus.MENTOR_ANALYSIS_NOT_COMPLETED);
+        }
+
+        MentorChatSession session = sessionRepository.findByAnalysisId(analysisId)
+                .orElseGet(() -> sessionRepository.save(
+                        MentorChatSession.createActive(analysis, analysis.getUser())));
+        String generationToken = session.startGenerating(STALE_GENERATION_AFTER);
+
+        String prompt = buildPrompt(analysis, content.trim());
+        MentorMessage userMessage = messageRepository.saveAndFlush(
+                MentorMessage.createUserMessage(session, content.trim()));
+        return new PreparedQuestion(
+                session.getId(),
+                generationToken,
+                prompt,
+                new MentorStreamEventDTO.Start(
+                        analysisId,
+                        session.getId(),
+                        MentorStreamEventDTO.Message.user(userMessage)
+                )
+        );
+    }
+
+    @Transactional
+    public MentorStreamEventDTO.Complete complete(Long sessionId, String generationToken, String answer) {
+        MentorChatSession session = findSessionForUpdate(sessionId);
+        session.completeGenerating(generationToken);
+        MentorMessage assistantMessage = messageRepository.saveAndFlush(
+                MentorMessage.createAssistantMessage(session, REFERENCES_JSON, answer));
+        try {
+            return new MentorStreamEventDTO.Complete(MentorStreamEventDTO.Message.assistant(
+                    assistantMessage,
+                    objectMapper.readTree(REFERENCES_JSON)
+            ));
+        } catch (JsonProcessingException exception) {
+            throw new IllegalStateException("Invalid server-managed mentor references.", exception);
+        }
+    }
+
+    @Transactional
+    public void fail(Long sessionId, String generationToken) {
+        findSessionForUpdate(sessionId).failGenerating(generationToken);
+    }
+
+    private MentorChatSession findSessionForUpdate(Long sessionId) {
+        return sessionRepository.findByIdForUpdate(sessionId)
+                .orElseThrow(() -> new GeneralException(MentorErrorStatus.MENTOR_INVALID_REQUEST));
+    }
+
+    private String buildPrompt(Analysis analysis, String question) {
+        AnalysisReport report = analysisReportRepository
+                .findFirstByAnalysisIdAndLlmStatusOrderByCreatedAtDesc(analysis.getId(), LlmStatus.SUCCESS)
+                .orElse(null);
+        List<MentorMessage> recentMessages = new ArrayList<>(
+                messageRepository.findTop10ByMentorChatSessionAnalysisIdOrderByCreatedAtDescIdDesc(
+                        analysis.getId()));
+        Collections.reverse(recentMessages);
+
+        Map<String, Object> context = new LinkedHashMap<>();
+        context.put("analysis", analysis.getRawResultJson());
+        context.put("report", report == null ? null : report.getContent());
+        context.put("history", recentMessages.stream()
+                .map(message -> Map.of(
+                        "role", message.getRole().name(),
+                        "content", message.getContent()
+                ))
+                .toList());
+        context.put("question", question);
+        try {
+            return objectMapper.writeValueAsString(context);
+        } catch (JsonProcessingException exception) {
+            throw new GeneralException(MentorErrorStatus.MENTOR_INVALID_REQUEST);
+        }
+    }
+
+    private void validateOwner(Analysis analysis, Long userId) {
+        if (!Objects.equals(analysis.getUser().getUserId(), userId)) {
+            throw new GeneralException(MentorErrorStatus.MENTOR_ACCESS_DENIED);
+        }
+    }
+
+    private void validateContent(String content) {
+        if (content == null || content.isBlank()) {
+            throw new GeneralException(MentorErrorStatus.MENTOR_QUESTION_REQUIRED);
+        }
+        if (content.trim().length() > 500) {
+            throw new GeneralException(MentorErrorStatus.MENTOR_QUESTION_TOO_LONG);
+        }
+    }
+
+    public record PreparedQuestion(
+            Long sessionId,
+            String generationToken,
+            String prompt,
+            MentorStreamEventDTO.Start startEvent
+    ) {
+    }
+}