kt-event-marketing/develop/dev/event-api-mapping.md

# Event Service API 매핑표

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

---

## 1. 매핑 현황 요약

### 구현 현황
- **설계된 API**: 14개
- **구현된 API**: 9개 (64.3%)
- **미구현 API**: 5개 (35.7%)

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

---

## 2. 상세 매핑표

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

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

---

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

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

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

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

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

**구현 내용**:
- **이미지 생성 요청**: Kafka Topic `image-generation-job`에 메시지 발행, Job ID 반환
- **이미지 선택**: 사용자가 생성된 이미지 중 하나를 선택하여 이벤트에 연결

**미구현 상세 이유 (이미지 편집)**:
- Content Service의 이미지 재생성 API와 연동 필요
- 편집된 이미지를 다시 생성하고 CDN에 업로드하는 로직 필요

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

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

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

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

---

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

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

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

---

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

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

---

## 3. 구현된 API 상세

### 3.1 EventController (8개 API)

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

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

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

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

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

#### 7. POST /api/v1/events/{eventId}/images
- **설명**: AI를 통해 이벤트 이미지를 생성 요청
- **유저스토리**: UFR-CONT-010
- **요청**: ImageGenerationRequest (prompt, style, count)
- **응답**: ImageGenerationResponse (jobId)
- **비즈니스 로직**:
  - Kafka Topic `image-generation-job`에 메시지 발행
  - 비동기 작업을 위한 Job 엔티티 생성 및 반환
  - EventService.requestImageGeneration() 호출

#### 8. PUT /api/v1/events/{eventId}/images/{imageId}/select
- **설명**: 생성된 이미지 중 하나를 선택
- **유저스토리**: UFR-CONT-020
- **요청**: SelectImageRequest (imageId)
- **응답**: ApiResponse<Void>
- **비즈니스 로직**:
  - 선택한 이미지를 이벤트에 연결
  - 이미지 URL을 Event 엔티티에 저장
  - EventService.selectImage() 호출

---

### 3.2 JobController (1개 API)

#### 1. GET /api/v1/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/v1/events/{eventId}/ai-recommendations** - AI 추천 요청
- **PUT /api/v1/events/{eventId}/recommendations** - AI 추천 선택

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

---

### 4.2 우선순위 2 (Content Service 연동)
- **PUT /api/v1/events/{eventId}/images/{imageId}/edit** - 이미지 편집

**개발 선행 조건**:
1. Content Service 개발 완료
2. 이미지 재생성 API 구현

**참고**: 이미지 생성 요청과 이미지 선택 API는 이미 구현 완료

---

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

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

---

### 4.4 우선순위 4 (이벤트 수정)
- **PUT /api/v1/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/v1/events/objectives
   - GET /api/v1/events
   - GET /api/v1/events/{eventId}
   - DELETE /api/v1/events/{eventId}
   - POST /api/v1/events/{eventId}/publish
   - POST /api/v1/events/{eventId}/end
   - POST /api/v1/events/{eventId}/images
   - PUT /api/v1/events/{eventId}/images/{imageId}/select
   - GET /api/v1/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.1
**최종 수정일**: 2025-10-27
**작성자**: Event Service Team

---

## 변경 이력

### v1.1 (2025-10-27)
- **구현 현황 업데이트**: 7개 → 9개 API (64.3% 구현)
- **신규 구현 API 추가**:
  - POST /api/v1/events/{eventId}/images - 이미지 생성 요청
  - PUT /api/v1/events/{eventId}/images/{imageId}/select - 이미지 선택
- **API 경로 수정**: /api/events → /api/v1/events (버전 명시)
- **구현률 재계산**:
  - Event Creation Flow: 12.5% → 37.5%
  - Event Management: 100% → 66.7% (이벤트 수정 미구현 반영)
- **미구현 API 계획 업데이트**: Content Service 연동 우선순위 조정

### v1.0 (2025-10-24)
- 초기 문서 작성