kt-event-marketing/design/backend/class/ai-service-simple.puml

@startuml
!theme mono

title AI Service 클래스 다이어그램 (요약) - Clean Architecture

' ===== Presentation Layer =====
package "Presentation Layer" <<Rectangle>> #E8F5E9 {
    class HealthController
    class InternalRecommendationController
    class InternalJobController
}

' ===== Application Layer =====
package "Application Layer (Use Cases)" <<Rectangle>> #FFF9C4 {
    class AIRecommendationService
    class TrendAnalysisService
    class JobStatusService
    class CacheService
}

' ===== Domain Layer =====
package "Domain Layer" <<Rectangle>> #E1BEE7 {
    class AIRecommendationResult
    class TrendAnalysis
    class EventRecommendation
    class ExpectedMetrics
    class JobStatusResponse
    class HealthCheckResponse

    enum AIProvider
    enum JobStatus
    enum EventMechanicsType
    enum ServiceStatus
}

' ===== Infrastructure Layer =====
package "Infrastructure Layer" <<Rectangle>> #FFCCBC {
    interface ClaudeApiClient
    class ClaudeRequest
    class ClaudeResponse
    class CircuitBreakerManager
    class AIServiceFallback
    class AIJobConsumer
    class AIJobMessage
}

' ===== Exception Layer =====
package "Exception Layer" <<Rectangle>> #FFEBEE {
    class GlobalExceptionHandler
    class AIServiceException
    class JobNotFoundException
    class RecommendationNotFoundException
    class CircuitBreakerOpenException
}

' ===== Configuration Layer =====
package "Configuration Layer" <<Rectangle>> #E3F2FD {
    class SecurityConfig
    class RedisConfig
    class CircuitBreakerConfig
    class KafkaConsumerConfig
    class JacksonConfig
    class SwaggerConfig
}

' ===== 레이어 간 의존성 =====
InternalRecommendationController --> AIRecommendationService
InternalJobController --> JobStatusService

AIRecommendationService --> TrendAnalysisService
AIRecommendationService --> CacheService
AIRecommendationService --> JobStatusService
AIRecommendationService --> ClaudeApiClient
AIRecommendationService --> CircuitBreakerManager
AIRecommendationService --> AIServiceFallback

TrendAnalysisService --> ClaudeApiClient
TrendAnalysisService --> CircuitBreakerManager
TrendAnalysisService --> AIServiceFallback

JobStatusService --> CacheService

AIJobConsumer --> AIRecommendationService

AIRecommendationService ..> AIRecommendationResult : creates
TrendAnalysisService ..> TrendAnalysis : creates
JobStatusService ..> JobStatusResponse : creates

AIRecommendationResult *-- TrendAnalysis
AIRecommendationResult *-- EventRecommendation
EventRecommendation *-- ExpectedMetrics

ClaudeApiClient ..> ClaudeRequest : uses
ClaudeApiClient ..> ClaudeResponse : returns

GlobalExceptionHandler ..> AIServiceException : handles
GlobalExceptionHandler ..> JobNotFoundException : handles
GlobalExceptionHandler ..> RecommendationNotFoundException : handles
GlobalExceptionHandler ..> CircuitBreakerOpenException : handles

note right of InternalRecommendationController
  **Controller API Mappings**

  GET /api/v1/ai-service/internal/recommendations/{eventId}
  → AI 추천 결과 조회

  GET /api/v1/ai-service/internal/recommendations/debug/redis-keys
  → Redis 키 조회 (디버그)

  GET /api/v1/ai-service/internal/recommendations/debug/redis-key/{key}
  → Redis 특정 키 조회 (디버그)

  GET /api/v1/ai-service/internal/recommendations/debug/search-all-databases
  → 모든 Redis DB 검색 (디버그)

  GET /api/v1/ai-service/internal/recommendations/debug/create-test-data/{eventId}
  → 테스트 데이터 생성 (디버그)
end note

note right of InternalJobController
  **Controller API Mappings**

  GET /api/v1/ai-service/internal/jobs/{jobId}/status
  → 작업 상태 조회

  GET /api/v1/ai-service/internal/jobs/debug/create-test-job/{jobId}
  → Job 테스트 데이터 생성 (디버그)
end note

note right of HealthController
  **Controller API Mappings**

  GET /api/v1/ai-service/health
  → 헬스 체크
end note

note bottom of "Application Layer (Use Cases)"
  **Clean Architecture - Use Cases**

  - AIRecommendationService: AI 추천 생성 유스케이스
  - TrendAnalysisService: 트렌드 분석 유스케이스
  - JobStatusService: 작업 상태 관리 유스케이스
  - CacheService: 캐싱 인프라 서비스

  비즈니스 로직과 외부 의존성 격리
end note

note bottom of "Domain Layer"
  **Clean Architecture - Entities**

  - 순수 비즈니스 도메인 객체
  - 외부 의존성 없음 (Framework-independent)
  - 불변 객체 (Immutable)
  - Builder 패턴 적용
end note

note bottom of "Infrastructure Layer"
  **Clean Architecture - External Interfaces**

  - ClaudeApiClient: 외부 AI API 연동
  - CircuitBreakerManager: 장애 격리 인프라
  - AIJobConsumer: Kafka 메시지 수신
  - AIServiceFallback: Fallback 로직

  외부 시스템과의 통신 계층
end note

note top of "Configuration Layer"
  **Spring Configuration**

  - SecurityConfig: 보안 설정
  - RedisConfig: Redis 연결 설정
  - CircuitBreakerConfig: Circuit Breaker 설정
  - KafkaConsumerConfig: Kafka Consumer 설정
  - JacksonConfig: JSON 변환 설정
  - SwaggerConfig: API 문서 설정
end note

note as N1
  **Clean Architecture 적용**

  1. **Domain Layer (Core)**
     - 순수 비즈니스 로직
     - 외부 의존성 없음

  2. **Application Layer (Use Cases)**
     - 비즈니스 유스케이스 구현
     - Domain과 Infrastructure 연결

  3. **Infrastructure Layer**
     - 외부 시스템 연동
     - 데이터베이스, API, 메시징

  4. **Presentation Layer**
     - REST API 컨트롤러
     - 요청/응답 처리

  **의존성 규칙:**
  Presentation → Application → Domain
  Infrastructure → Application
  (Domain은 외부 의존성 없음)
end note

@enduml