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

## 문서 정보
- **작성일**: 2025-10-22
- **버전**: 1.0
- **작성자**: System Architect
- **관련 문서**:
  - [유저스토리](../../userstory.md)
  - [외부 시퀀스 설계서](../outer/)
  - [논리 아키텍처](../../logical/logical-architecture.md)

---

## 목차
1. [개요](#1-개요)
2. [서비스별 시나리오 목록](#2-서비스별-시나리오-목록)
3. [설계 원칙](#3-설계-원칙)
4. [주요 패턴](#4-주요-패턴)
5. [파일 구조](#5-파일-구조)
6. [PlantUML 다이어그램 확인 방법](#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 검증
```bash
# 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. 참고 문서
- [유저스토리](../../userstory.md)
- [외부 시퀀스 설계서](../outer/)
- [논리 아키텍처](../../logical/logical-architecture.md)
- [공통설계원칙](../../../../claude/common-principles.md)
- [내부시퀀스설계 가이드](../../../../claude/sequence-inner-design.md)

---

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