# Event Service API 매핑표

## 문서 정보
- **작성일**: 2025-10-24
- **버전**: 1.0
- **작성자**: Event Service Team
- **관련 문서**:
  - [API 설계서](../../design/backend/api/API-설계서.md)
  - [Event Service OpenAPI](../../design/backend/api/event-service-api.yaml)

---

## 1. 매핑 현황 요약

### 구현 현황
- **설계된 API**: 14개
- **구현된 API**: 7개 (50.0%)
- **미구현 API**: 7개 (50.0%)

### 구현률 세부
| 카테고리 | 설계 | 구현 | 미구현 | 구현률 |
|---------|------|------|--------|--------|
| Dashboard & Event List | 2 | 2 | 0 | 100% |
| Event Creation Flow | 8 | 1 | 7 | 12.5% |
| Event Management | 3 | 3 | 0 | 100% |
| Job Status | 1 | 1 | 0 | 100% |

---

## 2. 상세 매핑표

### 2.1 Dashboard & Event List (구현률 100%)

| 설계서 API | Controller | 메서드 | 경로 | 구현 여부 | 비고 |
|-----------|-----------|--------|------|----------|------|
| 이벤트 목록 조회 | EventController | GET | /api/events | ✅ 구현 | EventController:84 |
| 이벤트 상세 조회 | EventController | GET | /api/events/{eventId} | ✅ 구현 | EventController:130 |

---

### 2.2 Event Creation Flow (구현률 12.5%)

#### Step 1: 이벤트 목적 선택
| 설계서 API | Controller | 메서드 | 경로 | 구현 여부 | 비고 |
|-----------|-----------|--------|------|----------|------|
| 이벤트 목적 선택 | EventController | POST | /api/events/objectives | ✅ 구현 | EventController:52 |

#### Step 2: AI 추천 (미구현)
| 설계서 API | Controller | 메서드 | 경로 | 구현 여부 | 미구현 이유 |
|-----------|-----------|--------|------|----------|-----------|
| AI 추천 요청 | - | POST | /api/events/{eventId}/ai-recommendations | ❌ 미구현 | AI Service 연동 필요 |
| AI 추천 선택 | - | PUT | /api/events/{eventId}/recommendations | ❌ 미구현 | AI Service 연동 필요 |

**미구현 상세 이유**:
- Kafka Topic `ai-event-generation-job` 발행 로직 필요
- AI Service와의 연동이 선행되어야 함
- Redis에서 AI 추천 결과를 읽어오는 로직 필요
- 현재 단계에서는 이벤트 생명주기 관리에 집중

#### Step 3: 이미지 생성 (미구현)
| 설계서 API | Controller | 메서드 | 경로 | 구현 여부 | 미구현 이유 |
|-----------|-----------|--------|------|----------|-----------|
| 이미지 생성 요청 | - | POST | /api/events/{eventId}/images | ❌ 미구현 | Content Service 연동 필요 |
| 이미지 선택 | - | PUT | /api/events/{eventId}/images/{imageId}/select | ❌ 미구현 | Content Service 연동 필요 |
| 이미지 편집 | - | PUT | /api/events/{eventId}/images/{imageId}/edit | ❌ 미구현 | Content Service 연동 필요 |

**미구현 상세 이유**:
- Kafka Topic `image-generation-job` 발행 로직 필요
- Content Service와의 연동이 선행되어야 함
- Redis에서 생성된 이미지 URL을 읽어오는 로직 필요
- 이미지 편집은 Content Service의 이미지 재생성 API와 연동 필요

#### Step 4: 배포 채널 선택 (미구현)
| 설계서 API | Controller | 메서드 | 경로 | 구현 여부 | 미구현 이유 |
|-----------|-----------|--------|------|----------|-----------|
| 배포 채널 선택 | - | PUT | /api/events/{eventId}/channels | ❌ 미구현 | Distribution Service 연동 필요 |

**미구현 상세 이유**:
- Distribution Service의 채널 목록 검증 로직 필요
- Event 엔티티의 channels 필드 업데이트 로직은 구현 가능하나, 채널별 검증은 Distribution Service 개발 후 추가 예정

#### Step 5: 최종 승인 및 배포
| 설계서 API | Controller | 메서드 | 경로 | 구현 여부 | 비고 |
|-----------|-----------|--------|------|----------|------|
| 최종 승인 및 배포 | EventController | POST | /api/events/{eventId}/publish | ✅ 구현 | EventController:172 |

**구현 내용**:
- 이벤트 상태를 DRAFT → PUBLISHED로 변경
- Distribution Service 동기 호출은 추후 추가 예정
- 현재는 상태 변경만 처리

---

### 2.3 Event Management (구현률 100%)

| 설계서 API | Controller | 메서드 | 경로 | 구현 여부 | 비고 |
|-----------|-----------|--------|------|----------|------|
| 이벤트 수정 | - | PUT | /api/events/{eventId} | ❌ 미구현 | 이유는 아래 참조 |
| 이벤트 삭제 | EventController | DELETE | /api/events/{eventId} | ✅ 구현 | EventController:151 |
| 이벤트 조기 종료 | EventController | POST | /api/events/{eventId}/end | ✅ 구현 | EventController:193 |

**이벤트 수정 API 미구현 이유**:
- 이벤트 수정은 여러 단계의 데이터를 수정하는 복잡한 로직
- AI 추천 재선택, 이미지 재생성 등 다른 서비스와의 연동이 필요
- 우선순위: 신규 이벤트 생성 플로우 완성 후 구현 예정
- 현재는 DRAFT 상태에서만 삭제 가능하므로 수정 대신 삭제 후 재생성 가능

---

### 2.4 Job Status (구현률 100%)

| 설계서 API | Controller | 메서드 | 경로 | 구현 여부 | 비고 |
|-----------|-----------|--------|------|----------|------|
| Job 상태 폴링 | JobController | GET | /api/jobs/{jobId} | ✅ 구현 | JobController:42 |

---

## 3. 구현된 API 상세

### 3.1 EventController (6개 API)

#### 1. POST /api/events/objectives
- **설명**: 이벤트 생성의 첫 단계로 목적을 선택
- **유저스토리**: UFR-EVENT-020
- **요청**: SelectObjectiveRequest (objective)
- **응답**: EventCreatedResponse (eventId, status, objective, createdAt)
- **비즈니스 로직**:
  - Long userId/storeId를 UUID로 변환하여 Event 엔티티 생성
  - 초기 상태는 DRAFT
  - EventService.createEvent() 호출

#### 2. GET /api/events
- **설명**: 사용자의 이벤트 목록 조회 (페이징, 필터링, 정렬)
- **유저스토리**: UFR-EVENT-010, UFR-EVENT-070
- **요청 파라미터**:
  - status (EventStatus, 선택)
  - search (String, 선택)
  - objective (String, 선택)
  - page, size, sort, order (페이징/정렬)
- **응답**: PageResponse<EventDetailResponse>
- **비즈니스 로직**:
  - Long userId를 UUID로 변환
  - Repository에서 필터링 및 페이징 처리
  - EventService.getEvents() 호출

#### 3. GET /api/events/{eventId}
- **설명**: 특정 이벤트의 상세 정보 조회
- **유저스토리**: UFR-EVENT-060
- **요청**: eventId (UUID)
- **응답**: EventDetailResponse (이벤트 정보 + 생성된 이미지 + AI 추천)
- **비즈니스 로직**:
  - Long userId를 UUID로 변환
  - 사용자 소유 이벤트만 조회 가능 (보안)
  - EventService.getEvent() 호출

#### 4. DELETE /api/events/{eventId}
- **설명**: 이벤트 삭제 (DRAFT 상태만 가능)
- **유저스토리**: UFR-EVENT-070
- **요청**: eventId (UUID)
- **응답**: ApiResponse<Void>
- **비즈니스 로직**:
  - DRAFT 상태만 삭제 가능 검증 (Event.isDeletable())
  - 다른 상태(PUBLISHED, ENDED)는 삭제 불가
  - EventService.deleteEvent() 호출

#### 5. POST /api/events/{eventId}/publish
- **설명**: 이벤트 배포 (DRAFT → PUBLISHED)
- **유저스토리**: UFR-EVENT-050
- **요청**: eventId (UUID)
- **응답**: ApiResponse<Void>
- **비즈니스 로직**:
  - Event.publish() 메서드로 상태 전환
  - Distribution Service 호출은 추후 추가 예정
  - EventService.publishEvent() 호출

#### 6. POST /api/events/{eventId}/end
- **설명**: 이벤트 조기 종료 (PUBLISHED → ENDED)
- **유저스토리**: UFR-EVENT-060
- **요청**: eventId (UUID)
- **응답**: ApiResponse<Void>
- **비즈니스 로직**:
  - Event.end() 메서드로 상태 전환
  - PUBLISHED 상태만 종료 가능
  - EventService.endEvent() 호출

---

### 3.2 JobController (1개 API)

#### 1. GET /api/jobs/{jobId}
- **설명**: 비동기 작업의 상태를 조회 (폴링 방식)
- **유저스토리**: UFR-EVENT-030, UFR-CONT-010
- **요청**: jobId (UUID)
- **응답**: JobStatusResponse (jobId, jobType, status, progress, resultKey, errorMessage)
- **비즈니스 로직**:
  - Job 엔티티 조회
  - 상태: PENDING, PROCESSING, COMPLETED, FAILED
  - JobService.getJobStatus() 호출

---

## 4. 미구현 API 개발 계획

### 4.1 우선순위 1 (AI Service 연동)
- **POST /api/events/{eventId}/ai-recommendations** - AI 추천 요청
- **PUT /api/events/{eventId}/recommendations** - AI 추천 선택

**개발 선행 조건**:
1. AI Service 개발 완료
2. Kafka Topic `ai-event-generation-job` 설정
3. Redis 캐시 연동 구현

---

### 4.2 우선순위 2 (Content Service 연동)
- **POST /api/events/{eventId}/images** - 이미지 생성 요청
- **PUT /api/events/{eventId}/images/{imageId}/select** - 이미지 선택
- **PUT /api/events/{eventId}/images/{imageId}/edit** - 이미지 편집

**개발 선행 조건**:
1. Content Service 개발 완료
2. Kafka Topic `image-generation-job` 설정
3. Redis 캐시 연동 구현
4. CDN (Azure Blob Storage) 연동

---

### 4.3 우선순위 3 (Distribution Service 연동)
- **PUT /api/events/{eventId}/channels** - 배포 채널 선택

**개발 선행 조건**:
1. Distribution Service 개발 완료
2. 채널별 검증 로직 구현
3. POST /api/events/{eventId}/publish API에 Distribution Service 동기 호출 추가

---

### 4.4 우선순위 4 (이벤트 수정)
- **PUT /api/events/{eventId}** - 이벤트 수정

**개발 선행 조건**:
1. 우선순위 1~3 API 모두 구현 완료
2. 이벤트 수정 범위 정의 (이름/설명/날짜만 수정 vs 전체 재생성)
3. 각 단계별 수정 로직 설계

---

## 5. 추가 구현된 API (설계서에 없음)

현재 추가 구현된 API는 없습니다. 모든 구현은 설계서를 기준으로 진행되었습니다.

---

## 6. 다음 단계

### 6.1 즉시 가능한 작업
1. **서버 시작 테스트**:
   - PostgreSQL 연결 확인
   - Swagger UI 접근 테스트 (http://localhost:8081/swagger-ui.html)

2. **구현된 API 테스트**:
   - POST /api/events/objectives
   - GET /api/events
   - GET /api/events/{eventId}
   - DELETE /api/events/{eventId}
   - POST /api/events/{eventId}/publish
   - POST /api/events/{eventId}/end
   - GET /api/jobs/{jobId}

### 6.2 후속 개발 필요
1. AI Service 개발 완료 → AI 추천 API 구현
2. Content Service 개발 완료 → 이미지 관련 API 구현
3. Distribution Service 개발 완료 → 배포 채널 선택 API 구현
4. 전체 서비스 연동 → 이벤트 수정 API 구현

---

## 부록

### A. 개발 우선순위 결정 근거

**현재 구현 범위 선정 이유**:
1. **핵심 생명주기 먼저**: 이벤트 생성, 조회, 삭제, 상태 변경
2. **서비스 독립성**: 다른 서비스 없이도 Event Service 단독 테스트 가능
3. **점진적 통합**: 각 서비스 개발 완료 시점에 순차적 통합
4. **리스크 최소화**: 복잡한 서비스 간 연동은 각 서비스 안정화 후 진행

---

**문서 버전**: 1.0
**최종 수정일**: 2025-10-24
**작성자**: Event Service Team