P82282866/kt-event-marketing
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
kt-event-marketing/design/backend/sequence/inner/README-event-sequences.md
cherry2250 9fd060b275 add outer/inner sequence
2025-10-22 14:13:57 +09:00

9.3 KiB
Raw Blame History

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

문서 정보

작성 완료 시나리오 (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개 시나리오 모두 작성)