kt-event-marketing/design/pattern/backup/architecture-pattern-backup.md

# KT AI 기반 소상공인 이벤트 자동 생성 서비스 - 클라우드 아키텍처 패턴 적용 방안

**문서 정보**
- 프로젝트명: KT AI 기반 소상공인 이벤트 자동 생성 서비스
- 작성일: 2025-10-21
- 버전: 1.0
- 작성자: System Architect

---

## 목차
1. [요구사항 분석 결과](#1-요구사항-분석-결과)
2. [패턴 평가 매트릭스](#2-패턴-평가-매트릭스)
3. [서비스별 패턴 적용 설계](#3-서비스별-패턴-적용-설계)
4. [Phase별 구현 로드맵](#4-phase별-구현-로드맵)
5. [예상 성과 지표](#5-예상-성과-지표)

---

## 1. 요구사항 분석 결과

### 1.1 기능적 요구사항

#### 마이크로서비스별 핵심 기능
1. **User 서비스** (4개 유저스토리)
   - 회원가입/로그인/프로필 관리
   - 사업자번호 검증 (국세청 API 연동)
   - 세션 관리 및 인증/인가

2. **Event 서비스** (7개 유저스토리)
   - 이벤트 CRUD 관리
   - 대시보드 현황 조회
   - 이벤트 목적 선택 및 생성 플로우 관리
   - AI/Content/Distribution 서비스 연동

3. **AI 서비스** (1개 유저스토리)
   - 업종/지역/시즌 트렌드 분석 (5초 이내)
   - 3가지 이벤트 추천 생성 (5초 이내)
   - Claude API/GPT-4 API 연동
   - **병렬 처리**: 트렌드 분석 + 이벤트 추천 동시 실행 (총 10초 목표)

4. **Content 서비스** (2개 유저스토리)
   - SNS 이미지 3가지 스타일 자동 생성 (5초 이내)
   - 플랫폼별 이미지 최적화 (Instagram/Naver/Kakao)
   - Stable Diffusion/DALL-E API 연동

5. **Distribution 서비스** (2개 유저스토리)
   - 다중 채널 동시 배포 (우리동네TV, 링고비즈, 지니TV, SNS)
   - 채널별 독립 처리 및 실패 복구
   - 배포 상태 실시간 모니터링

6. **Participation 서비스** (3개 유저스토리)
   - 이벤트 참여자 관리 (중복 체크)
   - 자동 추첨 시스템
   - 참여자 목록 조회 및 필터링

7. **Analytics 서비스** (1개 유저스토리)
   - 실시간 통합 대시보드 (5분 간격 업데이트)
   - 다중 데이터 소스 통합 (Participation, Distribution, POS, 외부 API)
   - 채널별 성과 분석 및 투자대비수익률 계산

### 1.2 비기능적 요구사항

#### 성능 요구사항
| 항목 | 목표 | 우선순위 |
|------|------|---------|
| AI 트렌드 분석 + 추천 | 10초 이내 | 🔴 Critical |
| SNS 이미지 생성 | 5초 이내 | 🔴 Critical |
| 다중 채널 배포 | 1분 이내 | 🟡 High |
| 실시간 대시보드 업데이트 | 5분 간격 | 🟢 Medium |
| API 응답 시간 (CRUD) | 200ms 이하 | 🟡 High |

#### 가용성 및 신뢰성
- **시스템 가용성**: 99.9% (월 43분 다운타임 허용)
- **외부 API 장애 대응**: 개별 채널 실패가 전체 서비스에 영향 없도록 격리
- **데이터 일관성**: 이벤트 생성 트랜잭션 보장

#### 확장성
- **사용자 증가 대응**: 초기 100명 → 1년 후 10,000명
- **이벤트 처리량**: 동시 이벤트 생성 50개
- **데이터 증가**: 일 평균 1,000개 참여 데이터

#### 보안 요구사항
- JWT 토큰 기반 인증
- API Gateway를 통한 중앙 인증/인가
- 개인정보 암호화 저장 (전화번호, 이름)
- 사업자번호 검증 강화

### 1.3 UI/UX 분석에서 도출된 기술적 요구사항

#### 사용자 인터랙션 패턴
- **Mobile First**: 60% 모바일, 40% 데스크톱
- **짧은 세션**: 5-10분 내 이벤트 생성 완료
- **실시간 피드백**: 로딩 상태, 진행률 표시 필수
- **3 Tap Rule**: 모든 주요 기능 3번 탭 내 도달

#### 실시간 처리 요구사항
- AI 처리 진행 상황 실시간 표시
- 배포 상태 실시간 모니터링
- 대시보드 자동 갱신 (5분 간격)

### 1.4 기술적 도전과제

#### 1. AI 응답 시간 관리 (🔴 Critical)
**문제**: AI API 응답이 10초 목표를 초과할 수 있음

**영향**:
- 사용자 이탈 증가
- 서비스 만족도 저하

**해결 필요성**: MVP 단계부터 필수

#### 2. 다중 외부 API 의존성 (🔴 Critical)
**문제**: 7개 외부 API 연동 (국세청, Claude/GPT-4, Stable Diffusion, 우리동네TV, 링고비즈, 지니TV, SNS)

**영향**:
- API 장애 시 서비스 중단 위험
- 응답 시간 불안정성
- 비용 증가 (API 호출량)

**해결 필요성**: MVP 단계부터 필수

#### 3. 실시간 대시보드 성능 (🟡 High)
**문제**: 다중 데이터 소스 통합 (Participation, Distribution, POS, 외부 API)

**영향**:
- 대시보드 로딩 지연
- 서버 부하 증가

**해결 필요성**: Phase 2 확장 단계에서 해결

#### 4. 복잡한 비즈니스 트랜잭션 (🟡 High)
**문제**: 이벤트 생성 → AI 추천 → 콘텐츠 생성 → 배포 → 참여자 관리 → 분석

**영향**:
- 부분 실패 시 데이터 불일치
- 보상 트랜잭션 복잡도 증가

**해결 필요성**: Phase 1 MVP에서 기본 구조 확립

---

## 2. 패턴 평가 매트릭스

### 2.1 평가 기준

| 기준 | 가중치 | 평가 내용 |
|------|--------|-----------|
| **기능 적합성** | 35% | 요구사항을 직접 해결하는 능력 |
| **성능 효과** | 25% | 응답시간 및 처리량 개선 효과 |
| **운영 복잡도** | 20% | 구현 및 운영의 용이성 |
| **확장성** | 15% | 미래 요구사항에 대한 대응력 |
| **비용 효율성** | 5% | 개발/운영 비용 대비 효과(ROI) |

### 2.2 핵심 패턴 평가

#### 2.2.1 API Gateway (필수 패턴)

| 평가 기준 | 점수 | 가중치 | 계산 | 근거 |
|----------|-----|--------|------|------|
| 기능 적합성 | 9 | 35% | 3.15 | 중앙 인증, 라우팅, 로깅 통합 제공 |
| 성능 효과 | 7 | 25% | 1.75 | 단일 엔드포인트로 네트워크 최적화 |
| 운영 복잡도 | 8 | 20% | 1.60 | 표준 솔루션 활용 (Kong, AWS API Gateway) |
| 확장성 | 9 | 15% | 1.35 | 마이크로서비스 증가에 유연 대응 |
| 비용 효율성 | 8 | 5% | 0.40 | 오픈소스(Kong) 또는 클라우드 서비스 활용 |
| **총점** | | | **8.25** | **선정** |

**선정 이유**:
- 7개 마이크로서비스의 단일 진입점 필요
- 횡단 관심사(인증, 로깅, Rate Limiting) 중앙 관리
- Mobile First 환경에서 단일 엔드포인트 필수

**적용 방안**:
- Kong Gateway 또는 AWS API Gateway 활용
- JWT 토큰 검증 중앙화
- Rate Limiting 적용 (DoS 방지)
- Request/Response 로깅

---

#### 2.2.2 Cache-Aside (필수 패턴)

| 평가 기준 | 점수 | 가중치 | 계산 | 근거 |
|----------|-----|--------|------|------|
| 기능 적합성 | 9 | 35% | 3.15 | AI 트렌드 분석, 이미지 생성 결과 캐싱 |
| 성능 효과 | 10 | 25% | 2.50 | AI API 호출 대폭 감소 (10초 → 0.1초) |
| 운영 복잡도 | 9 | 20% | 1.80 | Redis 표준 패턴, 간단한 구현 |
| 확장성 | 8 | 15% | 1.20 | Redis Cluster로 확장 가능 |
| 비용 효율성 | 10 | 5% | 0.50 | AI API 비용 90% 절감 |
| **총점** | | | **9.15** | **선정** |

**선정 이유**:
- AI API 비용 절감 (동일한 요청에 대한 반복 호출 방지)
- 성능 대폭 개선 (10초 → 캐시 히트 시 0.1초)
- 외부 API 의존성 감소

**적용 대상**:
1. **AI 트렌드 분석 결과**: 업종/지역/시즌별 1시간 캐싱
2. **AI 이벤트 추천 결과**: 동일 조건 24시간 캐싱
3. **SNS 이미지 생성 결과**: 영구 캐싱 (CDN 연동)
4. **사업자번호 검증 결과**: 30일 캐싱

---

#### 2.2.3 Asynchronous Request-Reply (필수 패턴)

| 평가 기준 | 점수 | 가중치 | 계산 | 근거 |
|----------|-----|--------|------|------|
| 기능 적합성 | 10 | 35% | 3.50 | AI 처리 비동기 대응 필수 |
| 성능 효과 | 9 | 25% | 2.25 | 사용자 대기 시간 단축, 서버 리소스 효율화 |
| 운영 복잡도 | 6 | 20% | 1.20 | 폴링/WebSocket 구현 필요 |
| 확장성 | 9 | 15% | 1.35 | 장시간 작업 증가 시 대응 가능 |
| 비용 효율성 | 7 | 5% | 0.35 | 개발 비용 증가하지만 사용자 경험 개선 |
| **총점** | | | **8.65** | **선정** |

**선정 이유**:
- AI 트렌드 분석 + 이벤트 추천 (10초 이상 소요)
- SNS 이미지 생성 (5초 이상 소요)
- 사용자 이탈 방지 (로딩 인디케이터 + 진행률 표시)

**적용 방안**:
1. **요청 단계**: 클라이언트 → API Gateway → AI 서비스 (Job ID 반환)
2. **처리 단계**: AI 서비스 비동기 처리, 진행 상황 Redis 저장
3. **응답 단계**: 클라이언트 폴링 또는 WebSocket으로 진행 상황 확인
4. **완료 단계**: 결과 반환 및 캐싱

---

#### 2.2.4 Circuit Breaker (필수 패턴)

| 평가 기준 | 점수 | 가중치 | 계산 | 근거 |
|----------|-----|--------|------|------|
| 기능 적합성 | 10 | 35% | 3.50 | 외부 API 장애 격리 필수 |
| 성능 효과 | 8 | 25% | 2.00 | 장애 전파 방지로 전체 시스템 안정성 유지 |
| 운영 복잡도 | 7 | 20% | 1.40 | 라이브러리 활용 (Resilience4j, Netflix Hystrix) |
| 확장성 | 9 | 15% | 1.35 | 외부 API 증가 시 동일 패턴 적용 |
| 비용 효율성 | 8 | 5% | 0.40 | 장애 시 전체 시스템 다운 방지로 손실 감소 |
| **총점** | | | **8.65** | **선정** |

**선정 이유**:
- 7개 외부 API 연동 (Claude/GPT-4, Stable Diffusion, 우리동네TV 등)
- API 장애 시 전체 서비스 중단 방지
- 빠른 실패 및 폴백 처리

**적용 대상**:
1. **AI API**: Claude/GPT-4 장애 시 미리 준비된 템플릿 반환
2. **이미지 생성 API**: Stable Diffusion 장애 시 기본 템플릿 이미지 제공
3. **배포 채널 API**: 개별 채널 장애가 다른 채널에 영향 없도록 격리
4. **국세청 API**: 검증 실패 시 캐시된 결과 또는 수동 승인 플로우

---

#### 2.2.5 Retry (필수 패턴)

| 평가 기준 | 점수 | 가중치 | 계산 | 근거 |
|----------|-----|--------|------|------|
| 기능 적합성 | 9 | 35% | 3.15 | 일시적 네트워크 오류 대응 |
| 성능 효과 | 7 | 25% | 1.75 | 일시적 오류 복구로 사용자 재시도 불필요 |
| 운영 복잡도 | 9 | 20% | 1.80 | 라이브러리 활용 (Resilience4j) |
| 확장성 | 8 | 15% | 1.20 | 모든 외부 API에 동일 적용 |
| 비용 효율성 | 7 | 5% | 0.35 | 재시도 비용 < 실패 처리 비용 |
| **총점** | | | **8.25** | **선정** |

**선정 이유**:
- 외부 API 일시적 오류 빈번 (네트워크 타임아웃 등)
- 사용자 경험 개선 (자동 복구)

**적용 방안**:
- **Exponential Backoff**: 1초 → 2초 → 4초
- **최대 재시도**: 3회
- **적용 대상**: 모든 외부 API 호출
- **Circuit Breaker 연동**: 재시도 실패 시 Circuit 오픈

---

#### 2.2.6 Queue-Based Load Leveling (확장 단계 패턴)

| 평가 기준 | 점수 | 가중치 | 계산 | 근거 |
|----------|-----|--------|------|------|
| 기능 적합성 | 7 | 35% | 2.45 | 대량 이벤트 생성 시 부하 분산 |
| 성능 효과 | 8 | 25% | 2.00 | 피크 시간대 서버 안정성 확보 |
| 운영 복잡도 | 5 | 20% | 1.00 | 메시지 큐 인프라 필요 (RabbitMQ/Kafka) |
| 확장성 | 9 | 15% | 1.35 | 트래픽 증가 시 수평 확장 용이 |
| 비용 효율성 | 6 | 5% | 0.30 | 인프라 추가 비용 발생 |
| **총점** | | | **7.10** | **Phase 2 선정** |

**선정 이유**:
- MVP에서는 불필요 (사용자 100명 이하)
- Phase 2 확장 단계에서 사용자 증가 시 필요

**적용 시기**: Phase 2 (사용자 1,000명 이상)

**적용 대상**:
- AI 트렌드 분석 요청 큐
- SNS 이미지 생성 요청 큐
- 배포 요청 큐

---

#### 2.2.7 CQRS (고도화 단계 패턴)

| 평가 기준 | 점수 | 가중치 | 계산 | 근거 |
|----------|-----|--------|------|------|
| 기능 적합성 | 8 | 35% | 2.80 | Analytics 대시보드 읽기 최적화 |
| 성능 효과 | 9 | 25% | 2.25 | 읽기 전용 DB로 대시보드 성능 대폭 개선 |
| 운영 복잡도 | 4 | 20% | 0.80 | 읽기/쓰기 DB 분리, 동기화 복잡도 증가 |
| 확장성 | 10 | 15% | 1.50 | 읽기/쓰기 독립 확장 가능 |
| 비용 효율성 | 5 | 5% | 0.25 | DB 인프라 비용 증가 |
| **총점** | | | **7.60** | **Phase 3 선정** |

**선정 이유**:
- MVP에서는 과도한 복잡도
- Phase 3 고도화 단계에서 대시보드 성능 최적화 시 적용

**적용 시기**: Phase 3 (사용자 5,000명 이상)

**적용 대상**:
- Analytics 서비스 (읽기 전용 DB)
- 복잡한 집계 쿼리 최적화

---

#### 2.2.8 Saga (확장 단계 패턴)

| 평가 기준 | 점수 | 가중치 | 계산 | 근거 |
|----------|-----|--------|------|------|
| 기능 적합성 | 8 | 35% | 2.80 | 이벤트 생성 → AI → 콘텐츠 → 배포 트랜잭션 |
| 성능 효과 | 6 | 25% | 1.50 | 성능 개선 효과 미미 |
| 운영 복잡도 | 3 | 20% | 0.60 | 보상 트랜잭션 설계 복잡도 매우 높음 |
| 확장성 | 9 | 15% | 1.35 | 복잡한 비즈니스 플로우 증가 시 필수 |
| 비용 효율성 | 4 | 5% | 0.20 | 개발 비용 증가 |
| **총점** | | | **6.45** | **Phase 2 선정** |

**선정 이유**:
- MVP에서는 단순 롤백 처리로 충분
- Phase 2에서 복잡한 플로우 증가 시 필요

**적용 시기**: Phase 2

**적용 대상**:
- 이벤트 생성 플로우 (Event → AI → Content → Distribution)
- 결제 연동 시 (Phase 3)

---

#### 2.2.9 Event Sourcing (고도화 단계 패턴)

| 평가 기준 | 점수 | 가중치 | 계산 | 근거 |
|----------|-----|--------|------|------|
| 기능 적합성 | 7 | 35% | 2.45 | 이벤트 변경 이력 추적 |
| 성능 효과 | 5 | 25% | 1.25 | 성능 개선 효과 미미 |
| 운영 복잡도 | 3 | 20% | 0.60 | 이벤트 저장소 관리, 이벤트 재생 복잡도 매우 높음 |
| 확장성 | 8 | 15% | 1.20 | 감사 추적, 디버깅에 유용 |
| 비용 효율성 | 4 | 5% | 0.20 | 스토리지 비용 증가 |
| **총점** | | | **5.70** | **Phase 3 선정** |

**선정 이유**:
- MVP에서는 불필요
- Phase 3에서 감사 추적 요구사항 발생 시 적용

**적용 시기**: Phase 3

**적용 대상**:
- Event 서비스 (이벤트 생성/수정/삭제 이력)

---

### 2.3 선정 패턴 요약

#### Phase 1 (MVP) - 필수 패턴
| 패턴 | 총점 | 적용 서비스 | 우선순위 |
|------|------|------------|---------|
| Cache-Aside | 9.15 | AI, Content, User | 🔴 Critical |
| API Gateway | 8.25 | 전체 | 🔴 Critical |
| Asynchronous Request-Reply | 8.65 | AI, Content | 🔴 Critical |
| Circuit Breaker | 8.65 | AI, Content, Distribution | 🔴 Critical |
| Retry | 8.25 | 전체 (외부 API) | 🔴 Critical |

#### Phase 2 (확장) - 추가 패턴
| 패턴 | 총점 | 적용 서비스 | 우선순위 |
|------|------|------------|---------|
| Queue-Based Load Leveling | 7.10 | AI, Content, Distribution | 🟡 High |
| Saga | 6.45 | Event, AI, Content, Distribution | 🟡 High |

#### Phase 3 (고도화) - 최적화 패턴
| 패턴 | 총점 | 적용 서비스 | 우선순위 |
|------|------|------------|---------|
| CQRS | 7.60 | Analytics | 🟢 Medium |
| Event Sourcing | 5.70 | Event | 🟢 Medium |

---

## 3. 서비스별 패턴 적용 설계

### 3.1 전체 아키텍처 구조 (Phase 1 MVP)

```mermaid
graph TB
    subgraph "클라이언트"
        Mobile[모바일 앱]
        Web[웹 브라우저]
    end

    subgraph "API Gateway 레이어"
        Gateway[API Gateway<br/>- JWT 인증<br/>- Rate Limiting<br/>- Logging]
    end

    Mobile --> Gateway
    Web --> Gateway

    subgraph "마이크로서비스"
        User[User 서비스<br/>- 인증/인가<br/>- 프로필 관리]
        Event[Event 서비스<br/>- 이벤트 CRUD<br/>- 플로우 관리]
        AI[AI 서비스<br/>- 트렌드 분석<br/>- 이벤트 추천<br/>⏱️ Async]
        Content[Content 서비스<br/>- 이미지 생성<br/>⏱️ Async]
        Distribution[Distribution 서비스<br/>- 다중 채널 배포]
        Participation[Participation 서비스<br/>- 참여자 관리<br/>- 추첨]
        Analytics[Analytics 서비스<br/>- 실시간 대시보드]
    end

    Gateway --> User
    Gateway --> Event
    Gateway --> Participation
    Gateway --> Analytics

    Event --> AI
    Event --> Content
    Event --> Distribution

    subgraph "캐시 레이어"
        Redis[Redis Cache<br/>💾 Cache-Aside<br/>- AI 결과<br/>- 이미지<br/>- 사업자번호]
    end

    AI -.->|캐시 조회/저장| Redis
    Content -.->|캐시 조회/저장| Redis
    User -.->|캐시 조회/저장| Redis

    subgraph "외부 API (Circuit Breaker + Retry)"
        Claude[Claude/GPT-4 API]
        StableDiff[Stable Diffusion API]
        NTS[국세청 API]
        UDTV[우리동네TV API]
        RingoBiz[링고비즈 API]
        GenieTV[지니TV API]
        SNS[SNS APIs]
    end

    AI -->|🔴 Circuit Breaker| Claude
    Content -->|🔴 Circuit Breaker| StableDiff
    User -->|🔴 Circuit Breaker| NTS
    Distribution -->|🔴 Circuit Breaker| UDTV
    Distribution -->|🔴 Circuit Breaker| RingoBiz
    Distribution -->|🔴 Circuit Breaker| GenieTV
    Distribution -->|🔴 Circuit Breaker| SNS

    subgraph "데이터 레이어"
        UserDB[(User DB)]
        EventDB[(Event DB)]
        ParticipationDB[(Participation DB)]
    end

    User --> UserDB
    Event --> EventDB
    Participation --> ParticipationDB

    Analytics -.->|데이터 수집| ParticipationDB
    Analytics -.->|데이터 수집| EventDB
    Analytics -.->|데이터 수집| Distribution

    classDef asyncService fill:#ffe6e6,stroke:#ff4444,stroke-width:3px
    classDef cacheLayer fill:#e6f3ff,stroke:#4444ff,stroke-width:3px
    classDef gateway fill:#fff3e6,stroke:#ff8800,stroke-width:3px

    class AI,Content asyncService
    class Redis cacheLayer
    class Gateway gateway
```

### 3.2 서비스별 상세 패턴 적용

#### 3.2.1 User 서비스

**적용 패턴**:
1. **Cache-Aside** (사업자번호 검증 결과)
   - 검증 완료된 사업자번호 30일 캐싱
   - 캐시 미스 시 국세청 API 호출
   - 국세청 API 비용 90% 절감

2. **Circuit Breaker** (국세청 API)
   - 장애 시 폴백: 캐시된 결과 또는 수동 승인 플로우
   - Threshold: 10회 연속 실패
   - Timeout: 30초

3. **Retry** (국세청 API)
   - 재시도: 3회
   - Backoff: 1초 → 2초 → 4초

**핵심 플로우**:
```
회원가입 요청
  → 사업자번호 검증
    → Redis 캐시 조회
      → 캐시 히트: 즉시 반환
      → 캐시 미스: 국세청 API 호출 (Circuit Breaker + Retry)
        → 성공: Redis 캐싱 (30일)
        → 실패: 폴백 처리
```

---

#### 3.2.2 AI 서비스 (🔴 Critical)

**적용 패턴**:
1. **Asynchronous Request-Reply** (트렌드 분석 + 이벤트 추천)
   - 비동기 처리: 10초 이상 소요
   - Job ID 반환 → 클라이언트 폴링
   - 진행 상황 Redis 저장

2. **Cache-Aside** (트렌드 분석 결과)
   - 업종/지역/시즌별 1시간 캐싱
   - 동일 조건 요청 시 즉시 반환 (10초 → 0.1초)

3. **Circuit Breaker** (Claude/GPT-4 API)
   - 장애 시 폴백: 미리 준비된 템플릿 기반 추천
   - Threshold: 5회 연속 실패
   - Timeout: 15초

4. **Retry** (Claude/GPT-4 API)
   - 재시도: 3회
   - Backoff: 2초 → 4초 → 8초

**핵심 플로우**:
```mermaid
sequenceDiagram
    participant Client
    participant API_GW as API Gateway
    participant Event
    participant AI
    participant Redis
    participant Claude as Claude API

    Client->>API_GW: POST /events/ai-recommend
    API_GW->>Event: 이벤트 추천 요청
    Event->>AI: 트렌드 분석 + 추천 요청

    AI->>Redis: 캐시 조회 (업종/지역/시즌)

    alt 캐시 히트
        Redis-->>AI: 캐시 데이터 반환
        AI-->>Event: 즉시 결과 반환
    else 캐시 미스
        AI->>AI: Job ID 생성
        AI-->>Event: Job ID 반환
        Event-->>Client: Job ID + 폴링 URL

        par 비동기 처리
            AI->>Claude: 트렌드 분석 요청 (Circuit Breaker)
            Claude-->>AI: 분석 결과
            AI->>Redis: 진행률 업데이트 (50%)

            AI->>Claude: 이벤트 추천 요청 (Circuit Breaker)
            Claude-->>AI: 추천 결과
            AI->>Redis: 진행률 업데이트 (100%)

            AI->>Redis: 결과 캐싱 (1시간)
        end

        loop 폴링 (5초 간격)
            Client->>API_GW: GET /jobs/{jobId}
            API_GW->>AI: 진행 상황 조회
            AI->>Redis: 진행률 조회
            Redis-->>AI: 진행률 반환
            AI-->>Client: 진행률 또는 최종 결과
        end
    end
```

---

#### 3.2.3 Content 서비스 (🔴 Critical)

**적용 패턴**:
1. **Asynchronous Request-Reply** (이미지 생성)
   - 비동기 처리: 5초 이상 소요
   - Job ID 반환 → 클라이언트 폴링

2. **Cache-Aside** (생성된 이미지)
   - 영구 캐싱 (S3 + CloudFront CDN)
   - 동일 요청 시 CDN URL 즉시 반환

3. **Circuit Breaker** (Stable Diffusion API)
   - 장애 시 폴백: 기본 템플릿 이미지 제공
   - Threshold: 5회 연속 실패
   - Timeout: 10초

4. **Retry** (Stable Diffusion API)
   - 재시도: 3회
   - Backoff: 2초 → 4초 → 8초

**핵심 플로우**:
```
이미지 생성 요청
  → Job ID 반환
  → 비동기 처리
    → Stable Diffusion API 호출 (Circuit Breaker + Retry)
      → 성공: S3 업로드 + CDN URL 반환 + Redis 캐싱
      → 실패: 기본 템플릿 이미지 반환
  → 클라이언트 폴링으로 결과 확인
```

---

#### 3.2.4 Distribution 서비스

**적용 패턴**:
1. **Bulkhead** (채널별 격리)
   - 우리동네TV, 링고비즈, 지니TV, SNS 독립 처리
   - 하나의 채널 실패가 다른 채널에 영향 없음

2. **Circuit Breaker** (채널별 API)
   - 장애 시 폴백: 해당 채널 배포 스킵
   - Threshold: 5회 연속 실패
   - Timeout: 30초

3. **Retry** (채널별 API)
   - 재시도: 3회
   - Backoff: 1초 → 2초 → 4초

**핵심 플로우**:
```mermaid
graph LR
    Distribution[Distribution 서비스]

    subgraph "병렬 배포 (Bulkhead)"
        UDTV[우리동네TV<br/>Circuit Breaker]
        Ringo[링고비즈<br/>Circuit Breaker]
        Genie[지니TV<br/>Circuit Breaker]
        SNS[SNS<br/>Circuit Breaker]
    end

    Distribution -->|독립 처리| UDTV
    Distribution -->|독립 처리| Ringo
    Distribution -->|독립 처리| Genie
    Distribution -->|독립 처리| SNS

    UDTV -->|성공/실패| Result[배포 결과 집계]
    Ringo -->|성공/실패| Result
    Genie -->|성공/실패| Result
    SNS -->|성공/실패| Result
```

---

#### 3.2.5 Analytics 서비스

**적용 패턴**:
1. **Cache-Aside** (대시보드 데이터)
   - 5분 간격 데이터 캐싱
   - 실시간성 vs 성능 트레이드오프

2. **Materialized View** (Phase 2)
   - 복잡한 집계 쿼리 미리 계산
   - 5분 간격 업데이트

**핵심 플로우**:
```
대시보드 조회 요청
  → Redis 캐시 조회
    → 캐시 히트 (5분 이내): 즉시 반환
    → 캐시 미스:
      → Participation DB 조회
      → Distribution 서비스 API 호출
      → 외부 API 호출 (우리동네TV, SNS 통계)
      → 집계 계산
      → Redis 캐싱 (5분)
      → 결과 반환
```

---

### 3.3 Phase 2 확장 단계 아키텍처 (Queue 추가)

```mermaid
graph TB
    subgraph "클라이언트"
        Mobile[모바일 앱]
        Web[웹 브라우저]
    end

    subgraph "API Gateway 레이어"
        Gateway[API Gateway]
    end

    Mobile --> Gateway
    Web --> Gateway

    subgraph "마이크로서비스"
        Event[Event 서비스]
        AI[AI 서비스<br/>Worker Pool]
        Content[Content 서비스<br/>Worker Pool]
        Distribution[Distribution 서비스<br/>Worker Pool]
    end

    Gateway --> Event

    subgraph "메시지 큐 (Queue-Based Load Leveling)"
        AIQueue[AI 요청 큐]
        ContentQueue[콘텐츠 요청 큐]
        DistQueue[배포 요청 큐]
    end

    Event --> AIQueue
    Event --> ContentQueue
    Event --> DistQueue

    AIQueue --> AI
    ContentQueue --> Content
    DistQueue --> Distribution

    subgraph "캐시 레이어"
        Redis[Redis Cache]
    end

    AI -.->|캐시| Redis
    Content -.->|캐시| Redis

    classDef queueLayer fill:#fff3e6,stroke:#ff8800,stroke-width:3px
    class AIQueue,ContentQueue,DistQueue queueLayer
```

**Phase 2 추가 패턴**:
- **Queue-Based Load Leveling**: 피크 시간대 부하 분산
- **Saga**: 이벤트 생성 플로우 트랜잭션 관리

---

### 3.4 Phase 3 고도화 단계 아키텍처 (CQRS 추가)

```mermaid
graph TB
    subgraph "Analytics 서비스 (CQRS)"
        AnalyticsAPI[Analytics API]

        subgraph "Command Side (쓰기)"
            CommandHandler[Command Handler]
            WriteDB[(Write DB<br/>PostgreSQL)]
        end

        subgraph "Query Side (읽기)"
            QueryHandler[Query Handler]
            ReadDB[(Read DB<br/>MongoDB)]
        end
    end

    AnalyticsAPI --> CommandHandler
    AnalyticsAPI --> QueryHandler

    CommandHandler --> WriteDB
    WriteDB -.->|이벤트 발행| EventBus[이벤트 버스]
    EventBus --> ReadDB
    QueryHandler --> ReadDB

    Client[클라이언트] --> AnalyticsAPI
```

**Phase 3 추가 패턴**:
- **CQRS**: Analytics 서비스 읽기/쓰기 분리
- **Event Sourcing**: Event 서비스 변경 이력 추적

---

## 4. Phase별 구현 로드맵

### 4.1 Phase 1: MVP (12주)

**목표**: 핵심 기능 구현 및 사용자 검증

| 주차 | 작업 내용 | 적용 패턴 | 담당 서비스 |
|------|----------|----------|------------|
| 1-2 | 인프라 구축 | API Gateway | 전체 |
| 3-4 | User 서비스 개발 | Cache-Aside, Circuit Breaker, Retry | User |
| 5-6 | Event 서비스 개발 | - | Event |
| 7-8 | AI 서비스 개발 | Asynchronous Request-Reply, Cache-Aside, Circuit Breaker, Retry | AI |
| 9-10 | Content 서비스 개발 | Asynchronous Request-Reply, Cache-Aside, Circuit Breaker, Retry | Content |
| 11 | Distribution 서비스 개발 | Circuit Breaker, Retry, Bulkhead | Distribution |
| 12 | Participation & Analytics | Cache-Aside | Participation, Analytics |

**Phase 1 완료 기준**:
- ✅ 20개 유저스토리 완료
- ✅ AI 응답 시간 10초 이내
- ✅ 외부 API 장애 격리
- ✅ 사용자 100명 지원

---

### 4.2 Phase 2: 확장 (8주)

**목표**: 사용자 증가 대응 및 성능 최적화

| 주차 | 작업 내용 | 적용 패턴 | 담당 서비스 |
|------|----------|----------|------------|
| 1-2 | 메시지 큐 도입 | Queue-Based Load Leveling | AI, Content, Distribution |
| 3-4 | Saga 패턴 구현 | Saga | Event, AI, Content, Distribution |
| 5-6 | 수평 확장 테스트 | - | 전체 |
| 7-8 | 모니터링 강화 | - | 전체 |

**Phase 2 완료 기준**:
- ✅ 동시 이벤트 생성 50개 지원
- ✅ 사용자 1,000명 지원
- ✅ 피크 시간대 안정성 확보

---

### 4.3 Phase 3: 고도화 (8주)

**목표**: 성능 최적화 및 고급 기능 추가

| 주차 | 작업 내용 | 적용 패턴 | 담당 서비스 |
|------|----------|----------|------------|
| 1-3 | CQRS 구현 | CQRS | Analytics |
| 4-6 | Event Sourcing 구현 | Event Sourcing | Event |
| 7-8 | 성능 튜닝 | - | 전체 |

**Phase 3 완료 기준**:
- ✅ 대시보드 로딩 1초 이내
- ✅ 사용자 10,000명 지원
- ✅ 감사 추적 기능

---

## 5. 예상 성과 지표

### 5.1 성능 개선 효과

| 지표 | Before (패턴 미적용) | After (패턴 적용) | 개선율 |
|------|-------------------|-----------------|-------|
| **AI 응답 시간** (캐시 히트) | 10초 | 0.1초 | **99%** ↓ |
| **이미지 생성 시간** (캐시 히트) | 5초 | 0.1초 | **98%** ↓ |
| **사업자번호 검증** (캐시 히트) | 2초 | 0.05초 | **97.5%** ↓ |
| **API Gateway 응답 시간** | - | 10ms | - |
| **외부 API 장애 복구 시간** | 수동 처리 (5분+) | 자동 폴백 (0.1초) | **99.9%** ↓ |
| **대시보드 로딩 시간** (Phase 3) | 5초 | 1초 | **80%** ↓ |

### 5.2 비용 절감 효과

| 항목 | Before (월간) | After (월간) | 절감율 |
|------|-------------|------------|-------|
| **AI API 호출 비용** | $1,000 | $100 | **90%** ↓ |
| **이미지 생성 API 비용** | $500 | $50 | **90%** ↓ |
| **국세청 API 호출 비용** | $200 | $20 | **90%** ↓ |
| **서버 인프라 비용** (Phase 2) | $500 | $300 | **40%** ↓ |
| **총 운영 비용** | $2,200 | $470 | **78.6%** ↓ |

**연간 절감액**: $20,760

### 5.3 안정성 개선 효과

| 지표 | Before | After | 개선율 |
|------|--------|-------|-------|
| **시스템 가용성** | 95% | 99.9% | **4.9%** ↑ |
| **외부 API 장애 영향도** | 전체 서비스 중단 | 해당 기능만 폴백 | **99%** ↓ |
| **평균 복구 시간 (MTTR)** | 30분 | 0.1초 (자동) | **99.9%** ↓ |
| **사용자 이탈률** (에러 발생 시) | 80% | 5% | **93.75%** ↓ |

### 5.4 개발 생산성 효과

| 지표 | Before | After | 개선율 |
|------|--------|-------|-------|
| **외부 API 연동 시간** | 2주 | 3일 | **78.6%** ↓ |
| **에러 처리 코드 작성 시간** | 1주 | 1일 | **85.7%** ↓ |
| **모니터링 구축 시간** | 2주 | 3일 | **78.6%** ↓ |
| **총 개발 기간** | 20주 | 12주 (Phase 1) | **40%** ↓ |

### 5.5 사용자 경험 개선 효과

| 지표 | Before | After | 개선율 |
|------|--------|-------|-------|
| **이벤트 생성 완료 시간** | 15분 | 5분 | **66.7%** ↓ |
| **사용자 만족도** | 70점 | 90점 | **28.6%** ↑ |
| **재방문율** | 40% | 70% | **75%** ↑ |
| **이벤트 생성 성공률** | 80% | 98% | **22.5%** ↑ |

---

## 6. 구현 시 고려사항

### 6.1 Cache-Aside 구현

**Redis 캐시 키 전략**:
```
ai:trend:{업종}:{지역}:{시즌}  → TTL: 1시간
ai:recommend:{목적}:{업종}     → TTL: 24시간
content:image:{eventId}       → TTL: 영구 (CDN)
user:bizno:{사업자번호}       → TTL: 30일
```

**캐시 무효화 전략**:
- AI 트렌드: 1시간 자동 만료
- 이미지: 영구 보관 (S3 + CDN)
- 사업자번호: 30일 자동 만료 또는 재검증 요청 시 무효화

### 6.2 Circuit Breaker 설정

**Resilience4j 설정 예시**:
```yaml
resilience4j.circuitbreaker:
  instances:
    claudeAPI:
      failureRateThreshold: 50
      waitDurationInOpenState: 60s
      slidingWindowSize: 10
      minimumNumberOfCalls: 5
      permittedNumberOfCallsInHalfOpenState: 3
```

**폴백 전략**:
- **AI API**: 미리 준비된 템플릿 기반 추천
- **이미지 생성 API**: 기본 템플릿 이미지
- **국세청 API**: 캐시된 결과 또는 수동 승인
- **배포 채널 API**: 해당 채널 스킵, 다른 채널 계속 진행

### 6.3 Asynchronous Request-Reply 구현

**폴링 vs WebSocket**:
- **Phase 1**: 폴링 (간단한 구현)
  - 클라이언트: 5초 간격 폴링
  - 서버: Job 상태 Redis 저장
- **Phase 2**: WebSocket (실시간 업데이트)
  - 진행률 실시간 푸시
  - 서버 부하 감소

**Job 상태 관리**:
```json
{
  "jobId": "job-12345",
  "status": "processing",
  "progress": 50,
  "result": null,
  "error": null,
  "createdAt": "2025-10-21T10:00:00Z",
  "updatedAt": "2025-10-21T10:00:05Z"
}
```

### 6.4 Bulkhead 구현

**채널별 스레드 풀 분리**:
```java
@Configuration
public class ThreadPoolConfig {
    @Bean("udtv-pool")
    public ThreadPoolTaskExecutor udtvThreadPool() {
        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
        executor.setCorePoolSize(2);
        executor.setMaxPoolSize(5);
        executor.setQueueCapacity(100);
        return executor;
    }

    // 링고비즈, 지니TV, SNS도 동일하게 분리
}
```

---

## 7. 위험 요소 및 대응 방안

### 7.1 AI API 비용 폭발

**위험**:
- 캐싱 미적용 시 AI API 비용 월 $10,000+ 발생 가능

**대응 방안**:
1. Cache-Aside 패턴 필수 적용
2. 캐시 히트율 모니터링 (목표: 90% 이상)
3. 월간 비용 임계값 설정 ($500)
4. 임계값 초과 시 알림 및 자동 차단

### 7.2 외부 API 의존성

**위험**:
- 7개 외부 API 중 하나라도 장애 시 서비스 중단

**대응 방안**:
1. Circuit Breaker 패턴 필수 적용
2. 폴백 전략 명확히 정의
3. SLA 계약 체결 (우리동네TV, 지니TV 등)
4. 대체 API 준비 (예: Claude ↔ GPT-4 전환)

### 7.3 캐시 데이터 불일치

**위험**:
- 트렌드 데이터 변경 시 캐시 무효화 누락

**대응 방안**:
1. TTL 기반 자동 만료
2. 수동 무효화 API 제공
3. 캐시 버전 관리

### 7.4 비동기 처리 복잡도

**위험**:
- Job 상태 관리 실패, 폴링 부하

**대응 방안**:
1. Redis를 통한 안정적인 상태 관리
2. Job TTL 설정 (24시간 자동 삭제)
3. Phase 2에서 WebSocket으로 전환

---

## 8. 모니터링 및 운영

### 8.1 핵심 메트릭

**성능 메트릭**:
- AI 응답 시간 (p50, p95, p99)
- 이미지 생성 시간 (p50, p95, p99)
- 캐시 히트율 (목표: 90%)
- API Gateway 응답 시간 (목표: 10ms)

**안정성 메트릭**:
- Circuit Breaker 상태 (Open/Half-Open/Closed)
- 외부 API 실패율 (목표: 1% 이하)
- 시스템 가용성 (목표: 99.9%)

**비용 메트릭**:
- AI API 호출 횟수 및 비용
- 이미지 생성 API 호출 횟수 및 비용
- 캐시 절감 효과 (예상 비용 - 실제 비용)

### 8.2 알림 규칙

**Critical 알림**:
- Circuit Breaker Open 상태
- AI 응답 시간 > 20초
- 캐시 히트율 < 80%
- 시스템 가용성 < 99%

**Warning 알림**:
- 외부 API 실패율 > 5%
- 월간 AI API 비용 > $500
- 동시 접속자 > 80% 임계값

---

## 9. 결론

### 9.1 선정된 패턴 요약

**Phase 1 (MVP)**:
1. ✅ API Gateway - 중앙 인증 및 라우팅
2. ✅ Cache-Aside - AI/이미지 비용 90% 절감
3. ✅ Asynchronous Request-Reply - 사용자 경험 개선
4. ✅ Circuit Breaker - 외부 API 장애 격리
5. ✅ Retry - 일시적 오류 자동 복구

**Phase 2 (확장)**:
6. ✅ Queue-Based Load Leveling - 부하 분산
7. ✅ Saga - 복잡한 트랜잭션 관리

**Phase 3 (고도화)**:
8. ✅ CQRS - 대시보드 성능 최적화
9. ✅ Event Sourcing - 감사 추적

### 9.2 예상 효과

**성능**:
- AI 응답 시간: 99% 개선 (캐시 히트 시)
- 이미지 생성: 98% 개선 (캐시 히트 시)

**비용**:
- 연간 $20,760 절감 (78.6% 감소)

**안정성**:
- 시스템 가용성: 95% → 99.9%
- 외부 API 장애 영향: 99% 감소

**사용자 경험**:
- 이벤트 생성 시간: 66.7% 단축
- 사용자 만족도: 28.6% 향상

### 9.3 다음 단계

1. **Phase 1 (주 1-2)**: API Gateway 구축
2. **Phase 1 (주 3-4)**: User 서비스 + Cache-Aside + Circuit Breaker
3. **Phase 1 (주 5-6)**: Event 서비스
4. **Phase 1 (주 7-8)**: AI 서비스 + Asynchronous Request-Reply
5. **Phase 1 (주 9-10)**: Content 서비스 + Asynchronous Request-Reply
6. **Phase 1 (주 11)**: Distribution 서비스 + Bulkhead
7. **Phase 1 (주 12)**: Participation & Analytics + 통합 테스트

---

**문서 작성자**: System Architect - 박영자
**검토자**: Backend Developer - 최수연, DevOps Engineer - 송근정
**승인일**: 2025-10-21