shared-dg05-dodari/kt-event-marketing

Fork 0

mirror of https://github.com/ktds-dg0501/kt-event-marketing.git synced 2025-12-06 17:26:23 +00:00

cherry2250 597e3716e7 add logical architecture

2025-10-21 17:38:07 +09:00

21 KiB

Raw Blame History

KT AI 기반 소상공인 이벤트 자동 생성 서비스 - 논리 아키텍처

문서 정보

작성일: 2025-10-21
버전: 1.0
작성자: System Architect
관련 문서:

1. 개요

1.1 설계 원칙

본 논리 아키텍처는 다음 원칙을 기반으로 설계되었습니다:

유저스토리 기반 설계

20개 유저스토리와 정확히 매칭
불필요한 추가 기능 배제
비즈니스 요구사항 우선 반영

마이크로서비스 아키텍처

서비스 독립성: 각 서비스는 독립적으로 배포 및 확장 가능
캐시 우선 전략: Redis를 통한 서비스 간 데이터 공유 최소화
선택적 비동기: AI 및 이미지 생성 등 장시간 작업만 비동기 처리
느슨한 결합: 서비스 간 직접 의존성 최소화

클라우드 디자인 패턴 적용

Cache-Aside: AI 응답, 이미지 생성 결과 캐싱 (응답 시간 90% 개선)
API Gateway: 중앙집중식 인증/라우팅/Rate Limiting
Asynchronous Request-Reply: AI 추천, 이미지 생성 비동기 처리
Circuit Breaker: 7개 외부 API 장애 격리 (가용성 99% 목표)

1.2 핵심 컴포넌트 정의

Client Layer

Web/Mobile Client: 반응형 React 애플리케이션
- Mobile First 설계 (60% 모바일 사용자)
- Progressive Web App (PWA) 지원

Gateway Layer

API Gateway: Kong 또는 AWS API Gateway
- JWT 토큰 기반 인증/인가
- URL 기반 서비스 라우팅
- Rate Limiting (사용자당 100 req/min)
- 중앙집중식 로깅 및 모니터링

Service Layer (7개 마이크로서비스)

User Service: 사용자 인증 및 매장정보 관리
Event Service: 이벤트 CRUD 및 상태 관리
AI Service: 트렌드 분석 및 이벤트 추천
Content Service: SNS 이미지 자동 생성
Distribution Service: 다중 채널 배포 관리
Participation Service: 이벤트 참여 및 당첨자 관리
Analytics Service: 실시간 성과 대시보드

Data Layer

Redis Cache:
- 세션 정보 (User)
- AI 추천 결과 (TTL 24시간)
- 이미지 생성 결과 (TTL 7일)
- 사업자번호 검증 결과 (TTL 7일)
- 대시보드 데이터 (TTL 5분)
Message Queue (RabbitMQ/Kafka):
- AI 작업 큐 (비동기 처리)
- 이미지 생성 큐
- 배포 작업 큐
Database (PostgreSQL):
- 서비스별 독립 데이터베이스
- User DB, Event DB, Participation DB, Analytics DB

External APIs

국세청 사업자등록정보 진위확인 API: 사업자번호 검증
Claude API / GPT-4 API: AI 트렌드 분석 및 이벤트 추천
Stable Diffusion / DALL-E API: SNS 이미지 생성
우리동네TV API: 영상 배포
링고비즈 API: 연결음 업데이트
지니TV 광고 API: TV 광고 배포
SNS APIs (Instagram, Naver, Kakao): SNS 자동 포스팅

2. 서비스 아키텍처

2.1 서비스별 책임

User Service

핵심 책임:

회원가입/로그인 (JWT 토큰 발급)
프로필 관리 (매장 정보 포함)
사업자번호 검증 (국세청 API 연동)
로그아웃 및 세션 관리

관련 유저스토리: UFR-USER-010, 020, 030, 040

주요 기능:

JWT 기반 인증/인가
Redis를 통한 세션 관리
사업자번호 검증 결과 캐싱 (TTL 7일)
매장 정보 CRUD

데이터 저장:

User DB: users, stores 테이블
Redis: 세션 정보, 사업자번호 검증 결과

Event Service

핵심 책임:

이벤트 CRUD 및 상태 관리
이벤트 생성 플로우 오케스트레이션
이벤트 목록 조회 및 필터링
이벤트 상세 정보 조회

관련 유저스토리: UFR-EVENT-010, 020, 030, 040, 050, 060, 070

주요 기능:

이벤트 생성 플로우 관리 (목적 선택 → AI 추천 → 콘텐츠 생성 → 배포)
이벤트 상태 관리 (진행중/예정/종료)
대시보드용 이벤트 목록 제공
이벤트 검색 및 필터링

데이터 저장:

Event DB: events, event_objectives, event_prizes 테이블

AI Service

핵심 책임:

업종/지역/시즌 트렌드 분석
3가지 이벤트 기획안 자동 생성
예상 성과 계산 (참여자 수, 비용, ROI)

관련 유저스토리: UFR-AI-010

주요 기능:

Claude/GPT-4 API 연동
비동기 처리 (Job 기반)
트렌드 분석 결과 캐싱 (TTL 24시간)
3가지 옵션 차별화 (저비용/중비용/고비용)

처리 시간:

캐시 HIT: 0.1초
캐시 MISS: 10초 이내 (비동기 Job 처리)

데이터 저장:

Redis: AI 추천 결과 (TTL 24시간)
Redis: Job 상태 정보 (TTL 1시간)

Content Service

핵심 책임:

3가지 스타일 SNS 이미지 자동 생성
플랫폼별 이미지 최적화 (Instagram, Naver, Kakao)
이미지 편집 기능 제공

관련 유저스토리: UFR-CONT-010, 020

주요 기능:

Stable Diffusion/DALL-E API 연동
비동기 이미지 생성 (Job 기반)
3가지 스타일 카드 생성 (심플/화려한/트렌디)
생성 이미지 캐싱 및 CDN 업로드

처리 시간:

캐시 HIT: 0.1초
캐시 MISS: 5초 이내 (비동기 Job 처리)

데이터 저장:

Redis: 이미지 생성 결과 (CDN URL, TTL 7일)
CDN: 생성된 이미지 파일

Distribution Service

핵심 책임:

다중 채널 동시 배포 (우리동네TV, 링고비즈, 지니TV, SNS)
배포 상태 모니터링
채널별 독립적 처리 및 실패 재시도

관련 유저스토리: UFR-DIST-010, 020

주요 기능:

7개 외부 API 병렬 연동 (Circuit Breaker 적용)
채널별 독립 처리 (하나 실패해도 다른 채널 계속)
자동 재시도 (최대 3회)
Fallback 전략 (배포 스킵 + 알림)

처리 시간: 1분 이내 (모든 채널 배포 완료)

데이터 저장:

Event DB: distribution_logs 테이블

Participation Service

핵심 책임:

고객 이벤트 참여 접수
참여자 목록 관리
당첨자 자동 추첨

관련 유저스토리: UFR-PART-010, 020, 030

주요 기능:

중복 참여 체크 (전화번호 기반)
참여자 목록 조회 및 필터링
난수 기반 무작위 추첨
매장 방문 고객 가산점 옵션

데이터 저장:

Participation DB: participants, winners 테이블

Analytics Service

핵심 책임:

실시간 성과 대시보드
채널별 성과 분석
투자 대비 수익률 계산

관련 유저스토리: UFR-ANAL-010

주요 기능:

다중 데이터 소스 통합 (7개 외부 API + 내부 서비스)
5분 간격 데이터 폴링 및 캐싱
실시간 차트 및 그래프 생성
POS 시스템 연동 (선택)

처리 시간: 0.5초 (캐시 기반)

데이터 저장:

Analytics DB: event_stats, channel_stats 테이블
Redis: 대시보드 데이터 (TTL 5분)

2.2 서비스 간 통신 전략

동기 통신 (Synchronous)

사용 시나리오: 즉시 응답이 필요한 단순 조회

User → Redis: 세션 정보 조회
Event → User: 사용자 정보 검증 (Token 검증은 API Gateway에서 처리)
Participation → Event: 이벤트 정보 조회
Analytics → Event/Participation: 통계 데이터 조회

통신 방식: REST API (HTTP/JSON)

캐시 우선 전략 (Cache-Aside)

사용 시나리오: 자주 사용되는 데이터, 외부 API 결과

AI Service: 트렌드 분석 및 이벤트 추천 결과
- 캐시 키: ai:recommendation:{업종}:{지역}:{목적}
- TTL: 24시간
- 히트율 목표: 80%
Content Service: 생성된 이미지 URL
- 캐시 키: content:image:{이벤트ID}:{스타일}
- TTL: 7일
- 히트율 목표: 80%
User Service: 사업자번호 검증 결과
- 캐시 키: user:business:{사업자번호}
- TTL: 7일
- 히트율 목표: 90%
Analytics Service: 대시보드 데이터
- 캐시 키: analytics:dashboard:{이벤트ID}
- TTL: 5분
- 히트율 목표: 95%

효과:

AI 응답 시간: 10초 → 0.1초 (99% 개선, 캐시 히트 시)
이미지 생성 시간: 5초 → 0.1초 (98% 개선, 캐시 히트 시)
대시보드 로딩 시간: 3초 → 0.5초 (83% 개선)

비동기 처리 (Asynchronous Request-Reply)

사용 시나리오: 장시간 작업 (10초 이상 소요)

AI Service: 트렌드 분석 + 이벤트 추천 (10초)
1. 클라이언트 → Event Service: POST /api/ai/recommendations
2. Event Service → AI Service: Job 생성
3. AI Service → 클라이언트: Job ID 즉시 반환 (0.1초)
4. 백그라운드: AI Service → Claude API (10초)
5. 폴링: 클라이언트 → Event Service: GET /api/jobs/{id} (5초 간격)
6. 완료: AI Service → 클라이언트: 최종 결과 반환
Content Service: 이미지 생성 (5초)
1. 클라이언트 → Event Service: POST /api/content/images
2. Event Service → Content Service: Job 생성
3. Content Service → 클라이언트: Job ID 즉시 반환 (0.1초)
4. 백그라운드: Content Service → Stable Diffusion API (5초)
5. 폴링: 클라이언트 → Event Service: GET /api/jobs/{id} (3초 간격)
6. 완료: Content Service → 클라이언트: 최종 결과 반환

Message Queue 사용:

RabbitMQ 또는 Kafka
Priority Queue: AI 작업 우선순위 관리
Dead Letter Queue: 실패 작업 처리

Circuit Breaker 패턴

사용 시나리오: 외부 API 장애 격리

적용 대상: 7개 외부 API
- 국세청 API
- Claude/GPT-4 API
- Stable Diffusion/DALL-E API
- 우리동네TV API
- 링고비즈 API
- 지니TV API
- SNS APIs (Instagram, Naver, Kakao)
동작 방식:
- Closed (정상): 실패율 5% 미만
- Open (차단): 실패율 5% 초과 시 Circuit Open → 모든 요청 Fallback
- Half-Open (테스트): 30초 후 1개 요청 시도 → 성공 시 Closed로 전환
Fallback 전략:
- AI Service: 캐시된 이전 추천 결과 + 안내 메시지
- Distribution Service: 해당 채널 배포 스킵 + 알림
- User Service: 사업자번호 검증 스킵 (수동 확인으로 대체)

효과: 가용성 95% → 99% 개선

3. 주요 사용자 플로우

3.1 이벤트 생성 플로우 (핵심 플로우)

1. [User] 07-이벤트목적선택
   - 클라이언트 → API Gateway → Event Service
   - Event: 목적 저장 (신규 고객 유치/재방문 유도/매출 증대/인지도 향상)

2. [AI] 08-AI이벤트추천
   - 클라이언트 → API Gateway → Event Service → AI Service
   - AI: Job ID 즉시 반환 (0.1초)
   - 백그라운드: AI Service → Claude API (10초)
     * 캐시 확인 (Cache-Aside)
     * 캐시 MISS: Claude API 호출 → 결과 캐싱 (TTL 24시간)
   - 폴링: 클라이언트 → Event Service (5초 간격)
   - 완료: AI 추천 결과 (3가지 옵션) 반환

3. [Content] 09-SNS이미지생성
   - 클라이언트 → API Gateway → Event Service → Content Service
   - Content: Job ID 즉시 반환 (0.1초)
   - 백그라운드: Content Service → Stable Diffusion API (5초)
     * 캐시 확인 (Cache-Aside)
     * 캐시 MISS: Stable Diffusion API 호출 → 이미지 CDN 업로드 → 결과 캐싱 (TTL 7일)
   - 폴링: 클라이언트 → Event Service (3초 간격)
   - 완료: 3가지 스타일 이미지 URL 반환

4. [Content] 10-콘텐츠편집
   - 클라이언트 → API Gateway → Content Service
   - Content: 텍스트/색상 편집 적용 → 새 이미지 생성

5. [Distribution] 11-배포채널선택
   - 클라이언트 → API Gateway → Event Service
   - Event: 배포 채널 정보 저장

6. [Event] 12-최종승인
   - 클라이언트 → API Gateway → Event Service
   - Event: 이벤트 생성 완료 → Distribution Service 호출
   - Distribution: 다중 채널 배포 시작 (Circuit Breaker 적용)
     * 우리동네TV API (영상 업로드)
     * 링고비즈 API (연결음 업데이트)
     * 지니TV API (광고 등록)
     * SNS APIs (Instagram, Naver, Kakao 자동 포스팅)
   - 배포 완료: 대시보드로 이동

3.2 고객 참여 플로우

1. [Participation] 15-이벤트참여
   - 외부 채널 (SNS/TV/연결음) → 이벤트 발견
   - 클라이언트 → API Gateway → Participation Service
   - Participation: 중복 참여 체크 (전화번호 기반)
   - 참여 접수 완료 → 응모 번호 발급

3.3 성과 분석 플로우

1. [Analytics] 17-실시간대시보드
   - 클라이언트 → API Gateway → Analytics Service
   - Analytics: 캐시 확인 (TTL 5분)
     * 캐시 HIT: 즉시 반환 (0.5초)
     * 캐시 MISS: 다중 데이터 소스 통합
       - Participation Service: 참여자 데이터
       - Distribution Service: 채널별 노출 수
       - 외부 APIs: 우리동네TV, 지니TV, SNS 통계
       - POS 시스템: 매출 데이터 (선택)
     * 결과 캐싱 (TTL 5분)
   - 실시간 차트/그래프 렌더링

4. 데이터 흐름 및 캐싱 전략

4.1 데이터 흐름

읽기 플로우 (Cache-Aside 패턴)

1. Application → Cache 확인
   - Cache HIT: 캐시된 데이터 즉시 반환
   - Cache MISS:
     2. Application → Database/External API 조회
     3. Database/External API → Application 데이터 반환
     4. Application → Cache 데이터 저장 (TTL 설정)
     5. Application → Client 데이터 반환

쓰기 플로우 (Write-Through 패턴)

1. Application → Database 쓰기
2. Database → Application 성공 응답
3. Application → Cache 무효화 또는 업데이트
4. Application → Client 성공 응답

4.2 캐싱 전략

Redis 캐시 구조

서비스	캐시 키 패턴	데이터 타입	TTL	예상 크기	히트율 목표
User	`user:session:{token}`	String	7일	1KB	-
User	`user:business:{사업자번호}`	String	7일	0.5KB	90%
AI	`ai:recommendation:{업종}:{지역}:{목적}`	Hash	24시간	10KB	80%
Content	`content:image:{이벤트ID}:{스타일}`	String	7일	0.2KB (URL)	80%
Analytics	`analytics:dashboard:{이벤트ID}`	Hash	5분	5KB	95%
AI	`job:{jobId}`	Hash	1시간	1KB	-
Content	`job:{jobId}`	Hash	1시간	1KB	-

Redis 메모리 산정

예상 동시 사용자: 100명
예상 이벤트 수: 50개
예상 캐시 항목 수: 10,000개
예상 총 메모리: 약 50MB (운영 환경 2GB 할당)

캐시 무효화 전략

TTL 기반 자동 만료: 대부분의 캐시
수동 무효화: 이벤트 수정/삭제 시 관련 캐시 삭제
Lazy 무효화: 데이터 변경 시 다음 조회 시점에 갱신

4.3 데이터베이스 전략

서비스별 독립 데이터베이스

User DB: users, stores
Event DB: events, event_objectives, event_prizes, distribution_logs
Participation DB: participants, winners
Analytics DB: event_stats, channel_stats

데이터 일관성 전략

Eventual Consistency: 서비스 간 데이터는 최종 일관성 보장
Strong Consistency: 서비스 내부 트랜잭션은 강한 일관성 보장
Saga 패턴: 이벤트 생성 플로우 (보상 트랜잭션)

5. 확장성 및 성능 고려사항

5.1 수평 확장 전략

서비스별 확장 전략

서비스	초기 인스턴스	확장 조건	최대 인스턴스	Auto-scaling 메트릭
User	2	CPU > 70%	5	CPU, 메모리
Event	2	CPU > 70%	10	CPU, 메모리
AI	1	Job Queue > 10	3	Queue 길이
Content	1	Job Queue > 10	3	Queue 길이
Distribution	2	CPU > 70%	5	CPU, 메모리
Participation	1	CPU > 70%	3	CPU, 메모리
Analytics	1	CPU > 70%	3	CPU, 메모리

Redis Cluster

초기 구성: 3 노드 (Master 3, Replica 3)
확장: 노드 추가를 통한 수평 확장
HA: Redis Sentinel을 통한 자동 Failover

Database Replication

Primary-Replica 구조: 읽기 부하 분산
읽기 확장: Read Replica 추가 (필요 시)
쓰기 확장: Sharding (Phase 2 이후)

5.2 성능 목표

응답 시간 목표

기능	목표 시간	캐시 HIT	캐시 MISS
로그인	0.5초	-	-
이벤트 목록 조회	0.3초	-	-
AI 트렌드 분석 + 추천	0.1초	✅	10초 (비동기)
SNS 이미지 생성	0.1초	✅	5초 (비동기)
다중 채널 배포	1분	-	-
대시보드 로딩	0.5초	✅	3초

처리량 목표

동시 사용자: 100명 (MVP 목표)
API 요청: 1,000 req/min
AI 작업: 10 jobs/min
이미지 생성: 10 jobs/min

5.3 성능 최적화 기법

Frontend 최적화

Code Splitting: 페이지별 번들 분할
Lazy Loading: 차트 라이브러리 지연 로딩
CDN: 정적 자산 CDN 배포
Compression: Gzip/Brotli 압축

Backend 최적화

Connection Pooling: 데이터베이스 연결 풀 관리
Query Optimization: 인덱스 최적화, N+1 쿼리 방지
Batch Processing: 대량 데이터 일괄 처리
Pagination: 목록 조회 페이지네이션

Cache 최적화

Multi-Level Caching: Browser Cache → CDN → Redis → Database
Cache Warming: 자주 사용되는 데이터 사전 로딩
Cache Preloading: 피크 시간 전 캐시 준비

6. 보안 고려사항

6.1 인증 및 인가

JWT 기반 인증

토큰 발급: User Service에서 로그인 시 JWT 토큰 발급
토큰 검증: API Gateway에서 모든 요청의 JWT 토큰 검증
토큰 저장: Redis에 세션 정보 저장 (TTL 7일)
토큰 갱신: Refresh Token 패턴 (선택)

역할 기반 접근 제어 (RBAC)

역할: OWNER (매장 사장님), CUSTOMER (이벤트 참여자)
권한 관리: API별 필요 역할 정의
API Gateway 검증: 요청자의 역할 확인

6.2 데이터 보안

민감 정보 암호화

비밀번호: bcrypt 해싱 (Cost Factor: 10)
사업자번호: AES-256 암호화 저장
개인정보: 전화번호 마스킹 (010-****-1234)

전송 보안

HTTPS: 모든 통신 TLS 1.3 암호화
API Key: 외부 API 호출 시 안전한 Key 관리 (AWS Secrets Manager)

데이터 접근 통제

Database: 서비스별 독립 계정, 최소 권한 원칙
Redis: 비밀번호 설정, ACL 적용
백업: 암호화된 백업 저장

6.3 보안 모니터링

위협 탐지

Rate Limiting: API Gateway에서 사용자당 100 req/min
Brute Force 방지: 로그인 5회 실패 시 계정 잠금 (삭제됨, 향후 추가 가능)
SQL Injection 방지: Prepared Statement 사용
XSS 방지: 입력 데이터 Sanitization

로깅 및 감사

Access Log: 모든 API 요청 로깅
Audit Log: 민감 작업 (로그인, 이벤트 생성, 당첨자 추첨) 감사 로그
중앙집중식 로깅: ELK Stack 또는 CloudWatch Logs

7. 논리 아키텍처 다이어그램

논리 아키텍처 다이어그램은 별도 Mermaid 파일로 작성되었습니다.

파일 위치: logical-architecture.mmd

다이어그램 확인 방법:

https://mermaid.live/edit 접속
logical-architecture.mmd 파일 내용 붙여넣기
다이어그램 시각적 확인

다이어그램 구성:

Client Layer: Web/Mobile Client
Gateway Layer: API Gateway
Service Layer: 7개 마이크로서비스
Data Layer: Redis Cache, Message Queue, Databases
External APIs: 7개 외부 API

의존성 표현:

실선 화살표 (→): 동기적 의존성
점선 화살표 (-.->): 비동기 의존성 또는 캐시 접근
화살표 레이블: 의존성 목적 명시

부록

A. 참고 문서

B. 주요 결정사항

Cache-Aside 패턴 채택: AI 응답 시간 90% 개선 목표
Asynchronous Request-Reply 패턴 채택: AI/이미지 생성 비동기 처리
Circuit Breaker 패턴 채택: 외부 API 장애 격리
서비스별 독립 Database: 마이크로서비스 독립성 보장
Redis 캐시 우선 전략: 서비스 간 직접 의존성 최소화

C. 향후 개선 방안 (Phase 2 이후)

Saga 패턴: 복잡한 분산 트랜잭션 관리
CQRS 패턴: 읽기/쓰기 분리로 대시보드 성능 최적화
Event Sourcing: 이벤트 변경 이력 추적 및 감사
Service Mesh: Istio를 통한 고급 트래픽 관리
Database Sharding: 쓰기 확장성 개선

문서 버전: 1.0 최종 수정일: 2025-10-21 작성자: System Architect

21 KiB Raw Blame History

KT AI 기반 소상공인 이벤트 자동 생성 서비스 - 논리 아키텍처

문서 정보

목차

1. 개요

1.1 설계 원칙

유저스토리 기반 설계

마이크로서비스 아키텍처

클라우드 디자인 패턴 적용

1.2 핵심 컴포넌트 정의

Client Layer

Gateway Layer

Service Layer (7개 마이크로서비스)

Data Layer

External APIs

2. 서비스 아키텍처

2.1 서비스별 책임

User Service

Event Service

AI Service

Content Service

Distribution Service

Participation Service

Analytics Service

2.2 서비스 간 통신 전략

동기 통신 (Synchronous)

캐시 우선 전략 (Cache-Aside)

비동기 처리 (Asynchronous Request-Reply)

Circuit Breaker 패턴

3. 주요 사용자 플로우

3.1 이벤트 생성 플로우 (핵심 플로우)

3.2 고객 참여 플로우

3.3 성과 분석 플로우

4. 데이터 흐름 및 캐싱 전략

4.1 데이터 흐름

읽기 플로우 (Cache-Aside 패턴)

쓰기 플로우 (Write-Through 패턴)

4.2 캐싱 전략

Redis 캐시 구조

Redis 메모리 산정

캐시 무효화 전략

4.3 데이터베이스 전략

서비스별 독립 데이터베이스

데이터 일관성 전략

5. 확장성 및 성능 고려사항

5.1 수평 확장 전략

서비스별 확장 전략

Redis Cluster

Database Replication

5.2 성능 목표

응답 시간 목표

처리량 목표

5.3 성능 최적화 기법

Frontend 최적화

Backend 최적화

Cache 최적화

6. 보안 고려사항

6.1 인증 및 인가

JWT 기반 인증

역할 기반 접근 제어 (RBAC)

6.2 데이터 보안

민감 정보 암호화

전송 보안

데이터 접근 통제

6.3 보안 모니터링

위협 탐지

로깅 및 감사

7. 논리 아키텍처 다이어그램

부록

A. 참고 문서

B. 주요 결정사항

C. 향후 개선 방안 (Phase 2 이후)

21 KiB

Raw Blame History