mirror of
https://github.com/ktds-dg0501/kt-event-marketing-fe.git
synced 2025-12-06 12:56:24 +00:00
3f6e005026
🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
305 lines
9.4 KiB
Markdown
305 lines
9.4 KiB
Markdown
# KT AI 기반 소상공인 이벤트 자동 생성 서비스 - 외부 시퀀스 설계
|
|
|
|
## 문서 정보
|
|
- **작성일**: 2025-10-22
|
|
- **작성자**: System Architect
|
|
- **버전**: 1.0
|
|
- **관련 문서**:
|
|
- [유저스토리](../../../userstory.md)
|
|
- [논리 아키텍처](../../logical/logical-architecture.md)
|
|
- [UI/UX 설계서](../../../uiux/uiux.md)
|
|
|
|
---
|
|
|
|
## 개요
|
|
|
|
본 문서는 KT AI 기반 소상공인 이벤트 자동 생성 서비스의 **외부 시퀀스 설계**를 정의합니다.
|
|
외부 시퀀스는 서비스 간의 상호작용과 데이터 흐름을 표현하며, 유저스토리와 논리 아키텍처를 기반으로 설계되었습니다.
|
|
|
|
### 설계 원칙
|
|
1. **유저스토리 기반**: 20개 유저스토리와 정확히 매칭
|
|
2. **Event-Driven 아키텍처**: Kafka를 통한 비동기 이벤트 발행/구독
|
|
3. **Resilience 패턴**: Circuit Breaker, Retry, Timeout, Fallback 적용
|
|
4. **Cache-Aside 패턴**: Redis 캐싱을 통한 성능 최적화
|
|
5. **서비스 독립성**: 느슨한 결합과 장애 격리
|
|
|
|
---
|
|
|
|
## 외부 시퀀스 플로우 목록
|
|
|
|
총 **4개의 주요 비즈니스 플로우**로 구성되어 있습니다:
|
|
|
|
### 1. 사용자 인증 플로우
|
|
**파일**: `사용자인증플로우.puml`
|
|
|
|
**포함된 유저스토리**:
|
|
- UFR-USER-010: 회원가입
|
|
- UFR-USER-020: 로그인
|
|
- UFR-USER-040: 로그아웃
|
|
|
|
**주요 참여자**:
|
|
- Frontend (Web/Mobile)
|
|
- API Gateway
|
|
- User Service
|
|
- Redis Cache
|
|
- User DB (PostgreSQL)
|
|
- 국세청 API (외부)
|
|
|
|
**핵심 기능**:
|
|
- JWT 기반 인증
|
|
- 사업자번호 검증 (Circuit Breaker 적용)
|
|
- Redis 캐싱 (사업자번호 검증 결과, TTL 7일)
|
|
- 비밀번호 해싱 (bcrypt)
|
|
- 사업자번호 암호화 (AES-256)
|
|
|
|
**Resilience 패턴**:
|
|
- Circuit Breaker: 국세청 API (실패율 50% 초과 시 Open)
|
|
- Retry: 최대 3회 재시도 (지수 백오프: 1초, 2초, 4초)
|
|
- Timeout: 5초
|
|
- Fallback: 사업자번호 검증 스킵 (수동 확인 안내)
|
|
|
|
---
|
|
|
|
### 2. 이벤트 생성 플로우
|
|
**파일**: `이벤트생성플로우.puml`
|
|
|
|
**포함된 유저스토리**:
|
|
- UFR-EVENT-020: 이벤트 목적 선택
|
|
- UFR-EVENT-030: AI 이벤트 추천
|
|
- UFR-CONT-010: SNS 이미지 생성
|
|
- UFR-EVENT-050: 최종 승인 및 배포
|
|
|
|
**주요 참여자**:
|
|
- Frontend
|
|
- API Gateway
|
|
- Event Service
|
|
- AI Service (Kafka 구독)
|
|
- Content Service (Kafka 구독)
|
|
- Distribution Service (동기 호출)
|
|
- Kafka (Event Topics + Job Topics)
|
|
- Redis Cache
|
|
- Event DB
|
|
- 외부 API (AI API, 이미지 생성 API, 배포 채널 APIs)
|
|
|
|
**핵심 기능**:
|
|
1. **이벤트 목적 선택** (동기)
|
|
- Event DB에 목적 저장
|
|
- EventCreated 이벤트 발행
|
|
|
|
2. **AI 이벤트 추천** (비동기)
|
|
- Kafka ai-job 토픽 발행
|
|
- AI Service 구독 및 처리
|
|
- Polling 패턴으로 Job 상태 확인 (최대 30초)
|
|
- Redis 캐싱 (TTL 24시간)
|
|
|
|
3. **SNS 이미지 생성** (비동기)
|
|
- Kafka image-job 토픽 발행
|
|
- Content Service 구독 및 처리
|
|
- Polling 패턴으로 Job 상태 확인 (최대 20초)
|
|
- CDN 업로드 및 Redis 캐싱 (TTL 7일)
|
|
|
|
4. **최종 승인 및 배포** (동기)
|
|
- Distribution Service REST API 직접 호출
|
|
- 다중 채널 병렬 배포 (1분 이내)
|
|
- DistributionCompleted 이벤트 발행
|
|
|
|
**Resilience 패턴**:
|
|
- Circuit Breaker: 모든 외부 API 호출 시 적용
|
|
- Retry: 최대 3회 재시도 (지수 백오프)
|
|
- Timeout: AI API 30초, 이미지 API 20초, 배포 API 10초
|
|
- Bulkhead: 채널별 스레드 풀 격리
|
|
- Fallback: AI 추천 시 캐시된 이전 결과, 이미지 생성 시 기본 템플릿
|
|
|
|
---
|
|
|
|
### 3. 고객 참여 플로우
|
|
**파일**: `고객참여플로우.puml`
|
|
|
|
**포함된 유저스토리**:
|
|
- UFR-PART-010: 이벤트 참여
|
|
- UFR-PART-030: 당첨자 추첨
|
|
|
|
**주요 참여자**:
|
|
- Frontend (고객용 / 사장님용)
|
|
- API Gateway
|
|
- Participation Service
|
|
- Kafka (Event Topics)
|
|
- Participation DB
|
|
- Analytics Service (이벤트 구독)
|
|
|
|
**핵심 기능**:
|
|
1. **이벤트 참여**
|
|
- 중복 참여 체크 (전화번호 기반)
|
|
- 응모 번호 발급
|
|
- ParticipantRegistered 이벤트 발행 → Analytics Service 구독
|
|
|
|
2. **당첨자 추첨**
|
|
- 난수 기반 무작위 추첨 (Crypto.randomBytes)
|
|
- Fisher-Yates Shuffle 알고리즘
|
|
- 매장 방문 고객 가산점 적용 (선택 옵션)
|
|
- WinnerSelected 이벤트 발행
|
|
|
|
**Event-Driven 특징**:
|
|
- Analytics Service가 ParticipantRegistered 이벤트 구독하여 실시간 통계 업데이트
|
|
- 서비스 간 직접 의존성 없이 이벤트로 느슨한 결합
|
|
|
|
---
|
|
|
|
### 4. 성과 분석 플로우
|
|
**파일**: `성과분석플로우.puml`
|
|
|
|
**포함된 유저스토리**:
|
|
- UFR-ANAL-010: 실시간 성과분석 대시보드 조회
|
|
|
|
**주요 참여자**:
|
|
- Frontend
|
|
- API Gateway
|
|
- Analytics Service
|
|
- Redis Cache (TTL 5분)
|
|
- Analytics DB
|
|
- Kafka (Event Topics 구독)
|
|
- 외부 API (우리동네TV, 지니TV, SNS APIs)
|
|
|
|
**핵심 기능**:
|
|
1. **대시보드 조회 - Cache HIT** (0.5초)
|
|
- Redis에서 캐시된 데이터 즉시 반환
|
|
- 히트율 목표: 95%
|
|
|
|
2. **대시보드 조회 - Cache MISS** (3초)
|
|
- Analytics DB 로컬 데이터 조회
|
|
- 외부 채널 API 병렬 호출 (Circuit Breaker 적용)
|
|
- 데이터 통합 및 ROI 계산
|
|
- Redis 캐싱 (TTL 5분)
|
|
|
|
3. **실시간 업데이트 (Background)**
|
|
- EventCreated 구독: 이벤트 기본 정보 초기화
|
|
- ParticipantRegistered 구독: 참여자 수 실시간 증가
|
|
- DistributionCompleted 구독: 배포 채널 통계 업데이트
|
|
|
|
**Resilience 패턴**:
|
|
- Circuit Breaker: 외부 채널 API 조회 시 (실패율 50% 초과 시 Open)
|
|
- Timeout: 10초
|
|
- Fallback: 캐시된 이전 데이터 반환 또는 기본값 설정
|
|
- 병렬 처리: 외부 채널 API 동시 호출
|
|
|
|
---
|
|
|
|
## 설계 특징
|
|
|
|
### 1. Event-Driven 아키텍처
|
|
- **Kafka 통합**: Event Topics와 Job Topics를 Kafka로 통합
|
|
- **느슨한 결합**: 서비스 간 직접 의존성 제거
|
|
- **장애 격리**: 한 서비스 장애가 다른 서비스에 영향 없음
|
|
- **확장 용이**: 새로운 구독자 추가로 기능 확장
|
|
|
|
### 2. 비동기 처리 패턴
|
|
- **Kafka Job Topics**: ai-job, image-job
|
|
- **Polling 패턴**: Job 상태 확인 (2-5초 간격)
|
|
- **처리 시간**: AI 추천 10초, 이미지 생성 5초
|
|
|
|
### 3. 동기 처리 패턴
|
|
- **Distribution Service**: REST API 직접 호출
|
|
- **다중 채널 배포**: 병렬 처리 (1분 이내)
|
|
- **Circuit Breaker**: 장애 전파 방지
|
|
|
|
### 4. Resilience 패턴 전면 적용
|
|
- **Circuit Breaker**: 모든 외부 API 호출
|
|
- **Retry**: 일시적 장애 자동 복구
|
|
- **Timeout**: 응답 시간 제한
|
|
- **Bulkhead**: 리소스 격리
|
|
- **Fallback**: 장애 시 대체 로직
|
|
|
|
### 5. Cache-Aside 패턴
|
|
- **Redis 캐싱**: 성능 최적화
|
|
- **TTL 설정**: 데이터 유효성 관리
|
|
- **히트율 목표**: 80-95%
|
|
- **응답 시간 개선**: 90-99%
|
|
|
|
---
|
|
|
|
## 파일 구조
|
|
|
|
```
|
|
design/backend/sequence/outer/
|
|
├── README.md (본 문서)
|
|
├── 사용자인증플로우.puml
|
|
├── 이벤트생성플로우.puml
|
|
├── 고객참여플로우.puml
|
|
└── 성과분석플로우.puml
|
|
```
|
|
|
|
---
|
|
|
|
## 다이어그램 확인 방법
|
|
|
|
### 1. Online PlantUML Viewer
|
|
1. https://www.plantuml.com/plantuml/uml 접속
|
|
2. `.puml` 파일 내용 붙여넣기
|
|
3. 다이어그램 시각적 확인
|
|
|
|
### 2. VSCode Extension
|
|
1. "PlantUML" 확장 프로그램 설치
|
|
2. `.puml` 파일 열기
|
|
3. `Alt+D` 또는 `Cmd+D`로 미리보기
|
|
|
|
### 3. IntelliJ IDEA Plugin
|
|
1. "PlantUML integration" 플러그인 설치
|
|
2. `.puml` 파일 열기
|
|
3. 우측 미리보기 패널에서 확인
|
|
|
|
---
|
|
|
|
## 주요 결정사항
|
|
|
|
1. **Kafka 통합**: Event Bus와 Job Queue를 Kafka로 통합하여 운영 복잡도 감소
|
|
2. **비동기 처리**: AI 추천 및 이미지 생성은 Kafka Job Topics를 통한 비동기 처리
|
|
3. **동기 배포**: Distribution Service는 REST API 직접 호출하여 동기 처리 (1분 이내)
|
|
4. **Resilience 패턴**: 모든 외부 API 호출 시 Circuit Breaker, Retry, Timeout, Fallback 적용
|
|
5. **Cache-Aside 패턴**: Redis 캐싱으로 응답 시간 90-99% 개선
|
|
6. **Event Topics**: EventCreated, ParticipantRegistered, WinnerSelected, DistributionCompleted
|
|
7. **Job Topics**: ai-job, image-job
|
|
|
|
---
|
|
|
|
## 검증 사항
|
|
|
|
### 1. 유저스토리 매칭
|
|
✅ 모든 유저스토리가 외부 시퀀스에 정확히 반영됨
|
|
- User 서비스: 4개 유저스토리
|
|
- Event 서비스: 4개 유저스토리
|
|
- Participation 서비스: 2개 유저스토리
|
|
- Analytics 서비스: 1개 유저스토리
|
|
|
|
### 2. 논리 아키텍처 일치성
|
|
✅ 논리 아키텍처의 모든 컴포넌트와 통신 패턴 반영
|
|
- Core Services: User, Event, Participation, Analytics
|
|
- Async Services: AI, Content, Distribution
|
|
- Kafka: Event Topics + Job Topics
|
|
- External Systems: 국세청 API, AI API, 이미지 생성 API, 배포 채널 APIs
|
|
|
|
### 3. Resilience 패턴 적용
|
|
✅ 모든 외부 API 호출에 Resilience 패턴 적용
|
|
- Circuit Breaker, Retry, Timeout, Bulkhead, Fallback
|
|
|
|
### 4. PlantUML 문법 검증
|
|
✅ PlantUML 기본 문법 검증 완료
|
|
- `!theme mono` 적용
|
|
- 동기/비동기 화살표 구분
|
|
- 한글 설명 추가
|
|
- 참여자 및 플로우 명확히 표현
|
|
|
|
---
|
|
|
|
## 향후 개선 방안
|
|
|
|
1. **WebSocket 기반 실시간 푸시**: 대시보드 실시간 업데이트 (폴링 대체)
|
|
2. **Saga 패턴 적용**: 복잡한 분산 트랜잭션 보상 로직 체계화
|
|
3. **Service Mesh 도입**: Istio를 통한 서비스 간 통신 관찰성 및 보안 강화
|
|
4. **Dead Letter Queue 고도화**: 실패 이벤트 재처리 및 알림 자동화
|
|
|
|
---
|
|
|
|
**문서 버전**: 1.0
|
|
**최종 수정일**: 2025-10-22
|
|
**작성자**: System Architect
|