# 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 장애 대응