kt-event-marketing/design/backend/sequence/outer/README.md

KT AI 기반 소상공인 이벤트 자동 생성 서비스 - 외부 시퀀스 설계

문서 정보

• 작성일: 2025-10-22
• 작성자: System Architect
• 버전: 1.0
• 관련 문서:
  • 유저스토리
  • 논리 아키텍처
  • UI/UX 설계서

---

개요

본 문서는 KT AI 기반 소상공인 이벤트 자동 생성 서비스의 외부 시퀀스 설계를 정의합니다. 외부 시퀀스는 서비스 간의 상호작용과 데이터 흐름을 표현하며, 유저스토리와 논리 아키텍처를 기반으로 설계되었습니다.

설계 원칙

1. 유저스토리 기반: 20개 유저스토리와 정확히 매칭
2. Event-Driven 아키텍처: Kafka를 통한 비동기 이벤트 발행/구독
3. Resilience 패턴: Circuit Breaker, Retry, Timeout, Fallback 적용
4. Cache-Aside 패턴: Redis 캐싱을 통한 성능 최적화
5. 서비스 독립성: 느슨한 결합과 장애 격리

---

외부 시퀀스 플로우 목록

총 4개의 주요 비즈니스 플로우로 구성되어 있습니다:

1. 사용자 인증 플로우

파일: 사용자인증플로우.puml

포함된 유저스토리:

• UFR-USER-010: 회원가입
• UFR-USER-020: 로그인
• UFR-USER-040: 로그아웃

주요 참여자:

• Frontend (Web/Mobile)
• API Gateway
• User Service
• Redis Cache
• User DB (PostgreSQL)
• 국세청 API (외부)

핵심 기능:

• JWT 기반 인증
• 사업자번호 검증 (Circuit Breaker 적용)
• Redis 캐싱 (사업자번호 검증 결과, TTL 7일)
• 비밀번호 해싱 (bcrypt)
• 사업자번호 암호화 (AES-256)

Resilience 패턴:

• Circuit Breaker: 국세청 API (실패율 50% 초과 시 Open)
• Retry: 최대 3회 재시도 (지수 백오프: 1초, 2초, 4초)
• Timeout: 5초
• Fallback: 사업자번호 검증 스킵 (수동 확인 안내)

---

2. 이벤트 생성 플로우

파일: 이벤트생성플로우.puml

포함된 유저스토리:

• UFR-EVENT-020: 이벤트 목적 선택
• UFR-EVENT-030: AI 이벤트 추천
• UFR-CONT-010: SNS 이미지 생성
• UFR-EVENT-050: 최종 승인 및 배포

주요 참여자:

• Frontend
• API Gateway
• Event Service
• AI Service (Kafka 구독)
• Content Service (Kafka 구독)
• Distribution Service (동기 호출)
• Kafka (Event Topics + Job Topics)
• Redis Cache
• Event DB
• 외부 API (AI API, 이미지 생성 API, 배포 채널 APIs)

핵심 기능:

1. 이벤트 목적 선택 (동기)

   • Event DB에 목적 저장
   • EventCreated 이벤트 발행

2. AI 이벤트 추천 (비동기)

   • Kafka ai-job 토픽 발행
   • AI Service 구독 및 처리
   • Polling 패턴으로 Job 상태 확인 (최대 30초)
   • Redis 캐싱 (TTL 24시간)

3. SNS 이미지 생성 (비동기)

   • Kafka image-job 토픽 발행
   • Content Service 구독 및 처리
   • Polling 패턴으로 Job 상태 확인 (최대 20초)
   • CDN 업로드 및 Redis 캐싱 (TTL 7일)

4. 최종 승인 및 배포 (동기)

   • Distribution Service REST API 직접 호출
   • 다중 채널 병렬 배포 (1분 이내)
   • DistributionCompleted 이벤트 발행

Resilience 패턴:

• Circuit Breaker: 모든 외부 API 호출 시 적용
• Retry: 최대 3회 재시도 (지수 백오프)
• Timeout: AI API 30초, 이미지 API 20초, 배포 API 10초
• Bulkhead: 채널별 스레드 풀 격리
• Fallback: AI 추천 시 캐시된 이전 결과, 이미지 생성 시 기본 템플릿

---

3. 고객 참여 플로우

파일: 고객참여플로우.puml

포함된 유저스토리:

• UFR-PART-010: 이벤트 참여
• UFR-PART-030: 당첨자 추첨

주요 참여자:

• Frontend (고객용 / 사장님용)
• API Gateway
• Participation Service
• Kafka (Event Topics)
• Participation DB
• Analytics Service (이벤트 구독)

핵심 기능:

1. 이벤트 참여

   • 중복 참여 체크 (전화번호 기반)
   • 응모 번호 발급
   • ParticipantRegistered 이벤트 발행 → Analytics Service 구독

2. 당첨자 추첨

   • 난수 기반 무작위 추첨 (Crypto.randomBytes)
   • Fisher-Yates Shuffle 알고리즘
   • 매장 방문 고객 가산점 적용 (선택 옵션)
   • WinnerSelected 이벤트 발행

Event-Driven 특징:

• Analytics Service가 ParticipantRegistered 이벤트 구독하여 실시간 통계 업데이트
• 서비스 간 직접 의존성 없이 이벤트로 느슨한 결합

---

4. 성과 분석 플로우

파일: 성과분석플로우.puml

포함된 유저스토리:

• UFR-ANAL-010: 실시간 성과분석 대시보드 조회

주요 참여자:

• Frontend
• API Gateway
• Analytics Service
• Redis Cache (TTL 5분)
• Analytics DB
• Kafka (Event Topics 구독)
• 외부 API (우리동네TV, 지니TV, SNS APIs)

핵심 기능:

1. 대시보드 조회 - Cache HIT (0.5초)

   • Redis에서 캐시된 데이터 즉시 반환
   • 히트율 목표: 95%

2. 대시보드 조회 - Cache MISS (3초)

   • Analytics DB 로컬 데이터 조회
   • 외부 채널 API 병렬 호출 (Circuit Breaker 적용)
   • 데이터 통합 및 ROI 계산
   • Redis 캐싱 (TTL 5분)

3. 실시간 업데이트 (Background)

   • EventCreated 구독: 이벤트 기본 정보 초기화
   • ParticipantRegistered 구독: 참여자 수 실시간 증가
   • DistributionCompleted 구독: 배포 채널 통계 업데이트

Resilience 패턴:

• Circuit Breaker: 외부 채널 API 조회 시 (실패율 50% 초과 시 Open)
• Timeout: 10초
• Fallback: 캐시된 이전 데이터 반환 또는 기본값 설정
• 병렬 처리: 외부 채널 API 동시 호출

---

설계 특징

1. Event-Driven 아키텍처

• Kafka 통합: Event Topics와 Job Topics를 Kafka로 통합
• 느슨한 결합: 서비스 간 직접 의존성 제거
• 장애 격리: 한 서비스 장애가 다른 서비스에 영향 없음
• 확장 용이: 새로운 구독자 추가로 기능 확장

2. 비동기 처리 패턴

• Kafka Job Topics: ai-job, image-job
• Polling 패턴: Job 상태 확인 (2-5초 간격)
• 처리 시간: AI 추천 10초, 이미지 생성 5초

3. 동기 처리 패턴

• Distribution Service: REST API 직접 호출
• 다중 채널 배포: 병렬 처리 (1분 이내)
• Circuit Breaker: 장애 전파 방지

4. Resilience 패턴 전면 적용

• Circuit Breaker: 모든 외부 API 호출
• Retry: 일시적 장애 자동 복구
• Timeout: 응답 시간 제한
• Bulkhead: 리소스 격리
• Fallback: 장애 시 대체 로직

5. Cache-Aside 패턴

• Redis 캐싱: 성능 최적화
• TTL 설정: 데이터 유효성 관리
• 히트율 목표: 80-95%
• 응답 시간 개선: 90-99%

---

파일 구조

design/backend/sequence/outer/
├── README.md (본 문서)
├── 사용자인증플로우.puml
├── 이벤트생성플로우.puml
├── 고객참여플로우.puml
└── 성과분석플로우.puml

---

다이어그램 확인 방법

1. Online PlantUML Viewer

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

2. VSCode Extension

1. "PlantUML" 확장 프로그램 설치
2. .puml 파일 열기
3. Alt+D 또는 Cmd+D로 미리보기

3. IntelliJ IDEA Plugin

1. "PlantUML integration" 플러그인 설치
2. .puml 파일 열기
3. 우측 미리보기 패널에서 확인

---

주요 결정사항

1. Kafka 통합: Event Bus와 Job Queue를 Kafka로 통합하여 운영 복잡도 감소
2. 비동기 처리: AI 추천 및 이미지 생성은 Kafka Job Topics를 통한 비동기 처리
3. 동기 배포: Distribution Service는 REST API 직접 호출하여 동기 처리 (1분 이내)
4. Resilience 패턴: 모든 외부 API 호출 시 Circuit Breaker, Retry, Timeout, Fallback 적용
5. Cache-Aside 패턴: Redis 캐싱으로 응답 시간 90-99% 개선
6. Event Topics: EventCreated, ParticipantRegistered, WinnerSelected, DistributionCompleted
7. Job Topics: ai-job, image-job

---

검증 사항

1. 유저스토리 매칭

✅ 모든 유저스토리가 외부 시퀀스에 정확히 반영됨

• User 서비스: 4개 유저스토리
• Event 서비스: 4개 유저스토리
• Participation 서비스: 2개 유저스토리
• Analytics 서비스: 1개 유저스토리

2. 논리 아키텍처 일치성

✅ 논리 아키텍처의 모든 컴포넌트와 통신 패턴 반영

• Core Services: User, Event, Participation, Analytics
• Async Services: AI, Content, Distribution
• Kafka: Event Topics + Job Topics
• External Systems: 국세청 API, AI API, 이미지 생성 API, 배포 채널 APIs

3. Resilience 패턴 적용

✅ 모든 외부 API 호출에 Resilience 패턴 적용

• Circuit Breaker, Retry, Timeout, Bulkhead, Fallback

4. PlantUML 문법 검증

✅ PlantUML 기본 문법 검증 완료

• !theme mono 적용
• 동기/비동기 화살표 구분
• 한글 설명 추가
• 참여자 및 플로우 명확히 표현

---

향후 개선 방안

1. WebSocket 기반 실시간 푸시: 대시보드 실시간 업데이트 (폴링 대체)
2. Saga 패턴 적용: 복잡한 분산 트랜잭션 보상 로직 체계화
3. Service Mesh 도입: Istio를 통한 서비스 간 통신 관찰성 및 보안 강화
4. Dead Letter Queue 고도화: 실패 이벤트 재처리 및 알림 자동화

---

문서 버전: 1.0 최종 수정일: 2025-10-22 작성자: System Architect