kt-event-marketing/design/backend/sequence/inner

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

문서 정보

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

---

목차

1. 개요
2. 서비스별 시나리오 목록
3. 설계 원칙
4. 주요 패턴
5. 파일 구조
6. PlantUML 다이어그램 확인 방법

---

1. 개요

본 문서는 KT AI 기반 소상공인 이벤트 자동 생성 서비스의 7개 마이크로서비스에 대한 26개 내부 시퀀스 다이어그램을 포함합니다.

1.1 설계 범위

각 마이크로서비스 내부의 처리 흐름을 상세히 표현:

• API 레이어: Controller
• 비즈니스 레이어: Service, Validator, Domain Logic
• 데이터 레이어: Repository, Cache Manager
• 인프라 레이어: Kafka, Redis, Database, External APIs

1.2 설계 대상 서비스

서비스	시나리오 수	주요 책임
User	4	사용자 인증, 프로필 관리
Event	10	이벤트 생명주기 관리, 오케스트레이션
Participation	3	참여자 관리, 당첨자 추첨
Analytics	5	실시간 성과 분석, 대시보드
AI	1	AI 트렌드 분석 및 이벤트 추천
Content	1	SNS 이미지 생성
Distribution	2	다중 채널 배포
총계	26	-

---

2. 서비스별 시나리오 목록

2.1 User 서비스 (4개)

시나리오	파일명	유저스토리	주요 처리 내용
회원가입	user-회원가입.puml	UFR-USER-010	사업자번호 검증(Circuit Breaker), 트랜잭션, JWT 발급
로그인	user-로그인.puml	UFR-USER-020	비밀번호 검증(bcrypt), JWT 발급, 세션 저장
프로필수정	user-프로필수정.puml	UFR-USER-030	기본/매장 정보 수정, 비밀번호 변경, 트랜잭션
로그아웃	user-로그아웃.puml	UFR-USER-040	JWT 검증, 세션 삭제, Blacklist 추가

주요 특징:

• Resilience 패턴: Circuit Breaker (국세청 API), Retry, Timeout, Fallback
• 보안: bcrypt 해싱, AES-256 암호화, JWT 관리
• 캐싱: 사업자번호 검증 결과 (TTL 7일), 세션 정보 (TTL 7일)

---

2.2 Event 서비스 (10개)

시나리오	파일명	유저스토리	주요 처리 내용
목적선택	event-목적선택.puml	UFR-EVENT-020	이벤트 목적 선택 및 저장, EventCreated 발행
AI추천요청	event-AI추천요청.puml	UFR-EVENT-030	Kafka ai-job 발행, Job ID 반환 (202 Accepted)
추천결과조회	event-추천결과조회.puml	UFR-EVENT-030	Redis Job 상태 폴링 조회
이미지생성요청	event-이미지생성요청.puml	UFR-CONT-010	Kafka image-job 발행, Job ID 반환 (202 Accepted)
이미지결과조회	event-이미지결과조회.puml	UFR-CONT-010	Redis Job 상태 폴링 조회
콘텐츠선택	event-콘텐츠선택.puml	UFR-CONT-020	선택한 콘텐츠 저장
최종승인및배포	event-최종승인및배포.puml	UFR-EVENT-050	Distribution Service 동기 호출, 상태 변경
상세조회	event-상세조회.puml	UFR-EVENT-060	이벤트 상세 조회 (캐싱)
목록조회	event-목록조회.puml	UFR-EVENT-070	이벤트 목록 조회 (필터/검색/페이지네이션)
대시보드조회	event-대시보드조회.puml	UFR-EVENT-010	대시보드 이벤트 목록 (병렬 쿼리)

주요 특징:

• Kafka 통합: Event Topics (EventCreated), Job Topics (ai-job, image-job)
• 비동기 처리: Job 발행 → 폴링 방식 결과 조회
• 동기 호출: Distribution Service REST API 직접 호출
• 캐싱 전략: 목적(30분), 상세(5분), 목록/대시보드(1분)

---

2.3 Participation 서비스 (3개)

시나리오	파일명	유저스토리	주요 처리 내용
이벤트참여	participation-이벤트참여.puml	UFR-PART-010	중복 체크, ParticipantRegistered 발행
참여자목록조회	participation-참여자목록조회.puml	UFR-PART-020	필터/검색, 페이지네이션, 전화번호 마스킹
당첨자추첨	participation-당첨자추첨.puml	UFR-PART-030	Fisher-Yates Shuffle, WinnerSelected 발행

주요 특징:

• 중복 방지: Redis Cache + DB 2단계 체크
• 추첨 알고리즘: 난수 기반 공정성, 가산점 시스템, Fisher-Yates Shuffle
• Kafka Event: ParticipantRegistered, WinnerSelected → Analytics Service 구독
• 보안: 전화번호 마스킹 (010-****-1234)

---

2.4 Analytics 서비스 (5개)

시나리오	파일명	유저스토리	주요 처리 내용
대시보드조회-캐시히트	analytics-대시보드조회-캐시히트.puml	UFR-ANAL-010	Redis 캐시 HIT (0.5초)
대시보드조회-캐시미스	analytics-대시보드조회-캐시미스.puml	UFR-ANAL-010	외부 API 병렬 호출, ROI 계산 (3초)
이벤트생성구독	analytics-이벤트생성구독.puml	-	EventCreated 구독, 통계 초기화
참여자등록구독	analytics-참여자등록구독.puml	-	ParticipantRegistered 구독, 실시간 통계
배포완료구독	analytics-배포완료구독.puml	-	DistributionCompleted 구독, 배포 통계

주요 특징:

• Cache-Aside 패턴: Redis 캐싱 (TTL 5분, 히트율 95%)
• 외부 API 병렬 호출: 우리동네TV, 지니TV, SNS APIs (Circuit Breaker, Timeout, Fallback)
• Kafka 구독: 3개 Event Topics 실시간 처리
• 멱등성 보장: Redis Set으로 중복 이벤트 방지

---

2.5 AI 서비스 (1개)

시나리오	파일명	유저스토리	주요 처리 내용
트렌드분석및추천	ai-트렌드분석및추천.puml	UFR-AI-010	Kafka ai-job 구독, 트렌드 분석, 3가지 추천 병렬 생성

주요 특징:

• Kafka Job 구독: ai-job 토픽 Consumer
• 외부 AI API: Claude/GPT-4 호출 (Circuit Breaker, Timeout 30초)
• 캐싱 전략: 트렌드 분석 결과 (TTL 1시간), 추천 결과 (TTL 24시간)
• 3가지 옵션 병렬 생성: 저비용/중비용/고비용 추천안

---

2.6 Content 서비스 (1개)

시나리오	파일명	유저스토리	주요 처리 내용
이미지생성	content-이미지생성.puml	UFR-CONT-010	Kafka image-job 구독, 3가지 스타일 병렬 생성

주요 특징:

• Kafka Job 구독: image-job 토픽 Consumer
• 외부 이미지 API: Stable Diffusion/DALL-E 병렬 호출 (Circuit Breaker, Timeout 20초)
• 3가지 스타일 병렬: 심플/화려한/트렌디 (par 블록)
• CDN 업로드: 이미지 URL 캐싱 (TTL 7일)
• Fallback 2단계: Stable Diffusion 실패 → DALL-E → 기본 템플릿

---

2.7 Distribution 서비스 (2개)

시나리오	파일명	유저스토리	주요 처리 내용
다중채널배포	distribution-다중채널배포.puml	UFR-DIST-010	REST API 동기 호출, 채널별 병렬 배포, DistributionCompleted 발행
배포상태조회	distribution-배포상태조회.puml	UFR-DIST-020	배포 상태 모니터링, 재시도 기능

주요 특징:

• 동기 호출: Event Service → Distribution Service REST API
• 채널별 병렬 배포: 우리동네TV, 링고비즈, 지니TV, SNS APIs (par 블록)
• Resilience 패턴: Circuit Breaker, Retry (3회), Bulkhead (채널별 독립)
• 독립 처리: 하나 실패해도 다른 채널 계속
• Kafka Event: DistributionCompleted → Analytics Service 구독

---

3. 설계 원칙

3.1 공통설계원칙 준수

✅ PlantUML 표준

• !theme mono 테마 적용
• 명확한 타이틀 및 참여자 타입 표시
• 외부 시스템/인프라 <<E>> 표시

✅ 레이어 아키텍처

Controller (API Layer)
    ↓
Service (Business Layer)
    ↓
Repository (Data Layer)
    ↓
External Systems (Redis, DB, Kafka, APIs)

✅ 동기/비동기 구분

• 실선 화살표 (→): 동기 호출
• 점선 화살표 (-->): 비동기 호출 (Kafka)
• activate/deactivate: 생명선 활성화

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

✅ 유저스토리 기반 설계

• 20개 유저스토리와 정확히 매칭
• 불필요한 추가 설계 배제

✅ 외부 시퀀스와 일치

• 외부 시퀀스 다이어그램과 플로우 일치
• 서비스 간 통신 방식 동일

✅ 모든 레이어 표시

• API, 비즈니스, 데이터, 인프라 레이어 명시
• 캐시, DB, 외부 API 접근 표시

---

4. 주요 패턴

4.1 Resilience 패턴

Circuit Breaker

• 적용 대상: 모든 외부 API 호출
• 설정: 실패율 50% 초과 시 Open, 30초 후 Half-Open
• 효과: 빠른 실패로 리소스 보호

Retry Pattern

• 적용 대상: 일시적 장애가 예상되는 외부 API
• 설정: 최대 3회, 지수 백오프 (1초, 2초, 4초)
• 효과: 일시적 장애 자동 복구

Timeout Pattern

• 적용 대상: 모든 외부 API 호출
• 설정: 국세청 5초, AI 30초, 이미지 20초, 배포 10초
• 효과: 리소스 점유 방지

Fallback Pattern

• 적용 대상: 외부 API 장애 시
• 전략: 캐시된 이전 데이터, 기본값, 검증 스킵
• 효과: 서비스 지속성 보장 (Graceful Degradation)

Bulkhead Pattern

• 적용 대상: Distribution Service 다중 채널 배포
• 설정: 채널별 독립 스레드 풀
• 효과: 채널 장애 격리, 장애 전파 차단

4.2 캐싱 전략 (Cache-Aside)

서비스	캐시 키 패턴	TTL	히트율 목표	효과
User	user:business:{사업자번호}	7일	90%	5초 → 0.1초 (98% 개선)
AI	ai:recommendation:{업종}:{지역}:{목적}	24시간	80%	10초 → 0.1초 (99% 개선)
Content	content:image:{이벤트ID}:{스타일}	7일	80%	5초 → 0.1초 (98% 개선)
Analytics	analytics:dashboard:{이벤트ID}	5분	95%	3초 → 0.5초 (83% 개선)
Event	event:detail:{eventId}	5분	85%	1초 → 0.2초 (80% 개선)
Participation	participation:list:{eventId}:{filter}	5분	90%	2초 → 0.3초 (85% 개선)

4.3 Event-Driven 패턴

Kafka Event Topics (도메인 이벤트)

• EventCreated: 이벤트 생성 시 → Analytics Service 구독
• ParticipantRegistered: 참여자 등록 시 → Analytics Service 구독
• WinnerSelected: 당첨자 선정 시 → (추후 확장)
• DistributionCompleted: 배포 완료 시 → Analytics Service 구독

Kafka Job Topics (비동기 작업)

• ai-job: AI 추천 요청 → AI Service 구독
• image-job: 이미지 생성 요청 → Content Service 구독

멱등성 보장

• Redis Set으로 이벤트 ID 중복 체크
• 동일 이벤트 중복 처리 시 무시

---

5. 파일 구조

design/backend/sequence/inner/
├── README.md (본 문서)
├── user-회원가입.puml
├── user-로그인.puml
├── user-프로필수정.puml
├── user-로그아웃.puml
├── event-목적선택.puml
├── event-AI추천요청.puml
├── event-추천결과조회.puml
├── event-이미지생성요청.puml
├── event-이미지결과조회.puml
├── event-콘텐츠선택.puml
├── event-최종승인및배포.puml
├── event-상세조회.puml
├── event-목록조회.puml
├── event-대시보드조회.puml
├── participation-이벤트참여.puml
├── participation-참여자목록조회.puml
├── participation-당첨자추첨.puml
├── analytics-대시보드조회-캐시히트.puml
├── analytics-대시보드조회-캐시미스.puml
├── analytics-이벤트생성구독.puml
├── analytics-참여자등록구독.puml
├── analytics-배포완료구독.puml
├── ai-트렌드분석및추천.puml
├── content-이미지생성.puml
├── distribution-다중채널배포.puml
└── distribution-배포상태조회.puml

총 26개 파일, 약 114KB

---

6. PlantUML 다이어그램 확인 방법

6.1 온라인 확인

PlantUML Web Server

1. https://www.plantuml.com/plantuml/uml 접속
2. 각 .puml 파일 내용 복사
3. 에디터에 붙여넣기
4. 다이어그램 시각적 확인
5. PNG/SVG/PDF 다운로드 가능

PlantUML Editor (추천)

1. https://plantuml-editor.kkeisuke.com/ 접속
2. 실시간 미리보기 제공
3. 편집 및 다운로드 지원

6.2 로컬 확인 (Docker)

Docker로 PlantUML 검증

# Docker 실행 필요
docker run -d --name plantuml -p 8080:8080 plantuml/plantuml-server:jetty

# 각 파일 문법 검사
cat "user-회원가입.puml" | docker exec -i plantuml java -jar /app/plantuml.jar -syntax

6.3 IDE 플러그인

IntelliJ IDEA

• PlantUML Integration 플러그인 설치
• .puml 파일 우클릭 → "Show PlantUML Diagram"

VS Code

• PlantUML 확장 설치
• Alt+D: 미리보기 열기

---

부록

A. 파일 크기 및 통계

서비스	시나리오 수	총 크기	평균 크기
User	4	21.2KB	5.3KB
Event	10	20.2KB	2.0KB
Participation	3	15.4KB	5.1KB
Analytics	5	20.8KB	4.2KB
AI	1	12KB	12KB
Content	1	8.5KB	8.5KB
Distribution	2	17.5KB	8.8KB
총계	26	115.6KB	4.4KB

B. 주요 기술 스택

Backend

• Framework: Spring Boot
• ORM: JPA/Hibernate
• Security: Spring Security + JWT
• Cache: Redis
• Database: PostgreSQL
• Message Queue: Apache Kafka

Resilience

• Circuit Breaker: Resilience4j
• Retry: Resilience4j RetryRegistry
• Timeout: Resilience4j TimeLimiterRegistry

Utilities

• Password: bcrypt (Spring Security)
• JWT: jjwt library
• Encryption: AES-256 (javax.crypto)

C. 참고 문서

• 유저스토리
• 외부 시퀀스 설계서
• 논리 아키텍처
• 공통설계원칙
• 내부시퀀스설계 가이드

---

문서 버전: 1.0 최종 수정일: 2025-10-22 작성자: System Architect (박영자) 내부 시퀀스 설계 완료: ✅ 26개 시나리오 모두 작성 완료