서비스	시나리오 수	주요 책임
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

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

PlantUML Editor (추천)

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

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

README.md

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

문서 정보

목차

1. 개요

1.1 설계 범위

1.2 설계 대상 서비스

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

2.1 User 서비스 (4개)

2.2 Event 서비스 (10개)

2.3 Participation 서비스 (3개)

2.4 Analytics 서비스 (5개)

2.5 AI 서비스 (1개)

2.6 Content 서비스 (1개)

2.7 Distribution 서비스 (2개)

3. 설계 원칙

3.1 공통설계원칙 준수

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

4. 주요 패턴

4.1 Resilience 패턴

Circuit Breaker

Retry Pattern

Timeout Pattern

Fallback Pattern

Bulkhead Pattern

4.2 캐싱 전략 (Cache-Aside)

4.3 Event-Driven 패턴

Kafka Event Topics (도메인 이벤트)

Kafka Job Topics (비동기 작업)

멱등성 보장

5. 파일 구조

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

6.1 온라인 확인

PlantUML Web Server

PlantUML Editor (추천)

6.2 로컬 확인 (Docker)

Docker로 PlantUML 검증

6.3 IDE 플러그인

IntelliJ IDEA

VS Code

부록

A. 파일 크기 및 통계

B. 주요 기술 스택

Backend

Resilience

Utilities

C. 참고 문서