# 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개 시나리오 모두 작성)