AIM-17-챌린지-루트-생성-로직-구현 (#12)

* feat: langchain4j에 대한 dependency 추가

* feat: gemini 사용을 위한 configuration 설정

* fix: config에 따른 langchain4j dependency 수정

* feat: LLM 호출 결과를 담을 DTO 정의

* feat: LLM 프롬포트 Generator 정의

* refact: Payload 타겟 시간을 integer로 변환

* feat: 챌린지 주차별 내용 생성 로직 구현

* feat: service 테스트 코드 작성

Author: HuniHuns

build.gradle

@@ -67,9 +67,13 @@ dependencies {
     // Validation
     implementation 'org.springframework.boot:spring-boot-starter-validation'
 
-    //oauth
+    // oauth
     implementation 'org.springframework.boot:spring-boot-starter-oauth2-client'
 
+    // Langchain4j
+    implementation 'dev.langchain4j:langchain4j:1.0.0-beta3'
+    implementation 'dev.langchain4j:langchain4j-spring-boot-starter:1.0.0-beta3'
+    implementation 'dev.langchain4j:langchain4j-google-ai-gemini:1.0.0-beta3'
 }
 
 tasks.named('test') {

src/main/java/targeter/aim/domain/ai/llm/dto/RoutePayload.java

@@ -0,0 +1,18 @@
+package targeter.aim.domain.ai.llm.dto;
+
+import lombok.Data;
+
+import java.util.List;
+
+@Data
+public class RoutePayload {
+    private List<Week> weeks;
+
+    @Data
+    public static class Week {
+        private Integer weekNumber; // 주차
+        private String title;       // 제목
+        private String content;     // 내용
+        private Integer targetSeconds; // 목표 시간초
+    }
+}

src/main/java/targeter/aim/domain/ai/llm/service/RouteGenerator.java

@@ -0,0 +1,60 @@
+package targeter.aim.domain.ai.llm.service;
+
+import dev.langchain4j.service.SystemMessage;
+import dev.langchain4j.service.UserMessage;
+import dev.langchain4j.service.V;
+import dev.langchain4j.service.spring.AiService;
+import targeter.aim.domain.ai.llm.dto.RoutePayload;
+
+@AiService
+public interface RouteGenerator {
+
+    @SystemMessage("""
+        You are a world-class expert in the requested field and a supportive mentor.
+        Your goal is to create a highly effective, step-by-step learning path (Challenge Route) that guides the mentee to success.
+        
+        [YOUR PERSONA]
+        1. Professional Authority: Deep knowledge of the provided tags and jobs.
+        2. Mentor's Heart: Encouraging and supportive.
+        3. Practicality: Focus on actionable items.
+        
+        [SEASONAL ADAPTATION]
+        You must consider the 'Start Date' of the challenge.
+        - If the challenge involves physical activity (e.g., Diet, Workout) or lifestyle:
+          - Winter: Suggest indoor alternatives (Home training, Gym) instead of outdoor running. Focus on immune system or warming up.
+          - Summer: Warn about heatstroke, suggest hydration, or early morning/night activities.
+        - Even for desk jobs (e.g., Coding, Reading):
+          - New Year (Jan): Leverage "New Year's Resolution" motivation.
+          - Year-End (Dec): Focus on "Finishing strong" or "Retrospective".
+        
+        [OUTPUT CONSTRAINT]
+        1. Output MUST be a valid JSON format matching the provided Java Record structure.
+        2. Return ONLY the RAW JSON. No markdown blocks.
+        3. Language: Korean (한국어).
+        """)
+    @UserMessage("""
+        Please design a {{duration}}-week study challenge for a mentee.
+        
+        [MENTEE CONTEXT]
+        - Start Date: {{startDate}} (YYYY-MM-DD)
+        - Challenge Name: {{name}}
+        - Tags: {{tags}}
+        - Fields: {{fields}}
+        - Job: {{job}}
+        - User Request: {{userRequest}}
+        
+        [GENERATION RULES]
+        1. Generate exactly {{duration}} items in the 'weeks' list.
+        2. 'content': Detailed description. **Must reflect the season/weather of the {{startDate}}**.
+        3. 'targetSeconds': Realistic study/action time in seconds.
+        """)
+    RoutePayload generate(
+            @V("name") String name,
+            @V("tags") String tags,
+            @V("fields") String fields,
+            @V("job") String job,
+            @V("duration") int duration,
+            @V("startDate") String startDate, // 날짜 추가
+            @V("userRequest") String userRequest
+    );
+}

src/main/java/targeter/aim/domain/challenge/dto/ChallengeDto.java

@@ -0,0 +1,38 @@
+package targeter.aim.domain.challenge.dto;
+
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+import targeter.aim.domain.challenge.entity.ChallengeMode;
+import targeter.aim.domain.challenge.entity.ChallengeVisibility;
+
+import java.time.LocalDate;
+import java.util.List;
+
+public class ChallengeDto {
+
+    @Data
+    @AllArgsConstructor
+    @NoArgsConstructor
+    @Builder
+    public static class ProgressCreateRequest {
+        private String name;
+
+        private LocalDate startedAt;
+
+        private Integer duration;
+
+        private List<String> tags;
+
+        private List<String> fields;
+
+        private List<String> jobs;
+
+        private String userRequest;
+
+        private ChallengeMode mode;
+
+        private ChallengeVisibility visibility;
+    }
+}

src/main/java/targeter/aim/domain/challenge/repository/ChallengeRepository.java

@@ -2,6 +2,12 @@
 
 import org.springframework.data.jpa.repository.JpaRepository;
 import targeter.aim.domain.challenge.entity.Challenge;
+import targeter.aim.domain.user.entity.User;
+
+import java.time.LocalDate;
+import java.util.Optional;
 
 public interface ChallengeRepository extends JpaRepository<Challenge, Long> {
+
+    Optional<Challenge> findByHostAndNameAndStartedAt(User host, String name, LocalDate startedAt);
 }

src/main/java/targeter/aim/domain/challenge/service/ChallengeRouteGenerationService.java

@@ -0,0 +1,119 @@
+package targeter.aim.domain.challenge.service;
+
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.stereotype.Service;
+import targeter.aim.domain.ai.llm.dto.RoutePayload;
+import targeter.aim.domain.ai.llm.service.RouteGenerator;
+import targeter.aim.domain.challenge.dto.ChallengeDto;
+
+import java.time.format.DateTimeFormatter;
+import java.util.List;
+import java.util.function.Supplier;
+
+@Slf4j
+@Service
+@RequiredArgsConstructor
+public class ChallengeRouteGenerationService {
+
+    private final RouteGenerator routeGenerator;
+
+    private static final int MAX_TITLE_LENGTH = 100;
+    private static final int MAX_CONTENT_LENGTH = 500;
+
+    public RoutePayload generateRoute(ChallengeDto.ProgressCreateRequest req) {
+        // 1. AI 호출 (Retry 최대 3회 수행)
+        RoutePayload payload = retry(() ->
+                routeGenerator.generate(
+                        req.getName(),
+                        listToString(req.getTags()),
+                        listToString(req.getFields()),
+                        listToString(req.getJobs()),
+                        req.getDuration(),
+                        req.getStartedAt().format(DateTimeFormatter.ISO_LOCAL_DATE),
+                        req.getUserRequest() != null ? req.getUserRequest() : ""
+                ),
+                3, 1000L    // 3회 시도, 1초 대기부터 시작
+        );
+
+        // 2. 데이터 정제 (공백 제거, 길이 자르기 등)
+        sanitizePayload(payload);
+
+        // 3. 결과 검증 (필수값 확인)
+        validatePayload(payload, req.getDuration());
+
+        return payload;
+    }
+
+    // [1] retry 로직
+    private <T> T retry(Supplier<T> action, int maxAttempts, long initialDelayMs) {
+        long delay = initialDelayMs;
+        RuntimeException lastException = null;
+
+        for(int i = 1; i <= maxAttempts; i++) {
+            try{
+                return action.get();
+            } catch (RuntimeException ex) {
+                lastException = ex;
+                if(i < maxAttempts) {
+                    sleep(delay);
+                    delay = Math.min(delay * 2, 8000);
+                }
+            }
+        }
+
+        throw lastException != null ? lastException : new RuntimeException("Retry failed");
+    }
+
+    private void sleep(long ms) {
+        try { Thread.sleep(ms); }
+        catch (InterruptedException e) { Thread.currentThread().interrupt(); }
+    }
+
+    // [2] Sanitization 로직
+    private void sanitizePayload(RoutePayload payload) {
+        if (payload == null || payload.getWeeks() == null) return;
+
+        for (RoutePayload.Week week : payload.getWeeks()) {
+            // 앞뒤 공백 제거
+            week.setTitle(normalize(week.getTitle()));
+            week.setContent(normalize(week.getContent()));
+
+            // 안전 장치: 제목이 DB 함량보다 길면 자름
+            if (week.getTitle().length() > MAX_TITLE_LENGTH) {
+                week.setTitle(week.getTitle().substring(0, MAX_TITLE_LENGTH));
+            }
+        }
+    }
+
+    // [3] Validation 로직
+    private void validatePayload(RoutePayload payload, int expectedWeeks) {
+        if (payload == null || payload.getWeeks() == null) {
+            throw new IllegalStateException("AI 응답 데이터가 비어있습니다.");
+        }
+        if (payload.getWeeks().size() != expectedWeeks) {
+            throw new IllegalStateException(
+                    String.format("AI 생성 기간 불일치: 요청(%d주) != 응답(%d주)", expectedWeeks, payload.getWeeks().size())
+            );
+        }
+
+        for(RoutePayload.Week week : payload.getWeeks()) {
+            if(isBlank(week.getTitle()) || isBlank(week.getContent())) {
+                throw new IllegalStateException("AI가 빈 내용(제목/본문)을 반환했습니다.");
+            }
+        }
+    }
+
+    // Help 로직
+    private String listToString(List<String> list) {
+        return (list == null || list.isEmpty()) ? "" : String.join(", ", list);
+    }
+
+    private String normalize(String s) {
+        return s == null ? "" : s.trim().replaceAll("\\s+", " ");
+    }
+
+    private boolean isBlank(String s) {
+        return s == null || s.trim().isEmpty();
+    }
+}

src/main/java/targeter/aim/domain/challenge/service/ChallengeRoutePersistService.java

@@ -0,0 +1,81 @@
+package targeter.aim.domain.challenge.service;
+
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Propagation;
+import org.springframework.transaction.annotation.Transactional;
+import targeter.aim.domain.ai.llm.dto.RoutePayload;
+import targeter.aim.domain.challenge.dto.ChallengeDto;
+import targeter.aim.domain.challenge.entity.*;
+import targeter.aim.domain.challenge.repository.ChallengeMemberRepository;
+import targeter.aim.domain.challenge.repository.ChallengeRepository;
+import targeter.aim.domain.challenge.repository.WeeklyProgressRepository;
+import targeter.aim.domain.user.entity.User;
+import targeter.aim.domain.user.repository.UserRepository;
+
+import java.util.Optional;
+
+@Slf4j
+@Service
+@RequiredArgsConstructor
+public class ChallengeRoutePersistService {
+
+    private final ChallengeRepository challengeRepository;
+    private final ChallengeMemberRepository challengeMemberRepository;
+    private final WeeklyProgressRepository weeklyProgressRepository;
+    private final UserRepository userRepository;
+
+    // 상위 트랜잭션과 독립적으로 실행
+    @Transactional(propagation = Propagation.REQUIRES_NEW)
+    public Long persistAtomic(Long userId, ChallengeDto.ProgressCreateRequest req, RoutePayload payload) {
+        // 1. Host 유저 조회
+        User host = userRepository.findById(userId)
+                .orElseThrow(() -> new IllegalArgumentException("User not found"));
+
+        // 2. 멱등성
+        Optional<Challenge> existing = challengeRepository.findByHostAndNameAndStartedAt(host, req.getName(), req.getStartedAt());
+
+        if(existing.isPresent()) {
+            log.warn("Challenge with id {} already exists", existing.get().getId());
+            return existing.get().getId();
+        }
+
+        // 3. Challenge 엔티티 생성 및 저장
+        Challenge challenge = Challenge.builder()
+                .host(host)
+                .name(req.getName())
+                .job(String.join(",", req.getJobs()))
+                .startedAt(req.getStartedAt())
+                .durationWeek(req.getDuration())
+                .mode(req.getMode())
+                .visibility(req.getVisibility())
+                .status(ChallengeStatus.IN_PROGRESS)
+                .build();
+
+        Challenge savedChallenge = challengeRepository.save(challenge);
+
+        // 4. ChallengeMember 저장
+        ChallengeMember hostMember = ChallengeMember.builder()
+                .id(ChallengeMemberId.of(savedChallenge, host))
+                .role(MemberRole.HOST)
+                .build();
+        challengeMemberRepository.save(hostMember);
+
+        // 5. WeeklyProgress 저장
+        for(RoutePayload.Week week : payload.getWeeks()) {
+            WeeklyProgress progress = WeeklyProgress.builder()
+                    .challenge(savedChallenge)
+                    .user(host)
+                    .weekNumber(week.getWeekNumber())
+                    .title(week.getTitle())
+                    .content(week.getContent())
+                    .stopwatchTimeSeconds(week.getTargetSeconds())
+                    .isComplete(false)
+                    .build();
+            weeklyProgressRepository.save(progress);
+        }
+
+        return savedChallenge.getId();
+    }
+}

src/main/java/targeter/aim/system/configuration/llm/GeminiConfig.java

@@ -0,0 +1,20 @@
+package targeter.aim.system.configuration.llm;
+
+import dev.langchain4j.model.googleai.GoogleAiGeminiChatModel;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+@Configuration
+public class GeminiConfig {
+    @Bean
+    public GoogleAiGeminiChatModel googleAiGeminiChatModel (
+            @Value("${gemini.api-key}") String apiKey
+    ) {
+        return GoogleAiGeminiChatModel.builder()
+                .apiKey(apiKey)
+                .modelName("gemini-2.0-flash")
+                .build();
+    };
+
+}

src/main/resources/application-remote.yml

@@ -53,6 +53,9 @@ cache:
       expiration-week: ${JWT_REFRESH_TOKEN_EXPIRATION_WEEKS:2}
       maximum-size: 10000
 
+gemini:
+  api-key: ${GEMINI_API_KEY}
+
 app:
   cors:
     allowed-origins: ${APP_CORS_ORIGINS:}