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

## 컴파일 및 빌드 결과

### 컴파일 테스트
```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 발급 후 추가 개발이 필요합니다.