diff --git a/claude/architecture-patterns-guide.md b/claude/architecture-patterns-guide.md new file mode 100644 index 0000000..4177e80 --- /dev/null +++ b/claude/architecture-patterns-guide.md @@ -0,0 +1,169 @@ +# 클라우드 아키텍처패턴선정 가이드 + +## 개요 +이 가이드는 마이크로서비스 기반 클라우드 시스템을 위한 아키텍처 패턴 선정 방법론을 제공합니다. 체계적인 분석과 정량적 평가를 통해 최적의 패턴을 선정할 수 있습니다. + +## 1. 요구사항 분석 + +### 1.1 유저스토리 분석 +각 서비스별로 기능적/비기능적 요구사항을 명확히 도출합니다. + +**기능적 요구사항**: +- 각 유저스토리에서 요구하는 핵심 기능 +- 서비스 간 데이터 교환 요구사항 +- 비즈니스 로직의 복잡도와 특성 + +**비기능적 요구사항**: +- 성능 요구사항 (응답시간, 처리량) +- 가용성 및 신뢰성 요구사항 +- 확장성 및 유지보수성 요구사항 +- 보안 및 컴플라이언스 요구사항 + +### 1.2 UI/UX설계 분석 +Wireframe을 통해 사용자 인터랙션 패턴과 데이터 플로우를 파악합니다. + +**분석 항목**: +- 사용자 인터랙션 패턴 (동기/비동기 처리 필요성) +- 데이터 조회/변경 패턴 +- 화면 간 전환 흐름 +- 실시간 업데이트 요구사항 + +### 1.3 통합 분석 +유저스토리와 UI/UX 설계를 연계하여 **기술적 도전과제를 식별**합니다. + +**도전과제 식별**: +- 복잡한 비즈니스 트랜잭션 +- 대용량 데이터 처리 +- 실시간 처리 요구사항 +- 외부 시스템 연동 복잡성 +- 서비스 간 의존성 관리 + +## 2. 패턴 선정 + +### 2.1 평가 기준 +다음 5가지 기준으로 각 패턴을 정량적으로 평가합니다. + +| 기준 | 가중치 | 평가 내용 | +|------|--------|-----------| +| **기능 적합성** | 35% | 요구사항을 직접 해결하는 능력 | +| **성능 효과** | 25% | 응답시간 및 처리량 개선 효과 | +| **운영 복잡도** | 20% | 구현 및 운영의 용이성 | +| **확장성** | 15% | 미래 요구사항에 대한 대응력 | +| **비용 효율성** | 5% | 개발/운영 비용 대비 효과(ROI) | + +### 2.2 정량적 평가 방법 + +**평가 척도**: 1-10점 (10점이 가장 우수) + +**패턴별 평가 매트릭스 예시**: + +| 패턴 | 기능 적합성
(35%) | 성능 효과
(25%) | 운영 복잡도
(20%) | 확장성
(15%) | 비용 효율성
(5%) | **총점** | +|------|:---:|:---:|:---:|:---:|:---:|:---:| +| API Gateway | 8 × 0.35 = 2.8 | 7 × 0.25 = 1.75 | 8 × 0.20 = 1.6 | 9 × 0.15 = 1.35 | 7 × 0.05 = 0.35 | **7.85** | +| CQRS | 9 × 0.35 = 3.15 | 9 × 0.25 = 2.25 | 5 × 0.20 = 1.0 | 8 × 0.15 = 1.2 | 6 × 0.05 = 0.3 | **7.90** | +| Event Sourcing | 7 × 0.35 = 2.45 | 8 × 0.25 = 2.0 | 4 × 0.20 = 0.8 | 9 × 0.15 = 1.35 | 5 × 0.05 = 0.25 | **6.85** | + +### 2.3 단계별 적용 로드맵 +MVP → 확장 → 고도화 3단계로 구분하여 점진적 적용 계획을 수립합니다. + +**Phase 1: MVP (Minimum Viable Product)** +- 핵심 비즈니스 기능 중심 +- 단순하고 안정적인 패턴 우선 +- 빠른 출시를 위한 최소 기능 + +**Phase 2: 확장 (Scale-up)** +- 사용자 증가에 따른 성능 최적화 +- 고급 패턴 도입 +- 모니터링 및 운영 자동화 + +**Phase 3: 고도화 (Advanced)** +- 복잡한 비즈니스 요구사항 대응 +- 최신 기술 및 패턴 적용 +- 글로벌 확장 대비 + +## 3. 문서 작성 + +### 3.1 구조화된 작성 순서 +1. **요구사항 분석 결과** +2. **패턴 평가** (평가 매트릭스 포함) +3. **적용 설계** (Mermaid 다이어그램) +4. **구현 계획** (Phase별 로드맵) + +### 3.2 Mermaid 다이어그램 작성 +서비스 아키텍처와 패턴 적용을 시각적으로 표현합니다. + +```mermaid +graph TB + Client[클라이언트] --> Gateway[API Gateway] + Gateway --> Auth[인증 서비스] + Gateway --> UserSvc[사용자 서비스] + Gateway --> OrderSvc[주문 서비스] + + OrderSvc --> EventBus[이벤트 버스] + EventBus --> PaymentSvc[결제 서비스] + EventBus --> NotificationSvc[알림 서비스] + + UserSvc --> UserDB[(사용자 DB)] + OrderSvc --> OrderDB[(주문 DB)] + PaymentSvc --> PaymentDB[(결제 DB)] +``` + +### 3.3 실용적 내용 포함 +- **코드 예시**: 패턴 구현을 위한 구체적인 코드 스니펫 +- **구현 시 고려사항**: 실제 개발 시 주의할 점 +- **예상 효과**: 정량적 성과 지표 (응답시간 개선, 처리량 증가 등) + +## 참고 자료 +- **유저스토리** +- UI/UX설계서 +- **클라우드아키텍처패턴요약표** + +## 결과 파일 +선정된 아키텍처 패턴은 다음과 같이 문서화됩니다: + +### 파일명 +design/pattern/architecture-pattern.md + +### 필수 포함 내용 +1. **요구사항 분석 결과** + - 기능적/비기능적 요구사항 상세 분석 + - 기술적 도전과제 식별 + +2. **패턴 선정 매트릭스 (평가표)** + - 후보 패턴별 정량적 평가 점수 + - 선정 근거 및 이유 + +3. **서비스별 패턴 적용 설계 (Mermaid)** + - 전체 아키텍처 구조 + - 패턴별 적용 영역 표시 + +4. **Phase별 구현 로드맵** + - 단계별 적용 계획 + - 마일스톤 및 목표 설정 + +5. **예상 성과 지표** + - 성능 개선 예상치 + - 비용 절감 효과 + - 개발 생산성 향상 + +## 체크리스트 + +작성 완료 후 다음 항목들을 검토하세요: + +- [ ] **각 유저스토리가 어떤 패턴으로 해결되는지 명시했는가?** +- [ ] **패턴 선정 이유를 정량적으로 설명했는가?** +- [ ] **패턴 간 상호작용과 통합 아키텍처를 표현했는가?** +- [ ] **구현 우선순위와 단계별 목표가 명확한가?** +- [ ] **실무자가 바로 활용할 수 있는 수준인가?** + +## 작성 시 주의사항 + +1. **객관적 평가**: 주관적 판단보다는 정량적 데이터 기반 선정 +2. **현실성**: 팀의 기술 수준과 프로젝트 일정을 고려한 실현 가능한 패턴 선정 +3. **확장성**: 현재 요구사항뿐만 아니라 미래 확장성까지 고려 +4. **비용 효율성**: 과도한 엔지니어링 지양, 비즈니스 가치 중심 선정 +5. **문서화**: 선정 과정과 근거를 명확히 문서화하여 후속 의사결정 지원 + +## 완료 후 mermaid 스크립트 테스트 방법 안내 +- https://mermaid.live/edit 에 접근 +- 스크립트 내용을 붙여넣어 확인 \ No newline at end of file diff --git a/design/pattern/architecture-pattern-backup.md b/design/pattern/architecture-pattern-backup.md new file mode 100644 index 0000000..46f9f30 --- /dev/null +++ b/design/pattern/architecture-pattern-backup.md @@ -0,0 +1,1097 @@ +# 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
- JWT 인증
- Rate Limiting
- Logging] + end + + Mobile --> Gateway + Web --> Gateway + + subgraph "마이크로서비스" + User[User 서비스
- 인증/인가
- 프로필 관리] + Event[Event 서비스
- 이벤트 CRUD
- 플로우 관리] + AI[AI 서비스
- 트렌드 분석
- 이벤트 추천
⏱️ Async] + Content[Content 서비스
- 이미지 생성
⏱️ Async] + Distribution[Distribution 서비스
- 다중 채널 배포] + Participation[Participation 서비스
- 참여자 관리
- 추첨] + Analytics[Analytics 서비스
- 실시간 대시보드] + end + + Gateway --> User + Gateway --> Event + Gateway --> Participation + Gateway --> Analytics + + Event --> AI + Event --> Content + Event --> Distribution + + subgraph "캐시 레이어" + Redis[Redis Cache
💾 Cache-Aside
- AI 결과
- 이미지
- 사업자번호] + 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
Circuit Breaker] + Ringo[링고비즈
Circuit Breaker] + Genie[지니TV
Circuit Breaker] + SNS[SNS
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 서비스
Worker Pool] + Content[Content 서비스
Worker Pool] + Distribution[Distribution 서비스
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
PostgreSQL)] + end + + subgraph "Query Side (읽기)" + QueryHandler[Query Handler] + ReadDB[(Read DB
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 diff --git a/design/pattern/architecture-pattern.md b/design/pattern/architecture-pattern.md index 46f9f30..243552c 100644 --- a/design/pattern/architecture-pattern.md +++ b/design/pattern/architecture-pattern.md @@ -1,1097 +1,619 @@ -# KT AI 기반 소상공인 이벤트 자동 생성 서비스 - 클라우드 아키텍처 패턴 적용 방안 +# KT AI 기반 소상공인 이벤트 자동 생성 서비스 - 클라우드 아키텍처 패턴 적용 방안 (MVP) -**문서 정보** -- 프로젝트명: KT AI 기반 소상공인 이벤트 자동 생성 서비스 -- 작성일: 2025-10-21 -- 버전: 1.0 -- 작성자: System Architect +## 문서 정보 +- **작성일**: 2025-10-21 +- **버전**: 2.0 (MVP 집중) +- **적용 패턴**: 4개 핵심 패턴 +- **목표**: 빠른 MVP 출시와 안정적 서비스 제공 --- -## 목차 -1. [요구사항 분석 결과](#1-요구사항-분석-결과) -2. [패턴 평가 매트릭스](#2-패턴-평가-매트릭스) -3. [서비스별 패턴 적용 설계](#3-서비스별-패턴-적용-설계) -4. [Phase별 구현 로드맵](#4-phase별-구현-로드맵) -5. [예상 성과 지표](#5-예상-성과-지표) - ---- - -## 1. 요구사항 분석 결과 +## 1. 요구사항 분석 ### 1.1 기능적 요구사항 -#### 마이크로서비스별 핵심 기능 -1. **User 서비스** (4개 유저스토리) - - 회원가입/로그인/프로필 관리 - - 사업자번호 검증 (국세청 API 연동) - - 세션 관리 및 인증/인가 +**User 서비스** +- 회원가입/로그인 및 프로필 관리 +- 사업자번호 검증 (국세청 API) -2. **Event 서비스** (7개 유저스토리) - - 이벤트 CRUD 관리 - - 대시보드 현황 조회 - - 이벤트 목적 선택 및 생성 플로우 관리 - - AI/Content/Distribution 서비스 연동 +**Event 서비스** +- 이벤트 CRUD 및 상태 관리 +- 이벤트 목적 선택 → AI 추천 → 콘텐츠 생성 → 배포 → 분석 플로우 -3. **AI 서비스** (1개 유저스토리) - - 업종/지역/시즌 트렌드 분석 (5초 이내) - - 3가지 이벤트 추천 생성 (5초 이내) - - Claude API/GPT-4 API 연동 - - **병렬 처리**: 트렌드 분석 + 이벤트 추천 동시 실행 (총 10초 목표) +**AI 서비스** +- 트렌드 분석 (업종/지역/시즌) +- 3가지 이벤트 기획안 자동 생성 +- Claude API/GPT-4 API 연동 -4. **Content 서비스** (2개 유저스토리) - - SNS 이미지 3가지 스타일 자동 생성 (5초 이내) - - 플랫폼별 이미지 최적화 (Instagram/Naver/Kakao) - - Stable Diffusion/DALL-E API 연동 +**Content 서비스** +- 3가지 스타일 SNS 이미지 자동 생성 +- Stable Diffusion/DALL-E API 연동 +- 플랫폼별 이미지 최적화 (Instagram, Naver, Kakao) -5. **Distribution 서비스** (2개 유저스토리) - - 다중 채널 동시 배포 (우리동네TV, 링고비즈, 지니TV, SNS) - - 채널별 독립 처리 및 실패 복구 - - 배포 상태 실시간 모니터링 +**Distribution 서비스** +- 다중 채널 동시 배포 (우리동네TV, 링고비즈, 지니TV, SNS) +- 7개 외부 API 연동 -6. **Participation 서비스** (3개 유저스토리) - - 이벤트 참여자 관리 (중복 체크) - - 자동 추첨 시스템 - - 참여자 목록 조회 및 필터링 +**Participation 서비스** +- 이벤트 참여 접수 및 당첨자 추첨 -7. **Analytics 서비스** (1개 유저스토리) - - 실시간 통합 대시보드 (5분 간격 업데이트) - - 다중 데이터 소스 통합 (Participation, Distribution, POS, 외부 API) - - 채널별 성과 분석 및 투자대비수익률 계산 +**Analytics 서비스** +- 실시간 성과 대시보드 +- 채널별 성과 분석 ### 1.2 비기능적 요구사항 -#### 성능 요구사항 -| 항목 | 목표 | 우선순위 | -|------|------|---------| -| AI 트렌드 분석 + 추천 | 10초 이내 | 🔴 Critical | -| SNS 이미지 생성 | 5초 이내 | 🔴 Critical | -| 다중 채널 배포 | 1분 이내 | 🟡 High | -| 실시간 대시보드 업데이트 | 5분 간격 | 🟢 Medium | -| API 응답 시간 (CRUD) | 200ms 이하 | 🟡 High | +**성능 요구사항** +- AI 트렌드 분석 + 이벤트 추천: **10초 이내** +- SNS 이미지 생성: **5초 이내** +- 대시보드 데이터 업데이트: **5분 간격** +- 다중 채널 배포: **1분 이내** -#### 가용성 및 신뢰성 -- **시스템 가용성**: 99.9% (월 43분 다운타임 허용) -- **외부 API 장애 대응**: 개별 채널 실패가 전체 서비스에 영향 없도록 격리 -- **데이터 일관성**: 이벤트 생성 트랜잭션 보장 +**가용성 요구사항** +- 시스템 가용성: **99% 이상** (MVP 목표) +- 외부 API 장애 시 서비스 지속 가능 -#### 확장성 -- **사용자 증가 대응**: 초기 100명 → 1년 후 10,000명 -- **이벤트 처리량**: 동시 이벤트 생성 50개 -- **데이터 증가**: 일 평균 1,000개 참여 데이터 +**확장성 요구사항** +- 초기 사용자: **100명** +- 동시 이벤트: **50개** +- 캐시 히트율: **80% 이상** -#### 보안 요구사항 -- JWT 토큰 기반 인증 -- API Gateway를 통한 중앙 인증/인가 -- 개인정보 암호화 저장 (전화번호, 이름) -- 사업자번호 검증 강화 +**보안 요구사항** +- JWT 기반 인증/인가 +- API Gateway를 통한 중앙집중식 보안 -### 1.3 UI/UX 분석에서 도출된 기술적 요구사항 +### 1.3 외부 API 의존성 -#### 사용자 인터랙션 패턴 -- **Mobile First**: 60% 모바일, 40% 데스크톱 -- **짧은 세션**: 5-10분 내 이벤트 생성 완료 -- **실시간 피드백**: 로딩 상태, 진행률 표시 필수 -- **3 Tap Rule**: 모든 주요 기능 3번 탭 내 도달 - -#### 실시간 처리 요구사항 -- AI 처리 진행 상황 실시간 표시 -- 배포 상태 실시간 모니터링 -- 대시보드 자동 갱신 (5분 간격) +| 서비스 | 외부 API | 용도 | 응답시간 | +|--------|----------|------|----------| +| User | 국세청 사업자등록정보 진위확인 API | 사업자번호 검증 | 2-3초 | +| AI | Claude API / GPT-4 API | 트렌드 분석 및 이벤트 추천 | 5-10초 | +| Content | Stable Diffusion / DALL-E API | SNS 이미지 생성 | 3-5초 | +| Distribution | 우리동네TV API | 영상 업로드 및 송출 | 1-2초 | +| Distribution | 링고비즈 API | 연결음 업데이트 | 1초 | +| Distribution | 지니TV 광고 API | 광고 등록 | 1-2초 | +| Distribution | SNS API (Instagram, Naver, Kakao) | 자동 포스팅 | 1-3초 | ### 1.4 기술적 도전과제 #### 1. AI 응답 시간 관리 (🔴 Critical) + **문제**: AI API 응답이 10초 목표를 초과할 수 있음 +- Claude/GPT-4 API 응답 시간 변동성 (5-15초) +- 트렌드 분석 + 이벤트 추천 2단계 처리 필요 -**영향**: -- 사용자 이탈 증가 -- 서비스 만족도 저하 - -**해결 필요성**: MVP 단계부터 필수 +**해결방안**: +- **비동기 처리**: Job 기반 처리로 응답 대기 시간 최소화 +- **캐싱**: 동일 조건(업종, 지역, 목적) 결과 Redis 캐싱 (24시간) +- **응답 시간 90% 단축** (캐시 히트 시) #### 2. 다중 외부 API 의존성 (🔴 Critical) -**문제**: 7개 외부 API 연동 (국세청, Claude/GPT-4, Stable Diffusion, 우리동네TV, 링고비즈, 지니TV, SNS) -**영향**: -- API 장애 시 서비스 중단 위험 -- 응답 시간 불안정성 -- 비용 증가 (API 호출량) +**문제**: 7개 외부 API 연동으로 인한 장애 전파 위험 +- 각 API별 응답 시간 및 성공률 상이 +- 하나의 API 장애가 전체 서비스 중단으로 이어질 수 있음 -**해결 필요성**: MVP 단계부터 필수 +**해결방안**: +- **Circuit Breaker**: 장애 API 자동 차단 및 Fallback 처리 +- **독립적 처리**: 채널별 배포 실패가 다른 채널에 영향 없음 +- **자동 재시도**: 일시적 오류 시 최대 3회 재시도 -#### 3. 실시간 대시보드 성능 (🟡 High) -**문제**: 다중 데이터 소스 통합 (Participation, Distribution, POS, 외부 API) +#### 3. 이미지 생성 비용 및 시간 (🟡 Important) -**영향**: -- 대시보드 로딩 지연 -- 서버 부하 증가 +**문제**: AI 이미지 생성 API 비용이 높고 시간 소요 +- 이미지 1장당 생성 비용: $0.02-0.05 +- 3가지 스타일 생성 시 비용 3배 -**해결 필요성**: Phase 2 확장 단계에서 해결 +**해결방안**: +- **캐싱**: 동일 이벤트 정보 이미지 재사용 +- **비용 90% 절감** (캐시 히트 시) -#### 4. 복잡한 비즈니스 트랜잭션 (🟡 High) -**문제**: 이벤트 생성 → AI 추천 → 콘텐츠 생성 → 배포 → 참여자 관리 → 분석 +#### 4. 실시간 대시보드 성능 (🟡 Important) -**영향**: -- 부분 실패 시 데이터 불일치 -- 보상 트랜잭션 복잡도 증가 +**문제**: 다중 데이터 소스 통합으로 인한 응답 지연 +- 7개 외부 API + 내부 서비스 데이터 통합 +- 복잡한 차트 및 계산 로직 -**해결 필요성**: Phase 1 MVP에서 기본 구조 확립 +**해결방안**: +- **캐싱**: Redis를 통한 5분 간격 데이터 캐싱 +- **응답 시간 80% 단축** --- -## 2. 패턴 평가 매트릭스 +## 2. 패턴 선정 및 평가 -### 2.1 평가 기준 +### 2.1 MVP 핵심 패턴 (4개) -| 기준 | 가중치 | 평가 내용 | -|------|--------|-----------| -| **기능 적합성** | 35% | 요구사항을 직접 해결하는 능력 | -| **성능 효과** | 25% | 응답시간 및 처리량 개선 효과 | -| **운영 복잡도** | 20% | 구현 및 운영의 용이성 | -| **확장성** | 15% | 미래 요구사항에 대한 대응력 | -| **비용 효율성** | 5% | 개발/운영 비용 대비 효과(ROI) | +| 패턴 | 적용 목적 | 주요 효과 | +|------|----------|-----------| +| **Cache-Aside** | AI 응답 시간 단축 및 비용 절감 | 응답 시간 90% 단축, 비용 90% 절감 | +| **API Gateway** | 중앙집중식 보안 및 라우팅 | 개발 복잡도 감소, 보안 강화 | +| **Asynchronous Request-Reply** | 장시간 작업 응답 시간 개선 | 사용자 대기 시간 제거 | +| **Circuit Breaker** (Optional) | 외부 API 장애 격리 | 가용성 95% → 99% 개선 | -### 2.2 핵심 패턴 평가 +### 2.2 정량적 평가 매트릭스 -#### 2.2.1 API Gateway (필수 패턴) +**평가 기준**: +- **기능 적합성** (35%): 요구사항 직접 해결 능력 +- **성능 효과** (25%): 응답시간 및 처리량 개선 +- **운영 복잡도** (20%): 구현 및 운영 용이성 +- **확장성** (15%): 미래 요구사항 대응력 +- **비용 효율성** (5%): 개발/운영 비용 대비 효과 -| 평가 기준 | 점수 | 가중치 | 계산 | 근거 | -|----------|-----|--------|------|------| -| 기능 적합성 | 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** | **선정** | +| 패턴 | 기능 적합성
(35%) | 성능 효과
(25%) | 운영 복잡도
(20%) | 확장성
(15%) | 비용 효율성
(5%) | **총점** | 우선순위 | +|------|:---:|:---:|:---:|:---:|:---:|:---:|:---:| +| **Cache-Aside** | 10 × 0.35
= 3.5 | 10 × 0.25
= 2.5 | 8 × 0.20
= 1.6 | 9 × 0.15
= 1.35 | 10 × 0.05
= 0.5 | **9.45** | 🔴 Critical | +| **API Gateway** | 9 × 0.35
= 3.15 | 7 × 0.25
= 1.75 | 9 × 0.20
= 1.8 | 9 × 0.15
= 1.35 | 8 × 0.05
= 0.4 | **8.45** | 🔴 Critical | +| **Asynchronous Request-Reply** | 9 × 0.35
= 3.15 | 9 × 0.25
= 2.25 | 7 × 0.20
= 1.4 | 8 × 0.15
= 1.2 | 8 × 0.05
= 0.4 | **8.40** | 🔴 Critical | +| **Circuit Breaker** | 8 × 0.35
= 2.8 | 8 × 0.25
= 2.0 | 9 × 0.20
= 1.8 | 9 × 0.15
= 1.35 | 7 × 0.05
= 0.35 | **8.30** | 🟡 Optional | -**선정 이유**: -- 7개 마이크로서비스의 단일 진입점 필요 -- 횡단 관심사(인증, 로깅, Rate Limiting) 중앙 관리 -- Mobile First 환경에서 단일 엔드포인트 필수 +### 2.3 패턴별 상세 분석 -**적용 방안**: -- 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 의존성 감소 +#### 2.3.1 Cache-Aside (9.45점) - 🔴 Critical **적용 대상**: -1. **AI 트렌드 분석 결과**: 업종/지역/시즌별 1시간 캐싱 -2. **AI 이벤트 추천 결과**: 동일 조건 24시간 캐싱 -3. **SNS 이미지 생성 결과**: 영구 캐싱 (CDN 연동) -4. **사업자번호 검증 결과**: 30일 캐싱 +- AI 서비스: 트렌드 분석 결과, 이벤트 추천 결과 +- Content 서비스: 생성된 SNS 이미지 +- User 서비스: 사업자번호 검증 결과 ---- +**구현 방식**: +``` +1. 요청 수신 → 캐시 확인 (Redis GET) +2. 캐시 HIT: 즉시 반환 (응답 시간 0.1초) +3. 캐시 MISS: + - 외부 API 호출 (응답 시간 5-10초) + - 결과를 캐시에 저장 (Redis SET, TTL 24시간) + - 결과 반환 +``` -#### 2.2.3 Asynchronous Request-Reply (필수 패턴) +**기대 효과**: +- **응답 시간**: 10초 → 0.1초 (99% 개선, 캐시 히트 시) +- **비용 절감**: AI API 호출 90% 감소 → 월 $2,000 → $200 (90% 절감) +- **캐시 히트율**: 80% (동일 업종/지역 이벤트 반복 요청) -| 평가 기준 | 점수 | 가중치 | 계산 | 근거 | -|----------|-----|--------|------|------| -| 기능 적합성 | 10 | 35% | 3.50 | AI 처리 비동기 대응 필수 | -| 성능 효과 | 9 | 25% | 2.25 | 사용자 대기 시간 단축, 서버 리소스 효율화 | -| 운영 복잡도 | 6 | 20% | 1.20 | 폴링/WebSocket 구현 필요 | -| 확장성 | 9 | 15% | 1.35 | 장시간 작업 증가 시 대응 가능 | -| 비용 효율성 | 7 | 5% | 0.35 | 개발 비용 증가하지만 사용자 경험 개선 | -| **총점** | | | **8.65** | **선정** | +**운영 고려사항**: +- Redis 메모리 관리: 최대 2GB (약 10,000개 캐시 항목) +- TTL 정책: 24시간 (트렌드 변화 반영) +- 캐시 무효화: 수동 무효화 API 제공 -**선정 이유**: -- 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 장애 시 전체 서비스 중단 방지 -- 빠른 실패 및 폴백 처리 +#### 2.3.2 API Gateway (8.45점) - 🔴 Critical **적용 대상**: -1. **AI API**: Claude/GPT-4 장애 시 미리 준비된 템플릿 반환 -2. **이미지 생성 API**: Stable Diffusion 장애 시 기본 템플릿 이미지 제공 -3. **배포 채널 API**: 개별 채널 장애가 다른 채널에 영향 없도록 격리 -4. **국세청 API**: 검증 실패 시 캐시된 결과 또는 수동 승인 플로우 +- 전체 마이크로서비스 (User, Event, AI, Content, Distribution, Participation, Analytics) ---- +**주요 기능**: +1. **인증/인가**: JWT 토큰 검증 (모든 요청) +2. **라우팅**: URL 기반 서비스 라우팅 +3. **Rate Limiting**: API 호출 제한 (사용자당 100 req/min) +4. **로깅**: 중앙집중식 접근 로그 -#### 2.2.5 Retry (필수 패턴) +**구현 방식**: +``` +Client → API Gateway (Kong/AWS API Gateway) + ├─ /api/users/* → User Service + ├─ /api/events/* → Event Service + ├─ /api/ai/* → AI Service + ├─ /api/content/* → Content Service + ├─ /api/distribution/* → Distribution Service + ├─ /api/participation/* → Participation Service + └─ /api/analytics/* → Analytics Service +``` -| 평가 기준 | 점수 | 가중치 | 계산 | 근거 | -|----------|-----|--------|------|------| -| 기능 적합성 | 9 | 35% | 3.15 | 일시적 네트워크 오류 대응 | -| 성능 효과 | 7 | 25% | 1.75 | 일시적 오류 복구로 사용자 재시도 불필요 | -| 운영 복잡도 | 9 | 20% | 1.80 | 라이브러리 활용 (Resilience4j) | -| 확장성 | 8 | 15% | 1.20 | 모든 외부 API에 동일 적용 | -| 비용 효율성 | 7 | 5% | 0.35 | 재시도 비용 < 실패 처리 비용 | -| **총점** | | | **8.25** | **선정** | +**기대 효과**: +- **개발 생산성**: 각 서비스에서 인증 로직 제거 → 개발 시간 30% 단축 +- **보안 강화**: 중앙집중식 보안 정책 관리 +- **운영 효율**: 통합 모니터링 및 로깅 -**선정 이유**: -- 외부 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명 이상) +#### 2.3.3 Asynchronous Request-Reply (8.40점) - 🔴 Critical **적용 대상**: -- AI 트렌드 분석 요청 큐 -- SNS 이미지 생성 요청 큐 -- 배포 요청 큐 +- AI 서비스: 트렌드 분석 및 이벤트 추천 (10초 소요) +- Content 서비스: SNS 이미지 생성 (5초 소요) ---- +**구현 방식**: +``` +1. 클라이언트 요청 → Job ID 즉시 반환 (응답 시간 0.1초) +2. 백그라운드 처리: + - AI API 호출 및 결과 생성 (10초) + - 결과를 DB 저장 +3. 클라이언트 폴링: + - 5초 간격으로 Job 상태 확인 (GET /jobs/{id}) + - 완료 시 결과 수신 +``` -#### 2.2.7 CQRS (고도화 단계 패턴) +**기대 효과**: +- **사용자 경험**: 대기 화면에서 진행 상황 표시 → 이탈률 감소 +- **서버 부하**: 동기 대기 제거 → 동시 처리 가능 요청 5배 증가 -| 평가 기준 | 점수 | 가중치 | 계산 | 근거 | -|----------|-----|--------|------|------| -| 기능 적합성 | 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 선정** | +**운영 고려사항**: +- Job 상태 저장: Redis (TTL 1시간) +- 폴링 간격: 5초 (UX 고려) +- Job 만료: 1시간 후 자동 삭제 -**선정 이유**: -- MVP에서는 과도한 복잡도 -- Phase 3 고도화 단계에서 대시보드 성능 최적화 시 적용 - -**적용 시기**: Phase 3 (사용자 5,000명 이상) +#### 2.3.4 Circuit Breaker (8.30점) - 🟡 Optional **적용 대상**: -- Analytics 서비스 (읽기 전용 DB) -- 복잡한 집계 쿼리 최적화 +- 모든 외부 API 연동 지점 (7개 API) ---- +**동작 방식**: +``` +1. Closed (정상): + - 외부 API 정상 호출 + - 실패율 5% 미만 -#### 2.2.8 Saga (확장 단계 패턴) +2. Open (차단): + - 실패율 5% 초과 시 Circuit Open + - 모든 요청 즉시 실패 (Fallback 처리) + - 30초 대기 -| 평가 기준 | 점수 | 가중치 | 계산 | 근거 | -|----------|-----|--------|------|------| -| 기능 적합성 | 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 선정** | +3. Half-Open (테스트): + - 30초 후 1개 요청 시도 + - 성공 시 Closed로 전환 + - 실패 시 Open 유지 +``` -**선정 이유**: -- MVP에서는 단순 롤백 처리로 충분 -- Phase 2에서 복잡한 플로우 증가 시 필요 +**Fallback 전략**: +- **AI 서비스**: 캐시된 이전 추천 결과 제공 + 안내 메시지 +- **Distribution 서비스**: 해당 채널 배포 스킵 + 알림 +- **User 서비스**: 사업자번호 검증 스킵 (수동 확인으로 대체) -**적용 시기**: 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 | +**기대 효과**: +- **가용성**: 95% → 99% (외부 API 장애 격리) +- **장애 복구**: 자동 복구 시간 5분 → 30초 --- ## 3. 서비스별 패턴 적용 설계 -### 3.1 전체 아키텍처 구조 (Phase 1 MVP) +### 3.1 전체 아키텍처 (MVP) ```mermaid graph TB subgraph "클라이언트" - Mobile[모바일 앱] - Web[웹 브라우저] + Client[Web/Mobile App] end - subgraph "API Gateway 레이어" - Gateway[API Gateway
- JWT 인증
- Rate Limiting
- Logging] + subgraph "API Gateway Layer" + Gateway[API Gateway
인증, 라우팅, Rate Limiting] end - Mobile --> Gateway - Web --> Gateway - subgraph "마이크로서비스" - User[User 서비스
- 인증/인가
- 프로필 관리] - Event[Event 서비스
- 이벤트 CRUD
- 플로우 관리] - AI[AI 서비스
- 트렌드 분석
- 이벤트 추천
⏱️ Async] - Content[Content 서비스
- 이미지 생성
⏱️ Async] - Distribution[Distribution 서비스
- 다중 채널 배포] - Participation[Participation 서비스
- 참여자 관리
- 추첨] - Analytics[Analytics 서비스
- 실시간 대시보드] + UserSvc[User Service
회원관리] + EventSvc[Event Service
이벤트 관리] + AISvc[AI Service
트렌드 분석, 추천] + ContentSvc[Content Service
이미지 생성] + DistSvc[Distribution Service
다중 채널 배포] + PartSvc[Participation Service
참여자 관리] + AnalSvc[Analytics Service
성과 분석] end - Gateway --> User - Gateway --> Event - Gateway --> Participation - Gateway --> Analytics - - Event --> AI - Event --> Content - Event --> Distribution - - subgraph "캐시 레이어" - Redis[Redis Cache
💾 Cache-Aside
- AI 결과
- 이미지
- 사업자번호] + subgraph "Cache Layer" + Redis[(Redis Cache
Cache-Aside)] 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] + subgraph "외부 API (Circuit Breaker 적용)" + TaxAPI[국세청 API] + ClaudeAPI[Claude API] + SDAPI[Stable Diffusion] + UriAPI[우리동네TV API] + RingoAPI[링고비즈 API] + GenieAPI[지니TV API] + SNSAPI[SNS API] 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 + Client -->|HTTPS| Gateway + Gateway --> UserSvc + Gateway --> EventSvc + Gateway --> AISvc + Gateway --> ContentSvc + Gateway --> DistSvc + Gateway --> PartSvc + Gateway --> AnalSvc - subgraph "데이터 레이어" - UserDB[(User DB)] - EventDB[(Event DB)] - ParticipationDB[(Participation DB)] - end + UserSvc -.->|Cache-Aside| Redis + AISvc -.->|Cache-Aside| Redis + ContentSvc -.->|Cache-Aside| Redis - User --> UserDB - Event --> EventDB - Participation --> ParticipationDB + UserSvc -->|Circuit Breaker| TaxAPI + AISvc -->|Circuit Breaker| ClaudeAPI + ContentSvc -->|Circuit Breaker| SDAPI + DistSvc -->|Circuit Breaker| UriAPI + DistSvc -->|Circuit Breaker| RingoAPI + DistSvc -->|Circuit Breaker| GenieAPI + DistSvc -->|Circuit Breaker| SNSAPI - 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 + style Gateway fill:#e1f5ff + style Redis fill:#ffe1e1 + style AISvc fill:#fff4e1 + style ContentSvc fill:#fff4e1 ``` -### 3.2 서비스별 상세 패턴 적용 +### 3.2 AI Service - Asynchronous Request-Reply 패턴 -#### 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 Client as 클라이언트 + participant API as API Gateway + participant Event as Event Service + participant AI as AI Service + participant Cache as Redis Cache participant Claude as Claude API - Client->>API_GW: POST /events/ai-recommend - API_GW->>Event: 이벤트 추천 요청 - Event->>AI: 트렌드 분석 + 추천 요청 + Client->>API: POST /api/ai/recommendations
(업종, 지역, 목적) + API->>Event: 이벤트 추천 요청 + Event->>AI: 추천 요청 - AI->>Redis: 캐시 조회 (업종/지역/시즌) + AI->>Cache: GET cached_result + alt Cache HIT + Cache-->>AI: 캐시된 결과 + AI-->>Event: 즉시 반환 (0.1초) + Event-->>API: 결과 + API-->>Client: 결과 (Total: 0.2초) + else Cache MISS + Cache-->>AI: null + AI-->>Event: Job ID 즉시 반환 + Event-->>API: Job ID + API-->>Client: Job ID + 처리중 상태 (0.1초) - 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 + AI->>Claude: 비동기 AI 호출 + Note over AI,Claude: 백그라운드 처리 (10초) + Claude-->>AI: 추천 결과 + AI->>Cache: SET result (TTL 24h) + AI->>AI: Job 상태 = 완료 loop 폴링 (5초 간격) - Client->>API_GW: GET /jobs/{jobId} - API_GW->>AI: 진행 상황 조회 - AI->>Redis: 진행률 조회 - Redis-->>AI: 진행률 반환 - AI-->>Client: 진행률 또는 최종 결과 + Client->>API: GET /api/jobs/{id} + API->>Event: Job 상태 확인 + Event->>AI: Job 상태 + alt 완료 + AI-->>Event: 결과 + Event-->>API: 결과 + API-->>Client: 최종 결과 + else 진행중 + AI-->>Event: 진행중 + Event-->>API: 진행중 + API-->>Client: 진행 상황 (예: 70%) + end 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
Circuit Breaker] - Ringo[링고비즈
Circuit Breaker] - Genie[지니TV
Circuit Breaker] - SNS[SNS
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 추가) +### 3.3 Distribution Service - Circuit Breaker 패턴 ```mermaid graph TB - subgraph "클라이언트" - Mobile[모바일 앱] - Web[웹 브라우저] + subgraph "Distribution Service" + DistCtrl[Distribution Controller] + CB_Uri[Circuit Breaker
우리동네TV] + CB_Ringo[Circuit Breaker
링고비즈] + CB_Genie[Circuit Breaker
지니TV] + CB_SNS[Circuit Breaker
SNS] end - subgraph "API Gateway 레이어" - Gateway[API Gateway] + subgraph "외부 API" + UriAPI[우리동네TV API] + RingoAPI[링고비즈 API] + GenieAPI[지니TV API] + SNSAPI[SNS API] end - Mobile --> Gateway - Web --> Gateway + DistCtrl --> CB_Uri + DistCtrl --> CB_Ringo + DistCtrl --> CB_Genie + DistCtrl --> CB_SNS - subgraph "마이크로서비스" - Event[Event 서비스] - AI[AI 서비스
Worker Pool] - Content[Content 서비스
Worker Pool] - Distribution[Distribution 서비스
Worker Pool] - end + CB_Uri -->|실패율 < 5%
Closed| UriAPI + CB_Uri -.->|실패율 >= 5%
Open, Fallback| Fallback_Uri[배포 스킵
+ 알림] - Gateway --> Event + CB_Ringo -->|실패율 < 5%
Closed| RingoAPI + CB_Ringo -.->|실패율 >= 5%
Open, Fallback| Fallback_Ringo[배포 스킵
+ 알림] - subgraph "메시지 큐 (Queue-Based Load Leveling)" - AIQueue[AI 요청 큐] - ContentQueue[콘텐츠 요청 큐] - DistQueue[배포 요청 큐] - end + CB_Genie -->|실패율 < 5%
Closed| GenieAPI + CB_Genie -.->|실패율 >= 5%
Open, Fallback| Fallback_Genie[배포 스킵
+ 알림] - Event --> AIQueue - Event --> ContentQueue - Event --> DistQueue + CB_SNS -->|실패율 < 5%
Closed| SNSAPI + CB_SNS -.->|실패율 >= 5%
Open, Fallback| Fallback_SNS[배포 스킵
+ 알림] - 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
PostgreSQL)] - end - - subgraph "Query Side (읽기)" - QueryHandler[Query Handler] - ReadDB[(Read DB
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도 동일하게 분리 -} + style CB_Uri fill:#ffe1e1 + style CB_Ringo fill:#ffe1e1 + style CB_Genie fill:#ffe1e1 + style CB_SNS fill:#ffe1e1 ``` --- -## 7. 위험 요소 및 대응 방안 +## 4. MVP 구현 로드맵 -### 7.1 AI API 비용 폭발 +### 4.1 단일 Phase MVP 전략 -**위험**: -- 캐싱 미적용 시 AI API 비용 월 $10,000+ 발생 가능 +**목표**: 빠른 출시와 안정적 서비스 제공 -**대응 방안**: -1. Cache-Aside 패턴 필수 적용 -2. 캐시 히트율 모니터링 (목표: 90% 이상) -3. 월간 비용 임계값 설정 ($500) -4. 임계값 초과 시 알림 및 자동 차단 +**기간**: 12주 -### 7.2 외부 API 의존성 +**목표 지표**: +- 사용자: 100명 +- 동시 이벤트: 50개 +- 시스템 가용성: 99% +- AI 응답 시간: 10초 이내 (캐시 미스), 0.1초 (캐시 히트) -**위험**: -- 7개 외부 API 중 하나라도 장애 시 서비스 중단 +### 4.2 구현 순서 및 일정 -**대응 방안**: -1. Circuit Breaker 패턴 필수 적용 -2. 폴백 전략 명확히 정의 -3. SLA 계약 체결 (우리동네TV, 지니TV 등) -4. 대체 API 준비 (예: Claude ↔ GPT-4 전환) +| 주차 | 작업 내용 | 패턴 적용 | 완료 기준 | +|------|----------|-----------|-----------| +| **1-2주** | 인프라 구축 | API Gateway | - Kong/AWS API Gateway 설정
- Redis 클러스터 구축
- JWT 인증 구현 | +| **3-4주** | User/Event 서비스 | Cache-Aside | - 회원가입/로그인 완료
- 사업자번호 검증 캐싱
- 이벤트 CRUD 완료 | +| **5-6주** | AI 서비스 | Asynchronous Request-Reply
Cache-Aside | - Claude API 연동
- Job 기반 비동기 처리
- AI 결과 캐싱 (24시간 TTL) | +| **7-8주** | Content 서비스 | Asynchronous Request-Reply
Cache-Aside | - Stable Diffusion 연동
- 이미지 생성 Job 처리
- 이미지 캐싱 및 CDN | +| **9-10주** | Distribution 서비스 | Circuit Breaker | - 7개 외부 API 연동
- 각 API별 Circuit Breaker
- Fallback 전략 구현 | +| **11주** | Participation/Analytics | Cache-Aside | - 참여자 관리 및 추첨
- 대시보드 데이터 캐싱 | +| **12주** | 테스트 및 출시 | 전체 패턴 검증 | - 부하 테스트 (100명)
- 장애 시나리오 테스트
- MVP 출시 | -### 7.3 캐시 데이터 불일치 +### 4.3 기술 스택 -**위험**: -- 트렌드 데이터 변경 시 캐시 무효화 누락 +**백엔드**: +- Spring Boot 3.2 (Java 17) / Node.js 20 +- Redis 7.2 (Cache) +- PostgreSQL 15 (주 DB) +- RabbitMQ / Kafka (비동기 처리, Optional) -**대응 방안**: -1. TTL 기반 자동 만료 -2. 수동 무효화 API 제공 -3. 캐시 버전 관리 +**프론트엔드**: +- React 18 + TypeScript 5 +- Next.js 14 (SSR) +- Zustand (상태관리) +- React Query (서버 상태 관리) -### 7.4 비동기 처리 복잡도 +**인프라**: +- Docker + Kubernetes +- Kong API Gateway / AWS API Gateway +- Resilience4j (Circuit Breaker) +- Prometheus + Grafana (모니터링) -**위험**: -- Job 상태 관리 실패, 폴링 부하 - -**대응 방안**: -1. Redis를 통한 안정적인 상태 관리 -2. Job TTL 설정 (24시간 자동 삭제) -3. Phase 2에서 WebSocket으로 전환 +**외부 API**: +- Claude API / GPT-4 API +- Stable Diffusion API +- 국세청 사업자등록정보 진위확인 API +- 우리동네TV, 링고비즈, 지니TV, SNS API --- -## 8. 모니터링 및 운영 +## 5. 예상 성과 -### 8.1 핵심 메트릭 +### 5.1 성능 개선 -**성능 메트릭**: -- AI 응답 시간 (p50, p95, p99) -- 이미지 생성 시간 (p50, p95, p99) -- 캐시 히트율 (목표: 90%) -- API Gateway 응답 시간 (목표: 10ms) +| 항목 | Before | After | 개선율 | +|------|--------|-------|--------| +| AI 응답 시간 (캐시 히트) | 10초 | 0.1초 | **99% 개선** | +| AI 응답 시간 (캐시 미스) | 10초 | 10초 | - | +| 이미지 생성 시간 (캐시 히트) | 5초 | 0.1초 | **98% 개선** | +| 대시보드 로딩 시간 | 3초 | 0.5초 | **83% 개선** | -**안정성 메트릭**: -- Circuit Breaker 상태 (Open/Half-Open/Closed) -- 외부 API 실패율 (목표: 1% 이하) -- 시스템 가용성 (목표: 99.9%) +### 5.2 비용 절감 -**비용 메트릭**: -- AI API 호출 횟수 및 비용 -- 이미지 생성 API 호출 횟수 및 비용 -- 캐시 절감 효과 (예상 비용 - 실제 비용) +**AI API 비용 절감** (캐시 히트율 80% 가정): +- Before: 1,000 요청/일 × $0.02 = **$20/일** = **$600/월** +- After: 200 요청/일 × $0.02 = **$4/일** = **$120/월** +- **절감액**: $480/월 (**80% 절감**) -### 8.2 알림 규칙 +**이미지 생성 비용 절감** (캐시 히트율 80% 가정): +- Before: 500 이미지/일 × $0.04 = **$20/일** = **$600/월** +- After: 100 이미지/일 × $0.04 = **$4/일** = **$120/월** +- **절감액**: $480/월 (**80% 절감**) -**Critical 알림**: -- Circuit Breaker Open 상태 -- AI 응답 시간 > 20초 -- 캐시 히트율 < 80% -- 시스템 가용성 < 99% +**총 비용 절감**: +- Before: $1,200/월 +- After: $240/월 +- **총 절감액**: **$960/월** (**80% 절감**) -**Warning 알림**: -- 외부 API 실패율 > 5% -- 월간 AI API 비용 > $500 -- 동시 접속자 > 80% 임계값 +### 5.3 가용성 개선 + +| 지표 | Before | After | 개선 | +|------|--------|-------|------| +| 시스템 가용성 | 95% | 99% | **+4%p** | +| 외부 API 장애 시 서비스 지속 | ❌ 불가 | ✅ 가능 (Fallback) | - | +| 장애 자동 복구 시간 | 5분 (수동) | 30초 (자동) | **90% 단축** | + +### 5.4 개발 생산성 + +| 항목 | 효과 | +|------|------| +| API Gateway | 각 서비스 인증 로직 제거 → 개발 시간 **30% 단축** | +| Cache-Aside | 반복 API 호출 제거 → 테스트 시간 **50% 단축** | +| Circuit Breaker | 장애 처리 로직 자동화 → 예외 처리 코드 **40% 감소** | +| Async Request-Reply | 동시 처리 능력 **5배 증가** | --- -## 9. 결론 +## 6. 운영 고려사항 -### 9.1 선정된 패턴 요약 +### 6.1 모니터링 지표 -**Phase 1 (MVP)**: -1. ✅ API Gateway - 중앙 인증 및 라우팅 -2. ✅ Cache-Aside - AI/이미지 비용 90% 절감 -3. ✅ Asynchronous Request-Reply - 사용자 경험 개선 -4. ✅ Circuit Breaker - 외부 API 장애 격리 -5. ✅ Retry - 일시적 오류 자동 복구 +**Cache-Aside**: +- 캐시 히트율 (목표: 80% 이상) +- Redis 메모리 사용률 (목표: 70% 이하) +- 캐시 응답 시간 (목표: 100ms 이하) -**Phase 2 (확장)**: -6. ✅ Queue-Based Load Leveling - 부하 분산 -7. ✅ Saga - 복잡한 트랜잭션 관리 +**API Gateway**: +- 요청 처리량 (TPS) +- 평균 응답 시간 +- 인증 실패율 -**Phase 3 (고도화)**: -8. ✅ CQRS - 대시보드 성능 최적화 -9. ✅ Event Sourcing - 감사 추적 +**Circuit Breaker**: +- API별 실패율 +- Circuit 상태 (Closed/Open/Half-Open) +- Fallback 호출 횟수 -### 9.2 예상 효과 +**Asynchronous Request-Reply**: +- Job 처리 시간 +- 동시 Job 수 +- Job 완료율 -**성능**: -- AI 응답 시간: 99% 개선 (캐시 히트 시) -- 이미지 생성: 98% 개선 (캐시 히트 시) +### 6.2 알람 임계값 -**비용**: -- 연간 $20,760 절감 (78.6% 감소) +| 지표 | Warning | Critical | +|------|---------|----------| +| 캐시 히트율 | < 70% | < 50% | +| Redis 메모리 | > 80% | > 90% | +| API 응답 시간 | > 500ms | > 1000ms | +| Circuit Breaker Open | 1개 | 3개 이상 | +| 시스템 가용성 | < 99% | < 95% | -**안정성**: -- 시스템 가용성: 95% → 99.9% -- 외부 API 장애 영향: 99% 감소 +### 6.3 장애 대응 절차 -**사용자 경험**: -- 이벤트 생성 시간: 66.7% 단축 -- 사용자 만족도: 28.6% 향상 +**Circuit Breaker Open 발생 시**: +1. 알람 수신 (Slack/Email) +2. 해당 외부 API 상태 확인 +3. Fallback 전략 동작 확인 +4. 30초 후 자동 복구 확인 +5. 복구 실패 시 수동 개입 -### 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 + 통합 테스트 +**캐시 장애 시**: +1. Redis 클러스터 상태 확인 +2. Failover 자동 수행 (Sentinel) +3. 캐시 미스로 전환 (성능 저하 허용) +4. 긴급 Redis 복구 --- -**문서 작성자**: System Architect - 박영자 -**검토자**: Backend Developer - 최수연, DevOps Engineer - 송근정 -**승인일**: 2025-10-21 +## 7. 체크리스트 + +### 7.1 패턴 적용 완료 확인 + +- [x] **Cache-Aside**: AI 결과, 이미지, 사업자번호 검증 캐싱 완료 +- [x] **API Gateway**: 인증, 라우팅, Rate Limiting 구현 완료 +- [x] **Asynchronous Request-Reply**: AI 및 이미지 생성 Job 처리 완료 +- [x] **Circuit Breaker**: 7개 외부 API에 Circuit Breaker 및 Fallback 적용 완료 + +### 7.2 성능 목표 달성 확인 + +- [ ] AI 응답 시간: 10초 이내 (캐시 미스), 0.1초 (캐시 히트) +- [ ] 캐시 히트율: 80% 이상 +- [ ] 시스템 가용성: 99% 이상 +- [ ] 비용 절감: 월 $960 (80%) + +### 7.3 운영 준비 완료 확인 + +- [ ] 모니터링 대시보드 구축 (Prometheus + Grafana) +- [ ] 알람 설정 완료 (Slack/Email) +- [ ] 장애 대응 매뉴얼 작성 +- [ ] 부하 테스트 완료 (100명) + +--- + +## 8. 다음 단계 (Phase 2 이후) + +**MVP 이후 확장 계획** (선택 사항): + +- **Retry 패턴**: 일시적 오류 자동 재시도 (현재는 Circuit Breaker로 커버) +- **Queue-Based Load Leveling**: 트래픽 폭증 시 부하 분산 +- **Saga 패턴**: 복잡한 분산 트랜잭션 관리 (이벤트 생성 플로우) +- **CQRS**: 읽기/쓰기 분리로 대시보드 성능 최적화 +- **Event Sourcing**: 이벤트 변경 이력 추적 및 감사 + +--- + +## 참고 문서 + +- [유저스토리](../userstory.md) +- [UI/UX 설계서](../uiux/uiux.md) +- [클라우드 디자인 패턴 개요](../../claude/cloud-design-patterns.md) +- [백업 파일](./architecture-pattern-backup.md) - 이전 버전 (9개 패턴)