kt-event-marketing/develop/dev/dev-backend-ai-service.md

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 스펙

컴파일 및 빌드 결과

컴파일 테스트

./gradlew ai-service:compileJava

결과: ✅ BUILD SUCCESSFUL (26초)

빌드 테스트

./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)

환경 변수

필수 환경 변수

# 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로 실행

./gradlew ai-service:bootRun

3. JAR로 실행

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

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 발급 후 추가 개발이 필요합니다.