Feat: 책모 챗봇 구현

src/main/java/checkmo/authentication/internal/config/SecurityConfig.java

@@ -83,6 +83,7 @@ public SecurityFilterChain filterChain(
                         .requestMatchers(HttpMethod.GET, "/api/v1/news/sitemap", "/api/v1/news/**").permitAll()
                         .requestMatchers(HttpMethod.GET, "/api/v1/app/version").permitAll()
                         .requestMatchers(HttpMethod.GET, "/api/v1/terms").permitAll()
+                        .requestMatchers(HttpMethod.POST, "/api/v1/chatbot/messages").permitAll()
                         .requestMatchers(HttpMethod.GET, "/api/v1/members/me", "/api/v1/members/me/**").authenticated()
                         .requestMatchers(HttpMethod.GET, "/api/v1/members/*").permitAll()
                         .requestMatchers(HttpMethod.POST, "/api/v1/members/find-email").permitAll()

src/main/java/checkmo/chatbot/internal/config/ChatbotRestTemplateConfig.java

@@ -0,0 +1,32 @@
+package checkmo.chatbot.internal.config;
+
+import checkmo.chatbot.internal.config.properties.ChatbotProperties;
+import lombok.RequiredArgsConstructor;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.http.client.SimpleClientHttpRequestFactory;
+import org.springframework.web.client.RestTemplate;
+
+@Configuration
+@RequiredArgsConstructor
+public class ChatbotRestTemplateConfig {
+
+    private final ChatbotProperties chatbotProperties;
+
+    /**
+     * book 모듈의 기본 {@code restTemplate} 빈(Aladin 전용 타임아웃/XML 컨버터 설정)과 분리된
+     * 챗봇(Gemini) 전용 RestTemplate. 빈 이름을 파라미터/필드명과 일치시켜 이름 기준으로 주입되도록 한다.
+     *
+     * 주의: classpath에 jackson-dataformat-xml(Aladin 연동용)이 있어 RestTemplate 기본 컨버터 목록에
+     * XML 컨버터가 JSON 컨버터보다 먼저 등록된다. 호출부(GeminiApiService)에서 Content-Type을
+     * application/json으로 명시하지 않으면 요청 바디가 XML로 직렬화되어 버리니 반드시 명시할 것.
+     */
+    @Bean
+    public RestTemplate chatbotRestTemplate() {
+        SimpleClientHttpRequestFactory factory = new SimpleClientHttpRequestFactory();
+        factory.setConnectTimeout(chatbotProperties.getTimeoutMs());
+        factory.setReadTimeout(chatbotProperties.getTimeoutMs());
+
+        return new RestTemplate(factory);
+    }
+}

src/main/java/checkmo/chatbot/internal/config/properties/ChatbotProperties.java

@@ -0,0 +1,54 @@
+package checkmo.chatbot.internal.config.properties;
+
+import jakarta.validation.Valid;
+import jakarta.validation.constraints.NotBlank;
+import jakarta.validation.constraints.Positive;
+import lombok.Getter;
+import lombok.Setter;
+import org.springframework.boot.context.properties.ConfigurationProperties;
+import org.springframework.stereotype.Component;
+
+@Getter
+@Setter
+@Component
+@ConfigurationProperties(prefix = "chatbot.gemini")
+public class ChatbotProperties {
+
+    @NotBlank(message = "Gemini API 키는 필수입니다")
+    private String apiKey;
+
+    @NotBlank(message = "Gemini API 기본 URL은 필수입니다")
+    private String baseUrl = "https://generativelanguage.googleapis.com";
+
+    @NotBlank(message = "Gemini API 버전은 필수입니다")
+    private String apiVersion = "v1beta";
+
+    @Positive(message = "타임아웃은 양수여야 합니다")
+    private int timeoutMs = 15000;
+
+    @Valid
+    private Model defaultModel = new Model();
+
+    @Valid
+    private Model escalationModel = new Model();
+
+    @Valid
+    private Handoff handoff = new Handoff();
+
+    @Getter
+    @Setter
+    public static class Model {
+        @NotBlank(message = "모델명은 필수입니다")
+        private String name;
+    }
+
+    @Getter
+    @Setter
+    public static class Handoff {
+        @NotBlank(message = "고객센터 URL은 필수입니다")
+        private String supportUrl;
+
+        @NotBlank(message = "문의 폼 URL은 필수입니다")
+        private String inquiryFormUrl;
+    }
+}

src/main/java/checkmo/chatbot/internal/converter/ChatbotConverter.java

@@ -0,0 +1,22 @@
+package checkmo.chatbot.internal.converter;
+
+import checkmo.chatbot.internal.service.ChatReply;
+import checkmo.chatbot.web.dto.ChatbotResponseDTO;
+import lombok.AccessLevel;
+import lombok.NoArgsConstructor;
+
+@NoArgsConstructor(access = AccessLevel.PRIVATE)
+public class ChatbotConverter {
+
+    public static ChatbotResponseDTO.Reply toReplyResponse(ChatReply chatReply) {
+        return ChatbotResponseDTO.Reply.builder()
+                .sessionToken(chatReply.sessionToken())
+                .replyText(chatReply.replyText())
+                .escalated(chatReply.escalated())
+                .modelUsed(chatReply.modelUsed())
+                .handoffSuggested(chatReply.handoffSuggested())
+                .supportUrl(chatReply.supportUrl())
+                .inquiryFormUrl(chatReply.inquiryFormUrl())
+                .build();
+    }
+}

src/main/java/checkmo/chatbot/internal/entity/ChatMessage.java

@@ -0,0 +1,79 @@
+package checkmo.chatbot.internal.entity;
+
+import checkmo.common.BaseEntity;
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.EnumType;
+import jakarta.persistence.Enumerated;
+import jakarta.persistence.GeneratedValue;
+import jakarta.persistence.GenerationType;
+import jakarta.persistence.Id;
+import lombok.AccessLevel;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+
+@Getter
+@NoArgsConstructor(access = AccessLevel.PROTECTED)
+@Entity
+public class ChatMessage extends BaseEntity {
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    private Long id;
+
+    @Column(nullable = false)
+    private Long chatSessionId;
+
+    @Enumerated(EnumType.STRING)
+    @Column(nullable = false, length = 20)
+    private ChatRole role;
+
+    // 마스킹된 텍스트만 저장한다. 원문(PII 포함 가능)은 어떤 컬럼에도 저장하지 않는다.
+    // @Lob만 쓰면 기본 length(255) 때문에 Hibernate가 TINYTEXT를 기대해 TEXT 컬럼과 스키마 검증이 어긋난다.
+    @Column(nullable = false, columnDefinition = "TEXT")
+    private String maskedContent;
+
+    @Column(length = 100)
+    private String modelUsed; // ASSISTANT 메시지에만 사용
+
+    @Column(nullable = false)
+    private boolean escalated;
+
+    @Column(nullable = false)
+    private boolean botUncertain;
+
+    @Column(nullable = false)
+    private boolean userNegativeReaction;
+
+    private ChatMessage(
+            Long chatSessionId,
+            ChatRole role,
+            String maskedContent,
+            String modelUsed,
+            boolean escalated,
+            boolean botUncertain,
+            boolean userNegativeReaction
+    ) {
+        this.chatSessionId = chatSessionId;
+        this.role = role;
+        this.maskedContent = maskedContent;
+        this.modelUsed = modelUsed;
+        this.escalated = escalated;
+        this.botUncertain = botUncertain;
+        this.userNegativeReaction = userNegativeReaction;
+    }
+
+    public static ChatMessage userMessage(Long chatSessionId, String maskedContent, boolean userNegativeReaction) {
+        return new ChatMessage(chatSessionId, ChatRole.USER, maskedContent, null, false, false, userNegativeReaction);
+    }
+
+    public static ChatMessage assistantMessage(
+            Long chatSessionId,
+            String maskedContent,
+            String modelUsed,
+            boolean escalated,
+            boolean botUncertain
+    ) {
+        return new ChatMessage(chatSessionId, ChatRole.ASSISTANT, maskedContent, modelUsed, escalated, botUncertain, false);
+    }
+}

src/main/java/checkmo/chatbot/internal/entity/ChatRole.java

@@ -0,0 +1,6 @@
+package checkmo.chatbot.internal.entity;
+
+public enum ChatRole {
+    USER,
+    ASSISTANT
+}

src/main/java/checkmo/chatbot/internal/entity/ChatSession.java

@@ -0,0 +1,53 @@
+package checkmo.chatbot.internal.entity;
+
+import checkmo.common.BaseEntity;
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.GeneratedValue;
+import jakarta.persistence.GenerationType;
+import jakarta.persistence.Id;
+import java.time.LocalDateTime;
+import lombok.AccessLevel;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+
+@Getter
+@NoArgsConstructor(access = AccessLevel.PROTECTED)
+@Entity
+public class ChatSession extends BaseEntity {
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    private Long id;
+
+    @Column
+    private Long memberId; // 비로그인 사용자는 null
+
+    @Column(nullable = false, unique = true, length = 64)
+    private String sessionToken;
+
+    @Column(nullable = false)
+    private boolean unresolved;
+
+    @Column(nullable = false)
+    private LocalDateTime lastActivityAt;
+
+    private ChatSession(Long memberId, String sessionToken) {
+        this.memberId = memberId;
+        this.sessionToken = sessionToken;
+        this.unresolved = false;
+        this.lastActivityAt = LocalDateTime.now();
+    }
+
+    public static ChatSession start(Long memberId, String sessionToken) {
+        return new ChatSession(memberId, sessionToken);
+    }
+
+    public void recordActivity() {
+        this.lastActivityAt = LocalDateTime.now();
+    }
+
+    public void flagUnresolved() {
+        this.unresolved = true;
+    }
+}

src/main/java/checkmo/chatbot/internal/exception/ChatbotErrorStatus.java

@@ -0,0 +1,39 @@
+package checkmo.chatbot.internal.exception;
+
+import checkmo.common.apiPayload.code.BaseErrorCode;
+import checkmo.common.apiPayload.code.ErrorReasonDTO;
+import lombok.AllArgsConstructor;
+import lombok.Getter;
+import org.springframework.http.HttpStatus;
+
+@Getter
+@AllArgsConstructor
+public enum ChatbotErrorStatus implements BaseErrorCode {
+
+    GEMINI_API_CALL_FAILED(HttpStatus.BAD_GATEWAY, "CHATBOT_502", "챗봇 응답 생성에 실패했습니다."),
+    GEMINI_EMPTY_RESPONSE(HttpStatus.BAD_GATEWAY, "CHATBOT_503", "챗봇 응답이 비어 있습니다."),
+    SESSION_NOT_FOUND(HttpStatus.NOT_FOUND, "CHATBOT_404", "존재하지 않는 챗봇 세션입니다.");
+
+    private final HttpStatus httpStatus;
+    private final String code;
+    private final String message;
+
+    @Override
+    public ErrorReasonDTO getReason() {
+        return ErrorReasonDTO.builder()
+                .code(code)
+                .message(message)
+                .isSuccess(false)
+                .build();
+    }
+
+    @Override
+    public ErrorReasonDTO getReasonHttpStatus() {
+        return ErrorReasonDTO.builder()
+                .httpStatus(httpStatus)
+                .code(code)
+                .message(message)
+                .isSuccess(false)
+                .build();
+    }
+}

src/main/java/checkmo/chatbot/internal/exception/ChatbotException.java

@@ -0,0 +1,14 @@
+package checkmo.chatbot.internal.exception;
+
+import checkmo.common.apiPayload.exception.GeneralException;
+
+public class ChatbotException extends GeneralException {
+
+    public ChatbotException(ChatbotErrorStatus status) {
+        super(status);
+    }
+
+    public ChatbotException(ChatbotErrorStatus status, Throwable cause) {
+        super(status, cause);
+    }
+}