P82282866/kt-event-marketing
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
kt-event-marketing/develop/dev/dev-backend-ai-service.md
박세원 f0699b2e2b add ai-service
2025-10-27 11:09:12 +09:00

7.5 KiB
Raw Blame History

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