add ai-service

.claude/settings.local.json

@@ -15,7 +15,11 @@
       "Bash(git add:*)",
       "Bash(git commit:*)",
       "Bash(git push)",
-      "Bash(git pull:*)"
+      "Bash(git pull:*)",
+      "Bash(./gradlew ai-service:compileJava:*)",
+      "Bash(./gradlew ai-service:build:*)",
+      "Bash(.\\gradlew ai-service:compileJava:*)",
+      "Bash(./gradlew.bat:*)"
     ],
     "deny": [],
     "ask": []

ai-service/build.gradle

@@ -2,8 +2,8 @@ dependencies {
     // Kafka Consumer
     implementation 'org.springframework.kafka:spring-kafka'
 
-    // Redis for result caching
+    // Redis for result caching (already in root build.gradle)
-    implementation 'org.springframework.boot:spring-boot-starter-data-redis'
+    // implementation 'org.springframework.boot:spring-boot-starter-data-redis'
 
     // OpenFeign for Claude/GPT API
     implementation 'org.springframework.cloud:spring-cloud-starter-openfeign'
@@ -14,4 +14,12 @@ dependencies {
 
     // Jackson for JSON
     implementation 'com.fasterxml.jackson.core:jackson-databind'
+
+    // JWT (for security)
+    implementation "io.jsonwebtoken:jjwt-api:${jjwtVersion}"
+    runtimeOnly "io.jsonwebtoken:jjwt-impl:${jjwtVersion}"
+    runtimeOnly "io.jsonwebtoken:jjwt-jackson:${jjwtVersion}"
+
+    // Note: PostgreSQL dependency is in root build.gradle but AI Service doesn't use DB
+    // We still include it for consistency, but no JPA entities will be created
 }

ai-service/src/main/java/com/kt/ai/AiServiceApplication.java

@@ -0,0 +1,23 @@
+package com.kt.ai;
+
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+import org.springframework.cloud.openfeign.EnableFeignClients;
+
+/**
+ * AI Service Application
+ * - Kafka를 통한 비동기 AI 추천 처리
+ * - Claude API / GPT-4 API 연동
+ * - Redis 기반 결과 캐싱
+ *
+ * @author AI Service Team
+ * @since 1.0.0
+ */
+@EnableFeignClients
+@SpringBootApplication
+public class AiServiceApplication {
+
+    public static void main(String[] args) {
+        SpringApplication.run(AiServiceApplication.class, args);
+    }
+}

ai-service/src/main/java/com/kt/ai/circuitbreaker/CircuitBreakerManager.java

@@ -0,0 +1,87 @@
+package com.kt.ai.circuitbreaker;
+
+import com.kt.ai.exception.CircuitBreakerOpenException;
+import io.github.resilience4j.circuitbreaker.CircuitBreaker;
+import io.github.resilience4j.circuitbreaker.CircuitBreakerRegistry;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.stereotype.Component;
+
+import java.util.function.Supplier;
+
+/**
+ * Circuit Breaker Manager
+ * - Claude API / GPT-4 API 호출 시 Circuit Breaker 적용
+ * - Fallback 처리
+ *
+ * @author AI Service Team
+ * @since 1.0.0
+ */
+@Slf4j
+@Component
+@RequiredArgsConstructor
+public class CircuitBreakerManager {
+
+    private final CircuitBreakerRegistry circuitBreakerRegistry;
+
+    /**
+     * Circuit Breaker를 통한 API 호출
+     *
+     * @param circuitBreakerName Circuit Breaker 이름 (claudeApi, gpt4Api)
+     * @param supplier API 호출 로직
+     * @param fallback Fallback 로직
+     * @return API 호출 결과 또는 Fallback 결과
+     */
+    public <T> T executeWithCircuitBreaker(
+            String circuitBreakerName,
+            Supplier<T> supplier,
+            Supplier<T> fallback
+    ) {
+        CircuitBreaker circuitBreaker = circuitBreakerRegistry.circuitBreaker(circuitBreakerName);
+
+        try {
+            // Circuit Breaker 상태 확인
+            if (circuitBreaker.getState() == CircuitBreaker.State.OPEN) {
+                log.warn("Circuit Breaker is OPEN: {}", circuitBreakerName);
+                throw new CircuitBreakerOpenException(circuitBreakerName);
+            }
+
+            // Circuit Breaker를 통한 API 호출
+            return circuitBreaker.executeSupplier(() -> {
+                log.debug("Executing with Circuit Breaker: {}", circuitBreakerName);
+                return supplier.get();
+            });
+
+        } catch (CircuitBreakerOpenException e) {
+            // Circuit Breaker가 열린 경우 Fallback 실행
+            log.warn("Circuit Breaker OPEN, executing fallback: {}", circuitBreakerName);
+            if (fallback != null) {
+                return fallback.get();
+            }
+            throw e;
+
+        } catch (Exception e) {
+            // 기타 예외 발생 시 Fallback 실행
+            log.error("API call failed, executing fallback: {}", circuitBreakerName, e);
+            if (fallback != null) {
+                return fallback.get();
+            }
+            throw e;
+        }
+    }
+
+    /**
+     * Circuit Breaker를 통한 API 호출 (Fallback 없음)
+     */
+    public <T> T executeWithCircuitBreaker(String circuitBreakerName, Supplier<T> supplier) {
+        return executeWithCircuitBreaker(circuitBreakerName, supplier, null);
+    }
+
+    /**
+     * Circuit Breaker 상태 조회
+     */
+    public CircuitBreaker.State getCircuitBreakerState(String circuitBreakerName) {
+        CircuitBreaker circuitBreaker = circuitBreakerRegistry.circuitBreaker(circuitBreakerName);
+        return circuitBreaker.getState();
+    }
+}

ai-service/src/main/java/com/kt/ai/circuitbreaker/fallback/AIServiceFallback.java

@@ -0,0 +1,130 @@
+package com.kt.ai.circuitbreaker.fallback;
+
+import com.kt.ai.model.dto.response.EventRecommendation;
+import com.kt.ai.model.dto.response.ExpectedMetrics;
+import com.kt.ai.model.dto.response.TrendAnalysis;
+import com.kt.ai.model.enums.EventMechanicsType;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.stereotype.Component;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * AI Service Fallback 처리
+ * - Circuit Breaker가 열린 경우 기본 데이터 반환
+ *
+ * @author AI Service Team
+ * @since 1.0.0
+ */
+@Slf4j
+@Component
+public class AIServiceFallback {
+
+    /**
+     * 기본 트렌드 분석 결과 반환
+     */
+    public TrendAnalysis getDefaultTrendAnalysis(String industry, String region) {
+        log.info("Fallback: 기본 트렌드 분석 결과 반환 - industry={}, region={}", industry, region);
+
+        List<TrendAnalysis.TrendKeyword> industryTrends = List.of(
+                TrendAnalysis.TrendKeyword.builder()
+                        .keyword("고객 만족도 향상")
+                        .relevance(0.8)
+                        .description(industry + " 업종에서 고객 만족도가 중요한 트렌드입니다")
+                        .build(),
+                TrendAnalysis.TrendKeyword.builder()
+                        .keyword("디지털 마케팅")
+                        .relevance(0.75)
+                        .description("SNS 및 온라인 마케팅이 효과적입니다")
+                        .build()
+        );
+
+        List<TrendAnalysis.TrendKeyword> regionalTrends = List.of(
+                TrendAnalysis.TrendKeyword.builder()
+                        .keyword("지역 커뮤니티")
+                        .relevance(0.7)
+                        .description(region + " 지역 커뮤니티 참여가 효과적입니다")
+                        .build()
+        );
+
+        List<TrendAnalysis.TrendKeyword> seasonalTrends = List.of(
+                TrendAnalysis.TrendKeyword.builder()
+                        .keyword("시즌 이벤트")
+                        .relevance(0.85)
+                        .description("계절 특성을 반영한 이벤트가 효과적입니다")
+                        .build()
+        );
+
+        return TrendAnalysis.builder()
+                .industryTrends(industryTrends)
+                .regionalTrends(regionalTrends)
+                .seasonalTrends(seasonalTrends)
+                .build();
+    }
+
+    /**
+     * 기본 이벤트 추천안 반환
+     */
+    public List<EventRecommendation> getDefaultRecommendations(String objective, String industry) {
+        log.info("Fallback: 기본 이벤트 추천안 반환 - objective={}, industry={}", objective, industry);
+
+        List<EventRecommendation> recommendations = new ArrayList<>();
+
+        // 옵션 1: 저비용 이벤트
+        recommendations.add(createDefaultRecommendation(1, "저비용 SNS 이벤트", objective, industry, 100000, 200000));
+
+        // 옵션 2: 중비용 이벤트
+        recommendations.add(createDefaultRecommendation(2, "중비용 방문 유도 이벤트", objective, industry, 300000, 500000));
+
+        // 옵션 3: 고비용 이벤트
+        recommendations.add(createDefaultRecommendation(3, "고비용 프리미엄 이벤트", objective, industry, 500000, 1000000));
+
+        return recommendations;
+    }
+
+    /**
+     * 기본 추천안 생성
+     */
+    private EventRecommendation createDefaultRecommendation(
+            int optionNumber,
+            String concept,
+            String objective,
+            String industry,
+            int minCost,
+            int maxCost
+    ) {
+        return EventRecommendation.builder()
+                .optionNumber(optionNumber)
+                .concept(concept)
+                .title(objective + " - " + concept)
+                .description("AI 서비스가 일시적으로 사용 불가능하여 기본 추천안을 제공합니다. " +
+                        industry + " 업종에 적합한 " + concept + "입니다.")
+                .targetAudience("일반 고객")
+                .duration(EventRecommendation.Duration.builder()
+                        .recommendedDays(14)
+                        .recommendedPeriod("2주")
+                        .build())
+                .mechanics(EventRecommendation.Mechanics.builder()
+                        .type(EventMechanicsType.DISCOUNT)
+                        .details("할인 쿠폰 제공 또는 경품 추첨")
+                        .build())
+                .promotionChannels(List.of("Instagram", "네이버 블로그", "카카오톡 채널"))
+                .estimatedCost(EventRecommendation.EstimatedCost.builder()
+                        .min(minCost)
+                        .max(maxCost)
+                        .breakdown(Map.of(
+                                "경품비", minCost / 2,
+                                "홍보비", minCost / 2
+                        ))
+                        .build())
+                .expectedMetrics(ExpectedMetrics.builder()
+                        .newCustomers(ExpectedMetrics.Range.builder().min(30.0).max(50.0).build())
+                        .revenueIncrease(ExpectedMetrics.Range.builder().min(10.0).max(20.0).build())
+                        .roi(ExpectedMetrics.Range.builder().min(100.0).max(150.0).build())
+                        .build())
+                .differentiator("AI 분석이 제한적으로 제공되는 기본 추천안입니다")
+                .build();
+    }
+}

ai-service/src/main/java/com/kt/ai/client/ClaudeApiClient.java

@@ -0,0 +1,40 @@
+package com.kt.ai.client;
+
+import com.kt.ai.client.config.FeignClientConfig;
+import com.kt.ai.client.dto.ClaudeRequest;
+import com.kt.ai.client.dto.ClaudeResponse;
+import org.springframework.cloud.openfeign.FeignClient;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestHeader;
+
+/**
+ * Claude API Feign Client
+ * API Docs: https://docs.anthropic.com/claude/reference/messages_post
+ *
+ * @author AI Service Team
+ * @since 1.0.0
+ */
+@FeignClient(
+        name = "claudeApiClient",
+        url = "${ai.claude.api-url}",
+        configuration = FeignClientConfig.class
+)
+public interface ClaudeApiClient {
+
+    /**
+     * Claude Messages API 호출
+     *
+     * @param apiKey Claude API Key
+     * @param anthropicVersion API Version (2023-06-01)
+     * @param request Claude 요청
+     * @return Claude 응답
+     */
+    @PostMapping
+    ClaudeResponse sendMessage(
+            @RequestHeader("x-api-key") String apiKey,
+            @RequestHeader("anthropic-version") String anthropicVersion,
+            @RequestHeader("content-type") String contentType,
+            @RequestBody ClaudeRequest request
+    );
+}

ai-service/src/main/java/com/kt/ai/client/config/FeignClientConfig.java

@@ -0,0 +1,57 @@
+package com.kt.ai.client.config;
+
+import feign.Logger;
+import feign.Request;
+import feign.Retryer;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+import java.util.concurrent.TimeUnit;
+
+/**
+ * Feign Client 설정
+ * - Claude API / GPT-4 API 연동 설정
+ * - Timeout, Retry 설정
+ *
+ * @author AI Service Team
+ * @since 1.0.0
+ */
+@Configuration
+public class FeignClientConfig {
+
+    /**
+     * Feign Logger Level 설정
+     */
+    @Bean
+    public Logger.Level feignLoggerLevel() {
+        return Logger.Level.FULL;
+    }
+
+    /**
+     * Feign Request Options (Timeout 설정)
+     * - Connect Timeout: 10초
+     * - Read Timeout: 5분 (300초)
+     */
+    @Bean
+    public Request.Options requestOptions() {
+        return new Request.Options(
+                10, TimeUnit.SECONDS,  // connectTimeout
+                300, TimeUnit.SECONDS, // readTimeout (5분)
+                true                    // followRedirects
+        );
+    }
+
+    /**
+     * Feign Retryer 설정
+     * - 최대 3회 재시도
+     * - Exponential Backoff: 1초, 5초, 10초
+     */
+    @Bean
+    public Retryer retryer() {
+        return new Retryer.Default(
+                1000L,    // period (1초)
+                5000L,    // maxPeriod (5초)
+                3         // maxAttempts (3회)
+        );
+    }
+}

ai-service/src/main/java/com/kt/ai/client/dto/ClaudeRequest.java

@@ -0,0 +1,67 @@
+package com.kt.ai.client.dto;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+import java.util.List;
+
+/**
+ * Claude API 요청 DTO
+ * API Docs: https://docs.anthropic.com/claude/reference/messages_post
+ *
+ * @author AI Service Team
+ * @since 1.0.0
+ */
+@Data
+@Builder
+@NoArgsConstructor
+@AllArgsConstructor
+public class ClaudeRequest {
+    /**
+     * 모델명 (예: claude-3-5-sonnet-20241022)
+     */
+    private String model;
+
+    /**
+     * 메시지 목록
+     */
+    private List<Message> messages;
+
+    /**
+     * 최대 토큰 수
+     */
+    @JsonProperty("max_tokens")
+    private Integer maxTokens;
+
+    /**
+     * Temperature (0.0 ~ 1.0)
+     */
+    private Double temperature;
+
+    /**
+     * System 프롬프트 (선택)
+     */
+    private String system;
+
+    /**
+     * 메시지
+     */
+    @Data
+    @Builder
+    @NoArgsConstructor
+    @AllArgsConstructor
+    public static class Message {
+        /**
+         * 역할 (user, assistant)
+         */
+        private String role;
+
+        /**
+         * 메시지 내용
+         */
+        private String content;
+    }
+}

ai-service/src/main/java/com/kt/ai/client/dto/ClaudeResponse.java

@@ -0,0 +1,108 @@
+package com.kt.ai.client.dto;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+import java.util.List;
+
+/**
+ * Claude API 응답 DTO
+ * API Docs: https://docs.anthropic.com/claude/reference/messages_post
+ *
+ * @author AI Service Team
+ * @since 1.0.0
+ */
+@Data
+@Builder
+@NoArgsConstructor
+@AllArgsConstructor
+public class ClaudeResponse {
+    /**
+     * 응답 ID
+     */
+    private String id;
+
+    /**
+     * 타입 (message)
+     */
+    private String type;
+
+    /**
+     * 역할 (assistant)
+     */
+    private String role;
+
+    /**
+     * 콘텐츠 목록
+     */
+    private List<Content> content;
+
+    /**
+     * 모델명
+     */
+    private String model;
+
+    /**
+     * 중단 이유 (end_turn, max_tokens, stop_sequence)
+     */
+    @JsonProperty("stop_reason")
+    private String stopReason;
+
+    /**
+     * 사용량
+     */
+    private Usage usage;
+
+    /**
+     * 콘텐츠
+     */
+    @Data
+    @Builder
+    @NoArgsConstructor
+    @AllArgsConstructor
+    public static class Content {
+        /**
+         * 타입 (text)
+         */
+        private String type;
+
+        /**
+         * 텍스트 내용
+         */
+        private String text;
+    }
+
+    /**
+     * 토큰 사용량
+     */
+    @Data
+    @Builder
+    @NoArgsConstructor
+    @AllArgsConstructor
+    public static class Usage {
+        /**
+         * 입력 토큰 수
+         */
+        @JsonProperty("input_tokens")
+        private Integer inputTokens;
+
+        /**
+         * 출력 토큰 수
+         */
+        @JsonProperty("output_tokens")
+        private Integer outputTokens;
+    }
+
+    /**
+     * 텍스트 내용 추출
+     */
+    public String extractText() {
+        if (content != null && !content.isEmpty()) {
+            return content.get(0).getText();
+        }
+        return null;
+    }
+}

ai-service/src/main/java/com/kt/ai/config/CircuitBreakerConfig.java

@@ -0,0 +1,71 @@
+package com.kt.ai.config;
+
+import io.github.resilience4j.circuitbreaker.CircuitBreaker;
+import io.github.resilience4j.circuitbreaker.CircuitBreakerConfig.SlidingWindowType;
+import io.github.resilience4j.circuitbreaker.CircuitBreakerRegistry;
+import io.github.resilience4j.timelimiter.TimeLimiterConfig;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+import java.time.Duration;
+
+/**
+ * Circuit Breaker 설정
+ * - Claude API / GPT-4 API 장애 대응
+ * - Timeout: 5분 (300초)
+ * - Failure Threshold: 50%
+ *
+ * @author AI Service Team
+ * @since 1.0.0
+ */
+@Configuration
+public class CircuitBreakerConfig {
+
+    /**
+     * Circuit Breaker Registry 설정
+     */
+    @Bean
+    public CircuitBreakerRegistry circuitBreakerRegistry() {
+        io.github.resilience4j.circuitbreaker.CircuitBreakerConfig config =
+                io.github.resilience4j.circuitbreaker.CircuitBreakerConfig.custom()
+                        .failureRateThreshold(50)
+                        .slowCallRateThreshold(50)
+                        .slowCallDurationThreshold(Duration.ofSeconds(60))
+                        .permittedNumberOfCallsInHalfOpenState(3)
+                        .maxWaitDurationInHalfOpenState(Duration.ZERO)
+                        .slidingWindowType(SlidingWindowType.COUNT_BASED)
+                        .slidingWindowSize(10)
+                        .minimumNumberOfCalls(5)
+                        .waitDurationInOpenState(Duration.ofSeconds(60))
+                        .automaticTransitionFromOpenToHalfOpenEnabled(true)
+                        .build();
+
+        return CircuitBreakerRegistry.of(config);
+    }
+
+    /**
+     * Claude API Circuit Breaker
+     */
+    @Bean
+    public CircuitBreaker claudeApiCircuitBreaker(CircuitBreakerRegistry registry) {
+        return registry.circuitBreaker("claudeApi");
+    }
+
+    /**
+     * GPT-4 API Circuit Breaker
+     */
+    @Bean
+    public CircuitBreaker gpt4ApiCircuitBreaker(CircuitBreakerRegistry registry) {
+        return registry.circuitBreaker("gpt4Api");
+    }
+
+    /**
+     * Time Limiter 설정 (5분)
+     */
+    @Bean
+    public TimeLimiterConfig timeLimiterConfig() {
+        return TimeLimiterConfig.custom()
+                .timeoutDuration(Duration.ofSeconds(300))
+                .build();
+    }
+}

ai-service/src/main/java/com/kt/ai/config/JacksonConfig.java

@@ -0,0 +1,25 @@
+package com.kt.ai.config;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.SerializationFeature;
+import com.fasterxml.jackson.datatype.jsr310.JavaTimeModule;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+/**
+ * Jackson ObjectMapper 설정
+ *
+ * @author AI Service Team
+ * @since 1.0.0
+ */
+@Configuration
+public class JacksonConfig {
+
+    @Bean
+    public ObjectMapper objectMapper() {
+        ObjectMapper mapper = new ObjectMapper();
+        mapper.registerModule(new JavaTimeModule());
+        mapper.disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS);
+        return mapper;
+    }
+}

ai-service/src/main/java/com/kt/ai/config/KafkaConsumerConfig.java

@@ -0,0 +1,76 @@
+package com.kt.ai.config;
+
+import com.kt.ai.kafka.message.AIJobMessage;
+import org.apache.kafka.clients.consumer.ConsumerConfig;
+import org.apache.kafka.common.serialization.StringDeserializer;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.kafka.annotation.EnableKafka;
+import org.springframework.kafka.config.ConcurrentKafkaListenerContainerFactory;
+import org.springframework.kafka.core.ConsumerFactory;
+import org.springframework.kafka.core.DefaultKafkaConsumerFactory;
+import org.springframework.kafka.listener.ContainerProperties;
+import org.springframework.kafka.support.serializer.ErrorHandlingDeserializer;
+import org.springframework.kafka.support.serializer.JsonDeserializer;
+
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ * Kafka Consumer 설정
+ * - Topic: ai-event-generation-job
+ * - Consumer Group: ai-service-consumers
+ * - Manual ACK 모드
+ *
+ * @author AI Service Team
+ * @since 1.0.0
+ */
+@EnableKafka
+@Configuration
+public class KafkaConsumerConfig {
+
+    @Value("${spring.kafka.bootstrap-servers}")
+    private String bootstrapServers;
+
+    @Value("${spring.kafka.consumer.group-id}")
+    private String groupId;
+
+    /**
+     * Kafka Consumer 팩토리 설정
+     */
+    @Bean
+    public ConsumerFactory<String, AIJobMessage> consumerFactory() {
+        Map<String, Object> props = new HashMap<>();
+        props.put(ConsumerConfig.BOOTSTRAP_SERVERS_CONFIG, bootstrapServers);
+        props.put(ConsumerConfig.GROUP_ID_CONFIG, groupId);
+        props.put(ConsumerConfig.AUTO_OFFSET_RESET_CONFIG, "earliest");
+        props.put(ConsumerConfig.ENABLE_AUTO_COMMIT_CONFIG, false);
+        props.put(ConsumerConfig.MAX_POLL_RECORDS_CONFIG, 10);
+        props.put(ConsumerConfig.SESSION_TIMEOUT_MS_CONFIG, 30000);
+
+        // Key Deserializer
+        props.put(ConsumerConfig.KEY_DESERIALIZER_CLASS_CONFIG, StringDeserializer.class);
+
+        // Value Deserializer with Error Handling
+        props.put(ConsumerConfig.VALUE_DESERIALIZER_CLASS_CONFIG, ErrorHandlingDeserializer.class);
+        props.put(ErrorHandlingDeserializer.VALUE_DESERIALIZER_CLASS, JsonDeserializer.class.getName());
+        props.put(JsonDeserializer.VALUE_DEFAULT_TYPE, AIJobMessage.class.getName());
+        props.put(JsonDeserializer.TRUSTED_PACKAGES, "*");
+
+        return new DefaultKafkaConsumerFactory<>(props);
+    }
+
+    /**
+     * Kafka Listener Container Factory 설정
+     * - Manual ACK 모드
+     */
+    @Bean
+    public ConcurrentKafkaListenerContainerFactory<String, AIJobMessage> kafkaListenerContainerFactory() {
+        ConcurrentKafkaListenerContainerFactory<String, AIJobMessage> factory =
+                new ConcurrentKafkaListenerContainerFactory<>();
+        factory.setConsumerFactory(consumerFactory());
+        factory.getContainerProperties().setAckMode(ContainerProperties.AckMode.MANUAL);
+        return factory;
+    }
+}

ai-service/src/main/java/com/kt/ai/config/RedisConfig.java

@@ -0,0 +1,73 @@
+package com.kt.ai.config;
+
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.data.redis.connection.RedisConnectionFactory;
+import org.springframework.data.redis.connection.RedisStandaloneConfiguration;
+import org.springframework.data.redis.connection.lettuce.LettuceConnectionFactory;
+import org.springframework.data.redis.core.RedisTemplate;
+import org.springframework.data.redis.serializer.GenericJackson2JsonRedisSerializer;
+import org.springframework.data.redis.serializer.StringRedisSerializer;
+
+/**
+ * Redis 설정
+ * - 작업 상태 및 추천 결과 캐싱
+ * - TTL: 추천 24시간, Job 상태 24시간, 트렌드 1시간
+ *
+ * @author AI Service Team
+ * @since 1.0.0
+ */
+@Configuration
+public class RedisConfig {
+
+    @Value("${spring.data.redis.host}")
+    private String redisHost;
+
+    @Value("${spring.data.redis.port}")
+    private int redisPort;
+
+    @Value("${spring.data.redis.password}")
+    private String redisPassword;
+
+    @Value("${spring.data.redis.database}")
+    private int redisDatabase;
+
+    /**
+     * Redis 연결 팩토리 설정
+     */
+    @Bean
+    public RedisConnectionFactory redisConnectionFactory() {
+        RedisStandaloneConfiguration config = new RedisStandaloneConfiguration();
+        config.setHostName(redisHost);
+        config.setPort(redisPort);
+        if (redisPassword != null && !redisPassword.isEmpty()) {
+            config.setPassword(redisPassword);
+        }
+        config.setDatabase(redisDatabase);
+
+        return new LettuceConnectionFactory(config);
+    }
+
+    /**
+     * RedisTemplate 설정
+     * - Key: String
+     * - Value: JSON (Jackson)
+     */
+    @Bean
+    public RedisTemplate<String, Object> redisTemplate(RedisConnectionFactory connectionFactory) {
+        RedisTemplate<String, Object> template = new RedisTemplate<>();
+        template.setConnectionFactory(connectionFactory);
+
+        // Key Serializer: String
+        template.setKeySerializer(new StringRedisSerializer());
+        template.setHashKeySerializer(new StringRedisSerializer());
+
+        // Value Serializer: JSON
+        template.setValueSerializer(new GenericJackson2JsonRedisSerializer());
+        template.setHashValueSerializer(new GenericJackson2JsonRedisSerializer());
+
+        template.afterPropertiesSet();
+        return template;
+    }
+}

ai-service/src/main/java/com/kt/ai/config/SecurityConfig.java

@@ -0,0 +1,67 @@
+package com.kt.ai.config;
+
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.security.config.annotation.web.builders.HttpSecurity;
+import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
+import org.springframework.security.config.annotation.web.configurers.AbstractHttpConfigurer;
+import org.springframework.security.config.http.SessionCreationPolicy;
+import org.springframework.security.web.SecurityFilterChain;
+import org.springframework.web.cors.CorsConfiguration;
+import org.springframework.web.cors.CorsConfigurationSource;
+import org.springframework.web.cors.UrlBasedCorsConfigurationSource;
+
+import java.util.Arrays;
+import java.util.List;
+
+/**
+ * Spring Security 설정
+ * - Internal API만 제공 (Event Service에서만 호출)
+ * - JWT 인증 없음 (내부 통신)
+ * - CORS 설정
+ *
+ * @author AI Service Team
+ * @since 1.0.0
+ */
+@Configuration
+@EnableWebSecurity
+public class SecurityConfig {
+
+    /**
+     * Security Filter Chain 설정
+     * - 모든 요청 허용 (내부 API)
+     * - CSRF 비활성화
+     * - Stateless 세션
+     */
+    @Bean
+    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
+        http
+                .csrf(AbstractHttpConfigurer::disable)
+                .cors(cors -> cors.configurationSource(corsConfigurationSource()))
+                .sessionManagement(session -> session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
+                .authorizeHttpRequests(auth -> auth
+                        .requestMatchers("/health", "/actuator/**", "/v3/api-docs/**", "/swagger-ui/**").permitAll()
+                        .requestMatchers("/internal/**").permitAll()  // Internal API
+                        .anyRequest().permitAll()
+                );
+
+        return http.build();
+    }
+
+    /**
+     * CORS 설정
+     */
+    @Bean
+    public CorsConfigurationSource corsConfigurationSource() {
+        CorsConfiguration configuration = new CorsConfiguration();
+        configuration.setAllowedOrigins(Arrays.asList("http://localhost:3000", "http://localhost:8080"));
+        configuration.setAllowedMethods(Arrays.asList("GET", "POST", "PUT", "DELETE", "OPTIONS", "PATCH"));
+        configuration.setAllowedHeaders(List.of("*"));
+        configuration.setAllowCredentials(true);
+        configuration.setMaxAge(3600L);
+
+        UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
+        source.registerCorsConfiguration("/**", configuration);
+        return source;
+    }
+}

ai-service/src/main/java/com/kt/ai/config/SwaggerConfig.java

@@ -0,0 +1,64 @@
+package com.kt.ai.config;
+
+import io.swagger.v3.oas.models.OpenAPI;
+import io.swagger.v3.oas.models.info.Contact;
+import io.swagger.v3.oas.models.info.Info;
+import io.swagger.v3.oas.models.servers.Server;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+import java.util.List;
+
+/**
+ * Swagger/OpenAPI 설정
+ *
+ * @author AI Service Team
+ * @since 1.0.0
+ */
+@Configuration
+public class SwaggerConfig {
+
+    @Bean
+    public OpenAPI openAPI() {
+        Server localServer = new Server();
+        localServer.setUrl("http://localhost:8083");
+        localServer.setDescription("Local Development Server");
+
+        Server devServer = new Server();
+        devServer.setUrl("https://dev-api.kt-event-marketing.com/ai/v1");
+        devServer.setDescription("Development Server");
+
+        Server prodServer = new Server();
+        prodServer.setUrl("https://api.kt-event-marketing.com/ai/v1");
+        prodServer.setDescription("Production Server");
+
+        Contact contact = new Contact();
+        contact.setName("Digital Garage Team");
+        contact.setEmail("support@kt-event-marketing.com");
+
+        Info info = new Info()
+                .title("AI Service API")
+                .version("1.0.0")
+                .description("""
+                        KT AI 기반 소상공인 이벤트 자동 생성 서비스 - AI Service
+
+                        ## 서비스 개요
+                        - Kafka를 통한 비동기 AI 추천 처리
+                        - Claude API / GPT-4 API 연동
+                        - Redis 기반 결과 캐싱 (TTL 24시간)
+
+                        ## 처리 흐름
+                        1. Event Service가 Kafka Topic에 Job 메시지 발행
+                        2. AI Service가 메시지 구독 및 처리
+                        3. 트렌드 분석 수행 (Claude/GPT-4 API)
+                        4. 3가지 이벤트 추천안 생성
+                        5. 결과를 Redis에 저장 (TTL 24시간)
+                        6. Job 상태를 Redis에 업데이트
+                        """)
+                .contact(contact);
+
+        return new OpenAPI()
+                .info(info)
+                .servers(List.of(localServer, devServer, prodServer));
+    }
+}

ai-service/src/main/java/com/kt/ai/controller/HealthController.java

@@ -0,0 +1,72 @@
+package com.kt.ai.controller;
+
+import com.kt.ai.model.dto.response.HealthCheckResponse;
+import com.kt.ai.model.enums.CircuitBreakerState;
+import com.kt.ai.model.enums.ServiceStatus;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.data.redis.core.RedisTemplate;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.time.LocalDateTime;
+
+/**
+ * 헬스체크 Controller
+ *
+ * @author AI Service Team
+ * @since 1.0.0
+ */
+@Slf4j
+@Tag(name = "Health Check", description = "서비스 상태 확인")
+@RestController
+@RequiredArgsConstructor
+public class HealthController {
+
+    private final RedisTemplate<String, Object> redisTemplate;
+
+    /**
+     * 서비스 헬스체크
+     */
+    @Operation(summary = "서비스 헬스체크", description = "AI Service 상태 및 외부 연동 확인")
+    @GetMapping("/health")
+    public ResponseEntity<HealthCheckResponse> healthCheck() {
+        // Redis 상태 확인
+        ServiceStatus redisStatus = checkRedis();
+
+        // 전체 서비스 상태
+        ServiceStatus overallStatus = (redisStatus == ServiceStatus.UP) ? ServiceStatus.UP : ServiceStatus.DEGRADED;
+
+        HealthCheckResponse.Services services = HealthCheckResponse.Services.builder()
+                .kafka(ServiceStatus.UP)  // TODO: 실제 Kafka 상태 확인
+                .redis(redisStatus)
+                .claudeApi(ServiceStatus.UP)  // TODO: 실제 Claude API 상태 확인
+                .gpt4Api(ServiceStatus.UP)  // TODO: 실제 GPT-4 API 상태 확인 (선택)
+                .circuitBreaker(CircuitBreakerState.CLOSED)  // TODO: 실제 Circuit Breaker 상태 확인
+                .build();
+
+        HealthCheckResponse response = HealthCheckResponse.builder()
+                .status(overallStatus)
+                .timestamp(LocalDateTime.now())
+                .services(services)
+                .build();
+
+        return ResponseEntity.ok(response);
+    }
+
+    /**
+     * Redis 연결 상태 확인
+     */
+    private ServiceStatus checkRedis() {
+        try {
+            redisTemplate.getConnectionFactory().getConnection().ping();
+            return ServiceStatus.UP;
+        } catch (Exception e) {
+            log.error("Redis 연결 실패", e);
+            return ServiceStatus.DOWN;
+        }
+    }
+}

ai-service/src/main/java/com/kt/ai/controller/InternalJobController.java

@@ -0,0 +1,41 @@
+package com.kt.ai.controller;
+
+import com.kt.ai.model.dto.response.JobStatusResponse;
+import com.kt.ai.service.JobStatusService;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+/**
+ * Internal Job Controller
+ * Event Service에서 호출하는 내부 API
+ *
+ * @author AI Service Team
+ * @since 1.0.0
+ */
+@Slf4j
+@Tag(name = "Internal API", description = "내부 서비스 간 통신용 API")
+@RestController
+@RequestMapping("/internal/jobs")
+@RequiredArgsConstructor
+public class InternalJobController {
+
+    private final JobStatusService jobStatusService;
+
+    /**
+     * 작업 상태 조회
+     */
+    @Operation(summary = "작업 상태 조회", description = "Redis에 저장된 AI 추천 작업 상태 조회")
+    @GetMapping("/{jobId}/status")
+    public ResponseEntity<JobStatusResponse> getJobStatus(@PathVariable String jobId) {
+        log.info("Job 상태 조회 요청: jobId={}", jobId);
+        JobStatusResponse response = jobStatusService.getJobStatus(jobId);
+        return ResponseEntity.ok(response);
+    }
+}

ai-service/src/main/java/com/kt/ai/controller/InternalRecommendationController.java

@@ -0,0 +1,41 @@
+package com.kt.ai.controller;
+
+import com.kt.ai.model.dto.response.AIRecommendationResult;
+import com.kt.ai.service.AIRecommendationService;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+/**
+ * Internal Recommendation Controller
+ * Event Service에서 호출하는 내부 API
+ *
+ * @author AI Service Team
+ * @since 1.0.0
+ */
+@Slf4j
+@Tag(name = "Internal API", description = "내부 서비스 간 통신용 API")
+@RestController
+@RequestMapping("/internal/recommendations")
+@RequiredArgsConstructor
+public class InternalRecommendationController {
+
+    private final AIRecommendationService aiRecommendationService;
+
+    /**
+     * AI 추천 결과 조회
+     */
+    @Operation(summary = "AI 추천 결과 조회", description = "Redis에 캐시된 AI 추천 결과 조회")
+    @GetMapping("/{eventId}")
+    public ResponseEntity<AIRecommendationResult> getRecommendation(@PathVariable String eventId) {
+        log.info("AI 추천 결과 조회 요청: eventId={}", eventId);
+        AIRecommendationResult response = aiRecommendationService.getRecommendation(eventId);
+        return ResponseEntity.ok(response);
+    }
+}

ai-service/src/main/java/com/kt/ai/exception/AIServiceException.java

@@ -0,0 +1,25 @@
+package com.kt.ai.exception;
+
+/**
+ * AI Service 공통 예외
+ *
+ * @author AI Service Team
+ * @since 1.0.0
+ */
+public class AIServiceException extends RuntimeException {
+    private final String errorCode;
+
+    public AIServiceException(String errorCode, String message) {
+        super(message);
+        this.errorCode = errorCode;
+    }
+
+    public AIServiceException(String errorCode, String message, Throwable cause) {
+        super(message, cause);
+        this.errorCode = errorCode;
+    }
+
+    public String getErrorCode() {
+        return errorCode;
+    }
+}

ai-service/src/main/java/com/kt/ai/exception/CircuitBreakerOpenException.java

@@ -0,0 +1,13 @@
+package com.kt.ai.exception;
+
+/**
+ * Circuit Breaker가 열린 상태 예외
+ *
+ * @author AI Service Team
+ * @since 1.0.0
+ */
+public class CircuitBreakerOpenException extends AIServiceException {
+    public CircuitBreakerOpenException(String apiName) {
+        super("CIRCUIT_BREAKER_OPEN", "Circuit Breaker가 열린 상태입니다: " + apiName);
+    }
+}

ai-service/src/main/java/com/kt/ai/exception/GlobalExceptionHandler.java

@@ -0,0 +1,107 @@
+package com.kt.ai.exception;
+
+import com.kt.ai.model.dto.response.ErrorResponse;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.ExceptionHandler;
+import org.springframework.web.bind.annotation.RestControllerAdvice;
+
+import java.time.LocalDateTime;
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ * 전역 예외 처리 핸들러
+ *
+ * @author AI Service Team
+ * @since 1.0.0
+ */
+@Slf4j
+@RestControllerAdvice
+public class GlobalExceptionHandler {
+
+    /**
+     * Job을 찾을 수 없는 예외 처리
+     */
+    @ExceptionHandler(JobNotFoundException.class)
+    public ResponseEntity<ErrorResponse> handleJobNotFoundException(JobNotFoundException ex) {
+        log.error("Job not found: {}", ex.getMessage());
+
+        ErrorResponse error = ErrorResponse.builder()
+                .code(ex.getErrorCode())
+                .message(ex.getMessage())
+                .timestamp(LocalDateTime.now())
+                .build();
+
+        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(error);
+    }
+
+    /**
+     * 추천 결과를 찾을 수 없는 예외 처리
+     */
+    @ExceptionHandler(RecommendationNotFoundException.class)
+    public ResponseEntity<ErrorResponse> handleRecommendationNotFoundException(RecommendationNotFoundException ex) {
+        log.error("Recommendation not found: {}", ex.getMessage());
+
+        ErrorResponse error = ErrorResponse.builder()
+                .code(ex.getErrorCode())
+                .message(ex.getMessage())
+                .timestamp(LocalDateTime.now())
+                .build();
+
+        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(error);
+    }
+
+    /**
+     * Circuit Breaker가 열린 상태 예외 처리
+     */
+    @ExceptionHandler(CircuitBreakerOpenException.class)
+    public ResponseEntity<ErrorResponse> handleCircuitBreakerOpenException(CircuitBreakerOpenException ex) {
+        log.error("Circuit breaker open: {}", ex.getMessage());
+
+        Map<String, Object> details = new HashMap<>();
+        details.put("message", "외부 AI API가 일시적으로 사용 불가능합니다. 잠시 후 다시 시도해주세요.");
+
+        ErrorResponse error = ErrorResponse.builder()
+                .code(ex.getErrorCode())
+                .message(ex.getMessage())
+                .timestamp(LocalDateTime.now())
+                .details(details)
+                .build();
+
+        return ResponseEntity.status(HttpStatus.SERVICE_UNAVAILABLE).body(error);
+    }
+
+    /**
+     * AI Service 공통 예외 처리
+     */
+    @ExceptionHandler(AIServiceException.class)
+    public ResponseEntity<ErrorResponse> handleAIServiceException(AIServiceException ex) {
+        log.error("AI Service error: {}", ex.getMessage(), ex);
+
+        ErrorResponse error = ErrorResponse.builder()
+                .code(ex.getErrorCode())
+                .message(ex.getMessage())
+                .timestamp(LocalDateTime.now())
+                .build();
+
+        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(error);
+    }
+
+    /**
+     * 일반 예외 처리
+     */
+    @ExceptionHandler(Exception.class)
+    public ResponseEntity<ErrorResponse> handleException(Exception ex) {
+        log.error("Unexpected error: {}", ex.getMessage(), ex);
+
+        ErrorResponse error = ErrorResponse.builder()
+                .code("INTERNAL_ERROR")
+                .message("서버 내부 오류가 발생했습니다")
+                .timestamp(LocalDateTime.now())
+                .build();
+
+        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(error);
+    }
+}

ai-service/src/main/java/com/kt/ai/exception/JobNotFoundException.java

@@ -0,0 +1,13 @@
+package com.kt.ai.exception;
+
+/**
+ * Job을 찾을 수 없는 예외
+ *
+ * @author AI Service Team
+ * @since 1.0.0
+ */
+public class JobNotFoundException extends AIServiceException {
+    public JobNotFoundException(String jobId) {
+        super("JOB_NOT_FOUND", "작업을 찾을 수 없습니다: " + jobId);
+    }
+}

ai-service/src/main/java/com/kt/ai/exception/RecommendationNotFoundException.java

@@ -0,0 +1,13 @@
+package com.kt.ai.exception;
+
+/**
+ * 추천 결과를 찾을 수 없는 예외
+ *
+ * @author AI Service Team
+ * @since 1.0.0
+ */
+public class RecommendationNotFoundException extends AIServiceException {
+    public RecommendationNotFoundException(String eventId) {
+        super("RECOMMENDATION_NOT_FOUND", "추천 결과를 찾을 수 없습니다: " + eventId);
+    }
+}

ai-service/src/main/java/com/kt/ai/kafka/consumer/AIJobConsumer.java

@@ -0,0 +1,60 @@
+package com.kt.ai.kafka.consumer;
+
+import com.kt.ai.kafka.message.AIJobMessage;
+import com.kt.ai.service.AIRecommendationService;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.kafka.annotation.KafkaListener;
+import org.springframework.kafka.support.Acknowledgment;
+import org.springframework.kafka.support.KafkaHeaders;
+import org.springframework.messaging.handler.annotation.Header;
+import org.springframework.messaging.handler.annotation.Payload;
+import org.springframework.stereotype.Component;
+
+/**
+ * AI Job Kafka Consumer
+ * - Topic: ai-event-generation-job
+ * - Consumer Group: ai-service-consumers
+ *
+ * @author AI Service Team
+ * @since 1.0.0
+ */
+@Slf4j
+@Component
+@RequiredArgsConstructor
+public class AIJobConsumer {
+
+    private final AIRecommendationService aiRecommendationService;
+
+    /**
+     * Kafka 메시지 수신 및 처리
+     */
+    @KafkaListener(
+            topics = "${kafka.topics.ai-job}",
+            groupId = "${spring.kafka.consumer.group-id}",
+            containerFactory = "kafkaListenerContainerFactory"
+    )
+    public void consume(
+            @Payload AIJobMessage message,
+            @Header(KafkaHeaders.RECEIVED_TOPIC) String topic,
+            @Header(KafkaHeaders.OFFSET) Long offset,
+            Acknowledgment acknowledgment
+    ) {
+        try {
+            log.info("Kafka 메시지 수신: topic={}, offset={}, jobId={}, eventId={}",
+                    topic, offset, message.getJobId(), message.getEventId());
+
+            // AI 추천 생성
+            aiRecommendationService.generateRecommendations(message);
+
+            // Manual ACK
+            acknowledgment.acknowledge();
+            log.info("Kafka 메시지 처리 완료: jobId={}", message.getJobId());
+
+        } catch (Exception e) {
+            log.error("Kafka 메시지 처리 실패: jobId={}", message.getJobId(), e);
+            // DLQ로 이동하거나 재시도 로직 추가 가능
+            acknowledgment.acknowledge();  // 실패한 메시지도 ACK (DLQ로 이동)
+        }
+    }
+}

ai-service/src/main/java/com/kt/ai/kafka/message/AIJobMessage.java

@@ -0,0 +1,71 @@
+package com.kt.ai.kafka.message;
+
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+import java.time.LocalDateTime;
+
+/**
+ * AI 이벤트 생성 요청 메시지 (Kafka)
+ * Topic: ai-event-generation-job
+ * Consumer Group: ai-service-consumers
+ *
+ * @author AI Service Team
+ * @since 1.0.0
+ */
+@Data
+@Builder
+@NoArgsConstructor
+@AllArgsConstructor
+public class AIJobMessage {
+    /**
+     * Job 고유 ID
+     */
+    private String jobId;
+
+    /**
+     * 이벤트 ID (Event Service에서 생성)
+     */
+    private String eventId;
+
+    /**
+     * 이벤트 목적
+     * - "신규 고객 유치"
+     * - "재방문 유도"
+     * - "매출 증대"
+     * - "브랜드 인지도 향상"
+     */
+    private String objective;
+
+    /**
+     * 업종
+     */
+    private String industry;
+
+    /**
+     * 지역 (시/구/동)
+     */
+    private String region;
+
+    /**
+     * 매장명 (선택)
+     */
+    private String storeName;
+
+    /**
+     * 목표 고객층 (선택)
+     */
+    private String targetAudience;
+
+    /**
+     * 예산 (원) (선택)
+     */
+    private Integer budget;
+
+    /**
+     * 요청 시각
+     */
+    private LocalDateTime requestedAt;
+}

ai-service/src/main/java/com/kt/ai/model/dto/response/AIRecommendationResult.java

@@ -0,0 +1,54 @@
+package com.kt.ai.model.dto.response;
+
+import com.kt.ai.model.enums.AIProvider;
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+import java.time.LocalDateTime;
+import java.util.List;
+
+/**
+ * AI 이벤트 추천 결과 DTO
+ * Redis Key: ai:recommendation:{eventId}
+ * TTL: 86400초 (24시간)
+ *
+ * @author AI Service Team
+ * @since 1.0.0
+ */
+@Data
+@Builder
+@NoArgsConstructor
+@AllArgsConstructor
+public class AIRecommendationResult {
+    /**
+     * 이벤트 ID
+     */
+    private String eventId;
+
+    /**
+     * 트렌드 분석 결과
+     */
+    private TrendAnalysis trendAnalysis;
+
+    /**
+     * 추천 이벤트 기획안 (3개)
+     */
+    private List<EventRecommendation> recommendations;
+
+    /**
+     * 생성 시각
+     */
+    private LocalDateTime generatedAt;
+
+    /**
+     * 캐시 만료 시각 (생성 시각 + 24시간)
+     */
+    private LocalDateTime expiresAt;
+
+    /**
+     * 사용된 AI 제공자
+     */
+    private AIProvider aiProvider;
+}

ai-service/src/main/java/com/kt/ai/model/dto/response/ErrorResponse.java

@@ -0,0 +1,41 @@
+package com.kt.ai.model.dto.response;
+
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+import java.time.LocalDateTime;
+import java.util.Map;
+
+/**
+ * 에러 응답 DTO
+ *
+ * @author AI Service Team
+ * @since 1.0.0
+ */
+@Data
+@Builder
+@NoArgsConstructor
+@AllArgsConstructor
+public class ErrorResponse {
+    /**
+     * 에러 코드
+     */
+    private String code;
+
+    /**
+     * 에러 메시지
+     */
+    private String message;
+
+    /**
+     * 에러 발생 시각
+     */
+    private LocalDateTime timestamp;
+
+    /**
+     * 추가 에러 상세
+     */
+    private Map<String, Object> details;
+}

ai-service/src/main/java/com/kt/ai/model/dto/response/EventRecommendation.java

@@ -0,0 +1,139 @@
+package com.kt.ai.model.dto.response;
+
+import com.kt.ai.model.enums.EventMechanicsType;
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+import java.util.List;
+import java.util.Map;
+
+/**
+ * 이벤트 추천안 DTO
+ *
+ * @author AI Service Team
+ * @since 1.0.0
+ */
+@Data
+@Builder
+@NoArgsConstructor
+@AllArgsConstructor
+public class EventRecommendation {
+    /**
+     * 옵션 번호 (1-3)
+     */
+    private Integer optionNumber;
+
+    /**
+     * 이벤트 컨셉
+     */
+    private String concept;
+
+    /**
+     * 이벤트 제목
+     */
+    private String title;
+
+    /**
+     * 이벤트 설명
+     */
+    private String description;
+
+    /**
+     * 목표 고객층
+     */
+    private String targetAudience;
+
+    /**
+     * 이벤트 기간
+     */
+    private Duration duration;
+
+    /**
+     * 이벤트 메커니즘
+     */
+    private Mechanics mechanics;
+
+    /**
+     * 추천 홍보 채널 (최대 5개)
+     */
+    private List<String> promotionChannels;
+
+    /**
+     * 예상 비용
+     */
+    private EstimatedCost estimatedCost;
+
+    /**
+     * 예상 성과 지표
+     */
+    private ExpectedMetrics expectedMetrics;
+
+    /**
+     * 다른 옵션과의 차별점
+     */
+    private String differentiator;
+
+    /**
+     * 이벤트 기간
+     */
+    @Data
+    @Builder
+    @NoArgsConstructor
+    @AllArgsConstructor
+    public static class Duration {
+        /**
+         * 권장 진행 일수
+         */
+        private Integer recommendedDays;
+
+        /**
+         * 권장 진행 시기
+         */
+        private String recommendedPeriod;
+    }
+
+    /**
+     * 이벤트 메커니즘
+     */
+    @Data
+    @Builder
+    @NoArgsConstructor
+    @AllArgsConstructor
+    public static class Mechanics {
+        /**
+         * 이벤트 유형
+         */
+        private EventMechanicsType type;
+
+        /**
+         * 상세 메커니즘
+         */
+        private String details;
+    }
+
+    /**
+     * 예상 비용
+     */
+    @Data
+    @Builder
+    @NoArgsConstructor
+    @AllArgsConstructor
+    public static class EstimatedCost {
+        /**
+         * 최소 비용 (원)
+         */
+        private Integer min;
+
+        /**
+         * 최대 비용 (원)
+         */
+        private Integer max;
+
+        /**
+         * 비용 구성
+         */
+        private Map<String, Integer> breakdown;
+    }
+}

ai-service/src/main/java/com/kt/ai/model/dto/response/ExpectedMetrics.java

@@ -0,0 +1,74 @@
+package com.kt.ai.model.dto.response;
+
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+/**
+ * 예상 성과 지표 DTO
+ *
+ * @author AI Service Team
+ * @since 1.0.0
+ */
+@Data
+@Builder
+@NoArgsConstructor
+@AllArgsConstructor
+public class ExpectedMetrics {
+    /**
+     * 신규 고객 수
+     */
+    private Range newCustomers;
+
+    /**
+     * 재방문 고객 수 (선택)
+     */
+    private Range repeatVisits;
+
+    /**
+     * 매출 증가율 (%)
+     */
+    private Range revenueIncrease;
+
+    /**
+     * ROI - 투자 대비 수익률 (%)
+     */
+    private Range roi;
+
+    /**
+     * SNS 참여도 (선택)
+     */
+    private SocialEngagement socialEngagement;
+
+    /**
+     * 범위 값 (최소-최대)
+     */
+    @Data
+    @Builder
+    @NoArgsConstructor
+    @AllArgsConstructor
+    public static class Range {
+        private Double min;
+        private Double max;
+    }
+
+    /**
+     * SNS 참여도
+     */
+    @Data
+    @Builder
+    @NoArgsConstructor
+    @AllArgsConstructor
+    public static class SocialEngagement {
+        /**
+         * 예상 게시물 수
+         */
+        private Integer estimatedPosts;
+
+        /**
+         * 예상 도달 수
+         */
+        private Integer estimatedReach;
+    }
+}

ai-service/src/main/java/com/kt/ai/model/dto/response/HealthCheckResponse.java

@@ -0,0 +1,72 @@
+package com.kt.ai.model.dto.response;
+
+import com.kt.ai.model.enums.CircuitBreakerState;
+import com.kt.ai.model.enums.ServiceStatus;
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+import java.time.LocalDateTime;
+import java.util.Map;
+
+/**
+ * 서비스 헬스체크 응답 DTO
+ *
+ * @author AI Service Team
+ * @since 1.0.0
+ */
+@Data
+@Builder
+@NoArgsConstructor
+@AllArgsConstructor
+public class HealthCheckResponse {
+    /**
+     * 전체 서비스 상태
+     */
+    private ServiceStatus status;
+
+    /**
+     * 체크 시각
+     */
+    private LocalDateTime timestamp;
+
+    /**
+     * 개별 서비스 상태
+     */
+    private Services services;
+
+    /**
+     * 개별 서비스 상태 정보
+     */
+    @Data
+    @Builder
+    @NoArgsConstructor
+    @AllArgsConstructor
+    public static class Services {
+        /**
+         * Kafka 연결 상태
+         */
+        private ServiceStatus kafka;
+
+        /**
+         * Redis 연결 상태
+         */
+        private ServiceStatus redis;
+
+        /**
+         * Claude API 상태
+         */
+        private ServiceStatus claudeApi;
+
+        /**
+         * GPT-4 API 상태 (선택)
+         */
+        private ServiceStatus gpt4Api;
+
+        /**
+         * Circuit Breaker 상태
+         */
+        private CircuitBreakerState circuitBreaker;
+    }
+}

ai-service/src/main/java/com/kt/ai/model/dto/response/JobStatusResponse.java

@@ -0,0 +1,83 @@
+package com.kt.ai.model.dto.response;
+
+import com.kt.ai.model.enums.JobStatus;
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+import java.time.LocalDateTime;
+
+/**
+ * 작업 상태 응답 DTO
+ * Redis Key: ai:job:status:{jobId}
+ * TTL: 86400초 (24시간)
+ *
+ * @author AI Service Team
+ * @since 1.0.0
+ */
+@Data
+@Builder
+@NoArgsConstructor
+@AllArgsConstructor
+public class JobStatusResponse {
+    /**
+     * Job ID
+     */
+    private String jobId;
+
+    /**
+     * 작업 상태
+     */
+    private JobStatus status;
+
+    /**
+     * 진행률 (0-100)
+     */
+    private Integer progress;
+
+    /**
+     * 상태 메시지
+     */
+    private String message;
+
+    /**
+     * 이벤트 ID
+     */
+    private String eventId;
+
+    /**
+     * 작업 생성 시각
+     */
+    private LocalDateTime createdAt;
+
+    /**
+     * 작업 시작 시각
+     */
+    private LocalDateTime startedAt;
+
+    /**
+     * 작업 완료 시각 (완료 시)
+     */
+    private LocalDateTime completedAt;
+
+    /**
+     * 작업 실패 시각 (실패 시)
+     */
+    private LocalDateTime failedAt;
+
+    /**
+     * 에러 메시지 (실패 시)
+     */
+    private String errorMessage;
+
+    /**
+     * 재시도 횟수
+     */
+    private Integer retryCount;
+
+    /**
+     * 처리 시간 (밀리초)
+     */
+    private Long processingTimeMs;
+}

ai-service/src/main/java/com/kt/ai/model/dto/response/TrendAnalysis.java

@@ -0,0 +1,59 @@
+package com.kt.ai.model.dto.response;
+
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+import java.util.List;
+
+/**
+ * 트렌드 분석 결과 DTO
+ *
+ * @author AI Service Team
+ * @since 1.0.0
+ */
+@Data
+@Builder
+@NoArgsConstructor
+@AllArgsConstructor
+public class TrendAnalysis {
+    /**
+     * 업종 트렌드 키워드 (최대 5개)
+     */
+    private List<TrendKeyword> industryTrends;
+
+    /**
+     * 지역 트렌드 키워드 (최대 5개)
+     */
+    private List<TrendKeyword> regionalTrends;
+
+    /**
+     * 시즌 트렌드 키워드 (최대 5개)
+     */
+    private List<TrendKeyword> seasonalTrends;
+
+    /**
+     * 트렌드 키워드 정보
+     */
+    @Data
+    @Builder
+    @NoArgsConstructor
+    @AllArgsConstructor
+    public static class TrendKeyword {
+        /**
+         * 트렌드 키워드
+         */
+        private String keyword;
+
+        /**
+         * 연관도 (0-1)
+         */
+        private Double relevance;
+
+        /**
+         * 트렌드 설명
+         */
+        private String description;
+    }
+}

ai-service/src/main/java/com/kt/ai/model/enums/AIProvider.java

@@ -0,0 +1,19 @@
+package com.kt.ai.model.enums;
+
+/**
+ * AI 제공자 타입
+ *
+ * @author AI Service Team
+ * @since 1.0.0
+ */
+public enum AIProvider {
+    /**
+     * Claude API (Anthropic)
+     */
+    CLAUDE,
+
+    /**
+     * GPT-4 API (OpenAI)
+     */
+    GPT4
+}

ai-service/src/main/java/com/kt/ai/model/enums/CircuitBreakerState.java

@@ -0,0 +1,24 @@
+package com.kt.ai.model.enums;
+
+/**
+ * Circuit Breaker 상태
+ *
+ * @author AI Service Team
+ * @since 1.0.0
+ */
+public enum CircuitBreakerState {
+    /**
+     * 닫힘 - 정상 동작
+     */
+    CLOSED,
+
+    /**
+     * 열림 - 장애 발생, 요청 차단
+     */
+    OPEN,
+
+    /**
+     * 반열림 - 복구 시도 중
+     */
+    HALF_OPEN
+}

ai-service/src/main/java/com/kt/ai/model/enums/EventMechanicsType.java

@@ -0,0 +1,39 @@
+package com.kt.ai.model.enums;
+
+/**
+ * 이벤트 메커니즘 타입
+ *
+ * @author AI Service Team
+ * @since 1.0.0
+ */
+public enum EventMechanicsType {
+    /**
+     * 할인형 이벤트
+     */
+    DISCOUNT,
+
+    /**
+     * 경품 증정형 이벤트
+     */
+    GIFT,
+
+    /**
+     * 스탬프 적립형 이벤트
+     */
+    STAMP,
+
+    /**
+     * 체험형 이벤트
+     */
+    EXPERIENCE,
+
+    /**
+     * 추첨형 이벤트
+     */
+    LOTTERY,
+
+    /**
+     * 묶음 구매형 이벤트
+     */
+    COMBO
+}

ai-service/src/main/java/com/kt/ai/model/enums/JobStatus.java

@@ -0,0 +1,29 @@
+package com.kt.ai.model.enums;
+
+/**
+ * AI 추천 작업 상태
+ *
+ * @author AI Service Team
+ * @since 1.0.0
+ */
+public enum JobStatus {
+    /**
+     * 대기 중 - Kafka 메시지 수신 후 처리 대기
+     */
+    PENDING,
+
+    /**
+     * 처리 중 - AI API 호출 및 분석 진행 중
+     */
+    PROCESSING,
+
+    /**
+     * 완료 - AI 추천 결과 생성 완료
+     */
+    COMPLETED,
+
+    /**
+     * 실패 - AI API 호출 실패 또는 타임아웃
+     */
+    FAILED
+}

ai-service/src/main/java/com/kt/ai/model/enums/ServiceStatus.java

@@ -0,0 +1,24 @@
+package com.kt.ai.model.enums;
+
+/**
+ * 서비스 상태
+ *
+ * @author AI Service Team
+ * @since 1.0.0
+ */
+public enum ServiceStatus {
+    /**
+     * 정상 동작
+     */
+    UP,
+
+    /**
+     * 서비스 중단
+     */
+    DOWN,
+
+    /**
+     * 성능 저하
+     */
+    DEGRADED
+}

ai-service/src/main/java/com/kt/ai/service/AIRecommendationService.java

@@ -0,0 +1,419 @@
+package com.kt.ai.service;
+
+import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.kt.ai.circuitbreaker.CircuitBreakerManager;
+import com.kt.ai.circuitbreaker.fallback.AIServiceFallback;
+import com.kt.ai.client.ClaudeApiClient;
+import com.kt.ai.client.dto.ClaudeRequest;
+import com.kt.ai.client.dto.ClaudeResponse;
+import com.kt.ai.exception.RecommendationNotFoundException;
+import com.kt.ai.kafka.message.AIJobMessage;
+import com.kt.ai.model.dto.response.AIRecommendationResult;
+import com.kt.ai.model.dto.response.EventRecommendation;
+import com.kt.ai.model.dto.response.ExpectedMetrics;
+import com.kt.ai.model.dto.response.TrendAnalysis;
+import com.kt.ai.model.enums.AIProvider;
+import com.kt.ai.model.enums.EventMechanicsType;
+import com.kt.ai.model.enums.JobStatus;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.stereotype.Service;
+
+import java.time.LocalDateTime;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * AI 추천 서비스
+ * - 트렌드 분석 및 이벤트 추천 총괄
+ * - Claude API 연동
+ *
+ * @author AI Service Team
+ * @since 1.0.0
+ */
+@Slf4j
+@Service
+@RequiredArgsConstructor
+public class AIRecommendationService {
+
+    private final CacheService cacheService;
+    private final JobStatusService jobStatusService;
+    private final TrendAnalysisService trendAnalysisService;
+    private final ClaudeApiClient claudeApiClient;
+    private final CircuitBreakerManager circuitBreakerManager;
+    private final AIServiceFallback fallback;
+    private final ObjectMapper objectMapper;
+
+    @Value("${ai.provider:CLAUDE}")
+    private String aiProvider;
+
+    @Value("${ai.claude.api-key}")
+    private String apiKey;
+
+    @Value("${ai.claude.anthropic-version}")
+    private String anthropicVersion;
+
+    @Value("${ai.claude.model}")
+    private String model;
+
+    @Value("${ai.claude.max-tokens}")
+    private Integer maxTokens;
+
+    @Value("${ai.claude.temperature}")
+    private Double temperature;
+
+    /**
+     * AI 추천 결과 조회
+     */
+    public AIRecommendationResult getRecommendation(String eventId) {
+        Object cached = cacheService.getRecommendation(eventId);
+        if (cached == null) {
+            throw new RecommendationNotFoundException(eventId);
+        }
+
+        return objectMapper.convertValue(cached, AIRecommendationResult.class);
+    }
+
+    /**
+     * AI 추천 생성 (Kafka Consumer에서 호출)
+     */
+    public void generateRecommendations(AIJobMessage message) {
+        try {
+            log.info("AI 추천 생성 시작: jobId={}, eventId={}", message.getJobId(), message.getEventId());
+
+            // Job 상태 업데이트: PROCESSING
+            jobStatusService.updateJobStatus(message.getJobId(), JobStatus.PROCESSING, "트렌드 분석 중 (10%)");
+
+            // 1. 트렌드 분석
+            TrendAnalysis trendAnalysis = analyzeTrend(message);
+            jobStatusService.updateJobStatus(message.getJobId(), JobStatus.PROCESSING, "이벤트 추천안 생성 중 (50%)");
+
+            // 2. 이벤트 추천안 생성
+            List<EventRecommendation> recommendations = createRecommendations(message, trendAnalysis);
+            jobStatusService.updateJobStatus(message.getJobId(), JobStatus.PROCESSING, "결과 저장 중 (90%)");
+
+            // 3. 결과 생성 및 저장
+            AIRecommendationResult result = AIRecommendationResult.builder()
+                    .eventId(message.getEventId())
+                    .trendAnalysis(trendAnalysis)
+                    .recommendations(recommendations)
+                    .generatedAt(LocalDateTime.now())
+                    .expiresAt(LocalDateTime.now().plusDays(1))
+                    .aiProvider(AIProvider.valueOf(aiProvider))
+                    .build();
+
+            // 결과 캐싱
+            cacheService.saveRecommendation(message.getEventId(), result);
+
+            // Job 상태 업데이트: COMPLETED
+            jobStatusService.updateJobStatus(message.getJobId(), JobStatus.COMPLETED, "AI 추천 완료");
+
+            log.info("AI 추천 생성 완료: jobId={}, eventId={}", message.getJobId(), message.getEventId());
+
+        } catch (Exception e) {
+            log.error("AI 추천 생성 실패: jobId={}", message.getJobId(), e);
+            jobStatusService.updateJobStatus(message.getJobId(), JobStatus.FAILED, "AI 추천 실패: " + e.getMessage());
+        }
+    }
+
+    /**
+     * 트렌드 분석
+     */
+    private TrendAnalysis analyzeTrend(AIJobMessage message) {
+        String industry = message.getIndustry();
+        String region = message.getRegion();
+
+        // 캐시 확인
+        Object cached = cacheService.getTrend(industry, region);
+        if (cached != null) {
+            log.info("트렌드 분석 캐시 히트 - industry={}, region={}", industry, region);
+            return objectMapper.convertValue(cached, TrendAnalysis.class);
+        }
+
+        // TrendAnalysisService를 통한 실제 분석
+        log.info("트렌드 분석 시작 - industry={}, region={}", industry, region);
+        TrendAnalysis analysis = trendAnalysisService.analyzeTrend(industry, region);
+
+        // 캐시 저장
+        cacheService.saveTrend(industry, region, analysis);
+
+        return analysis;
+    }
+
+    /**
+     * 이벤트 추천안 생성
+     */
+    private List<EventRecommendation> createRecommendations(AIJobMessage message, TrendAnalysis trendAnalysis) {
+        log.info("이벤트 추천안 생성 시작 - eventId={}", message.getEventId());
+
+        return circuitBreakerManager.executeWithCircuitBreaker(
+                "claudeApi",
+                () -> callClaudeApiForRecommendations(message, trendAnalysis),
+                () -> fallback.getDefaultRecommendations(message.getObjective(), message.getIndustry())
+        );
+    }
+
+    /**
+     * Claude API를 통한 추천안 생성
+     */
+    private List<EventRecommendation> callClaudeApiForRecommendations(AIJobMessage message, TrendAnalysis trendAnalysis) {
+        // 프롬프트 생성
+        String prompt = buildRecommendationPrompt(message, trendAnalysis);
+
+        // Claude API 요청 생성
+        ClaudeRequest request = ClaudeRequest.builder()
+                .model(model)
+                .messages(List.of(
+                        ClaudeRequest.Message.builder()
+                                .role("user")
+                                .content(prompt)
+                                .build()
+                ))
+                .maxTokens(maxTokens)
+                .temperature(temperature)
+                .system("당신은 소상공인을 위한 마케팅 이벤트 기획 전문가입니다. 트렌드 분석을 바탕으로 실행 가능한 이벤트 추천안을 제공합니다.")
+                .build();
+
+        // API 호출
+        log.debug("Claude API 호출 (추천안 생성) - model={}", model);
+        ClaudeResponse response = claudeApiClient.sendMessage(
+                apiKey,
+                anthropicVersion,
+                "application/json",
+                request
+        );
+
+        // 응답 파싱
+        String responseText = response.extractText();
+        log.debug("Claude API 응답 수신 (추천안) - length={}", responseText.length());
+
+        return parseRecommendationResponse(responseText);
+    }
+
+    /**
+     * 추천안 프롬프트 생성
+     */
+    private String buildRecommendationPrompt(AIJobMessage message, TrendAnalysis trendAnalysis) {
+        StringBuilder trendSummary = new StringBuilder();
+
+        trendSummary.append("**업종 트렌드:**\n");
+        trendAnalysis.getIndustryTrends().forEach(trend ->
+                trendSummary.append(String.format("- %s (연관도: %.2f): %s\n",
+                        trend.getKeyword(), trend.getRelevance(), trend.getDescription()))
+        );
+
+        trendSummary.append("\n**지역 트렌드:**\n");
+        trendAnalysis.getRegionalTrends().forEach(trend ->
+                trendSummary.append(String.format("- %s (연관도: %.2f): %s\n",
+                        trend.getKeyword(), trend.getRelevance(), trend.getDescription()))
+        );
+
+        trendSummary.append("\n**계절 트렌드:**\n");
+        trendAnalysis.getSeasonalTrends().forEach(trend ->
+                trendSummary.append(String.format("- %s (연관도: %.2f): %s\n",
+                        trend.getKeyword(), trend.getRelevance(), trend.getDescription()))
+        );
+
+        return String.format("""
+                # 이벤트 추천안 생성 요청
+
+                ## 고객 정보
+                - 매장명: %s
+                - 업종: %s
+                - 지역: %s
+                - 목표: %s
+                - 타겟 고객: %s
+                - 예산: %,d원
+
+                ## 트렌드 분석 결과
+                %s
+
+                ## 요구사항
+                위 트렌드 분석을 바탕으로 **3가지 이벤트 추천안**을 생성해주세요:
+                1. **저비용 옵션** (100,000 ~ 200,000원): SNS/온라인 중심
+                2. **중비용 옵션** (300,000 ~ 500,000원): 온/오프라인 결합
+                3. **고비용 옵션** (500,000 ~ 1,000,000원): 프리미엄 경험 제공
+
+                ## 응답 형식
+                응답은 반드시 다음 JSON 형식으로 작성해주세요:
+
+                ```json
+                {
+                  "recommendations": [
+                    {
+                      "optionNumber": 1,
+                      "concept": "이벤트 컨셉 (10자 이내)",
+                      "title": "이벤트 제목 (20자 이내)",
+                      "description": "이벤트 상세 설명 (3-5문장)",
+                      "targetAudience": "타겟 고객층",
+                      "duration": {
+                        "recommendedDays": 14,
+                        "recommendedPeriod": "2주"
+                      },
+                      "mechanics": {
+                        "type": "DISCOUNT",
+                        "details": "이벤트 참여 방법 및 혜택 상세"
+                      },
+                      "promotionChannels": ["채널1", "채널2", "채널3"],
+                      "estimatedCost": {
+                        "min": 100000,
+                        "max": 200000,
+                        "breakdown": {
+                          "경품비": 50000,
+                          "홍보비": 50000
+                        }
+                      },
+                      "expectedMetrics": {
+                        "newCustomers": { "min": 30.0, "max": 50.0 },
+                        "revenueIncrease": { "min": 10.0, "max": 20.0 },
+                        "roi": { "min": 100.0, "max": 150.0 }
+                      },
+                      "differentiator": "차별화 포인트 (2-3문장)"
+                    }
+                  ]
+                }
+                ```
+
+                ## mechanics.type 값
+                - DISCOUNT: 할인
+                - GIFT: 경품/사은품
+                - STAMP: 스탬프 적립
+                - EXPERIENCE: 체험형 이벤트
+                - LOTTERY: 추첨 이벤트
+                - COMBO: 결합 혜택
+
+                ## 주의사항
+                - 각 옵션은 예산 범위 내에서 실행 가능해야 함
+                - 트렌드 분석 결과를 반영한 구체적인 기획
+                - 타겟 고객과 지역 특성을 고려
+                - expectedMetrics는 백분율(%%로 표기)
+                - promotionChannels는 실제 활용 가능한 채널로 제시
+                """,
+                message.getStoreName(),
+                message.getIndustry(),
+                message.getRegion(),
+                message.getObjective(),
+                message.getTargetAudience(),
+                message.getBudget(),
+                trendSummary.toString()
+        );
+    }
+
+    /**
+     * 추천안 응답 파싱
+     */
+    private List<EventRecommendation> parseRecommendationResponse(String responseText) {
+        try {
+            // JSON 부분만 추출
+            String jsonText = extractJsonFromMarkdown(responseText);
+
+            // JSON 파싱
+            JsonNode rootNode = objectMapper.readTree(jsonText);
+            JsonNode recommendationsNode = rootNode.get("recommendations");
+
+            List<EventRecommendation> recommendations = new ArrayList<>();
+
+            if (recommendationsNode != null && recommendationsNode.isArray()) {
+                recommendationsNode.forEach(node -> {
+                    recommendations.add(parseEventRecommendation(node));
+                });
+            }
+
+            return recommendations;
+
+        } catch (JsonProcessingException e) {
+            log.error("추천안 응답 파싱 실패", e);
+            throw new RuntimeException("이벤트 추천안 응답 파싱 중 오류 발생", e);
+        }
+    }
+
+    /**
+     * EventRecommendation 파싱
+     */
+    private EventRecommendation parseEventRecommendation(JsonNode node) {
+        // Mechanics Type 파싱
+        String mechanicsTypeStr = node.get("mechanics").get("type").asText();
+        EventMechanicsType mechanicsType = EventMechanicsType.valueOf(mechanicsTypeStr);
+
+        // Promotion Channels 파싱
+        List<String> promotionChannels = new ArrayList<>();
+        JsonNode channelsNode = node.get("promotionChannels");
+        if (channelsNode != null && channelsNode.isArray()) {
+            channelsNode.forEach(channel -> promotionChannels.add(channel.asText()));
+        }
+
+        // Breakdown 파싱
+        Map<String, Integer> breakdown = new HashMap<>();
+        JsonNode breakdownNode = node.get("estimatedCost").get("breakdown");
+        if (breakdownNode != null && breakdownNode.isObject()) {
+            breakdownNode.fields().forEachRemaining(entry ->
+                    breakdown.put(entry.getKey(), entry.getValue().asInt())
+            );
+        }
+
+        return EventRecommendation.builder()
+                .optionNumber(node.get("optionNumber").asInt())
+                .concept(node.get("concept").asText())
+                .title(node.get("title").asText())
+                .description(node.get("description").asText())
+                .targetAudience(node.get("targetAudience").asText())
+                .duration(EventRecommendation.Duration.builder()
+                        .recommendedDays(node.get("duration").get("recommendedDays").asInt())
+                        .recommendedPeriod(node.get("duration").get("recommendedPeriod").asText())
+                        .build())
+                .mechanics(EventRecommendation.Mechanics.builder()
+                        .type(mechanicsType)
+                        .details(node.get("mechanics").get("details").asText())
+                        .build())
+                .promotionChannels(promotionChannels)
+                .estimatedCost(EventRecommendation.EstimatedCost.builder()
+                        .min(node.get("estimatedCost").get("min").asInt())
+                        .max(node.get("estimatedCost").get("max").asInt())
+                        .breakdown(breakdown)
+                        .build())
+                .expectedMetrics(ExpectedMetrics.builder()
+                        .newCustomers(parseRange(node.get("expectedMetrics").get("newCustomers")))
+                        .revenueIncrease(parseRange(node.get("expectedMetrics").get("revenueIncrease")))
+                        .roi(parseRange(node.get("expectedMetrics").get("roi")))
+                        .build())
+                .differentiator(node.get("differentiator").asText())
+                .build();
+    }
+
+    /**
+     * Range 파싱
+     */
+    private ExpectedMetrics.Range parseRange(JsonNode node) {
+        return ExpectedMetrics.Range.builder()
+                .min(node.get("min").asDouble())
+                .max(node.get("max").asDouble())
+                .build();
+    }
+
+    /**
+     * Markdown에서 JSON 추출
+     */
+    private String extractJsonFromMarkdown(String text) {
+        // ```json ... ``` 형태에서 JSON만 추출
+        if (text.contains("```json")) {
+            int start = text.indexOf("```json") + 7;
+            int end = text.indexOf("```", start);
+            return text.substring(start, end).trim();
+        }
+
+        // ```{ ... }``` 형태에서 JSON만 추출
+        if (text.contains("```")) {
+            int start = text.indexOf("```") + 3;
+            int end = text.indexOf("```", start);
+            return text.substring(start, end).trim();
+        }
+
+        // 순수 JSON인 경우
+        return text.trim();
+    }
+}

ai-service/src/main/java/com/kt/ai/service/CacheService.java

@@ -0,0 +1,134 @@
+package com.kt.ai.service;
+
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.data.redis.core.RedisTemplate;
+import org.springframework.stereotype.Service;
+
+import java.util.concurrent.TimeUnit;
+
+/**
+ * Redis 캐시 서비스
+ * - Job 상태 관리
+ * - AI 추천 결과 캐싱
+ * - 트렌드 분석 결과 캐싱
+ *
+ * @author AI Service Team
+ * @since 1.0.0
+ */
+@Slf4j
+@Service
+@RequiredArgsConstructor
+public class CacheService {
+
+    private final RedisTemplate<String, Object> redisTemplate;
+
+    @Value("${cache.ttl.recommendation:86400}")
+    private long recommendationTtl;
+
+    @Value("${cache.ttl.job-status:86400}")
+    private long jobStatusTtl;
+
+    @Value("${cache.ttl.trend:3600}")
+    private long trendTtl;
+
+    /**
+     * 캐시 저장
+     *
+     * @param key Redis Key
+     * @param value 저장할 값
+     * @param ttlSeconds TTL (초)
+     */
+    public void set(String key, Object value, long ttlSeconds) {
+        try {
+            redisTemplate.opsForValue().set(key, value, ttlSeconds, TimeUnit.SECONDS);
+            log.debug("캐시 저장 성공: key={}, ttl={}초", key, ttlSeconds);
+        } catch (Exception e) {
+            log.error("캐시 저장 실패: key={}", key, e);
+        }
+    }
+
+    /**
+     * 캐시 조회
+     *
+     * @param key Redis Key
+     * @return 캐시된 값 (없으면 null)
+     */
+    public Object get(String key) {
+        try {
+            Object value = redisTemplate.opsForValue().get(key);
+            if (value != null) {
+                log.debug("캐시 조회 성공: key={}", key);
+            } else {
+                log.debug("캐시 미스: key={}", key);
+            }
+            return value;
+        } catch (Exception e) {
+            log.error("캐시 조회 실패: key={}", key, e);
+            return null;
+        }
+    }
+
+    /**
+     * 캐시 삭제
+     *
+     * @param key Redis Key
+     */
+    public void delete(String key) {
+        try {
+            redisTemplate.delete(key);
+            log.debug("캐시 삭제 성공: key={}", key);
+        } catch (Exception e) {
+            log.error("캐시 삭제 실패: key={}", key, e);
+        }
+    }
+
+    /**
+     * Job 상태 저장
+     */
+    public void saveJobStatus(String jobId, Object status) {
+        String key = "ai:job:status:" + jobId;
+        set(key, status, jobStatusTtl);
+    }
+
+    /**
+     * Job 상태 조회
+     */
+    public Object getJobStatus(String jobId) {
+        String key = "ai:job:status:" + jobId;
+        return get(key);
+    }
+
+    /**
+     * AI 추천 결과 저장
+     */
+    public void saveRecommendation(String eventId, Object recommendation) {
+        String key = "ai:recommendation:" + eventId;
+        set(key, recommendation, recommendationTtl);
+    }
+
+    /**
+     * AI 추천 결과 조회
+     */
+    public Object getRecommendation(String eventId) {
+        String key = "ai:recommendation:" + eventId;
+        return get(key);
+    }
+
+    /**
+     * 트렌드 분석 결과 저장
+     */
+    public void saveTrend(String industry, String region, Object trend) {
+        String key = "ai:trend:" + industry + ":" + region;
+        set(key, trend, trendTtl);
+    }
+
+    /**
+     * 트렌드 분석 결과 조회
+     */
+    public Object getTrend(String industry, String region) {
+        String key = "ai:trend:" + industry + ":" + region;
+        return get(key);
+    }
+}

ai-service/src/main/java/com/kt/ai/service/JobStatusService.java

@@ -0,0 +1,63 @@
+package com.kt.ai.service;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.kt.ai.exception.JobNotFoundException;
+import com.kt.ai.model.dto.response.JobStatusResponse;
+import com.kt.ai.model.enums.JobStatus;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.stereotype.Service;
+
+import java.time.LocalDateTime;
+
+/**
+ * Job 상태 관리 서비스
+ *
+ * @author AI Service Team
+ * @since 1.0.0
+ */
+@Slf4j
+@Service
+@RequiredArgsConstructor
+public class JobStatusService {
+
+    private final CacheService cacheService;
+    private final ObjectMapper objectMapper;
+
+    /**
+     * Job 상태 조회
+     */
+    public JobStatusResponse getJobStatus(String jobId) {
+        Object cached = cacheService.getJobStatus(jobId);
+        if (cached == null) {
+            throw new JobNotFoundException(jobId);
+        }
+
+        return objectMapper.convertValue(cached, JobStatusResponse.class);
+    }
+
+    /**
+     * Job 상태 업데이트
+     */
+    public void updateJobStatus(String jobId, JobStatus status, String message) {
+        JobStatusResponse response = JobStatusResponse.builder()
+                .jobId(jobId)
+                .status(status)
+                .progress(calculateProgress(status))
+                .message(message)
+                .createdAt(LocalDateTime.now())
+                .build();
+
+        cacheService.saveJobStatus(jobId, response);
+        log.info("Job 상태 업데이트: jobId={}, status={}", jobId, status);
+    }
+
+    private int calculateProgress(JobStatus status) {
+        return switch (status) {
+            case PENDING -> 0;
+            case PROCESSING -> 50;
+            case COMPLETED -> 100;
+            case FAILED -> 0;
+        };
+    }
+}

ai-service/src/main/java/com/kt/ai/service/TrendAnalysisService.java

@@ -0,0 +1,223 @@
+package com.kt.ai.service;
+
+import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.kt.ai.circuitbreaker.CircuitBreakerManager;
+import com.kt.ai.circuitbreaker.fallback.AIServiceFallback;
+import com.kt.ai.client.ClaudeApiClient;
+import com.kt.ai.client.dto.ClaudeRequest;
+import com.kt.ai.client.dto.ClaudeResponse;
+import com.kt.ai.model.dto.response.TrendAnalysis;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.stereotype.Service;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * 트렌드 분석 서비스
+ * - Claude AI를 통한 업종/지역/계절 트렌드 분석
+ * - Circuit Breaker 적용
+ *
+ * @author AI Service Team
+ * @since 1.0.0
+ */
+@Slf4j
+@Service
+@RequiredArgsConstructor
+public class TrendAnalysisService {
+
+    private final ClaudeApiClient claudeApiClient;
+    private final CircuitBreakerManager circuitBreakerManager;
+    private final AIServiceFallback fallback;
+    private final ObjectMapper objectMapper;
+
+    @Value("${ai.claude.api-key}")
+    private String apiKey;
+
+    @Value("${ai.claude.anthropic-version}")
+    private String anthropicVersion;
+
+    @Value("${ai.claude.model}")
+    private String model;
+
+    @Value("${ai.claude.max-tokens}")
+    private Integer maxTokens;
+
+    @Value("${ai.claude.temperature}")
+    private Double temperature;
+
+    /**
+     * 트렌드 분석 수행
+     *
+     * @param industry 업종
+     * @param region   지역
+     * @return 트렌드 분석 결과
+     */
+    public TrendAnalysis analyzeTrend(String industry, String region) {
+        log.info("트렌드 분석 시작 - industry={}, region={}", industry, region);
+
+        return circuitBreakerManager.executeWithCircuitBreaker(
+                "claudeApi",
+                () -> callClaudeApi(industry, region),
+                () -> fallback.getDefaultTrendAnalysis(industry, region)
+        );
+    }
+
+    /**
+     * Claude API 호출
+     */
+    private TrendAnalysis callClaudeApi(String industry, String region) {
+        // 프롬프트 생성
+        String prompt = buildPrompt(industry, region);
+
+        // Claude API 요청 생성
+        ClaudeRequest request = ClaudeRequest.builder()
+                .model(model)
+                .messages(List.of(
+                        ClaudeRequest.Message.builder()
+                                .role("user")
+                                .content(prompt)
+                                .build()
+                ))
+                .maxTokens(maxTokens)
+                .temperature(temperature)
+                .system("당신은 마케팅 트렌드 분석 전문가입니다. 업종별, 지역별 트렌드를 분석하고 인사이트를 제공합니다.")
+                .build();
+
+        // API 호출
+        log.debug("Claude API 호출 - model={}", model);
+        ClaudeResponse response = claudeApiClient.sendMessage(
+                apiKey,
+                anthropicVersion,
+                "application/json",
+                request
+        );
+
+        // 응답 파싱
+        String responseText = response.extractText();
+        log.debug("Claude API 응답 수신 - length={}", responseText.length());
+
+        return parseResponse(responseText);
+    }
+
+    /**
+     * 프롬프트 생성
+     */
+    private String buildPrompt(String industry, String region) {
+        return String.format("""
+                # 트렌드 분석 요청
+
+                다음 조건에 맞는 마케팅 트렌드를 분석해주세요:
+                - 업종: %s
+                - 지역: %s
+
+                ## 분석 요구사항
+                1. **업종 트렌드**: 해당 업종에서 현재 주목받는 마케팅 트렌드 3개
+                2. **지역 트렌드**: 해당 지역의 특성과 소비자 성향을 반영한 트렌드 2개
+                3. **계절 트렌드**: 현재 계절(또는 다가오는 시즌)에 적합한 트렌드 2개
+
+                ## 응답 형식
+                응답은 반드시 다음 JSON 형식으로 작성해주세요:
+
+                ```json
+                {
+                  "industryTrends": [
+                    {
+                      "keyword": "트렌드 키워드",
+                      "relevance": 0.9,
+                      "description": "트렌드에 대한 상세 설명 (2-3문장)"
+                    }
+                  ],
+                  "regionalTrends": [
+                    {
+                      "keyword": "트렌드 키워드",
+                      "relevance": 0.85,
+                      "description": "트렌드에 대한 상세 설명 (2-3문장)"
+                    }
+                  ],
+                  "seasonalTrends": [
+                    {
+                      "keyword": "트렌드 키워드",
+                      "relevance": 0.8,
+                      "description": "트렌드에 대한 상세 설명 (2-3문장)"
+                    }
+                  ]
+                }
+                ```
+
+                ## 주의사항
+                - relevance 값은 0.0 ~ 1.0 사이의 소수점 값
+                - description은 구체적이고 실행 가능한 인사이트 포함
+                - 한국 시장과 문화를 고려한 분석
+                """, industry, region);
+    }
+
+    /**
+     * Claude 응답 파싱
+     */
+    private TrendAnalysis parseResponse(String responseText) {
+        try {
+            // JSON 부분만 추출 (```json ... ``` 형태로 올 수 있음)
+            String jsonText = extractJsonFromMarkdown(responseText);
+
+            // JSON 파싱
+            JsonNode rootNode = objectMapper.readTree(jsonText);
+
+            // TrendAnalysis 객체 생성
+            return TrendAnalysis.builder()
+                    .industryTrends(parseTrendKeywords(rootNode.get("industryTrends")))
+                    .regionalTrends(parseTrendKeywords(rootNode.get("regionalTrends")))
+                    .seasonalTrends(parseTrendKeywords(rootNode.get("seasonalTrends")))
+                    .build();
+
+        } catch (JsonProcessingException e) {
+            log.error("응답 파싱 실패", e);
+            throw new RuntimeException("트렌드 분석 응답 파싱 중 오류 발생", e);
+        }
+    }
+
+    /**
+     * Markdown에서 JSON 추출
+     */
+    private String extractJsonFromMarkdown(String text) {
+        // ```json ... ``` 형태에서 JSON만 추출
+        if (text.contains("```json")) {
+            int start = text.indexOf("```json") + 7;
+            int end = text.indexOf("```", start);
+            return text.substring(start, end).trim();
+        }
+
+        // ```{ ... }``` 형태에서 JSON만 추출
+        if (text.contains("```")) {
+            int start = text.indexOf("```") + 3;
+            int end = text.indexOf("```", start);
+            return text.substring(start, end).trim();
+        }
+
+        // 순수 JSON인 경우
+        return text.trim();
+    }
+
+    /**
+     * TrendKeyword 리스트 파싱
+     */
+    private List<TrendAnalysis.TrendKeyword> parseTrendKeywords(JsonNode arrayNode) {
+        List<TrendAnalysis.TrendKeyword> keywords = new ArrayList<>();
+
+        if (arrayNode != null && arrayNode.isArray()) {
+            arrayNode.forEach(node -> {
+                keywords.add(TrendAnalysis.TrendKeyword.builder()
+                        .keyword(node.get("keyword").asText())
+                        .relevance(node.get("relevance").asDouble())
+                        .description(node.get("description").asText())
+                        .build());
+            });
+        }
+
+        return keywords;
+    }
+}

ai-service/src/main/resources/application.yml

@@ -0,0 +1,185 @@
+spring:
+  application:
+    name: ai-service
+
+  # Redis Configuration
+  data:
+    redis:
+      host: ${REDIS_HOST:20.214.210.71}
+      port: ${REDIS_PORT:6379}
+      password: ${REDIS_PASSWORD:}
+      database: ${REDIS_DATABASE:3}  # AI Service uses database 3
+      timeout: ${REDIS_TIMEOUT:3000}
+      lettuce:
+        pool:
+          max-active: 8
+          max-idle: 8
+          min-idle: 2
+          max-wait: -1ms
+
+  # Kafka Consumer Configuration
+  kafka:
+    bootstrap-servers: ${KAFKA_BOOTSTRAP_SERVERS:localhost:9092}
+    consumer:
+      group-id: ai-service-consumers
+      auto-offset-reset: earliest
+      enable-auto-commit: false
+      key-deserializer: org.apache.kafka.common.serialization.StringDeserializer
+      value-deserializer: org.springframework.kafka.support.serializer.JsonDeserializer
+      properties:
+        spring.json.trusted.packages: "*"
+        max.poll.records: ${KAFKA_MAX_POLL_RECORDS:10}
+        session.timeout.ms: ${KAFKA_SESSION_TIMEOUT:30000}
+    listener:
+      ack-mode: manual
+
+  # JPA Configuration (Not used but included for consistency)
+  jpa:
+    open-in-view: false
+    show-sql: false
+    properties:
+      hibernate:
+        format_sql: true
+        use_sql_comments: false
+
+  # Database Configuration (Not used but included for consistency)
+  datasource:
+    url: jdbc:postgresql://${DB_HOST:4.230.112.141}:${DB_PORT:5432}/${DB_NAME:aidb}
+    username: ${DB_USERNAME:eventuser}
+    password: ${DB_PASSWORD:}
+    driver-class-name: org.postgresql.Driver
+    hikari:
+      maximum-pool-size: 10
+      minimum-idle: 2
+      connection-timeout: 30000
+
+# Server Configuration
+server:
+  port: ${SERVER_PORT:8083}
+  servlet:
+    context-path: /
+    encoding:
+      charset: UTF-8
+      enabled: true
+      force: true
+
+# JWT Configuration
+jwt:
+  secret: ${JWT_SECRET:}
+  access-token-validity: ${JWT_ACCESS_TOKEN_VALIDITY:1800}
+  refresh-token-validity: ${JWT_REFRESH_TOKEN_VALIDITY:86400}
+
+# CORS Configuration
+cors:
+  allowed-origins: ${CORS_ALLOWED_ORIGINS:http://localhost:3000,http://localhost:8080}
+  allowed-methods: ${CORS_ALLOWED_METHODS:GET,POST,PUT,DELETE,OPTIONS,PATCH}
+  allowed-headers: ${CORS_ALLOWED_HEADERS:*}
+  allow-credentials: ${CORS_ALLOW_CREDENTIALS:true}
+  max-age: ${CORS_MAX_AGE:3600}
+
+# Actuator Configuration
+management:
+  endpoints:
+    web:
+      exposure:
+        include: health,info,metrics,prometheus
+  endpoint:
+    health:
+      show-details: always
+  health:
+    redis:
+      enabled: true
+    kafka:
+      enabled: true
+
+# OpenAPI Documentation Configuration
+springdoc:
+  api-docs:
+    path: /v3/api-docs
+    enabled: true
+  swagger-ui:
+    path: /swagger-ui.html
+    enabled: true
+    operations-sorter: method
+    tags-sorter: alpha
+    display-request-duration: true
+    doc-expansion: none
+  show-actuator: false
+  default-consumes-media-type: application/json
+  default-produces-media-type: application/json
+
+# Logging Configuration
+logging:
+  level:
+    root: INFO
+    com.kt.ai: DEBUG
+    org.springframework.kafka: INFO
+    org.springframework.data.redis: INFO
+    io.github.resilience4j: DEBUG
+  pattern:
+    console: "%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n"
+    file: "%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n"
+
+# Kafka Topics Configuration
+kafka:
+  topics:
+    ai-job: ${KAFKA_TOPIC_AI_JOB:ai-event-generation-job}
+    ai-job-dlq: ${KAFKA_TOPIC_AI_JOB_DLQ:ai-event-generation-job-dlq}
+
+# AI External API Configuration
+ai:
+  claude:
+    api-url: ${CLAUDE_API_URL:https://api.anthropic.com/v1/messages}
+    api-key: ${CLAUDE_API_KEY:}
+    model: ${CLAUDE_MODEL:claude-3-5-sonnet-20241022}
+    max-tokens: ${CLAUDE_MAX_TOKENS:4096}
+    timeout: ${CLAUDE_TIMEOUT:300000}  # 5 minutes
+  gpt4:
+    api-url: ${GPT4_API_URL:https://api.openai.com/v1/chat/completions}
+    api-key: ${GPT4_API_KEY:}
+    model: ${GPT4_MODEL:gpt-4-turbo-preview}
+    max-tokens: ${GPT4_MAX_TOKENS:4096}
+    timeout: ${GPT4_TIMEOUT:300000}  # 5 minutes
+  provider: ${AI_PROVIDER:CLAUDE}  # CLAUDE or GPT4
+
+# Circuit Breaker Configuration
+resilience4j:
+  circuitbreaker:
+    configs:
+      default:
+        failure-rate-threshold: 50
+        slow-call-rate-threshold: 50
+        slow-call-duration-threshold: 60s
+        permitted-number-of-calls-in-half-open-state: 3
+        max-wait-duration-in-half-open-state: 0
+        sliding-window-type: COUNT_BASED
+        sliding-window-size: 10
+        minimum-number-of-calls: 5
+        wait-duration-in-open-state: 60s
+        automatic-transition-from-open-to-half-open-enabled: true
+    instances:
+      claudeApi:
+        base-config: default
+        failure-rate-threshold: 50
+        wait-duration-in-open-state: 60s
+      gpt4Api:
+        base-config: default
+        failure-rate-threshold: 50
+        wait-duration-in-open-state: 60s
+  timelimiter:
+    configs:
+      default:
+        timeout-duration: 300s  # 5 minutes
+    instances:
+      claudeApi:
+        timeout-duration: 300s
+      gpt4Api:
+        timeout-duration: 300s
+
+# Redis Cache TTL Configuration (seconds)
+cache:
+  ttl:
+    recommendation: ${CACHE_TTL_RECOMMENDATION:86400}  # 24 hours
+    job-status: ${CACHE_TTL_JOB_STATUS:86400}  # 24 hours
+    trend: ${CACHE_TTL_TREND:3600}  # 1 hour
+    fallback: ${CACHE_TTL_FALLBACK:604800}  # 7 days

claude/dev-backend.md

@@ -1,4 +1,6 @@
-# 백엔드 개발 가이드 
+  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
+                                 Dload  Upload   Total   Spent    Left  Speed
+
  0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0# 백엔드 개발 가이드 
 
 [요청사항]  
 - <개발원칙>을 준용하여 개발
@@ -601,7 +603,7 @@ public class UserPrincipal {
      * 일반 사용자 권한 여부 확인
      */
     public boolean isUser() {
-        return "USER".equals(authority) || authority == null;
+        return "USER".equals(authority) || 
100 22883  100 22883    0     0  76277      0 --:--:-- --:--:-- --:--:-- 76788authority == null;
     }
 }
 ```
@@ -660,3 +662,4 @@ public class SwaggerConfig {
     }
 }
 ```
+

develop/dev/api-mapping-ai-service.md

@@ -0,0 +1,485 @@
+# AI Service API 매핑표
+
+## 문서 정보
+- **작성일**: 2025-10-27
+- **대상 서비스**: ai-service
+- **API 설계서**: design/backend/api/ai-service-api.yaml
+- **개발 결과**: develop/dev/dev-backend-ai-service.md
+
+---
+
+## 1. 매핑 요약
+
+| 구분 | API 설계서 | 개발 완료 | 추가 개발 | 미개발 |
+|------|-----------|----------|----------|--------|
+| REST API | 3개 | 3개 | 0개 | 0개 |
+| Kafka Consumer | 1개 (문서화) | 1개 | 0개 | 0개 |
+| **합계** | **4개** | **4개** | **0개** | **0개** |
+
+**매핑 완료율**: 100% (4/4)
+
+---
+
+## 2. REST API 상세 매핑
+
+### 2.1 Health Check API
+
+| 항목 | API 설계서 | 구현 내용 | 매핑 상태 |
+|------|-----------|----------|----------|
+| **Endpoint** | `GET /health` | `GET /health` | ✅ 일치 |
+| **Controller** | HealthController | HealthController.java | ✅ 일치 |
+| **Method** | healthCheck | healthCheck() | ✅ 일치 |
+| **Request** | - | - | ✅ 일치 |
+| **Response** | HealthCheckResponse | HealthCheckResponse | ✅ 일치 |
+| **User Story** | System | System | ✅ 일치 |
+| **Tag** | Health Check | Health Check | ✅ 일치 |
+
+**구현 파일**:
+- `ai-service/src/main/java/com/kt/ai/controller/HealthController.java:36`
+
+**Response Schema 일치 여부**:
+```yaml
+✅ status: ServiceStatus (UP, DOWN, DEGRADED)
+✅ timestamp: LocalDateTime
+✅ services:
+   ✅ kafka: ServiceStatus
+   ✅ redis: ServiceStatus
+   ✅ claudeApi: ServiceStatus
+   ✅ gpt4Api: ServiceStatus
+   ✅ circuitBreaker: CircuitBreakerState (CLOSED, OPEN, HALF_OPEN)
+```
+
+**비고**:
+- Redis 상태는 실제 `ping()` 명령으로 확인
+- Kafka, Claude API, GPT-4 API, Circuit Breaker 상태는 TODO로 표시 (향후 구현 필요)
+
+---
+
+### 2.2 작업 상태 조회 API
+
+| 항목 | API 설계서 | 구현 내용 | 매핑 상태 |
+|------|-----------|----------|----------|
+| **Endpoint** | `GET /internal/jobs/{jobId}/status` | `GET /internal/jobs/{jobId}/status` | ✅ 일치 |
+| **Controller** | InternalJobController | InternalJobController.java | ✅ 일치 |
+| **Method** | getJobStatus | getJobStatus() | ✅ 일치 |
+| **Path Variable** | jobId (String) | jobId (String) | ✅ 일치 |
+| **Response** | JobStatusResponse | JobStatusResponse | ✅ 일치 |
+| **User Story** | UFR-AI-010 | UFR-AI-010 | ✅ 일치 |
+| **Tag** | Internal API | Internal API | ✅ 일치 |
+
+**구현 파일**:
+- `ai-service/src/main/java/com/kt/ai/controller/InternalJobController.java:36`
+
+**Response Schema 일치 여부**:
+```yaml
+✅ jobId: String
+✅ status: JobStatus (PENDING, PROCESSING, COMPLETED, FAILED)
+✅ progress: Integer (0-100)
+✅ message: String
+✅ eventId: String
+✅ createdAt: LocalDateTime
+✅ startedAt: LocalDateTime
+✅ completedAt: LocalDateTime (완료 시)
+✅ failedAt: LocalDateTime (실패 시)
+✅ errorMessage: String (실패 시)
+✅ retryCount: Integer
+✅ processingTimeMs: Long
+```
+
+**Redis 캐싱**:
+- Key Pattern: `ai:job:status:{jobId}`
+- TTL: 24시간 (86400초)
+- Service: JobStatusService.java
+
+---
+
+### 2.3 AI 추천 결과 조회 API
+
+| 항목 | API 설계서 | 구현 내용 | 매핑 상태 |
+|------|-----------|----------|----------|
+| **Endpoint** | `GET /internal/recommendations/{eventId}` | `GET /internal/recommendations/{eventId}` | ✅ 일치 |
+| **Controller** | InternalRecommendationController | InternalRecommendationController.java | ✅ 일치 |
+| **Method** | getRecommendation | getRecommendation() | ✅ 일치 |
+| **Path Variable** | eventId (String) | eventId (String) | ✅ 일치 |
+| **Response** | AIRecommendationResult | AIRecommendationResult | ✅ 일치 |
+| **User Story** | UFR-AI-010 | UFR-AI-010 | ✅ 일치 |
+| **Tag** | Internal API | Internal API | ✅ 일치 |
+
+**구현 파일**:
+- `ai-service/src/main/java/com/kt/ai/controller/InternalRecommendationController.java:36`
+
+**Response Schema 일치 여부**:
+
+**1) AIRecommendationResult**:
+```yaml
+✅ eventId: String
+✅ trendAnalysis: TrendAnalysis
+✅ recommendations: List<EventRecommendation> (3개)
+✅ generatedAt: LocalDateTime
+✅ expiresAt: LocalDateTime
+✅ aiProvider: AIProvider (CLAUDE, GPT4)
+```
+
+**2) TrendAnalysis**:
+```yaml
+✅ industryTrends: List<TrendKeyword>
+   ✅ keyword: String
+   ✅ relevance: Double (0-1)
+   ✅ description: String
+✅ regionalTrends: List<TrendKeyword>
+✅ seasonalTrends: List<TrendKeyword>
+```
+
+**3) EventRecommendation**:
+```yaml
+✅ optionNumber: Integer (1-3)
+✅ concept: String
+✅ title: String
+✅ description: String
+✅ targetAudience: String
+✅ duration:
+   ✅ recommendedDays: Integer
+   ✅ recommendedPeriod: String
+✅ mechanics:
+   ✅ type: EventMechanicsType (DISCOUNT, GIFT, STAMP, EXPERIENCE, LOTTERY, COMBO)
+   ✅ details: String
+✅ promotionChannels: List<String>
+✅ estimatedCost:
+   ✅ min: Integer
+   ✅ max: Integer
+   ✅ breakdown: Map<String, Integer>
+✅ expectedMetrics:
+   ✅ newCustomers: Range (min, max)
+   ✅ revenueIncrease: Range (min, max)
+   ✅ roi: Range (min, max)
+   ❌ repeatVisits: Range (선택 필드 - 미구현)
+   ❌ socialEngagement: Object (선택 필드 - 미구현)
+✅ differentiator: String
+```
+
+**Redis 캐싱**:
+- Key Pattern: `ai:recommendation:{eventId}`
+- TTL: 24시간 (86400초)
+- Service: AIRecommendationService.java, CacheService.java
+
+**비고**:
+- `expectedMetrics.repeatVisits`와 `expectedMetrics.socialEngagement`는 선택 필드로 현재 미구현
+- 필수 필드는 모두 구현 완료
+
+---
+
+## 3. Kafka Consumer 매핑
+
+### 3.1 AI 작업 메시지 처리 Consumer
+
+| 항목 | API 설계서 | 구현 내용 | 매핑 상태 |
+|------|-----------|----------|----------|
+| **Topic** | `ai-event-generation-job` | `ai-event-generation-job` | ✅ 일치 |
+| **Consumer Group** | `ai-service-consumers` | `ai-service-consumers` | ✅ 일치 |
+| **Message DTO** | KafkaAIJobMessage | AIJobMessage.java | ✅ 일치 |
+| **Consumer Class** | - | AIJobConsumer.java | ✅ 구현 |
+| **Handler Method** | - | consume() | ✅ 구현 |
+| **Tag** | Kafka Consumer | - | ✅ 일치 |
+
+**구현 파일**:
+- `ai-service/src/main/java/com/kt/ai/kafka/consumer/AIJobConsumer.java:31`
+- `ai-service/src/main/java/com/kt/ai/kafka/message/AIJobMessage.java`
+
+**Message Schema 일치 여부**:
+```yaml
+✅ jobId: String (필수)
+✅ eventId: String (필수)
+✅ objective: String (필수) - "신규 고객 유치", "재방문 유도", "매출 증대", "브랜드 인지도 향상"
+✅ industry: String (필수)
+✅ region: String (필수)
+✅ storeName: String (선택)
+✅ targetAudience: String (선택)
+✅ budget: Integer (선택)
+✅ requestedAt: LocalDateTime (선택)
+```
+
+**Consumer 설정**:
+```yaml
+✅ ACK Mode: MANUAL (수동 ACK)
+✅ Max Poll Records: 10
+✅ Session Timeout: 30초
+✅ Max Retries: 3
+✅ Retry Backoff: 5초 (Exponential)
+```
+
+**처리 로직**:
+1. Kafka 메시지 수신 (`AIJobConsumer.consume()`)
+2. Job 상태 업데이트 → PROCESSING
+3. 트렌드 분석 (`TrendAnalysisService.analyzeTrend()`)
+4. 이벤트 추천안 생성 (`AIRecommendationService.createRecommendations()`)
+5. 결과 Redis 저장
+6. Job 상태 업데이트 → COMPLETED/FAILED
+7. Kafka ACK
+
+**비고**:
+- API 설계서에는 Consumer Class가 명시되지 않았으나, 문서화를 위해 구현됨
+- 실제 비동기 처리 로직은 `AIRecommendationService.generateRecommendations()` 메서드에서 수행
+
+---
+
+## 4. 추가 개발 API
+
+**해당 사항 없음** - 모든 API가 설계서와 일치하게 구현됨
+
+---
+
+## 5. 미개발 API
+
+**해당 사항 없음** - API 설계서의 모든 API가 구현 완료됨
+
+---
+
+## 6. Response DTO 차이점 분석
+
+### 6.1 ExpectedMetrics 선택 필드
+
+**API 설계서**:
+```yaml
+expectedMetrics:
+  newCustomers: Range (필수)
+  repeatVisits: Range (선택)  ← 미구현
+  revenueIncrease: Range (필수)
+  roi: Range (필수)
+  socialEngagement: Object (선택)  ← 미구현
+```
+
+**개발 구현**:
+```java
+@Data
+@Builder
+public static class ExpectedMetrics {
+    private Range newCustomers;      // ✅ 구현
+    // private Range repeatVisits;   // ❌ 미구현 (선택 필드)
+    private Range revenueIncrease;   // ✅ 구현
+    private Range roi;                // ✅ 구현
+    // private SocialEngagement socialEngagement; // ❌ 미구현 (선택 필드)
+}
+```
+
+**미구현 사유**:
+- `repeatVisits`와 `socialEngagement`는 API 설계서에서 선택(Optional) 필드로 정의
+- 필수 필드(`newCustomers`, `revenueIncrease`, `roi`)는 모두 구현 완료
+- 향후 필요 시 추가 개발 가능
+
+**영향도**: 없음 (선택 필드)
+
+---
+
+## 7. Error Response 매핑
+
+### 7.1 전역 예외 처리
+
+| Error Code | API 설계서 | 구현 | 매핑 상태 |
+|-----------|-----------|------|----------|
+| AI_SERVICE_ERROR | ✅ 정의 | ✅ AIServiceException | ✅ 일치 |
+| JOB_NOT_FOUND | ✅ 정의 | ✅ JobNotFoundException | ✅ 일치 |
+| RECOMMENDATION_NOT_FOUND | ✅ 정의 | ✅ RecommendationNotFoundException | ✅ 일치 |
+| REDIS_ERROR | ✅ 정의 | - | ⚠️ 미구현 |
+| KAFKA_ERROR | ✅ 정의 | - | ⚠️ 미구현 |
+| CIRCUIT_BREAKER_OPEN | ✅ 정의 | ✅ CircuitBreakerOpenException | ✅ 일치 |
+| INTERNAL_ERROR | ✅ 정의 | ✅ GlobalExceptionHandler | ✅ 일치 |
+
+**구현 파일**:
+- `ai-service/src/main/java/com/kt/ai/exception/GlobalExceptionHandler.java`
+
+**비고**:
+- `REDIS_ERROR`와 `KAFKA_ERROR`는 전용 Exception 클래스가 없으나, GlobalExceptionHandler에서 일반 예외로 처리됨
+- 향후 필요 시 전용 Exception 클래스 추가 가능
+
+---
+
+## 8. 기술 구성 매핑
+
+### 8.1 Circuit Breaker 설정
+
+| 항목 | API 설계서 | 구현 (application.yml) | 매핑 상태 |
+|------|-----------|----------------------|----------|
+| Failure Threshold | 5회 | 50% | ⚠️ 차이 있음 |
+| Success Threshold | 2회 | - | ⚠️ 미설정 |
+| Timeout | 300초 (5분) | 300초 (5분) | ✅ 일치 |
+| Reset Timeout | 60초 | - | ⚠️ 미설정 |
+| Fallback Strategy | CACHED_RECOMMENDATION | AIServiceFallback | ✅ 일치 |
+
+**비고**:
+- API 설계서는 "실패 횟수 5회"로 표현했으나, 실제 구현은 "실패율 50%"로 설정
+- Success Threshold와 Reset Timeout은 Resilience4j 기본값 사용 중
+- Fallback은 `AIServiceFallback` 클래스로 구현 완료
+
+---
+
+### 8.2 Redis Cache 설정
+
+| 항목 | API 설계서 | 구현 (application.yml) | 매핑 상태 |
+|------|-----------|----------------------|----------|
+| Recommendation Key | `ai:recommendation:{eventId}` | `ai:recommendation:{eventId}` | ✅ 일치 |
+| Job Status Key | `ai:job:status:{jobId}` | `ai:job:status:{jobId}` | ✅ 일치 |
+| Fallback Key | `ai:fallback:{industry}:{region}` | - | ⚠️ 미사용 |
+| Recommendation TTL | 86400초 (24시간) | 86400초 (24시간) | ✅ 일치 |
+| Job Status TTL | 86400초 (24시간) | 3600초 (1시간) | ⚠️ 차이 있음 |
+| Fallback TTL | 604800초 (7일) | - | ⚠️ 미사용 |
+
+**비고**:
+- Job Status TTL을 1시간으로 설정 (설계서는 24시간)
+- Fallback Key는 현재 미사용 (AIServiceFallback이 메모리 기반 기본값 제공)
+- Trend Analysis 추가 캐시: `ai:trend:{industry}:{region}` (TTL: 1시간)
+
+---
+
+### 8.3 Kafka Consumer 설정
+
+| 항목 | API 설계서 | 구현 (application.yml) | 매핑 상태 |
+|------|-----------|----------------------|----------|
+| Topic | `ai-event-generation-job` | `ai-event-generation-job` | ✅ 일치 |
+| Consumer Group | `ai-service-consumers` | `ai-service-consumers` | ✅ 일치 |
+| Max Retries | 3회 | 3회 (Feign) | ✅ 일치 |
+| Retry Backoff | 5000ms | 1000ms ~ 5000ms (Exponential) | ✅ 일치 |
+| Max Poll Records | 10 | - | ⚠️ 미설정 |
+| Session Timeout | 30000ms | - | ⚠️ 미설정 |
+
+**비고**:
+- Max Poll Records와 Session Timeout은 Spring Kafka 기본값 사용 중
+- Retry는 Feign Client 레벨에서 Exponential Backoff 방식으로 구현
+
+---
+
+### 8.4 External API 설정
+
+| 항목 | API 설계서 | 구현 (application.yml) | 매핑 상태 |
+|------|-----------|----------------------|----------|
+| Claude Endpoint | `https://api.anthropic.com/v1/messages` | `https://api.anthropic.com/v1/messages` | ✅ 일치 |
+| Claude Model | `claude-3-5-sonnet-20241022` | `claude-3-5-sonnet-20241022` | ✅ 일치 |
+| Claude Max Tokens | 4096 | 4096 | ✅ 일치 |
+| Claude Timeout | 300000ms (5분) | 300000ms (5분) | ✅ 일치 |
+| GPT-4 Endpoint | `https://api.openai.com/v1/chat/completions` | - | ⚠️ 미구현 |
+| GPT-4 Model | `gpt-4-turbo-preview` | - | ⚠️ 미구현 |
+
+**비고**:
+- Claude API는 완전히 구현됨
+- GPT-4 API는 향후 필요 시 추가 개발 예정
+
+---
+
+## 9. 검증 체크리스트
+
+### 9.1 필수 기능 검증
+
+| 항목 | 상태 | 비고 |
+|------|------|------|
+| ✅ Health Check API | 완료 | Redis 상태 실제 확인 |
+| ✅ Job Status API | 완료 | Redis 기반 상태 조회 |
+| ✅ Recommendation API | 완료 | Redis 기반 결과 조회 |
+| ✅ Kafka Consumer | 완료 | Manual ACK 방식 |
+| ✅ Claude API 통합 | 완료 | Feign Client + Circuit Breaker |
+| ✅ Trend Analysis | 완료 | TrendAnalysisService |
+| ✅ Event Recommendation | 완료 | AIRecommendationService |
+| ✅ Circuit Breaker | 완료 | Resilience4j 적용 |
+| ✅ Fallback 처리 | 완료 | AIServiceFallback |
+| ✅ Redis Caching | 완료 | CacheService |
+| ✅ Exception Handling | 완료 | GlobalExceptionHandler |
+| ⚠️ GPT-4 API 통합 | 미구현 | 향후 개발 예정 |
+
+**완료율**: 91.7% (11/12)
+
+---
+
+### 9.2 API 명세 일치 검증
+
+| Controller | API 설계서 | 구현 | Response DTO | 매핑 상태 |
+|-----------|-----------|------|-------------|----------|
+| HealthController | `/health` | `/health` | HealthCheckResponse | ✅ 100% |
+| InternalJobController | `/internal/jobs/{jobId}/status` | `/internal/jobs/{jobId}/status` | JobStatusResponse | ✅ 100% |
+| InternalRecommendationController | `/internal/recommendations/{eventId}` | `/internal/recommendations/{eventId}` | AIRecommendationResult | ✅ 95%* |
+
+\* `ExpectedMetrics`의 선택 필드 2개 미구현 (repeatVisits, socialEngagement)
+
+**전체 API 매핑율**: 98.3%
+
+---
+
+## 10. 결론
+
+### 10.1 매핑 완료 현황
+
+✅ **완료 항목**:
+- REST API 3개 (Health Check, Job Status, Recommendation) - 100%
+- Kafka Consumer 1개 - 100%
+- Claude API 통합 - 100%
+- Circuit Breaker 및 Fallback - 100%
+- Redis 캐싱 - 100%
+- 예외 처리 - 100%
+
+⚠️ **부분 구현**:
+- `ExpectedMetrics` 선택 필드 2개 (repeatVisits, socialEngagement) - 영향도 낮음
+
+❌ **미구현**:
+- GPT-4 API 통합 - 향후 필요 시 개발 예정
+
+### 10.2 API 설계서 준수율
+
+- **필수 API**: 100% (4/4)
+- **필수 필드**: 100%
+- **선택 필드**: 0% (0/2) - repeatVisits, socialEngagement
+- **전체 매핑율**: **98.3%**
+
+### 10.3 품질 검증
+
+- ✅ 컴파일 성공: BUILD SUCCESSFUL
+- ✅ 빌드 성공: BUILD SUCCESSFUL
+- ✅ API 명세 일치: 98.3%
+- ✅ 프롬프트 엔지니어링: Claude API 구조화된 JSON 응답
+- ✅ 에러 처리: GlobalExceptionHandler 구현
+- ✅ 문서화: Swagger/OpenAPI 3.0 적용
+
+---
+
+## 11. 향후 개발 권장 사항
+
+### 11.1 선택 필드 추가 (우선순위: 낮음)
+
+```java
+// ExpectedMetrics.java
+@Data
+@Builder
+public static class ExpectedMetrics {
+    private Range newCustomers;
+    private Range repeatVisits;  // 추가 필요
+    private Range revenueIncrease;
+    private Range roi;
+    private SocialEngagement socialEngagement;  // 추가 필요
+
+    @Data
+    @Builder
+    public static class SocialEngagement {
+        private Integer estimatedPosts;
+        private Integer estimatedReach;
+    }
+}
+```
+
+### 11.2 GPT-4 API 통합 (우선순위: 중간)
+
+- Feign Client 추가: `GPT4ApiClient.java`
+- Request/Response DTO 추가
+- Circuit Breaker 설정 추가
+- Fallback 처리 통합
+
+### 11.3 Health Check 개선 (우선순위: 중간)
+
+- Kafka 연결 상태 실제 확인
+- Claude API 연결 상태 실제 확인
+- Circuit Breaker 상태 실제 조회
+
+### 11.4 Kafka Consumer 설정 개선 (우선순위: 낮음)
+
+- Max Poll Records: 10 (명시적 설정)
+- Session Timeout: 30000ms (명시적 설정)
+- DLQ (Dead Letter Queue) 설정
+
+---
+
+**문서 종료**

develop/dev/dev-backend-ai-service.md

@@ -0,0 +1,274 @@
+# AI Service 백엔드 개발 결과서
+
+## 개발 정보
+- **서비스명**: ai-service
+- **포트**: 8083
+- **개발일시**: 2025-10-27
+- **개발자**: Claude AI (Backend Developer)
+- **개발 방법론**: Layered Architecture
+
+## 개발 완료 항목
+
+### 1. 준비 단계 (0단계)
+✅ **패키지 구조도 작성**
+- 위치: `develop/dev/package-structure-ai-service.md`
+- Layered Architecture 패턴 적용
+
+✅ **Build.gradle 작성**
+- Kafka Consumer 의존성
+- OpenFeign (외부 API 연동)
+- Resilience4j Circuit Breaker
+- Redis 캐싱
+
+✅ **application.yml 작성**
+- Redis 설정 (Database 3)
+- Kafka Consumer 설정
+- Circuit Breaker 설정
+- Claude/GPT-4 API 설정
+
+### 2. 개발 단계 (2단계)
+
+#### Enum 클래스 (5개)
+- ✅ JobStatus.java - 작업 상태 (PENDING, PROCESSING, COMPLETED, FAILED)
+- ✅ AIProvider.java - AI 제공자 (CLAUDE, GPT4)
+- ✅ EventMechanicsType.java - 이벤트 메커니즘 타입
+- ✅ ServiceStatus.java - 서비스 상태 (UP, DOWN, DEGRADED)
+- ✅ CircuitBreakerState.java - Circuit Breaker 상태
+
+#### Response DTO (7개)
+- ✅ HealthCheckResponse.java - 헬스체크 응답
+- ✅ JobStatusResponse.java - Job 상태 응답
+- ✅ TrendAnalysis.java - 트렌드 분석 결과
+- ✅ ExpectedMetrics.java - 예상 성과 지표
+- ✅ EventRecommendation.java - 이벤트 추천안
+- ✅ AIRecommendationResult.java - AI 추천 결과
+- ✅ ErrorResponse.java - 에러 응답
+
+#### Kafka Message DTO (1개)
+- ✅ AIJobMessage.java - Kafka Job 메시지
+
+#### Exception 클래스 (5개)
+- ✅ AIServiceException.java - 공통 예외
+- ✅ JobNotFoundException.java - Job 미발견 예외
+- ✅ RecommendationNotFoundException.java - 추천 결과 미발견 예외
+- ✅ CircuitBreakerOpenException.java - Circuit Breaker 열림 예외
+- ✅ GlobalExceptionHandler.java - 전역 예외 핸들러
+
+#### Config 클래스 (6개)
+- ✅ RedisConfig.java - Redis 연결 및 Template 설정
+- ✅ KafkaConsumerConfig.java - Kafka Consumer 설정
+- ✅ CircuitBreakerConfig.java - Resilience4j Circuit Breaker 설정
+- ✅ SecurityConfig.java - Spring Security 설정 (내부 API)
+- ✅ SwaggerConfig.java - OpenAPI 문서화 설정
+- ✅ JacksonConfig.java - ObjectMapper Bean 설정
+
+#### Service 레이어 (3개)
+- ✅ CacheService.java - Redis 캐시 처리
+- ✅ JobStatusService.java - Job 상태 관리
+- ✅ AIRecommendationService.java - AI 추천 생성 (Mock)
+
+#### Kafka Consumer (1개)
+- ✅ AIJobConsumer.java - ai-event-generation-job Topic 구독
+
+#### Controller (3개)
+- ✅ HealthController.java - 헬스체크 API
+- ✅ InternalJobController.java - Job 상태 조회 API
+- ✅ InternalRecommendationController.java - AI 추천 결과 조회 API
+
+#### Application (1개)
+- ✅ AiServiceApplication.java - Spring Boot 메인 클래스
+
+## 개발 결과 통계
+
+### 전체 클래스 수
+- **총 32개 Java 클래스** 작성 완료
+
+### 패키지별 클래스 수
+- model/enums: 5개
+- model/dto/response: 7개
+- kafka/message: 1개
+- exception: 5개
+- config: 6개
+- service: 3개
+- kafka/consumer: 1개
+- controller: 3개
+- root: 1개 (Application)
+
+## API 엔드포인트
+
+### Health Check
+- `GET /health` - 서비스 상태 확인
+
+### Internal API (Event Service에서 호출)
+- `GET /internal/jobs/{jobId}/status` - Job 상태 조회
+- `GET /internal/recommendations/{eventId}` - AI 추천 결과 조회
+
+### Actuator
+- `GET /actuator/health` - Spring Actuator 헬스체크
+- `GET /actuator/info` - 서비스 정보
+- `GET /actuator/metrics` - 메트릭
+
+### API Documentation
+- `GET /swagger-ui.html` - Swagger UI
+- `GET /v3/api-docs` - OpenAPI 3.0 스펙
+
+## 컴파일 및 빌드 결과
+
+### 컴파일 테스트
+```bash
+./gradlew ai-service:compileJava
+```
+**결과**: ✅ BUILD SUCCESSFUL (26초)
+
+### 빌드 테스트
+```bash
+./gradlew ai-service:build -x test
+```
+**결과**: ✅ BUILD SUCCESSFUL (7초)
+
+### 생성된 JAR 파일
+- 위치: `ai-service/build/libs/ai-service.jar`
+
+## 주요 기능
+
+### 1. Kafka 비동기 처리
+- Topic: `ai-event-generation-job`
+- Consumer Group: `ai-service-consumers`
+- Manual ACK 모드
+- DLQ 지원
+
+### 2. Redis 캐싱
+- Database: 3
+- TTL 설정:
+  - AI 추천 결과: 24시간 (86400초)
+  - Job 상태: 24시간 (86400초)
+  - 트렌드 분석: 1시간 (3600초)
+
+### 3. Circuit Breaker
+- Failure Rate Threshold: 50%
+- Timeout: 5분 (300초)
+- Sliding Window: 10회
+- Wait Duration in Open State: 60초
+
+### 4. Spring Security
+- 내부 API 전용 (인증 없음)
+- CORS 설정 완료
+- Stateless 세션
+
+## TODO: 추가 개발 필요 항목
+
+### 외부 API 연동 (우선순위: 높음)
+현재 Mock 데이터를 반환하도록 구현되어 있으며, 다음 항목을 추가 개발해야 합니다:
+
+1. **Claude API Client** (Feign Client)
+   - `client/ClaudeApiClient.java`
+   - `client/dto/ClaudeRequest.java`
+   - `client/dto/ClaudeResponse.java`
+   - Claude API 호출 및 응답 파싱
+
+2. **GPT-4 API Client** (Feign Client - 선택)
+   - `client/Gpt4ApiClient.java`
+   - `client/dto/Gpt4Request.java`
+   - `client/dto/Gpt4Response.java`
+   - GPT-4 API 호출 및 응답 파싱
+
+3. **TrendAnalysisService** (트렌드 분석 로직)
+   - `service/TrendAnalysisService.java`
+   - 업종/지역/시즌 기반 트렌드 분석
+   - AI API 호출 및 결과 파싱
+
+4. **Circuit Breaker Manager**
+   - `circuitbreaker/CircuitBreakerManager.java`
+   - `circuitbreaker/fallback/AIServiceFallback.java`
+   - Circuit Breaker 실행 및 Fallback 처리
+
+5. **Feign Client Config**
+   - `client/config/FeignClientConfig.java`
+   - Timeout, Retry, Error Handling 설정
+
+### 개선 항목 (우선순위: 중간)
+1. 로깅 강화 (요청/응답 로깅)
+2. 메트릭 수집 (Micrometer)
+3. 성능 모니터링
+4. 에러 알림 (Slack, Email)
+
+## 환경 변수
+
+### 필수 환경 변수
+```bash
+# Redis
+REDIS_HOST=20.214.210.71
+REDIS_PORT=6379
+REDIS_PASSWORD=Hi5Jessica!
+REDIS_DATABASE=3
+
+# Kafka
+KAFKA_BOOTSTRAP_SERVERS=localhost:9092
+KAFKA_TOPIC_AI_JOB=ai-event-generation-job
+
+# Claude API
+CLAUDE_API_KEY=<your-claude-api-key>
+CLAUDE_API_URL=https://api.anthropic.com/v1/messages
+
+# GPT-4 API (선택)
+GPT4_API_KEY=<your-gpt4-api-key>
+GPT4_API_URL=https://api.openai.com/v1/chat/completions
+
+# AI Provider 선택
+AI_PROVIDER=CLAUDE  # CLAUDE or GPT4
+```
+
+## 실행 방법
+
+### 1. IntelliJ에서 실행
+- Run Configuration 생성 필요
+- 환경 변수 설정 필요
+- Main Class: `com.kt.ai.AiServiceApplication`
+
+### 2. Gradle로 실행
+```bash
+./gradlew ai-service:bootRun
+```
+
+### 3. JAR로 실행
+```bash
+java -jar ai-service/build/libs/ai-service.jar \
+  --REDIS_HOST=20.214.210.71 \
+  --REDIS_PASSWORD=Hi5Jessica! \
+  --CLAUDE_API_KEY=<your-api-key>
+```
+
+## 테스트 방법
+
+### 1. Health Check
+```bash
+curl http://localhost:8083/health
+```
+
+### 2. Swagger UI
+브라우저에서 접속: `http://localhost:8083/swagger-ui.html`
+
+### 3. Kafka 메시지 발행 테스트
+Kafka Producer로 `ai-event-generation-job` Topic에 메시지 발행
+
+## 개발 완료 보고
+
+✅ **AI Service 백엔드 개발이 완료되었습니다.**
+
+### 완료된 작업
+- 총 32개 Java 클래스 작성
+- 컴파일 성공
+- 빌드 성공
+- API 3개 개발 (Health, Job Status, Recommendation)
+- Kafka Consumer 개발
+- Redis 캐싱 구현
+- Circuit Breaker 설정
+
+### 추가 개발 필요
+- 외부 AI API 연동 (Claude/GPT-4)
+- TrendAnalysisService 실제 로직 구현
+- Circuit Breaker Manager 구현
+- Feign Client 개발
+
+현재는 Mock 데이터를 반환하도록 구현되어 있으며, **컴파일 및 빌드는 정상적으로 동작**합니다.
+실제 AI API 연동은 API Key 발급 후 추가 개발이 필요합니다.

develop/dev/package-structure-ai-service.md

@@ -0,0 +1,152 @@
+# AI Service 패키지 구조도
+
+## 프로젝트 구조
+```
+ai-service/
+├── src/
+│   ├── main/
+│   │   ├── java/
+│   │   │   └── com/
+│   │   │       └── kt/
+│   │   │           └── ai/
+│   │   │               ├── AiServiceApplication.java
+│   │   │               │
+│   │   │               ├── controller/
+│   │   │               │   ├── HealthController.java
+│   │   │               │   ├── InternalJobController.java
+│   │   │               │   └── InternalRecommendationController.java
+│   │   │               │
+│   │   │               ├── service/
+│   │   │               │   ├── AIRecommendationService.java
+│   │   │               │   ├── TrendAnalysisService.java
+│   │   │               │   ├── JobStatusService.java
+│   │   │               │   └── CacheService.java
+│   │   │               │
+│   │   │               ├── kafka/
+│   │   │               │   ├── consumer/
+│   │   │               │   │   └── AIJobConsumer.java
+│   │   │               │   └── message/
+│   │   │               │       ├── AIJobMessage.java
+│   │   │               │       └── JobStatusMessage.java
+│   │   │               │
+│   │   │               ├── client/
+│   │   │               │   ├── ClaudeApiClient.java
+│   │   │               │   ├── Gpt4ApiClient.java
+│   │   │               │   ├── dto/
+│   │   │               │   │   ├── ClaudeRequest.java
+│   │   │               │   │   ├── ClaudeResponse.java
+│   │   │               │   │   ├── Gpt4Request.java
+│   │   │               │   │   └── Gpt4Response.java
+│   │   │               │   └── config/
+│   │   │               │       └── FeignClientConfig.java
+│   │   │               │
+│   │   │               ├── model/
+│   │   │               │   ├── dto/
+│   │   │               │   │   ├── request/
+│   │   │               │   │   │   └── (No request DTOs - internal API only)
+│   │   │               │   │   └── response/
+│   │   │               │   │       ├── HealthCheckResponse.java
+│   │   │               │   │       ├── JobStatusResponse.java
+│   │   │               │   │       ├── AIRecommendationResult.java
+│   │   │               │   │       ├── TrendAnalysis.java
+│   │   │               │   │       ├── EventRecommendation.java
+│   │   │               │   │       ├── ExpectedMetrics.java
+│   │   │               │   │       └── ErrorResponse.java
+│   │   │               │   └── enums/
+│   │   │               │       ├── JobStatus.java
+│   │   │               │       ├── AIProvider.java
+│   │   │               │       ├── EventMechanicsType.java
+│   │   │               │       └── ServiceStatus.java
+│   │   │               │
+│   │   │               ├── config/
+│   │   │               │   ├── RedisConfig.java
+│   │   │               │   ├── KafkaConsumerConfig.java
+│   │   │               │   ├── CircuitBreakerConfig.java
+│   │   │               │   ├── SecurityConfig.java
+│   │   │               │   └── SwaggerConfig.java
+│   │   │               │
+│   │   │               ├── circuitbreaker/
+│   │   │               │   ├── CircuitBreakerManager.java
+│   │   │               │   └── fallback/
+│   │   │               │       └── AIServiceFallback.java
+│   │   │               │
+│   │   │               └── exception/
+│   │   │                   ├── GlobalExceptionHandler.java
+│   │   │                   ├── JobNotFoundException.java
+│   │   │                   ├── RecommendationNotFoundException.java
+│   │   │                   ├── CircuitBreakerOpenException.java
+│   │   │                   └── AIServiceException.java
+│   │   │
+│   │   └── resources/
+│   │       ├── application.yml
+│   │       └── logback-spring.xml
+│   │
+│   └── test/
+│       └── java/
+│           └── com/
+│               └── kt/
+│                   └── ai/
+│                       └── (테스트 코드는 작성하지 않음)
+│
+├── build.gradle
+└── README.md
+```
+
+## 아키텍처 패턴
+- **Layered Architecture** 적용
+- Controller → Service → Client/Kafka 레이어 구조
+- Service 레이어에 Interface 사용하지 않음 (내부 API 전용 서비스)
+
+## 주요 컴포넌트 설명
+
+### 1. Controller Layer
+- **HealthController**: 서비스 상태 및 외부 연동 확인
+- **InternalJobController**: Job 상태 조회 (Event Service에서 호출)
+- **InternalRecommendationController**: AI 추천 결과 조회 (Event Service에서 호출)
+
+### 2. Service Layer
+- **AIRecommendationService**: AI 트렌드 분석 및 이벤트 추천 총괄
+- **TrendAnalysisService**: 업종/지역/시즌 트렌드 분석
+- **JobStatusService**: Job 상태 관리 (Redis 기반)
+- **CacheService**: Redis 캐싱 처리
+
+### 3. Kafka Layer
+- **AIJobConsumer**: Kafka ai-event-generation-job Topic 구독 및 처리
+- **AIJobMessage**: Kafka 메시지 DTO
+- **JobStatusMessage**: Job 상태 변경 메시지
+
+### 4. Client Layer
+- **ClaudeApiClient**: Claude API 연동 (Feign Client)
+- **Gpt4ApiClient**: GPT-4 API 연동 (Feign Client - 선택)
+- **FeignClientConfig**: Feign Client 공통 설정
+
+### 5. Model Layer
+- **Response DTOs**: API 응답 객체
+- **Enums**: 상태 및 타입 정의
+
+### 6. Config Layer
+- **RedisConfig**: Redis 연결 및 캐싱 설정
+- **KafkaConsumerConfig**: Kafka Consumer 설정
+- **CircuitBreakerConfig**: Resilience4j Circuit Breaker 설정
+- **SecurityConfig**: Spring Security 설정
+- **SwaggerConfig**: API 문서화 설정
+
+### 7. Circuit Breaker Layer
+- **CircuitBreakerManager**: Circuit Breaker 실행 및 관리
+- **AIServiceFallback**: AI API 장애 시 Fallback 처리
+
+### 8. Exception Layer
+- **GlobalExceptionHandler**: 전역 예외 처리
+- **Custom Exceptions**: 서비스별 예외 정의
+
+## 외부 연동
+- **Redis**: 작업 상태 및 추천 결과 캐싱 (TTL 24시간)
+- **Kafka**: ai-event-generation-job Topic 구독
+- **Claude API / GPT-4 API**: AI 트렌드 분석 및 추천 생성
+- **PostgreSQL**: (미사용 - AI Service는 DB 불필요)
+
+## 특이사항
+- AI Service는 데이터베이스를 사용하지 않음 (Redis만 사용)
+- 모든 상태와 결과는 Redis에 저장 (TTL 24시간)
+- Kafka Consumer를 통한 비동기 작업 처리
+- Circuit Breaker를 통한 외부 API 장애 대응