264 lines
9.3 KiB
Markdown
264 lines
9.3 KiB
Markdown
# Event Service - 내부 시퀀스 설계 완료
|
|
|
|
## 문서 정보
|
|
- **작성일**: 2025-10-22
|
|
- **작성자**: System Architect
|
|
- **관련 문서**:
|
|
- [유저스토리](../../../userstory.md)
|
|
- [외부 시퀀스 - 이벤트생성플로우](../outer/이벤트생성플로우.puml)
|
|
- [논리 아키텍처](../../logical/logical-architecture.md)
|
|
|
|
---
|
|
|
|
## 작성 완료 시나리오 (10개)
|
|
|
|
### 1. event-목적선택.puml
|
|
- **유저스토리**: UFR-EVENT-020
|
|
- **기능**: 이벤트 목적 선택 및 저장
|
|
- **주요 흐름**:
|
|
- POST /api/events/purposes
|
|
- EventService → EventRepository → Event DB 저장
|
|
- Redis 캐시 저장 (TTL 30분)
|
|
- Kafka EventCreated 이벤트 발행
|
|
- **특징**: 캐시 히트 시 DB 조회 생략
|
|
|
|
### 2. event-AI추천요청.puml
|
|
- **유저스토리**: UFR-EVENT-030
|
|
- **기능**: AI 추천 요청 (Kafka Job 발행)
|
|
- **주요 흐름**:
|
|
- POST /api/events/{id}/ai-recommendations
|
|
- EventService → JobService
|
|
- Kafka ai-job 토픽 발행
|
|
- Job ID 즉시 반환 (202 Accepted)
|
|
- **특징**: 비동기 처리, AI Service는 백그라운드에서 Kafka 구독
|
|
|
|
### 3. event-추천결과조회.puml
|
|
- **유저스토리**: UFR-EVENT-030 (결과 조회)
|
|
- **기능**: AI 추천 결과 폴링 조회
|
|
- **주요 흐름**:
|
|
- GET /api/jobs/{jobId}/status
|
|
- JobService → Redis 캐시 조회
|
|
- Job 상태에 따라 응답 (COMPLETED/PROCESSING/FAILED)
|
|
- **특징**: 최대 30초 동안 폴링 (2초 간격)
|
|
|
|
### 4. event-이미지생성요청.puml
|
|
- **유저스토리**: UFR-CONT-010
|
|
- **기능**: 이미지 생성 요청 (Kafka Job 발행)
|
|
- **주요 흐름**:
|
|
- POST /api/events/{id}/content-generation
|
|
- EventService → JobService
|
|
- Kafka image-job 토픽 발행
|
|
- Job ID 즉시 반환 (202 Accepted)
|
|
- **특징**: Content Service는 백그라운드에서 3가지 스타일 생성
|
|
|
|
### 5. event-이미지결과조회.puml
|
|
- **유저스토리**: UFR-CONT-010 (결과 조회)
|
|
- **기능**: 이미지 생성 결과 폴링 조회
|
|
- **주요 흐름**:
|
|
- GET /api/jobs/{jobId}/status
|
|
- JobService → Redis 캐시 조회
|
|
- 완료 시 3가지 스타일 이미지 URL 반환
|
|
- **특징**: 최대 30초 동안 폴링 (3초 간격)
|
|
|
|
### 6. event-콘텐츠선택.puml
|
|
- **유저스토리**: UFR-CONT-020
|
|
- **기능**: 선택한 콘텐츠 저장
|
|
- **주요 흐름**:
|
|
- PUT /api/events/drafts/{id}/content
|
|
- EventService → EventRepository
|
|
- 선택한 이미지 URL 및 편집 내용 저장
|
|
- 캐시 무효화
|
|
- **특징**: 텍스트, 색상 편집 내용 적용
|
|
|
|
### 7. event-최종승인및배포.puml
|
|
- **유저스토리**: UFR-EVENT-050
|
|
- **기능**: 최종 승인 및 Distribution Service 동기 호출
|
|
- **주요 흐름**:
|
|
- POST /api/events/{id}/publish
|
|
- 이벤트 상태 변경 (DRAFT → APPROVED)
|
|
- Kafka EventCreated 이벤트 발행
|
|
- Distribution Service 동기 호출 (POST /api/distribution/distribute)
|
|
- 배포 완료 후 상태 변경 (APPROVED → ACTIVE)
|
|
- **특징**: Circuit Breaker 적용, Timeout 70초
|
|
|
|
### 8. event-상세조회.puml
|
|
- **유저스토리**: UFR-EVENT-060
|
|
- **기능**: 이벤트 상세 정보 조회
|
|
- **주요 흐름**:
|
|
- GET /api/events/{id}
|
|
- Redis 캐시 확인 (TTL 5분)
|
|
- 캐시 미스 시 DB 조회 (JOIN으로 경품, 배포 이력 포함)
|
|
- 사용자 권한 검증
|
|
- **특징**: JOIN 쿼리로 관련 데이터 한 번에 조회
|
|
|
|
### 9. event-목록조회.puml
|
|
- **유저스토리**: UFR-EVENT-070
|
|
- **기능**: 이벤트 목록 조회 (필터/검색)
|
|
- **주요 흐름**:
|
|
- GET /api/events?status={status}&keyword={keyword}
|
|
- Redis 캐시 확인 (TTL 1분)
|
|
- 캐시 미스 시 DB 조회 (필터/검색 조건 적용)
|
|
- 페이지네이션 (20개/페이지)
|
|
- **특징**: 인덱스 활용 (user_id, status, created_at)
|
|
|
|
### 10. event-대시보드조회.puml
|
|
- **유저스토리**: UFR-EVENT-010
|
|
- **기능**: 대시보드 이벤트 목록
|
|
- **주요 흐름**:
|
|
- GET /api/events/dashboard
|
|
- Redis 캐시 확인 (TTL 1분)
|
|
- 캐시 미스 시 병렬 조회 (진행중/예정/종료)
|
|
- 각 섹션 최대 5개 표시
|
|
- **특징**: 병렬 쿼리로 성능 최적화
|
|
|
|
---
|
|
|
|
## 설계 원칙 준수 사항
|
|
|
|
### 1. 공통설계원칙 준수
|
|
- ✅ 모든 레이어 표시 (Controller → Service → Repository)
|
|
- ✅ 외부 시스템/인프라 `<<E>>` 표시
|
|
- ✅ 캐시 접근 명시 (Redis)
|
|
- ✅ DB 접근 명시 (PostgreSQL)
|
|
- ✅ Kafka 이벤트/Job 발행 표시
|
|
|
|
### 2. 내부시퀀스설계 가이드 준수
|
|
- ✅ 각 시나리오별 독립 파일 생성
|
|
- ✅ PlantUML `!theme mono` 적용
|
|
- ✅ 명확한 타이틀 (서비스명 + 시나리오 + 유저스토리)
|
|
- ✅ 참여자 타입 표시 (<<C>>, <<S>>, <<R>>, <<E>>)
|
|
- ✅ 데이터베이스 쿼리 표시
|
|
- ✅ 캐싱 전략 표시 (Cache-Aside)
|
|
- ✅ 비동기 처리 흐름 표시 (Kafka)
|
|
|
|
### 3. Event-Driven 아키텍처 반영
|
|
- ✅ Kafka Event Topics 발행 (EventCreated)
|
|
- ✅ Kafka Job Topics 발행 (ai-job, image-job)
|
|
- ✅ 비동기 작업 Job ID 즉시 반환 (202 Accepted)
|
|
- ✅ 폴링 방식 결과 조회 (GET /api/jobs/{jobId}/status)
|
|
|
|
### 4. Resilience 패턴 명시
|
|
- ✅ Circuit Breaker 적용 표시 (Distribution Service 호출)
|
|
- ✅ Timeout 설정 표시 (70초)
|
|
- ✅ 캐싱 전략 표시 (TTL 설정)
|
|
|
|
---
|
|
|
|
## 검증 체크리스트
|
|
|
|
### 유저스토리 매칭
|
|
- [x] UFR-EVENT-010: 대시보드 이벤트 목록 → event-대시보드조회.puml
|
|
- [x] UFR-EVENT-020: 이벤트 목적 선택 → event-목적선택.puml
|
|
- [x] UFR-EVENT-030: AI 이벤트 추천 → event-AI추천요청.puml, event-추천결과조회.puml
|
|
- [x] UFR-EVENT-040: 배포 채널 선택 → (최종승인에 포함)
|
|
- [x] UFR-EVENT-050: 최종 승인 및 배포 → event-최종승인및배포.puml
|
|
- [x] UFR-EVENT-060: 이벤트 상세 조회 → event-상세조회.puml
|
|
- [x] UFR-EVENT-070: 이벤트 목록 관리 → event-목록조회.puml
|
|
- [x] UFR-CONT-010: SNS 이미지 생성 → event-이미지생성요청.puml, event-이미지결과조회.puml
|
|
- [x] UFR-CONT-020: 콘텐츠 편집 → event-콘텐츠선택.puml
|
|
|
|
### 외부 시퀀스 일치성
|
|
- [x] Kafka Job 발행 (AI 추천) - ai-job 토픽
|
|
- [x] Kafka Job 발행 (이미지 생성) - image-job 토픽
|
|
- [x] Kafka Event 발행 (EventCreated) - event-topic
|
|
- [x] Distribution Service 동기 호출 (REST API)
|
|
- [x] Redis 캐싱 전략 (Cache-Aside)
|
|
- [x] Job 폴링 방식 (5초 간격 AI, 3초 간격 이미지)
|
|
|
|
### 논리 아키텍처 일치성
|
|
- [x] Event Service 책임 범위
|
|
- [x] Kafka 통합 메시징 플랫폼
|
|
- [x] Redis 캐시 키 패턴
|
|
- [x] Database-per-Service 원칙
|
|
- [x] Resilience 패턴 적용
|
|
|
|
---
|
|
|
|
## 파일 위치
|
|
|
|
```
|
|
design/backend/sequence/inner/
|
|
├── event-목적선택.puml
|
|
├── event-AI추천요청.puml
|
|
├── event-추천결과조회.puml
|
|
├── event-이미지생성요청.puml
|
|
├── event-이미지결과조회.puml
|
|
├── event-콘텐츠선택.puml
|
|
├── event-최종승인및배포.puml
|
|
├── event-상세조회.puml
|
|
├── event-목록조회.puml
|
|
└── event-대시보드조회.puml
|
|
```
|
|
|
|
---
|
|
|
|
## 다이어그램 확인 방법
|
|
|
|
### PlantUML 렌더링
|
|
1. https://www.plantuml.com/plantuml/uml/ 접속
|
|
2. 각 `.puml` 파일 내용 붙여넣기
|
|
3. 다이어그램 시각적 확인
|
|
|
|
### 로컬 렌더링 (IntelliJ/VS Code)
|
|
- IntelliJ: PlantUML Integration 플러그인 설치
|
|
- VS Code: PlantUML 확장 설치
|
|
|
|
---
|
|
|
|
## 주요 설계 결정사항
|
|
|
|
### 1. 비동기 처리 전략
|
|
- **AI 추천**: Kafka ai-job 토픽 발행 → 비동기 처리 → Job 폴링
|
|
- **이미지 생성**: Kafka image-job 토픽 발행 → 비동기 처리 → Job 폴링
|
|
- **이유**: 장시간 작업 (10초, 5초)을 동기로 처리 시 사용자 경험 저하
|
|
|
|
### 2. 배포 동기 처리
|
|
- **Distribution Service**: REST API 동기 호출 (POST /api/distribution/distribute)
|
|
- **이유**: 배포 완료 여부를 즉시 확인하고 사용자에게 피드백 제공
|
|
- **Resilience**: Circuit Breaker + Timeout 70초
|
|
|
|
### 3. 캐싱 전략
|
|
- **목적 선택**: TTL 30분 (임시 저장 성격)
|
|
- **상세 조회**: TTL 5분 (자주 조회, 실시간성 중요)
|
|
- **목록/대시보드**: TTL 1분 (실시간 업데이트)
|
|
- **이유**: 조회 빈도와 실시간성 요구사항에 따라 차등 적용
|
|
|
|
### 4. Job 상태 관리
|
|
- **Redis 캐시**: Job 상태 및 결과 저장 (TTL 1시간)
|
|
- **폴링 방식**: 클라이언트가 주기적으로 Job 상태 확인
|
|
- **이유**: 간단한 구현, WebSocket 대비 낮은 복잡도
|
|
|
|
---
|
|
|
|
## 성능 최적화 포인트
|
|
|
|
### 1. 캐시 히트율
|
|
- 목적 선택: 90% 예상 (재방문 시 캐시 활용)
|
|
- 상세 조회: 95% 예상 (자주 조회)
|
|
- 목록/대시보드: 90% 예상 (1분 TTL로 대부분 캐시 활용)
|
|
|
|
### 2. 데이터베이스 최적화
|
|
- 인덱스: user_id, status, created_at
|
|
- JOIN 최적화: 상세 조회 시 관련 데이터 한 번에 조회
|
|
- 페이지네이션: 20개/페이지로 쿼리 부하 감소
|
|
|
|
### 3. 병렬 처리
|
|
- 대시보드 조회: 진행중/예정/종료 병렬 쿼리
|
|
- 이미지 생성: 3가지 스타일 병렬 생성 (Content Service에서)
|
|
|
|
---
|
|
|
|
## 향후 개선 방안
|
|
|
|
### Phase 2 이후
|
|
1. **WebSocket 실시간 푸시**: Job 폴링을 WebSocket으로 전환
|
|
2. **Event Sourcing**: 모든 상태 변경을 이벤트로 저장
|
|
3. **GraphQL**: 클라이언트 맞춤형 데이터 조회
|
|
4. **Database Read Replica**: 읽기 부하 분산
|
|
|
|
---
|
|
|
|
**문서 작성 완료일**: 2025-10-22
|
|
**작성자**: System Architect
|
|
**상태**: ✅ 완료 (10개 시나리오 모두 작성)
|