kt-event-marketing/design/backend/class/event-service-class-design.md

Event Service 클래스 설계서

1. 개요

1.1 목적

Event Service의 Clean Architecture 기반 클래스 설계를 정의합니다.

1.2 설계 원칙

• 아키텍처 패턴: Clean Architecture
• 패키지 그룹: com.kt.event
• 의존성 방향: Presentation → Application → Domain ← Infrastructure

1.3 핵심 특징

• 복잡한 이벤트 생명주기 관리 (DRAFT → PUBLISHED → ENDED)
• 상태 머신 패턴 적용
• AI 서비스 비동기 연동 (Kafka)
• Content Service 동기 연동 (Feign)
• Redis 캐시 활용

---

2. 계층별 구조

2.1 Domain Layer (핵심 비즈니스 로직)

2.1.1 Entity

Event (이벤트 집합 루트)

- 책임: 이벤트 전체 생명주기 관리
- 상태: DRAFT, PUBLISHED, ENDED
- 비즈니스 규칙:
  * DRAFT 상태에서만 수정 가능
  * 배포 시 필수 데이터 검증 (이벤트명, 기간, 이미지, 채널)
  * 상태 전이 제약 (DRAFT → PUBLISHED → ENDED)
- 관계:
  * 1:N GeneratedImage (생성된 이미지)
  * 1:N AiRecommendation (AI 추천안)

AiRecommendation (AI 추천 엔티티)

- 책임: AI가 생성한 이벤트 기획안 관리
- 속성: 이벤트명, 설명, 프로모션 유형, 타겟 고객
- 선택 상태: isSelected (단일 선택)

GeneratedImage (생성 이미지 엔티티)

- 책임: 이벤트별 생성된 이미지 관리
- 속성: 이미지 URL, 스타일, 플랫폼
- 선택 상태: isSelected (단일 선택)

Job (비동기 작업 엔티티)

- 책임: AI 추천, 이미지 생성 등 비동기 작업 상태 관리
- 상태: PENDING, PROCESSING, COMPLETED, FAILED
- 진행률: 0~100 (progress)
- 결과: Redis 키 (resultKey) 또는 에러 메시지

2.1.2 Enums

• EventStatus: DRAFT, PUBLISHED, ENDED
• JobStatus: PENDING, PROCESSING, COMPLETED, FAILED
• JobType: AI_RECOMMENDATION, IMAGE_GENERATION

2.1.3 Repository Interfaces

• EventRepository: 이벤트 조회, 필터링, 페이징
• AiRecommendationRepository: AI 추천 관리
• GeneratedImageRepository: 이미지 관리
• JobRepository: 작업 상태 관리

---

2.2 Application Layer (유스케이스)

2.2.1 Services

EventService (핵심 오케스트레이터)

책임:
- 이벤트 전체 생명주기 조율
- AI 서비스 연동 (Kafka 비동기)
- Content 서비스 연동 (Feign 동기)
- 트랜잭션 경계 관리

주요 유스케이스:
1. createEvent(): 이벤트 생성 (Step 1: 목적 선택)
2. requestAiRecommendations(): AI 추천 요청 (Step 2)
3. selectRecommendation(): AI 추천 선택
4. requestImageGeneration(): 이미지 생성 요청 (Step 3)
5. selectImage(): 이미지 선택
6. selectChannels(): 배포 채널 선택 (Step 4)
7. publishEvent(): 이벤트 배포 (Step 5)
8. endEvent(): 이벤트 종료

JobService (작업 관리)

책임:
- 비동기 작업 상태 조회
- 작업 진행률 업데이트
- 작업 완료/실패 처리

주요 유스케이스:
1. createJob(): 작업 생성
2. getJobStatus(): 작업 상태 조회
3. updateJobProgress(): 진행률 업데이트
4. completeJob(): 작업 완료 처리
5. failJob(): 작업 실패 처리

2.2.2 DTOs

Request DTOs

• SelectObjectiveRequest: 목적 선택
• AiRecommendationRequest: AI 추천 요청 (매장 정보 포함)
• SelectRecommendationRequest: AI 추천 선택 + 커스터마이징
• ImageGenerationRequest: 이미지 생성 요청 (스타일, 플랫폼)
• SelectImageRequest: 이미지 선택
• ImageEditRequest: 이미지 편집
• SelectChannelsRequest: 배포 채널 선택
• UpdateEventRequest: 이벤트 수정

Response DTOs

• EventCreatedResponse: 이벤트 생성 응답
• EventDetailResponse: 이벤트 상세 (이미지, 추천 포함)
• JobAcceptedResponse: 작업 접수 응답
• JobStatusResponse: 작업 상태 응답
• ImageGenerationResponse: 이미지 생성 응답

Kafka Message DTOs

• AIEventGenerationJobMessage: AI 작업 메시지
• ImageGenerationJobMessage: 이미지 생성 작업 메시지
• EventCreatedMessage: 이벤트 생성 이벤트

---

2.3 Infrastructure Layer (기술 구현)

2.3.1 Kafka (비동기 메시징)

AIJobKafkaProducer

책임: AI 추천 생성 작업 발행
토픽: ai-event-generation-job
메시지: AIEventGenerationJobMessage

AIJobKafkaConsumer

책임: AI 작업 결과 수신 및 처리
처리: COMPLETED, FAILED, PROCESSING 상태별 분기
수동 커밋: Acknowledgment 사용

ImageJobKafkaConsumer

책임: 이미지 생성 작업 결과 수신
처리: 생성된 이미지 DB 저장

EventKafkaProducer

책임: 이벤트 생성 이벤트 발행
토픽: event-created
용도: Distribution Service 연동

2.3.2 Client (외부 서비스 연동)

ContentServiceClient (Feign)

대상: Content Service (포트 8082)
API: POST /api/v1/content/images/generate
요청: ContentImageGenerationRequest
응답: ContentJobResponse (Job ID 반환)

2.3.3 Config

RedisConfig

책임: Redis 연결 설정
용도:
- AI 추천 결과 임시 저장
- 이미지 생성 결과 임시 저장
- Job 결과 캐싱

---

2.4 Presentation Layer (API)

2.4.1 Controllers

EventController

Base Path: /api/v1/events

주요 엔드포인트:
1. POST /objectives - 이벤트 목적 선택 (생성)
2. GET /events - 이벤트 목록 조회 (페이징, 필터링)
3. GET /events/{id} - 이벤트 상세 조회
4. DELETE /events/{id} - 이벤트 삭제
5. POST /events/{id}/publish - 이벤트 배포
6. POST /events/{id}/end - 이벤트 종료
7. POST /events/{id}/ai-recommendations - AI 추천 요청
8. PUT /events/{id}/recommendations - AI 추천 선택
9. POST /events/{id}/images - 이미지 생성 요청
10. PUT /events/{id}/images/{imageId}/select - 이미지 선택
11. PUT /events/{id}/images/{imageId}/edit - 이미지 편집
12. PUT /events/{id}/channels - 배포 채널 선택
13. PUT /events/{id} - 이벤트 수정

JobController

Base Path: /api/v1/jobs

엔드포인트:
1. GET /jobs/{id} - 작업 상태 조회

---

3. 핵심 플로우

3.1 이벤트 생성 플로우

1. 목적 선택 (POST /objectives)
   → Event 생성 (DRAFT 상태)

2. AI 추천 요청 (POST /events/{id}/ai-recommendations)
   → Job 생성 (AI_RECOMMENDATION)
   → Kafka 메시지 발행 (ai-event-generation-job)
   → AI Service 처리
   → Kafka 메시지 수신 (결과)
   → Redis 캐시 저장
   → Job 완료 처리

3. AI 추천 선택 (PUT /events/{id}/recommendations)
   → Redis에서 추천 목록 조회
   → 선택 + 커스터마이징 적용
   → Event 업데이트 (eventName, description, period)

4. 이미지 생성 요청 (POST /events/{id}/images)
   → Content Service 호출 (Feign)
   → Job ID 반환
   → 폴링으로 상태 확인

5. 이미지 선택 (PUT /events/{id}/images/{imageId}/select)
   → Event.selectedImageId 업데이트
   → GeneratedImage.isSelected = true

6. 배포 채널 선택 (PUT /events/{id}/channels)
   → Event.channels 업데이트

7. 이벤트 배포 (POST /events/{id}/publish)
   → 필수 데이터 검증
   → 상태 변경 (DRAFT → PUBLISHED)
   → Kafka 메시지 발행 (event-created)

3.2 상태 머신 다이어그램

DRAFT → publish() → PUBLISHED → end() → ENDED
  ↑                     |
  |                     ↓
  └─────── (수정 불가) ─────┘

상태별 제약:

• DRAFT: 모든 수정 가능, 삭제 가능
• PUBLISHED: 수정 불가, 삭제 불가, 종료만 가능
• ENDED: 모든 변경 불가 (읽기 전용)

---

4. 비동기 작업 처리

4.1 Job 생명주기

PENDING → start() → PROCESSING → complete() → COMPLETED
                         ↓
                      fail() → FAILED

4.2 작업 유형별 처리

AI_RECOMMENDATION (AI 추천 생성)

• 발행: AIJobKafkaProducer
• 수신: AIJobKafkaConsumer
• 결과: Redis 캐시 (추천 목록)
• 시간: 10~30초

IMAGE_GENERATION (이미지 생성)

• 발행: EventService → ContentServiceClient
• 수신: ImageJobKafkaConsumer (Content Service에서 발행)
• 결과: GeneratedImage 엔티티 (DB 저장)
• 시간: 30~60초

---

5. 패키지 구조

com.kt.event.eventservice
├── domain/
│   ├── entity/
│   │   ├── Event.java
│   │   ├── AiRecommendation.java
│   │   ├── GeneratedImage.java
│   │   └── Job.java
│   ├── enums/
│   │   ├── EventStatus.java
│   │   ├── JobStatus.java
│   │   └── JobType.java
│   └── repository/
│       ├── EventRepository.java
│       ├── AiRecommendationRepository.java
│       ├── GeneratedImageRepository.java
│       └── JobRepository.java
├── application/
│   ├── service/
│   │   ├── EventService.java
│   │   └── JobService.java
│   └── dto/
│       ├── request/
│       │   ├── SelectObjectiveRequest.java
│       │   ├── AiRecommendationRequest.java
│       │   ├── SelectRecommendationRequest.java
│       │   ├── ImageGenerationRequest.java
│       │   ├── SelectImageRequest.java
│       │   ├── ImageEditRequest.java
│       │   ├── SelectChannelsRequest.java
│       │   └── UpdateEventRequest.java
│       ├── response/
│       │   ├── EventCreatedResponse.java
│       │   ├── EventDetailResponse.java
│       │   ├── JobAcceptedResponse.java
│       │   ├── JobStatusResponse.java
│       │   ├── ImageGenerationResponse.java
│       │   └── ImageEditResponse.java
│       └── kafka/
│           ├── AIEventGenerationJobMessage.java
│           ├── ImageGenerationJobMessage.java
│           └── EventCreatedMessage.java
├── infrastructure/
│   ├── kafka/
│   │   ├── AIJobKafkaProducer.java
│   │   ├── AIJobKafkaConsumer.java
│   │   ├── ImageJobKafkaConsumer.java
│   │   └── EventKafkaProducer.java
│   ├── client/
│   │   └── ContentServiceClient.java (Feign)
│   ├── client.dto/
│   │   ├── ContentImageGenerationRequest.java
│   │   └── ContentJobResponse.java
│   └── config/
│       └── RedisConfig.java
├── presentation/
│   └── controller/
│       ├── EventController.java
│       └── JobController.java
└── config/
    ├── SecurityConfig.java
    ├── KafkaConfig.java
    └── DevAuthenticationFilter.java

---

6. 의존성 방향

6.1 Clean Architecture 계층

Presentation Layer (EventController)
         ↓ depends on
Application Layer (EventService)
         ↓ depends on
Domain Layer (Event, EventRepository)
         ↑ implements
Infrastructure Layer (EventRepositoryImpl, Kafka, Feign)

6.2 핵심 원칙

1. Domain Layer는 외부 의존성 없음 (순수 비즈니스 로직)
2. Application Layer는 Domain을 조율 (유스케이스)
3. Infrastructure Layer는 Domain 인터페이스 구현 (기술 세부사항)
4. Presentation Layer는 Application 호출 (API 엔드포인트)

---

7. 주요 설계 패턴

7.1 Domain 패턴

• Aggregate Root: Event (경계 내 일관성 보장)
• State Machine: EventStatus, JobStatus (상태 전이 제약)
• Value Object: StoreInfo, Customizations (불변 값)

7.2 Application 패턴

• Service Layer: EventService, JobService (유스케이스 조율)
• DTO Pattern: Request/Response 분리 (계층 간 데이터 전송)
• Repository Pattern: EventRepository (영속성 추상화)

7.3 Infrastructure 패턴

• Adapter Pattern: ContentServiceClient (외부 서비스 연동)
• Producer/Consumer: Kafka 메시징 (비동기 통신)
• Cache-Aside: Redis 캐싱 (성능 최적화)

---

8. 트랜잭션 경계

8.1 @Transactional 적용 위치

EventService:
- createEvent() - 쓰기
- deleteEvent() - 쓰기
- publishEvent() - 쓰기
- endEvent() - 쓰기
- updateEvent() - 쓰기
- requestAiRecommendations() - 쓰기 (Job 생성)
- selectRecommendation() - 쓰기
- selectImage() - 쓰기
- selectChannels() - 쓰기

JobService:
- createJob() - 쓰기
- updateJobProgress() - 쓰기
- completeJob() - 쓰기
- failJob() - 쓰기

8.2 읽기 전용 트랜잭션

@Transactional(readOnly = true):
- getEvent()
- getEvents()
- getJobStatus()

---

9. 보안 및 인증

9.1 인증 방식

• 개발 환경: DevAuthenticationFilter (Header 기반)
• 운영 환경: JWT 인증 (JwtAuthenticationFilter)

9.2 인가 처리

@AuthenticationPrincipal UserPrincipal
- userId: 요청자 ID
- storeId: 매장 ID

검증:
- Event는 userId로 소유권 확인
- EventRepository.findByEventIdAndUserId() 사용

---

10. 에러 처리

10.1 공통 에러 코드

ErrorCode:
- EVENT_001: 이벤트를 찾을 수 없음
- EVENT_002: 이벤트 수정/삭제 불가 (상태 제약)
- EVENT_003: 선택한 리소스를 찾을 수 없음
- JOB_001: 작업을 찾을 수 없음
- JOB_002: 작업 상태 변경 불가

10.2 예외 처리

Domain Layer:
- IllegalStateException (상태 전이 제약 위반)
- IllegalArgumentException (비즈니스 규칙 위반)

Application Layer:
- BusinessException (비즈니스 로직 에러)

Infrastructure Layer:
- InfraException (외부 시스템 에러)

---

11. 테스트 전략

11.1 단위 테스트

Domain Layer:
- Event 상태 전이 로직
- 비즈니스 규칙 검증

Application Layer:
- EventService 유스케이스
- DTO 변환 로직

11.2 통합 테스트

Infrastructure Layer:
- Kafka Producer/Consumer
- Feign Client
- Redis 캐싱

Presentation Layer:
- REST API 엔드포인트
- 인증/인가

---

12. 파일 정보

12.1 다이어그램 파일

• 상세 다이어그램: design/backend/class/event-service.puml
• 요약 다이어그램: design/backend/class/event-service-simple.puml

12.2 참조 문서

• 공통 컴포넌트: design/backend/class/common-base.puml
• API 설계서: design/backend/api/spec/event-service-api.yaml
• 데이터 설계서: design/backend/database/event-service-schema.sql

---

작성일: 2025-10-29 작성자: Backend Architect (Claude Code) 버전: 1.0.0