diff --git a/design/pattern/architecture-pattern.md b/design/pattern/architecture-pattern.md new file mode 100644 index 0000000..46f9f30 --- /dev/null +++ b/design/pattern/architecture-pattern.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/uiux/style-guide.md b/design/uiux/style-guide.md index 579120c..b1f46d5 100644 --- a/design/uiux/style-guide.md +++ b/design/uiux/style-guide.md @@ -1,6 +1,7 @@ # KT AI 기반 소상공인 이벤트 자동 생성 서비스 - 스타일 가이드 ## 문서 정보 + - 작성일: 2025-10-17 - 버전: 1.0 - 기반 설계: UI/UX 설계서 v1.0 @@ -11,6 +12,7 @@ ## 1. 브랜드 아이덴티티 ### 1.1 브랜드 비전 + **"AI로 간편하게, 성공으로 확실하게"** 소상공인이 전문 마케터 없이도 AI의 도움으로 효과적인 이벤트를 기획하고 실행할 수 있도록 돕는 혁신적인 서비스 @@ -18,16 +20,19 @@ ### 1.2 디자인 철학 #### 혁신성 (Innovation) + - 최신 AI 기술을 활용한 자동화된 이벤트 생성 - 복잡한 마케팅 프로세스를 단순화 - 3분 만에 완성되는 이벤트 콘텐츠 #### 신뢰성 (Trust) + - KT 브랜드의 안정성과 신뢰감 - 명확한 프로세스와 투명한 결과 제공 - 실시간 성과 모니터링 #### 친근함 (Approachability) + - 소상공인 눈높이에 맞춘 쉬운 인터페이스 - 초보자도 이해할 수 있는 명확한 안내 - 따뜻하고 친근한 톤앤매너 @@ -35,11 +40,13 @@ ### 1.3 브랜드 컬러 **Primary Color: KT Red** + - 정체성, 브랜드 대표 색상 - 행동 유도(CTA), 강조 요소 - KT 브랜드 헤리티지 계승 **Secondary Color: AI Blue** + - AI 기능, 기술적 신뢰감 - 정보 전달, 안내 요소 - 혁신과 미래지향성 @@ -49,6 +56,7 @@ ## 2. 디자인 원칙 ### 2.1 명확성 (Clarity) + **사용자가 무엇을 해야 하는지 항상 명확해야 합니다** - 직관적인 아이콘과 레이블 사용 @@ -56,12 +64,14 @@ - 현재 위치와 다음 단계를 항상 표시 예시: + ``` ✓ 좋은 예: "새 이벤트 만들기" + 큰 CTA 버튼 ✗ 나쁜 예: "시작하기" (무엇을 시작하는지 불분명) ``` ### 2.2 효율성 (Efficiency) + **최소한의 단계로 목표를 달성할 수 있어야 합니다** - 불필요한 스텝 제거 @@ -69,11 +79,13 @@ - AI가 대부분의 작업 자동화 목표: + - 이벤트 기획: 10초 이내 - 콘텐츠 생성: 3분 이내 - 배포 설정: 1분 이내 ### 2.3 신뢰성 (Trust) + **AI 처리 과정과 결과를 투명하게 보여줍니다** - AI 처리 시간 명시 (예: "AI가 분석중입니다 약 3초 소요") @@ -81,6 +93,7 @@ - 언제든 이전 단계로 돌아갈 수 있음 ### 2.4 친근함 (Approachability) + **초보자도 쉽게 사용할 수 있어야 합니다** - 전문 용어 최소화 @@ -88,6 +101,7 @@ - 도움말과 예시 제공 ### 2.5 일관성 (Consistency) + **모든 화면에서 동일한 패턴을 유지합니다** - 컴포넌트 재사용 @@ -101,6 +115,7 @@ ### 3.1 Primary Color (주 색상) #### KT Red - 브랜드 정체성 + ``` Main: #E31E24 // CTA 버튼, 주요 액션, 활성화 상태 Light: #FF4D52 // 호버 상태, 배경 강조 @@ -114,12 +129,14 @@ Dark: #C71820 // 눌림 상태, 진한 강조 ``` #### 색상 접근성 + - White 배경 대비: 7.2:1 (WCAG AAA) - Gray-100 배경 대비: 6.8:1 (WCAG AAA) ### 3.2 Secondary Color (보조 색상) #### AI Blue - 혁신과 신뢰 + ``` Main: #0066FF // AI 기능 강조, 정보 아이콘 Light: #4D94FF // AI 로딩 배경, 안내 영역 @@ -166,6 +183,7 @@ Info (정보): #0288D1 // 안내, 팁, 추가 정보 ### 3.5 Gradient (그라데이션) #### AI Feature Gradient + ``` Primary Gradient: background: linear-gradient(135deg, #E31E24 0%, #FF4D52 100%); @@ -183,13 +201,14 @@ Secondary Gradient: ### 4.1 Font Family **Primary: Pretendard** + ```css -font-family: 'Pretendard', -apple-system, BlinkMacSystemFont, - 'Segoe UI', 'Roboto', 'Helvetica Neue', - system-ui, sans-serif; +font-family: "Pretendard", -apple-system, BlinkMacSystemFont, "Segoe UI", "Roboto", + "Helvetica Neue", system-ui, sans-serif; ``` **선택 이유:** + - 한글 가독성이 뛰어남 - 다양한 Font Weight 지원 (100~900) - 모던하고 깔끔한 디자인 @@ -267,6 +286,7 @@ Bold (700): 제목, 헤딩 ### 4.4 Responsive Typography **Tablet (768px~)** + ``` Display: 32px (+4px) H1: 28px (+4px) @@ -279,6 +299,7 @@ Button: 16px (유지) ``` **Desktop (1024px~)** + ``` Display: 36px (+8px) H1: 32px (+8px) @@ -295,6 +316,7 @@ Button: 16px (유지) ## 5. 간격 시스템 (Spacing) ### 5.1 Base Unit + **4px Grid System** - 모든 간격은 4의 배수 ### 5.2 Spacing Scale @@ -311,6 +333,7 @@ XL (Extra Large): 32px // 섹션 간 간격 ### 5.3 Component Spacing #### Button + ``` Padding (세로 x 가로): - Large: 16px x 24px (높이 48px) @@ -321,12 +344,14 @@ Button 간 간격: 12px (S + XS) ``` #### Card + ``` 내부 패딩: 24px (L) 카드 간 간격: 16px (M) ``` #### Input Field + ``` 내부 패딩: 16px (M) 레이블-입력 간격: 8px (S) @@ -334,6 +359,7 @@ Button 간 간격: 12px (S + XS) ``` #### Screen Margins + ``` Mobile: 20px (양쪽) Tablet: 40px (양쪽) @@ -343,6 +369,7 @@ Desktop: 80px (양쪽, 최대 1200px container) ### 5.4 Touch Target **WCAG 2.1 AA 준수** + ``` 최소 터치 영역: 44 x 44px 권장 터치 영역: 48 x 48px @@ -361,6 +388,7 @@ Desktop: 80px (양쪽, 최대 1200px container) ### 6.1 Button (버튼) #### Primary Button + ``` 배경: #E31E24 (KT Red) 텍스트: #FFFFFF (White) @@ -375,6 +403,7 @@ Desktop: 80px (양쪽, 최대 1200px container) ``` #### Secondary Button + ``` 배경: #FFFFFF (White) 텍스트: #E31E24 (KT Red) @@ -389,6 +418,7 @@ Desktop: 80px (양쪽, 최대 1200px container) ``` #### Text Button + ``` 배경: 없음 텍스트: #E31E24 (KT Red) @@ -402,6 +432,7 @@ Desktop: 80px (양쪽, 최대 1200px container) ``` #### Button Sizes + ``` Large: - 높이: 48px @@ -425,6 +456,7 @@ Small: ### 6.2 Card (카드) #### Default Card + ``` 배경: #FFFFFF (White) 테두리: 1px solid #E0E0E0 @@ -439,6 +471,7 @@ Small: ``` #### Event Card (이벤트 카드) + ``` 배경: #FFFFFF 둥근 모서리: 12px @@ -455,6 +488,7 @@ Small: ``` #### Selection Card (선택형 카드) + ``` 사용: 옵션 선택 화면 (09-콘텐츠미리보기.html) 특징: 카드 전체가 선택 가능한 인터랙티브 영역 @@ -523,6 +557,7 @@ Radio Button: ``` #### Stat Card (지표 카드) + ``` 배경: Gradient 또는 Solid 둥근 모서리: 16px @@ -539,6 +574,7 @@ Radio Button: ### 6.3 Input Field (입력 필드) #### Text Input + ``` 배경: #FFFFFF (White) 테두리: 1px solid #D9D9D9 @@ -556,6 +592,7 @@ Radio Button: ``` #### Textarea + ``` 배경: #FFFFFF 테두리: 1px solid #D9D9D9 @@ -569,6 +606,7 @@ Resize: vertical (세로 방향만) ``` #### Editable Field (인라인 편집) + ``` 사용: 08-AI이벤트추천.html (제목, 경품 편집) 특징: contenteditable을 활용한 인라인 편집 @@ -610,6 +648,7 @@ Resize: vertical (세로 방향만) ``` #### Placeholder + ``` 색상: #9E9E9E (Gray-500) 폰트: Body-L (16px Regular) @@ -619,6 +658,7 @@ Resize: vertical (세로 방향만) ### 6.4 Checkbox & Radio #### Checkbox + ``` 크기: 24 x 24px (터치 영역 44px) 둥근 모서리: 4px @@ -631,6 +671,7 @@ Resize: vertical (세로 방향만) ``` #### Radio Button + ``` 크기: 24 x 24px (터치 영역 44px) 둥근 모서리: 50% (원형) @@ -766,6 +807,7 @@ Editable Field: ### 6.8 Stepper (단계 표시) #### Progress Stepper (AI 이벤트 생성) + ``` 전체 높이: 48px 배경: #F5F5F5 @@ -783,6 +825,7 @@ Editable Field: ``` #### Step Indicator (단계별 표시) + ``` ┌────┐ ┌────┐ ┌────┐ │ ✓ │─ │ 2 │─ │ 3 │ @@ -854,6 +897,7 @@ Desktop: ### 7.3 Grid System #### Mobile Grid (4 Columns) + ``` ┌─────┬─────┬─────┬─────┐ │ 1 │ 2 │ 3 │ 4 │ @@ -865,6 +909,7 @@ Desktop: ``` #### Tablet Grid (8 Columns) + ``` ┌──┬──┬──┬──┬──┬──┬──┬──┐ │ 1│ 2│ 3│ 4│ 5│ 6│ 7│ 8│ @@ -877,6 +922,7 @@ Desktop: ``` #### Desktop Grid (12 Columns) + ``` ┌┬┬┬┬┬┬┬┬┬┬┬┬┐ │││││││││││││ @@ -895,6 +941,7 @@ Desktop: ### 8.1 AI 처리 상태 컴포넌트 #### Loading Skeleton + ``` 배경: #F5F5F5 애니메이션: Shimmer (좌→우 반짝임) @@ -911,6 +958,7 @@ Duration: 1.5s infinite ``` #### Progress Indicator (AI 단계별) + ``` ┌─────────────────────────────┐ │ 🤖 AI가 트렌드를 분석중입니다 │ @@ -927,6 +975,7 @@ Duration: 1.5s infinite ``` #### Spinner (간단한 로딩) + ``` 크기: 32px 두께: 3px @@ -939,6 +988,7 @@ Duration: 1.5s infinite ### 8.2 AI 결과 카드 #### AI 생성 옵션 카드 (선택형) + ``` ┌─────────────────────────────┐ │ ◯ [이미지 미리보기] │ @@ -959,6 +1009,7 @@ Duration: 1.5s infinite ``` #### AI 추천 배지 + ``` 배경: linear-gradient(135deg, #0066FF 0%, #4D94FF 100%) 텍스트: White @@ -973,6 +1024,7 @@ Duration: 1.5s infinite ### 8.3 Real-time Dashboard Components #### KPI Card (핵심 지표) + ``` ┌─────────────────────────┐ │ 📊 참여자 수 │ @@ -993,6 +1045,7 @@ Duration: 1.5s infinite ``` #### Chart Container + ``` 배경: White 둥근 모서리: 12px @@ -1176,6 +1229,7 @@ Linear (일정): ### 10.3 주요 애니메이션 #### Page Transition + ``` 진입: - opacity: 0 → 1 @@ -1191,6 +1245,7 @@ Linear (일정): ``` #### Card Hover + ``` transform: translateY(0) → translateY(-4px) box-shadow: 증가 (0 2px 8px → 0 8px 16px) @@ -1199,6 +1254,7 @@ easing: ease-out ``` #### Button Press + ``` transform: scale(1) → scale(0.95) duration: 100ms @@ -1456,6 +1512,7 @@ Secondary: ## 15. 변경 이력 ### Version 1.1 (2025-10-21) + - 프로토타입 기반 컴포넌트 업데이트 - Editable Field 컴포넌트 추가 (인라인 편집) - Budget Navigation 컴포넌트 추가 (Sticky 탭 네비게이션) @@ -1464,6 +1521,7 @@ Secondary: - 이벤트 버블링 방지 가이드 추가 ### Version 1.0 (2025-10-17) + - 초안 작성 - 브랜드 아이덴티티 정의 - 디자인 원칙 5가지 수립 diff --git a/design/uiux/uiux-design.md b/design/uiux/uiux-design.md index b4e91d9..06951dd 100644 --- a/design/uiux/uiux-design.md +++ b/design/uiux/uiux-design.md @@ -1,6 +1,7 @@ # KT AI 기반 소상공인 이벤트 자동 생성 서비스 - UI/UX 설계서 ## 문서 정보 + - 작성일: 2025-10-21 - 버전: 2.0 - 기반 문서: 유저스토리 v2.0, 프로토타입 분석 @@ -11,14 +12,17 @@ ## 1. 서비스 개요 ### 1.1 서비스 목적 + 소상공인이 AI의 도움으로 전문 마케터 없이도 효과적인 이벤트를 기획하고 실행할 수 있도록 지원 ### 1.2 핵심 가치 + - **혁신성**: AI 기반 자동화로 3분 만에 이벤트 콘텐츠 생성 - **신뢰성**: KT 브랜드 기반의 안정적인 서비스 - **접근성**: 초보자도 쉽게 사용할 수 있는 직관적 인터페이스 ### 1.3 타겟 사용자 + - **Primary**: 마케팅 전문 지식이 부족한 소상공인 - **Secondary**: 이벤트 마케팅 경험이 있는 중소기업 담당자 @@ -29,12 +33,14 @@ ### 2.1 전체 화면 구조 (총 17개) #### 인증 영역 (01~04) + - **01-로그인.html**: 이메일/비밀번호 로그인 - **02-회원가입.html**: 신규 사용자 등록 - **03-프로필.html**: 사용자 프로필 및 매장 정보 관리 - **04-로그아웃확인.html**: 로그아웃 확인 모달 #### 대시보드 영역 (05~06) + - **05-대시보드.html**: 메인 홈 화면 - KPI 요약 (진행 중 이벤트, 총 참여자, 평균 ROI) - 빠른 시작 (새 이벤트, 분석) @@ -43,6 +49,7 @@ - **06-이벤트목록.html**: 전체 이벤트 목록 및 필터링 #### 이벤트 생성 플로우 (07~12, 7단계) + - **07-이벤트목적선택.html**: 이벤트 목적 선택 - **08-AI이벤트추천.html**: AI 트렌드 분석 및 이벤트 추천 - **09-콘텐츠미리보기.html**: SNS 이미지 스타일 선택 @@ -51,6 +58,7 @@ - **12-최종승인.html**: 이벤트 최종 검토 및 승인 #### 이벤트 관리 및 모니터링 (13~17) + - **13-이벤트상세.html**: 이벤트 상세 정보 및 실시간 KPI - **14-참여자목록.html**: 참여자 관리 및 필터링 - **15-이벤트참여.html**: 사용자 이벤트 참여 화면 (고객용) @@ -98,6 +106,7 @@ ### 3.1 Navigation #### Bottom Navigation (모든 메인 화면) + ``` 구조: 4개 탭 - 홈: 05-대시보드.html @@ -115,6 +124,7 @@ ``` #### Header + ``` 구조: 타이틀 + 뒤로가기 + 프로필 - 대시보드: 뒤로가기 없음 @@ -128,6 +138,7 @@ ``` #### FAB (Floating Action Button) + ``` 위치: 우측 하단 고정 기능: 새 이벤트 생성 (07-이벤트목적선택.html) @@ -143,6 +154,7 @@ ### 3.2 Card 컴포넌트 #### Default Card + ```css 배경: #FFFFFF 테두리: 1px solid #E0E0E0 @@ -152,6 +164,7 @@ ``` #### Event Card + ``` 구조: - 이벤트명 (H3) @@ -165,6 +178,7 @@ ``` #### Selection Card (09-콘텐츠미리보기) + ``` 특징: 카드 전체가 선택 가능한 영역 - Radio 버튼 숨김 (기능은 유지) @@ -178,6 +192,7 @@ ### 3.3 Form 컴포넌트 #### Text Input + ```css 높이: 48px 패딩: 16px @@ -195,6 +210,7 @@ Error: ``` #### Checkbox & Radio + ``` 크기: 24 x 24px (터치 영역 44px) @@ -210,6 +226,7 @@ Radio: ### 3.4 Modal 컴포넌트 #### Modal Dialog + ``` 최대 너비: 400px (Mobile), 480px (Tablet+) 패딩: 24px @@ -224,6 +241,7 @@ Backdrop: rgba(0, 0, 0, 0.6) ``` #### Bottom Sheet + ``` 최대 높이: 80vh 둥근 모서리: 24px 24px 0 0 @@ -235,6 +253,7 @@ Handle: 40px x 4px, #D9D9D9 (상단 중앙) ``` #### Toast + ``` 위치: 하단 중앙, Bottom Nav 위 80px 배경: #1A1A1A (90% opacity) @@ -256,6 +275,7 @@ Handle: 40px x 4px, #D9D9D9 (상단 중앙) ### 4.1 인증 영역 #### 01-로그인.html + ``` 레이아웃: - 로고 (상단 중앙) @@ -273,6 +293,7 @@ Handle: 40px x 4px, #D9D9D9 (상단 중앙) ``` #### 02-회원가입.html + ``` 레이아웃: 세로 스크롤 섹션: @@ -292,6 +313,7 @@ Handle: 40px x 4px, #D9D9D9 (상단 중앙) ``` #### 03-프로필.html + ``` 레이아웃: - 프로필 헤더 (상단) @@ -315,6 +337,7 @@ Bottom Nav: 프로필 탭 활성화 ``` #### 04-로그아웃확인.html + ``` 유형: Modal Dialog @@ -329,6 +352,7 @@ Bottom Nav: 프로필 탭 활성화 ### 4.2 대시보드 영역 #### 05-대시보드.html + ``` 레이아웃: 세로 스크롤 @@ -360,6 +384,7 @@ Bottom Nav: 홈 탭 활성화 ``` #### 06-이벤트목록.html + ``` 레이아웃: 세로 스크롤 @@ -384,6 +409,7 @@ Bottom Nav: 이벤트 탭 활성화 ### 4.3 이벤트 생성 플로우 #### 07-이벤트목적선택.html + ``` 레이아웃: 세로 스크롤 @@ -409,6 +435,7 @@ Progress: 1/7 단계 ``` #### 08-AI이벤트추천.html + ``` 레이아웃: 세로 스크롤 @@ -464,6 +491,7 @@ Progress: 2/7 단계 ``` #### 09-콘텐츠미리보기.html + ``` 레이아웃: 세로 스크롤 @@ -524,6 +552,7 @@ Progress: 3/7 단계 ``` #### 10-콘텐츠편집.html + ``` 레이아웃: - Mobile: 세로 스택 (편집폼 → 미리보기) @@ -558,6 +587,7 @@ Progress: 4/7 단계 ``` #### 11-배포채널선택.html + ``` 레이아웃: 세로 스크롤 @@ -587,6 +617,7 @@ Progress: 5/7 단계 ``` #### 12-최종승인.html + ``` 레이아웃: 세로 스크롤 @@ -618,6 +649,7 @@ Progress: 7/7 단계 ### 4.4 이벤트 관리 및 모니터링 #### 13-이벤트상세.html + ``` 레이아웃: 세로 스크롤 @@ -651,6 +683,7 @@ Bottom Nav: 이벤트 탭 활성화 ``` #### 14-참여자목록.html + ``` 레이아웃: 세로 스크롤 @@ -676,6 +709,7 @@ Bottom Nav: 이벤트 탭 활성화 ``` #### 15-이벤트참여.html + ``` 유형: 고객용 화면 (공개 URL) @@ -706,6 +740,7 @@ Bottom Nav: 이벤트 탭 활성화 ``` #### 16-당첨자추첨.html + ``` 레이아웃: 세로 스크롤 @@ -735,6 +770,7 @@ Bottom Nav: 이벤트 탭 활성화 ``` #### 17-성과분석.html + ``` 레이아웃: 세로 스크롤 @@ -773,6 +809,7 @@ Bottom Nav: 분석 탭 활성화 ## 5. 반응형 디자인 ### 5.1 Breakpoints + ``` Mobile (기본): 320px ~ 767px Tablet: 768px ~ 1023px @@ -782,6 +819,7 @@ Desktop: 1024px 이상 ### 5.2 레이아웃 변화 #### 대시보드 (05) + ``` Mobile: KPI 세로 스택 Tablet: KPI 2x2 그리드, 이벤트 2열 @@ -789,6 +827,7 @@ Desktop: KPI 4열, 이벤트 3열 + 사이드바 ``` #### 이벤트 생성 (09, 10) + ``` Mobile: 세로 스택 Tablet: 세로 스택 (간격 증가) @@ -796,6 +835,7 @@ Desktop: 좌우 분할 (편집 | 미리보기) ``` #### 성과 분석 (17) + ``` Mobile: 차트 세로 스택 Tablet: 차트 2x1 그리드 @@ -807,26 +847,31 @@ Desktop: 차트 2x2 그리드 ## 6. 인터랙션 패턴 ### 6.1 Navigation + - **Bottom Nav**: 탭 클릭 시 즉시 화면 전환 - **Back Button**: 이전 화면으로 이동 - **FAB**: 새 이벤트 생성 플로우 시작 ### 6.2 Form + - **실시간 검증**: 입력 필드 blur 시 유효성 검사 - **에러 메시지**: 필드 하단에 빨간색 텍스트 - **성공 피드백**: Toast 메시지 ### 6.3 Loading States + - **AI 처리**: Progress Indicator + 예상 시간 - **데이터 로딩**: Skeleton Screen - **버튼 클릭**: Spinner + 비활성화 ### 6.4 Feedback + - **성공**: Green Toast + 체크 아이콘 - **에러**: Red Toast + X 아이콘 - **정보**: Blue Toast + i 아이콘 ### 6.5 Gestures (Mobile) + - **Swipe**: 이벤트 카드 좌우 스와이프 (삭제/편집) - **Pull to Refresh**: 대시보드, 성과 분석 - **Long Press**: 컨텍스트 메뉴 표시 @@ -836,17 +881,20 @@ Desktop: 차트 2x2 그리드 ## 7. 접근성 고려사항 ### 7.1 WCAG 2.1 AA 준수 + - **색상 대비**: 최소 4.5:1 (텍스트), 3:1 (UI 요소) - **터치 영역**: 최소 44x44px - **키보드 네비게이션**: 모든 인터랙티브 요소 접근 가능 - **Focus Indicator**: 명확한 포커스 표시 ### 7.2 스크린 리더 지원 + - **ARIA Labels**: 모든 버튼, 링크, 폼 필드 - **ARIA Roles**: 적절한 역할 지정 - **Live Regions**: 동적 콘텐츠 업데이트 알림 ### 7.3 대안 제공 + - **색상 외 표현**: 아이콘 + 텍스트 조합 - **키보드 대안**: 드래그 앤 드롭 → 버튼 클릭 - **음성 대안**: 이미지 alt 텍스트 @@ -856,16 +904,19 @@ Desktop: 차트 2x2 그리드 ## 8. 성능 최적화 ### 8.1 이미지 + - **포맷**: WebP (fallback: JPG) - **압축**: Quality 80-85% - **Lazy Loading**: 스크롤 시 로드 ### 8.2 폰트 + - **Font Display**: swap - **Preload**: 주요 폰트 - **Subset**: 자주 쓰는 글자만 ### 8.3 애니메이션 + - **GPU 가속**: transform, opacity - **Will-Change**: 애니메이션 직전만 적용 @@ -874,6 +925,7 @@ Desktop: 차트 2x2 그리드 ## 9. 에러 처리 ### 9.1 네트워크 에러 + ``` 표시: Toast (빨간색) 메시지: "네트워크 연결을 확인해주세요" @@ -881,6 +933,7 @@ Desktop: 차트 2x2 그리드 ``` ### 9.2 Validation 에러 + ``` 표시: Input 하단 메시지 색상: Error Red (#D32F2F) @@ -888,6 +941,7 @@ Desktop: 차트 2x2 그리드 ``` ### 9.3 서버 에러 + ``` 표시: Modal Dialog 메시지: "일시적인 오류가 발생했습니다. 잠시 후 다시 시도해주세요." @@ -895,6 +949,7 @@ Desktop: 차트 2x2 그리드 ``` ### 9.4 Empty State + ``` 표시: 중앙 정렬 메시지 + 아이콘 예시: @@ -919,6 +974,7 @@ Desktop: 차트 2x2 그리드 ## 11. 변경 이력 ### Version 2.1 (2025-10-21) + - 프로토타입 실제 구현 내용 반영 - 08-AI이벤트추천: 예산별 2가지 방식(온라인/오프라인) 상세화 - 08-AI이벤트추천: Budget Navigation (Sticky) 추가 @@ -927,6 +983,7 @@ Desktop: 차트 2x2 그리드 - 09-콘텐츠미리보기: Fullscreen Modal, 이벤트 버블링 방지 추가 ### Version 2.0 (2025-10-21) + - 프로토타입 분석 기반 전면 개정 - 화면 번호 체계 정립 (01~17번) - 네비게이션 구조 변경 (햄버거 메뉴 제거, Bottom Nav 4탭) @@ -937,6 +994,7 @@ Desktop: 차트 2x2 그리드 - 실시간 KPI 업데이트 추가 (13-이벤트상세) ### Version 1.0 (2025-10-17) + - 초안 작성 ---