shared-dg05-dodari/kt-event-marketing-fe

mirror of https://github.com/ktds-dg0501/kt-event-marketing-fe.git synced 2025-12-06 22:46:25 +00:00

cherry2250 3f6e005026 초기 프로젝트 설정 및 설계 문서 추가

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

2025-10-24 10:10:16 +09:00

34 KiB

Raw Blame History

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

문서 정보

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

1. 요구사항 분석 결과

1.1 기능적 요구사항

마이크로서비스별 핵심 기능

User 서비스 (4개 유저스토리)
- 회원가입/로그인/프로필 관리
- 사업자번호 검증 (국세청 API 연동)
- 세션 관리 및 인증/인가
Event 서비스 (7개 유저스토리)
- 이벤트 CRUD 관리
- 대시보드 현황 조회
- 이벤트 목적 선택 및 생성 플로우 관리
- AI/Content/Distribution 서비스 연동
AI 서비스 (1개 유저스토리)
- 업종/지역/시즌 트렌드 분석 (5초 이내)
- 3가지 이벤트 추천 생성 (5초 이내)
- Claude API/GPT-4 API 연동
- 병렬 처리: 트렌드 분석 + 이벤트 추천 동시 실행 (총 10초 목표)
Content 서비스 (2개 유저스토리)
- SNS 이미지 3가지 스타일 자동 생성 (5초 이내)
- 플랫폼별 이미지 최적화 (Instagram/Naver/Kakao)
- Stable Diffusion/DALL-E API 연동
Distribution 서비스 (2개 유저스토리)
- 다중 채널 동시 배포 (우리동네TV, 링고비즈, 지니TV, SNS)
- 채널별 독립 처리 및 실패 복구
- 배포 상태 실시간 모니터링
Participation 서비스 (3개 유저스토리)
- 이벤트 참여자 관리 (중복 체크)
- 자동 추첨 시스템
- 참여자 목록 조회 및 필터링
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 의존성 감소

적용 대상:

AI 트렌드 분석 결과: 업종/지역/시즌별 1시간 캐싱
AI 이벤트 추천 결과: 동일 조건 24시간 캐싱
SNS 이미지 생성 결과: 영구 캐싱 (CDN 연동)
사업자번호 검증 결과: 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초 이상 소요)
사용자 이탈 방지 (로딩 인디케이터 + 진행률 표시)

적용 방안:

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

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 장애 시 전체 서비스 중단 방지
빠른 실패 및 폴백 처리

적용 대상:

AI API: Claude/GPT-4 장애 시 미리 준비된 템플릿 반환
이미지 생성 API: Stable Diffusion 장애 시 기본 템플릿 이미지 제공
배포 채널 API: 개별 채널 장애가 다른 채널에 영향 없도록 격리
국세청 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)

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 서비스

적용 패턴:

Cache-Aside (사업자번호 검증 결과)
- 검증 완료된 사업자번호 30일 캐싱
- 캐시 미스 시 국세청 API 호출
- 국세청 API 비용 90% 절감
Circuit Breaker (국세청 API)
- 장애 시 폴백: 캐시된 결과 또는 수동 승인 플로우
- Threshold: 10회 연속 실패
- Timeout: 30초
Retry (국세청 API)
- 재시도: 3회
- Backoff: 1초 → 2초 → 4초

핵심 플로우:

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

3.2.2 AI 서비스 (🔴 Critical)

적용 패턴:

Asynchronous Request-Reply (트렌드 분석 + 이벤트 추천)
- 비동기 처리: 10초 이상 소요
- Job ID 반환 → 클라이언트 폴링
- 진행 상황 Redis 저장
Cache-Aside (트렌드 분석 결과)
- 업종/지역/시즌별 1시간 캐싱
- 동일 조건 요청 시 즉시 반환 (10초 → 0.1초)
Circuit Breaker (Claude/GPT-4 API)
- 장애 시 폴백: 미리 준비된 템플릿 기반 추천
- Threshold: 5회 연속 실패
- Timeout: 15초
Retry (Claude/GPT-4 API)
- 재시도: 3회
- Backoff: 2초 → 4초 → 8초

핵심 플로우:

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)

적용 패턴:

Asynchronous Request-Reply (이미지 생성)
- 비동기 처리: 5초 이상 소요
- Job ID 반환 → 클라이언트 폴링
Cache-Aside (생성된 이미지)
- 영구 캐싱 (S3 + CloudFront CDN)
- 동일 요청 시 CDN URL 즉시 반환
Circuit Breaker (Stable Diffusion API)
- 장애 시 폴백: 기본 템플릿 이미지 제공
- Threshold: 5회 연속 실패
- Timeout: 10초
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 서비스

적용 패턴:

Bulkhead (채널별 격리)
- 우리동네TV, 링고비즈, 지니TV, SNS 독립 처리
- 하나의 채널 실패가 다른 채널에 영향 없음
Circuit Breaker (채널별 API)
- 장애 시 폴백: 해당 채널 배포 스킵
- Threshold: 5회 연속 실패
- Timeout: 30초
Retry (채널별 API)
- 재시도: 3회
- Backoff: 1초 → 2초 → 4초

핵심 플로우:

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 서비스

적용 패턴:

Cache-Aside (대시보드 데이터)
- 5분 간격 데이터 캐싱
- 실시간성 vs 성능 트레이드오프
Materialized View (Phase 2)
- 복잡한 집계 쿼리 미리 계산
- 5분 간격 업데이트

핵심 플로우:

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

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

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 추가)

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 설정 예시:

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 상태 관리:

{
  "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 구현

채널별 스레드 풀 분리:

@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+ 발생 가능

대응 방안:

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

7.2 외부 API 의존성

위험:

7개 외부 API 중 하나라도 장애 시 서비스 중단

대응 방안:

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

7.3 캐시 데이터 불일치

위험:

트렌드 데이터 변경 시 캐시 무효화 누락

대응 방안:

TTL 기반 자동 만료
수동 무효화 API 제공
캐시 버전 관리

7.4 비동기 처리 복잡도

위험:

Job 상태 관리 실패, 폴링 부하

대응 방안:

Redis를 통한 안정적인 상태 관리
Job TTL 설정 (24시간 자동 삭제)
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):

✅ API Gateway - 중앙 인증 및 라우팅
✅ Cache-Aside - AI/이미지 비용 90% 절감
✅ Asynchronous Request-Reply - 사용자 경험 개선
✅ Circuit Breaker - 외부 API 장애 격리
✅ 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 다음 단계

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

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

34 KiB Raw Blame History

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

목차

1. 요구사항 분석 결과

1.1 기능적 요구사항

마이크로서비스별 핵심 기능

1.2 비기능적 요구사항

성능 요구사항

가용성 및 신뢰성

확장성

보안 요구사항

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

사용자 인터랙션 패턴

실시간 처리 요구사항

1.4 기술적 도전과제

1. AI 응답 시간 관리 (🔴 Critical)

2. 다중 외부 API 의존성 (🔴 Critical)

3. 실시간 대시보드 성능 (🟡 High)

4. 복잡한 비즈니스 트랜잭션 (🟡 High)

2. 패턴 평가 매트릭스

2.1 평가 기준

2.2 핵심 패턴 평가

2.2.1 API Gateway (필수 패턴)

2.2.2 Cache-Aside (필수 패턴)

2.2.3 Asynchronous Request-Reply (필수 패턴)

2.2.4 Circuit Breaker (필수 패턴)

2.2.5 Retry (필수 패턴)

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

2.2.7 CQRS (고도화 단계 패턴)

2.2.8 Saga (확장 단계 패턴)

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

2.3 선정 패턴 요약

Phase 1 (MVP) - 필수 패턴

Phase 2 (확장) - 추가 패턴

Phase 3 (고도화) - 최적화 패턴

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

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

3.2 서비스별 상세 패턴 적용

3.2.1 User 서비스

3.2.2 AI 서비스 (🔴 Critical)

3.2.3 Content 서비스 (🔴 Critical)

3.2.4 Distribution 서비스

3.2.5 Analytics 서비스

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

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

4. Phase별 구현 로드맵

4.1 Phase 1: MVP (12주)

4.2 Phase 2: 확장 (8주)

4.3 Phase 3: 고도화 (8주)

5. 예상 성과 지표

5.1 성능 개선 효과

5.2 비용 절감 효과

5.3 안정성 개선 효과

5.4 개발 생산성 효과

5.5 사용자 경험 개선 효과

6. 구현 시 고려사항

6.1 Cache-Aside 구현

6.2 Circuit Breaker 설정

6.3 Asynchronous Request-Reply 구현

6.4 Bulkhead 구현

7. 위험 요소 및 대응 방안

7.1 AI API 비용 폭발

7.2 외부 API 의존성

7.3 캐시 데이터 불일치

7.4 비동기 처리 복잡도

8. 모니터링 및 운영

8.1 핵심 메트릭

8.2 알림 규칙

9. 결론

9.1 선정된 패턴 요약

9.2 예상 효과

9.3 다음 단계

34 KiB

Raw Blame History