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

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

**작성일**: 2025-10-21
**작성자**: System Architect (박영자)
**버전**: 2.0 (3개 핵심 패턴 적용)

---

## 1. 요구사항 분석

### 1.1 마이크로서비스별 기능 및 비기능 요구사항

#### 1.1.1 User 서비스
**기능 요구사항**:
- 회원가입/로그인 (JWT 인증)
- 매장 정보 관리 및 사업자번호 검증
- KT 인증 시스템 연동

**비기능 요구사항**:
- 응답시간: 1초 이내
- 가용성: 99.9%
- 보안: 개인정보 암호화 (AES-256), HTTPS/TLS
- 확장성: 1,000 동시 사용자

**기술적 도전과제**:
- 외부 사업자번호 검증 API 의존성
- 인증 토큰 관리 및 세션 유지
- 개인정보 보호 규정 준수

---

#### 1.1.2 Event Planning 서비스
**기능 요구사항**:
- AI 기반 업종/지역 트렌드 분석
- AI 이벤트상품 추천 (Claude API)
- AI 참여 방법 설계
- AI 홍보 문구 생성 (GPT-4 API)

**비기능 요구사항**:
- **응답시간: 10초 이내 (전체 기획 과정)** ⚡
- AI API 병렬 호출 필수
- 추첨형/선착순형 이벤트 자동 프로세스 분기
- 확장성: 100개 동시 이벤트 기획

**기술적 도전과제**:
- **Claude + GPT-4 API 병렬 호출 및 응답 시간 관리**
- AI 프롬프트 최적화로 10초 목표 달성
- 트렌드 데이터베이스 실시간 조회 성능
- 응답 캐싱 전략

---

#### 1.1.3 Content Generation 서비스
**기능 요구사항**:
- AI 이미지 생성 (Stable Diffusion, 3종)
- AI 영상 제작 (15초)
- SNS 콘텐츠 자동 생성 (플랫폼별 최적화)
- QR 포스터 생성

**비기능 요구사항**:
- **응답시간: 5-8분 이내 (병렬 처리 시)** ⚡
- 이미지 생성: 2-3분 (Stable Diffusion 특성)
- 영상 제작: 3-5분 (AI 영상 엔진 특성)
- GPU 가속 활용
- 확장성: 50개 동시 콘텐츠 생성

**기술적 도전과제**:
- **이미지 3종 + 영상 1개 병렬 생성**
- 진행 상황 실시간 피드백
- 백그라운드 비동기 처리 필수
- 품질과 속도 균형 유지

---

#### 1.1.4 Distribution 서비스
**기능 요구사항**:
- 다중 채널 배포 (우리동네TV, 링고비즈, 지니TV, Instagram, Naver Blog, Kakao Channel)
- 네이버 클로바 TTS 연동 (연결음 생성)
- 배포 실패 시 자동 재시도 (3회)

**비기능 요구사항**:
- **응답시간: 1분 이내 (전체 배포 과정)** ⚡
- 채널별 병렬 배포 필수
- 배포 상태 실시간 업데이트
- 확장성: 100개 동시 배포

**기술적 도전과제**:
- **6개 외부 API 병렬 호출 및 통합**
- API 장애 대응 (Circuit Breaker, Retry)
- 네이버 클로바 TTS 품질 보장
- 배포 실패 복구 전략

---

#### 1.1.5 Participation 서비스
**기능 요구사항**:
- 이벤트 참여 신청 및 중복 방지
- 추첨형 자동 추첨 (매장 방문 고객 가산점)
- 선착순형 쿠폰 소진 시 자동 종료
- 당첨 알림 발송 (SMS/카카오 알림톡)

**비기능 요구사항**:
- 응답시간: 1초 이내
- 1인 1회 참여 보장 (멱등성)
- 공정한 추첨 알고리즘
- 확장성: 10,000 동시 참여

**기술적 도전과제**:
- 중복 참여 방지 (전화번호 기준)
- 추첨형/선착순형 프로세스 분기
- 대량 SMS/알림톡 발송
- 매장 방문 고객 가산점 처리

---

#### 1.1.6 Analytics 서비스
**기능 요구사항**:
- 실시간 대시보드 (참여자 수, 노출 수, 매출 증가율)
- 5분 간격 데이터 수집 및 업데이트
- 채널별 성과 분석 (Instagram, Naver Blog, Kakao Channel API)
- ROI 자동 계산
- 분석 리포트 PDF 생성

**비기능 요구사항**:
- **데이터 수집 주기: 5분 간격** ⏱
- 실시간 데이터 시각화
- 확장성: 100개 이벤트 동시 분석

**기술적 도전과제**:
- **다중 데이터 소스 통합 (KT API, POS, SNS API)**
- 5분 간격 스케줄러 기반 수집
- 대시보드 실시간 업데이트

---

#### 1.1.7 AI Learning 서비스
**기능 요구사항**:
- 이벤트 결과 분석 및 개선안 생성
- 성공 패턴 학습 및 재활용
- 다음 이벤트 아이디어 제안 (시즌별)

**비기능 요구사항**:
- 빅데이터 분석 시스템 연동
- AI 머신러닝 엔진 API 호출
- 학습 데이터 누적 및 모델 개선
- 확장성: 누적 데이터 기반 지속적 학습

**기술적 도전과제**:
- 성공/실패 패턴 자동 학습
- 업종별/지역별 데이터 축적
- 추천 정확도 향상 알고리즘

---

### 1.2 통합 분석 및 핵심 도전과제

#### 성능 목표 요약
| 서비스 | 목표 응답시간 | 핵심 최적화 전략 |
|--------|--------------|------------------|
| Event Planning | **10초 이내** | AI API 병렬 호출 |
| Content Generation | **5-8분 이내** | 이미지+영상 병렬 생성, 비동기 처리 |
| Distribution | **1분 이내** | 6개 채널 병렬 배포 |
| Analytics | **5분 주기** | 스케줄러 수집 |

#### 확장성 요구사항
- **동시 이벤트 처리**: 최소 100개
- **AI API 동시 호출**: 최소 50개
- **배포 API 동시 호출**: 최소 100개

#### 외부 시스템 의존성
- **KT 채널**: 우리동네TV, 링고비즈, 지니TV
- **AI API**: Claude, GPT-4, Stable Diffusion
- **SNS**: Instagram, Naver Blog, Kakao Channel
- **기타**: 네이버 클로바 TTS, 사업자번호 검증, POS 시스템

---

## 2. 클라우드 아키텍처 패턴 선정

### 2.1 패턴 평가 매트릭스

#### 핵심 패턴 정량 평가

| 패턴 | 기능 적합성<br/>(35%) | 성능 효과<br/>(25%) | 운영 복잡도<br/>(20%) | 확장성<br/>(15%) | 비용 효율성<br/>(5%) | **총점** | **우선순위** |
|------|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
| **API Gateway** | 10 × 0.35 = 3.5 | 9 × 0.25 = 2.25 | 9 × 0.20 = 1.8 | 9 × 0.15 = 1.35 | 8 × 0.05 = 0.4 | **9.30** | 🥇 1위 |
| **Async Request-Reply** | 10 × 0.35 = 3.5 | 9 × 0.25 = 2.25 | 7 × 0.20 = 1.4 | 8 × 0.15 = 1.2 | 7 × 0.05 = 0.35 | **8.70** | 🥈 2위 |
| **Circuit Breaker** | 9 × 0.35 = 3.15 | 7 × 0.25 = 1.75 | 8 × 0.20 = 1.6 | 8 × 0.15 = 1.2 | 8 × 0.05 = 0.4 | **8.10** | 🥉 3위 |

---

### 2.2 선정 패턴 및 적용 전략

#### 🥇 **1. API Gateway** (총점: 9.30)

**선정 이유**:
- 단일 진입점으로 7개 마이크로서비스 라우팅
- 인증/인가 중앙 처리 (JWT 토큰 검증)
- Rate Limiting으로 100개 동시 이벤트 관리
- 횡단 관심사 분리 (로깅, 모니터링)

**적용 서비스**: 전체 서비스

**예상 효과**:
- 클라이언트 요청 단순화 (1개 엔드포인트)
- 인증 처리 시간 50% 단축
- 서비스 간 결합도 감소

**구현 기술**:
- **기술 스택**: Kong, AWS API Gateway, Spring Cloud Gateway
- **Rate Limiting**: 사용자당 1분 100 요청
- **JWT 토큰**: 만료 시간 1시간, Refresh Token 7일
- **로깅**: 모든 요청/응답 로그 저장 (CloudWatch, ELK)

---

#### 🥈 **2. Async Request-Reply** (총점: 8.70)

**선정 이유**:
- **Content Generation 서비스의 5-8분 처리 시간 대응**
- 이미지/영상 생성 백그라운드 처리
- 진행 상황 실시간 피드백 (폴링)
- 클라이언트 블로킹 방지

**적용 서비스**: Content Generation

**예상 효과**:
- 사용자 대기 시간 체감 80% 감소
- 시스템 응답성 향상
- 동시 콘텐츠 생성 50개 처리 가능

**구현 기술**:
- **Job ID 관리**: UUID v4 사용
- **상태 폴링**: 5초 간격, 최대 10분 타임아웃
- **상태 관리**: Redis 또는 DB 기반 Job 상태 추적

**구현 예시**:
```javascript
// 클라이언트: 콘텐츠 생성 요청
const response = await axios.post('/api/content/generate', {
  eventId: 'evt-001',
  imageCount: 3
});
const jobId = response.data.jobId; // Job ID 발급

// 상태 폴링 (5초 간격)
const checkStatus = setInterval(async () => {
  const status = await axios.get(`/api/content/status/${jobId}`);
  if (status.data.completed) {
    clearInterval(checkStatus);
    // 콘텐츠 다운로드
  }
}, 5000);
```

---

#### 🥉 **3. Circuit Breaker** (총점: 8.10)

**선정 이유**:
- **6개 외부 API 장애 대응 (KT 채널, AI API, SNS)**
- Distribution 서비스의 배포 실패 방지
- API 장애 시 빠른 실패 및 폴백
- 연쇄 장애 전파 차단

**적용 서비스**: Distribution, Event Planning, Content Generation

**예상 효과**:
- API 장애 시 응답 시간 95% 단축
- 시스템 가용성 99.9% 보장
- 배포 성공률 98% 이상 유지

**구현 기술**:
- **타임아웃 설정**: 외부 API별 차등 (15초 ~ 60초)
- **실패 임계값**: 50% 실패 시 OPEN
- **재시도 간격**: 30초 후 HALF-OPEN
- **폴백 전략**: 기본값 제공 또는 실패 메시지

**구현 예시** (Node.js with opossum):
```javascript
const CircuitBreaker = require('opossum');

// 우리동네TV API 호출
const callWooridongneTV = async (data) => {
  return axios.post('https://api.wooridongne.kt.com/deploy', data);
};

const breaker = new CircuitBreaker(callWooridongneTV, {
  timeout: 15000, // 15초 타임아웃
  errorThresholdPercentage: 50, // 50% 실패 시 OPEN
  resetTimeout: 30000 // 30초 후 재시도
});

breaker.fallback(() => ({
  success: false,
  message: '우리동네TV 배포 실패'
}));

// 배포 요청
const result = await breaker.fire(deployData);
```

**Spring Boot 예시** (Resilience4j):
```java
@Service
public class DistributionService {

    @CircuitBreaker(name = "wooridongneTV", fallbackMethod = "fallbackDeploy")
    public DeployResult deployToWooridongneTV(DeployData data) {
        return wooridongneAPI.deploy(data);
    }

    private DeployResult fallbackDeploy(DeployData data, Exception e) {
        return DeployResult.builder()
            .success(false)
            .message("우리동네TV 배포 실패: " + e.getMessage())
            .build();
    }
}
```

---

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

### 3.1 전체 아키텍처 구조

```mermaid
graph TB
    subgraph "클라이언트"
        Web[웹 애플리케이션]
        Mobile[모바일 앱]
    end

    subgraph "API Gateway Layer"
        Gateway[API Gateway<br/>인증/인가/라우팅/Rate Limiting]
    end

    subgraph "마이크로서비스"
        User[User 서비스<br/>회원/매장 관리]
        Planning[Event Planning 서비스<br/>AI 이벤트 기획]
        Content[Content Generation 서비스<br/>AI 콘텐츠 생성<br/>Async Request-Reply]
        Dist[Distribution 서비스<br/>다중 채널 배포<br/>Circuit Breaker]
        Participation[Participation 서비스<br/>참여/추첨 관리]
        Analytics[Analytics 서비스<br/>효과 측정]
        AILearn[AI Learning 서비스<br/>학습/개선]
    end

    subgraph "데이터 계층"
        UserDB[(User DB<br/>PostgreSQL)]
        PlanningDB[(Planning DB<br/>MongoDB)]
        ContentDB[(Content DB<br/>MongoDB)]
        DistDB[(Distribution DB<br/>PostgreSQL)]
        PartDB[(Participation DB<br/>PostgreSQL)]
        AnalyticsDB[(Analytics DB<br/>MongoDB)]
        AILearnDB[(AI Learning DB<br/>MongoDB)]
        JobStore[(Job Store<br/>Redis)]
    end

    subgraph "외부 시스템"
        KTAPI[KT 채널 API<br/>우리동네TV/링고비즈/지니TV]
        AIAPI[AI API<br/>Claude/GPT-4/Stable Diffusion]
        SNS[SNS API<br/>Instagram/Naver/Kakao]
        Clova[네이버 클로바 TTS]
        POS[POS 시스템]
    end

    Web --> Gateway
    Mobile --> Gateway

    Gateway --> User
    Gateway --> Planning
    Gateway --> Content
    Gateway --> Dist
    Gateway --> Participation
    Gateway --> Analytics
    Gateway --> AILearn

    User --> UserDB
    Planning --> PlanningDB
    Content --> ContentDB
    Content --> JobStore
    Dist --> DistDB
    Participation --> PartDB
    Analytics --> AnalyticsDB
    AILearn --> AILearnDB

    Planning -->|Circuit Breaker| AIAPI
    Content -->|Circuit Breaker| AIAPI
    Dist -->|Circuit Breaker| KTAPI
    Dist -->|Circuit Breaker| SNS
    Dist -->|Circuit Breaker| Clova
    Analytics --> KTAPI
    Analytics --> SNS
    Analytics --> POS
```

---

### 3.2 Event Planning 서비스 - 10초 응답 최적화

**패턴 적용**:
- **Circuit Breaker**: Claude + GPT-4 API 장애 대응
- **병렬 처리**: AI API 동시 호출

**아키텍처**:
```mermaid
sequenceDiagram
    participant Client
    participant Gateway
    participant Planning as Event Planning
    participant DB as Planning DB
    participant Claude as Claude API
    participant GPT4 as GPT-4 API

    Client->>Gateway: 이벤트 기획 시작
    Gateway->>Planning: 기획 요청

    Note over Planning,DB: Phase 1: 트렌드 분석 (3초 목표)
    Planning->>DB: 트렌드 데이터 조회
    DB-->>Planning: 트렌드 데이터

    Note over Planning,GPT4: Phase 2: AI 병렬 호출 (7초 목표)
    par Claude: 이벤트상품 + 참여방법
        Planning->>Claude: 이벤트상품 추천 요청<br/>+ 참여방법 설계 요청
        Claude-->>Planning: 추천 결과 (5초)
    and GPT-4: 홍보문구
        Planning->>GPT4: 홍보문구 생성 요청
        GPT4-->>Planning: 홍보문구 (4초)
    end

    Planning->>DB: 기획안 저장
    Planning-->>Gateway: 완성된 기획안 (총 10초 이내)
    Gateway-->>Client: 기획안 제공
```

**예상 성과**:
- **총 응답시간: 10초 이내** (목표 달성)
- AI API 병렬 호출: 9초 → 5초

---

### 3.3 Content Generation 서비스 - 비동기 처리

**패턴 적용**:
- **Async Request-Reply**: 5-8분 장시간 처리
- **Circuit Breaker**: Stable Diffusion API 장애 대응

**아키텍처**:
```mermaid
sequenceDiagram
    participant Client
    participant Gateway
    participant Content as Content Generation
    participant JobStore as Job Store (Redis)
    participant Worker as Background Worker
    participant SD as Stable Diffusion
    participant VideoAI as AI Video Engine
    participant DB as Content DB

    Client->>Gateway: 콘텐츠 생성 요청
    Gateway->>Content: 생성 요청
    Content->>JobStore: Job 생성 (상태: PENDING)
    Content-->>Gateway: Job ID 발급
    Gateway-->>Client: Job ID 반환

    Note over Client: 클라이언트는 다른 작업 가능

    Content->>Worker: 비동기 작업 시작

    par 이미지 3종 생성 (2-3분)
        Worker->>SD: 이미지 생성 요청 (3건 병렬)
        SD-->>Worker: 이미지 3종
    and 영상 1개 생성 (3-5분)
        Worker->>VideoAI: 영상 제작 요청
        VideoAI-->>Worker: 15초 영상
    end

    Worker->>DB: 콘텐츠 저장
    Worker->>JobStore: 상태 업데이트 (COMPLETED)

    loop 상태 확인 (5초 간격)
        Client->>Gateway: Job 상태 조회
        Gateway->>Content: 상태 조회
        Content->>JobStore: 상태 확인
        JobStore-->>Content: 상태 + 진행률
        Content-->>Gateway: 진행 상황 (예: 60% 완료)
        Gateway-->>Client: 진행률 표시
    end

    Client->>Gateway: 최종 상태 조회
    Gateway->>Content: 상태 조회
    Content-->>Gateway: COMPLETED + 콘텐츠 URL
    Gateway-->>Client: 콘텐츠 다운로드
```

**예상 성과**:
- **총 처리시간: 5-8분** (목표 달성)
- 사용자 대기 체감 시간: 8분 → 0초 (비동기)
- 동시 처리 능력: 50개 콘텐츠

---

### 3.4 Distribution 서비스 - 안정적 배포

**패턴 적용**:
- **Circuit Breaker**: 6개 외부 API 장애 대응
- **병렬 배포**: 6개 채널 동시 배포

**아키텍처**:
```mermaid
sequenceDiagram
    participant Client
    participant Gateway
    participant Dist as Distribution
    participant CB1 as Circuit Breaker<br/>(우리동네TV)
    participant CB2 as Circuit Breaker<br/>(지니TV)
    participant CB3 as Circuit Breaker<br/>(Instagram)
    participant KTAPI as KT API
    participant SNS as SNS API

    Client->>Gateway: 배포 요청 (6개 채널)
    Gateway->>Dist: 배포 시작

    par 병렬 배포 (1분 목표)
        Dist->>CB1: 우리동네TV 배포
        CB1->>KTAPI: API 호출
        alt API 성공
            KTAPI-->>CB1: 배포 완료
        else API 실패
            KTAPI--xCB1: 오류
            CB1-->>Dist: Fallback (배포 실패)
        end
        CB1-->>Dist: 결과 반환
    and
        Dist->>CB2: 지니TV 배포
        CB2->>KTAPI: API 호출
        KTAPI-->>CB2: 배포 완료
        CB2-->>Dist: 결과 반환
    and
        Dist->>CB3: Instagram 배포
        CB3->>SNS: API 호출
        SNS-->>CB3: 포스팅 완료
        CB3-->>Dist: 결과 반환
    end

    Dist-->>Gateway: 배포 결과 (성공 5/6)
    Gateway-->>Client: 배포 완료 + 실패 채널 안내
```

**예상 성과**:
- **총 배포시간: 1분 이내** (목표 달성)
- API 장애 시 응답: 30초 → 3초 (Circuit Breaker)
- 배포 안정성: 95% → 98%

---

## 4. 구현 로드맵

### Phase 1: MVP (Minimum Viable Product) - 3개월

**목표**: 핵심 비즈니스 기능 제공 및 빠른 출시

**적용 패턴**:
1. **API Gateway** - 단일 진입점 및 인증/인가
2. **Async Request-Reply** - 콘텐츠 생성 비동기 처리
3. **Circuit Breaker** - 외부 API 장애 대응

**구현 우선순위**:
1. **Week 1-4**: User 서비스 + API Gateway
   - 회원가입/로그인 (JWT 인증)
   - 매장 정보 관리
   - 사업자번호 검증 연동
   - API Gateway 구축 (Kong 또는 Spring Cloud Gateway)

2. **Week 5-8**: Event Planning 서비스
   - AI API 연동 (Claude, GPT-4)
   - Circuit Breaker 적용
   - AI API 병렬 호출 구현

3. **Week 9-10**: Content Generation 서비스
   - Async Request-Reply 패턴 구현
   - Stable Diffusion 연동
   - 진행 상황 폴링 API
   - Redis 기반 Job Store 구축

4. **Week 11-12**: Distribution + Participation 서비스
   - 6개 채널 병렬 배포 (Circuit Breaker)
   - 추첨/선착순 분기 로직

**성공 지표**:
- Event Planning: 10초 이내 응답 ✅
- Content Generation: 8분 이내 완료 ✅
- Distribution: 1분 이내 배포 ✅
- 동시 이벤트 처리: 50개

---

## 5. 예상 성과 지표

### 5.1 성능 개선

| 지표 | 현재 (패턴 미적용) | Phase 1 MVP |
|------|-------------------|-------------|
| **Event Planning 응답시간** | 25초 | **10초** ✅ |
| **Content Generation 완료시간** | 12분 | **8분** ✅ |
| **Distribution 배포시간** | 3분 | **1분** ✅ |
| **동시 이벤트 처리** | 20개 | 50개 |
| **시스템 가용성** | 95% | 99% |

---

### 5.2 패턴별 기대 효과

| 패턴 | 적용 효과 | 개선율 |
|------|----------|--------|
| **API Gateway** | 클라이언트 통합 엔드포인트, 인증 중앙화 | 인증 처리 50% 단축 |
| **Async Request-Reply** | 사용자 대기 시간 체감 감소 | 80% 체감 시간 감소 |
| **Circuit Breaker** | API 장애 시 빠른 실패, 연쇄 장애 방지 | 응답 시간 95% 단축 |

---

## 6. 리스크 관리

### 6.1 기술적 리스크

| 리스크 | 확률 | 영향도 | 완화 전략 |
|--------|------|--------|-----------|
| AI API 응답 지연 (>10초) | 중간 | 높음 | 병렬 호출, 프롬프트 최적화 |
| 외부 API 장애 | 높음 | 높음 | Circuit Breaker, 폴백 전략 |
| Job Store (Redis) 장애 | 낮음 | 중간 | Redis Cluster, DB 폴백 |

### 6.2 운영 리스크

| 리스크 | 확률 | 영향도 | 완화 전략 |
|--------|------|--------|-----------|
| 피크 타임 트래픽 폭주 | 높음 | 높음 | Auto Scaling, Rate Limiting |
| 배포 실패율 증가 | 중간 | 중간 | Circuit Breaker 폴백 전략 |

---

## 7. 결론

### 7.1 핵심 패턴 요약

본 서비스는 **3개의 클라우드 아키텍처 패턴**을 적용하여 성능, 확장성, 안정성을 보장합니다:

1. **API Gateway**: 단일 진입점 및 횡단 관심사 분리
2. **Async Request-Reply**: 장시간 처리 작업 비동기화
3. **Circuit Breaker**: 외부 API 장애 대응

### 7.2 예상 효과

- **Event Planning**: 25초 → **10초** (60% 단축) ✅
- **Content Generation**: 12분 → **8분** (33% 단축) ✅
- **Distribution**: 3분 → **1분** (67% 단축) ✅
- **시스템 가용성**: 95% → **99%** ✅
- **동시 이벤트 처리**: 20개 → **50개** (2.5배 향상) ✅

### 7.3 다음 단계

1. **Phase 1 MVP 착수** (3개월)
   - API Gateway + Async Request-Reply + Circuit Breaker 우선 구현
   - 핵심 비즈니스 기능 검증

2. **성능 모니터링**
   - Prometheus + Grafana 대시보드 구축
   - 각 패턴별 성과 지표 측정

3. **지속적 개선**
   - 추가 패턴 도입 검토 (Cache-Aside, CQRS 등)
   - AI 학습 정확도 향상

---

**문서 승인**:
- [ ] System Architect (박영자)
- [ ] Backend Developer (최수연)
- [ ] DevOps Engineer (송근정)
- [ ] PO (갑빠)

**참조 문서**:
- design/userstory.md
- claude/cloud-design-patterns.md
- design/pattern/architecture-pattern-backup-20251021.md (백업)