kt-event-marketing/design/backend/sequence/inner/README-event-sequences.md

Event Service - 내부 시퀀스 설계 완료

문서 정보

• 작성일: 2025-10-22
• 작성자: System Architect
• 관련 문서:
  • 유저스토리
  • 외부 시퀀스 - 이벤트생성플로우
  • 논리 아키텍처

---

작성 완료 시나리오 (10개)

1. event-목적선택.puml

• 유저스토리: UFR-EVENT-020
• 기능: 이벤트 목적 선택 및 저장
• 주요 흐름:
  • POST /api/events/purposes
  • EventService → EventRepository → Event DB 저장
  • Redis 캐시 저장 (TTL 30분)
  • Kafka EventCreated 이벤트 발행
• 특징: 캐시 히트 시 DB 조회 생략

2. event-AI추천요청.puml

• 유저스토리: UFR-EVENT-030
• 기능: AI 추천 요청 (Kafka Job 발행)
• 주요 흐름:
  • POST /api/events/{id}/ai-recommendations
  • EventService → JobService
  • Kafka ai-job 토픽 발행
  • Job ID 즉시 반환 (202 Accepted)
• 특징: 비동기 처리, AI Service는 백그라운드에서 Kafka 구독

3. event-추천결과조회.puml

• 유저스토리: UFR-EVENT-030 (결과 조회)
• 기능: AI 추천 결과 폴링 조회
• 주요 흐름:
  • GET /api/jobs/{jobId}/status
  • JobService → Redis 캐시 조회
  • Job 상태에 따라 응답 (COMPLETED/PROCESSING/FAILED)
• 특징: 최대 30초 동안 폴링 (2초 간격)

4. event-이미지생성요청.puml

• 유저스토리: UFR-CONT-010
• 기능: 이미지 생성 요청 (Kafka Job 발행)
• 주요 흐름:
  • POST /api/events/{id}/content-generation
  • EventService → JobService
  • Kafka image-job 토픽 발행
  • Job ID 즉시 반환 (202 Accepted)
• 특징: Content Service는 백그라운드에서 3가지 스타일 생성

5. event-이미지결과조회.puml

• 유저스토리: UFR-CONT-010 (결과 조회)
• 기능: 이미지 생성 결과 폴링 조회
• 주요 흐름:
  • GET /api/jobs/{jobId}/status
  • JobService → Redis 캐시 조회
  • 완료 시 3가지 스타일 이미지 URL 반환
• 특징: 최대 30초 동안 폴링 (3초 간격)

6. event-콘텐츠선택.puml

• 유저스토리: UFR-CONT-020
• 기능: 선택한 콘텐츠 저장
• 주요 흐름:
  • PUT /api/events/drafts/{id}/content
  • EventService → EventRepository
  • 선택한 이미지 URL 및 편집 내용 저장
  • 캐시 무효화
• 특징: 텍스트, 색상 편집 내용 적용

7. event-최종승인및배포.puml

• 유저스토리: UFR-EVENT-050
• 기능: 최종 승인 및 Distribution Service 동기 호출
• 주요 흐름:
  • POST /api/events/{id}/publish
  • 이벤트 상태 변경 (DRAFT → APPROVED)
  • Kafka EventCreated 이벤트 발행
  • Distribution Service 동기 호출 (POST /api/distribution/distribute)
  • 배포 완료 후 상태 변경 (APPROVED → ACTIVE)
• 특징: Circuit Breaker 적용, Timeout 70초

8. event-상세조회.puml

• 유저스토리: UFR-EVENT-060
• 기능: 이벤트 상세 정보 조회
• 주요 흐름:
  • GET /api/events/{id}
  • Redis 캐시 확인 (TTL 5분)
  • 캐시 미스 시 DB 조회 (JOIN으로 경품, 배포 이력 포함)
  • 사용자 권한 검증
• 특징: JOIN 쿼리로 관련 데이터 한 번에 조회

9. event-목록조회.puml

• 유저스토리: UFR-EVENT-070
• 기능: 이벤트 목록 조회 (필터/검색)
• 주요 흐름:
  • GET /api/events?status={status}&keyword={keyword}
  • Redis 캐시 확인 (TTL 1분)
  • 캐시 미스 시 DB 조회 (필터/검색 조건 적용)
  • 페이지네이션 (20개/페이지)
• 특징: 인덱스 활용 (user_id, status, created_at)

10. event-대시보드조회.puml

• 유저스토리: UFR-EVENT-010
• 기능: 대시보드 이벤트 목록
• 주요 흐름:
  • GET /api/events/dashboard
  • Redis 캐시 확인 (TTL 1분)
  • 캐시 미스 시 병렬 조회 (진행중/예정/종료)
  • 각 섹션 최대 5개 표시
• 특징: 병렬 쿼리로 성능 최적화

---

설계 원칙 준수 사항

1. 공통설계원칙 준수

• ✅ 모든 레이어 표시 (Controller → Service → Repository)
• ✅ 외부 시스템/인프라 <<E>> 표시
• ✅ 캐시 접근 명시 (Redis)
• ✅ DB 접근 명시 (PostgreSQL)
• ✅ Kafka 이벤트/Job 발행 표시

2. 내부시퀀스설계 가이드 준수

• ✅ 각 시나리오별 독립 파일 생성
• ✅ PlantUML !theme mono 적용
• ✅ 명확한 타이틀 (서비스명 + 시나리오 + 유저스토리)
• ✅ 참여자 타입 표시 (<>, <>, <>, <>)
• ✅ 데이터베이스 쿼리 표시
• ✅ 캐싱 전략 표시 (Cache-Aside)
• ✅ 비동기 처리 흐름 표시 (Kafka)

3. Event-Driven 아키텍처 반영

• ✅ Kafka Event Topics 발행 (EventCreated)
• ✅ Kafka Job Topics 발행 (ai-job, image-job)
• ✅ 비동기 작업 Job ID 즉시 반환 (202 Accepted)
• ✅ 폴링 방식 결과 조회 (GET /api/jobs/{jobId}/status)

4. Resilience 패턴 명시

• ✅ Circuit Breaker 적용 표시 (Distribution Service 호출)
• ✅ Timeout 설정 표시 (70초)
• ✅ 캐싱 전략 표시 (TTL 설정)

---

검증 체크리스트

유저스토리 매칭

• UFR-EVENT-010: 대시보드 이벤트 목록 → event-대시보드조회.puml
• UFR-EVENT-020: 이벤트 목적 선택 → event-목적선택.puml
• UFR-EVENT-030: AI 이벤트 추천 → event-AI추천요청.puml, event-추천결과조회.puml
• UFR-EVENT-040: 배포 채널 선택 → (최종승인에 포함)
• UFR-EVENT-050: 최종 승인 및 배포 → event-최종승인및배포.puml
• UFR-EVENT-060: 이벤트 상세 조회 → event-상세조회.puml
• UFR-EVENT-070: 이벤트 목록 관리 → event-목록조회.puml
• UFR-CONT-010: SNS 이미지 생성 → event-이미지생성요청.puml, event-이미지결과조회.puml
• UFR-CONT-020: 콘텐츠 편집 → event-콘텐츠선택.puml

외부 시퀀스 일치성

• Kafka Job 발행 (AI 추천) - ai-job 토픽
• Kafka Job 발행 (이미지 생성) - image-job 토픽
• Kafka Event 발행 (EventCreated) - event-topic
• Distribution Service 동기 호출 (REST API)
• Redis 캐싱 전략 (Cache-Aside)
• Job 폴링 방식 (5초 간격 AI, 3초 간격 이미지)

논리 아키텍처 일치성

• Event Service 책임 범위
• Kafka 통합 메시징 플랫폼
• Redis 캐시 키 패턴
• Database-per-Service 원칙
• Resilience 패턴 적용

---

파일 위치

design/backend/sequence/inner/
├── event-목적선택.puml
├── event-AI추천요청.puml
├── event-추천결과조회.puml
├── event-이미지생성요청.puml
├── event-이미지결과조회.puml
├── event-콘텐츠선택.puml
├── event-최종승인및배포.puml
├── event-상세조회.puml
├── event-목록조회.puml
└── event-대시보드조회.puml

---

다이어그램 확인 방법

PlantUML 렌더링

1. https://www.plantuml.com/plantuml/uml/ 접속
2. 각 .puml 파일 내용 붙여넣기
3. 다이어그램 시각적 확인

로컬 렌더링 (IntelliJ/VS Code)

• IntelliJ: PlantUML Integration 플러그인 설치
• VS Code: PlantUML 확장 설치

---

주요 설계 결정사항

1. 비동기 처리 전략

• AI 추천: Kafka ai-job 토픽 발행 → 비동기 처리 → Job 폴링
• 이미지 생성: Kafka image-job 토픽 발행 → 비동기 처리 → Job 폴링
• 이유: 장시간 작업 (10초, 5초)을 동기로 처리 시 사용자 경험 저하

2. 배포 동기 처리

• Distribution Service: REST API 동기 호출 (POST /api/distribution/distribute)
• 이유: 배포 완료 여부를 즉시 확인하고 사용자에게 피드백 제공
• Resilience: Circuit Breaker + Timeout 70초

3. 캐싱 전략

• 목적 선택: TTL 30분 (임시 저장 성격)
• 상세 조회: TTL 5분 (자주 조회, 실시간성 중요)
• 목록/대시보드: TTL 1분 (실시간 업데이트)
• 이유: 조회 빈도와 실시간성 요구사항에 따라 차등 적용

4. Job 상태 관리

• Redis 캐시: Job 상태 및 결과 저장 (TTL 1시간)
• 폴링 방식: 클라이언트가 주기적으로 Job 상태 확인
• 이유: 간단한 구현, WebSocket 대비 낮은 복잡도

---

성능 최적화 포인트

1. 캐시 히트율

• 목적 선택: 90% 예상 (재방문 시 캐시 활용)
• 상세 조회: 95% 예상 (자주 조회)
• 목록/대시보드: 90% 예상 (1분 TTL로 대부분 캐시 활용)

2. 데이터베이스 최적화

• 인덱스: user_id, status, created_at
• JOIN 최적화: 상세 조회 시 관련 데이터 한 번에 조회
• 페이지네이션: 20개/페이지로 쿼리 부하 감소

3. 병렬 처리

• 대시보드 조회: 진행중/예정/종료 병렬 쿼리
• 이미지 생성: 3가지 스타일 병렬 생성 (Content Service에서)

---

향후 개선 방안

Phase 2 이후

1. WebSocket 실시간 푸시: Job 폴링을 WebSocket으로 전환
2. Event Sourcing: 모든 상태 변경을 이벤트로 저장
3. GraphQL: 클라이언트 맞춤형 데이터 조회
4. Database Read Replica: 읽기 부하 분산

---

문서 작성 완료일: 2025-10-22 작성자: System Architect 상태: ✅ 완료 (10개 시나리오 모두 작성)