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

# Event Service API 매핑표

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

---

## 1. 매핑 현황 요약

### 구현 현황
- **설계된 API**: 14개
- **구현된 API**: 14개 (100%) ✅
- **미구현 API**: 0개 (0%)

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

**🎉 모든 API 구현 완료!** Event Service의 설계된 14개 API가 모두 구현되었습니다.

---

## 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 (구현률 100% ✅)

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

#### Step 2: AI 추천 (구현률 100% ✅)
| 설계서 API | Controller | 메서드 | 경로 | 구현 여부 | 비고 |
|-----------|-----------|--------|------|----------|------|
| AI 추천 요청 | EventController | POST | /api/v1/events/{eventId}/ai-recommendations | ✅ 구현 | EventController:272 |
| AI 추천 선택 | EventController | PUT | /api/v1/events/{eventId}/recommendations | ✅ 구현 | EventController:300 |

**구현 내용**:
- **AI 추천 요청**: Kafka Topic `ai-event-generation-job`에 메시지 발행, Job ID 반환
- **AI 추천 선택**: 사용자가 AI 추천 중 하나를 선택하고 커스터마이징하여 이벤트에 적용

#### Step 3: 이미지 생성 (구현률 100% ✅)
| 설계서 API | Controller | 메서드 | 경로 | 구현 여부 | 비고 |
|-----------|-----------|--------|------|----------|------|
| 이미지 생성 요청 | EventController | POST | /api/v1/events/{eventId}/images | ✅ 구현 | EventController:214 |
| 이미지 선택 | EventController | PUT | /api/v1/events/{eventId}/images/{imageId}/select | ✅ 구현 | EventController:243 |
| 이미지 편집 | EventController | PUT | /api/v1/events/{eventId}/images/{imageId}/edit | ✅ 구현 | EventController:328 |

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

#### Step 4: 배포 채널 선택 (구현률 100% ✅)
| 설계서 API | Controller | 메서드 | 경로 | 구현 여부 | 비고 |
|-----------|-----------|--------|------|----------|------|
| 배포 채널 선택 | EventController | PUT | /api/v1/events/{eventId}/channels | ✅ 구현 | EventController:357 |

**구현 내용**:
- 이벤트를 배포할 채널(SMS, KakaoTalk, App Push 등)을 선택
- Distribution Service와의 연동은 추후 추가 예정

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

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

---

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

| 설계서 API | Controller | 메서드 | 경로 | 구현 여부 | 비고 |
|-----------|-----------|--------|------|----------|------|
| 이벤트 수정 | EventController | PUT | /api/v1/events/{eventId} | ✅ 구현 | EventController:384 |
| 이벤트 삭제 | EventController | DELETE | /api/v1/events/{eventId} | ✅ 구현 | EventController:150 |
| 이벤트 조기 종료 | EventController | POST | /api/v1/events/{eventId}/end | ✅ 구현 | EventController:192 |

**구현 내용**:
- **이벤트 수정**: 기존 이벤트의 정보를 수정합니다. DRAFT 상태만 수정 가능
- **이벤트 삭제**: DRAFT 상태의 이벤트만 삭제 가능
- **이벤트 조기 종료**: PUBLISHED 상태의 이벤트를 ENDED 상태로 변경

---

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

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

---

## 3. 구현된 API 상세

### 3.1 EventController (13개 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() 호출

#### 9. POST /api/v1/events/{eventId}/ai-recommendations
- **설명**: AI 서비스에 이벤트 추천 생성을 요청
- **유저스토리**: UFR-EVENT-030
- **요청**: AiRecommendationRequest (이벤트 컨텍스트 정보)
- **응답**: JobAcceptedResponse (jobId)
- **비즈니스 로직**:
  - Kafka Topic `ai-event-generation-job`에 메시지 발행
  - 비동기 작업을 위한 Job 엔티티 생성 및 반환
  - EventService.requestAiRecommendations() 호출

#### 10. PUT /api/v1/events/{eventId}/recommendations
- **설명**: AI가 생성한 추천 중 하나를 선택하고 커스터마이징
- **유저스토리**: UFR-EVENT-030
- **요청**: SelectRecommendationRequest (recommendationId, customizations)
- **응답**: ApiResponse<Void>
- **비즈니스 로직**:
  - 선택한 AI 추천을 이벤트에 적용
  - 사용자 커스터마이징 반영
  - EventService.selectRecommendation() 호출

#### 11. PUT /api/v1/events/{eventId}/images/{imageId}/edit
- **설명**: 선택된 이미지를 편집
- **유저스토리**: UFR-CONT-030
- **요청**: ImageEditRequest (editInstructions)
- **응답**: ImageEditResponse (editedImageUrl, jobId)
- **비즈니스 로직**:
  - Content Service와 연동하여 이미지 편집 요청
  - 편집된 이미지를 다시 생성하고 CDN에 업로드
  - EventService.editImage() 호출

#### 12. PUT /api/v1/events/{eventId}/channels
- **설명**: 이벤트를 배포할 채널을 선택
- **유저스토리**: UFR-EVENT-040
- **요청**: SelectChannelsRequest (channels: List<String>)
- **응답**: ApiResponse<Void>
- **비즈니스 로직**:
  - 배포 채널(SMS, KakaoTalk, App Push 등) 선택
  - Event 엔티티의 channels 필드 업데이트
  - EventService.selectChannels() 호출

#### 13. PUT /api/v1/events/{eventId}
- **설명**: 기존 이벤트의 정보를 수정
- **유저스토리**: UFR-EVENT-080
- **요청**: UpdateEventRequest (이벤트 수정 정보)
- **응답**: EventDetailResponse (수정된 이벤트 정보)
- **비즈니스 로직**:
  - DRAFT 상태의 이벤트만 수정 가능
  - 이벤트 기본 정보, AI 추천, 이미지, 채널 등 수정
  - EventService.updateEvent() 호출

---

### 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 (설계서에 없음)

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

---

## 5. 다음 단계

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

2. **구현된 전체 API 테스트** (14개):
   - POST /api/v1/events/objectives (이벤트 목적 선택)
   - GET /api/v1/events (이벤트 목록 조회)
   - GET /api/v1/events/{eventId} (이벤트 상세 조회)
   - DELETE /api/v1/events/{eventId} (이벤트 삭제)
   - PUT /api/v1/events/{eventId} (이벤트 수정)
   - POST /api/v1/events/{eventId}/ai-recommendations (AI 추천 요청)
   - PUT /api/v1/events/{eventId}/recommendations (AI 추천 선택)
   - POST /api/v1/events/{eventId}/images (이미지 생성 요청)
   - PUT /api/v1/events/{eventId}/images/{imageId}/select (이미지 선택)
   - PUT /api/v1/events/{eventId}/images/{imageId}/edit (이미지 편집)
   - PUT /api/v1/events/{eventId}/channels (배포 채널 선택)
   - POST /api/v1/events/{eventId}/publish (이벤트 배포)
   - POST /api/v1/events/{eventId}/end (이벤트 종료)
   - GET /api/v1/jobs/{jobId} (Job 상태 조회)

### 5.2 서비스 간 연동 완성 필요
1. **AI Service 연동**:
   - Kafka Consumer에서 `ai-event-generation-job` 처리
   - Redis를 통한 AI 추천 결과 캐싱
   - AI 추천 API 완전 통합 테스트

2. **Content Service 연동**:
   - 이미지 생성/편집 API 통합
   - CDN 업로드 로직 연동
   - 이미지 편집 API 완전 통합 테스트

3. **Distribution Service 연동**:
   - 배포 채널 검증 로직 추가
   - 이벤트 배포 시 Distribution Service 동기 호출
   - 채널별 배포 상태 추적

### 5.3 통합 테스트 시나리오
전체 이벤트 생성 플로우를 End-to-End로 테스트:
1. 이벤트 목적 선택
2. AI 추천 요청 및 선택
3. 이미지 생성 및 선택/편집
4. 배포 채널 선택
5. 최종 배포 및 모니터링

---

## 부록

### A. 개발 완료 요약

**Event Service API 개발 현황**:
- ✅ **전체 API 구현 완료**: 설계된 14개 API 모두 구현
- ✅ **핵심 생명주기 관리**: 이벤트 생성, 조회, 수정, 삭제, 상태 변경
- ✅ **AI 추천 플로우**: AI 추천 요청 및 선택 API 완성
- ✅ **이미지 관리**: 생성, 선택, 편집 API 완성
- ✅ **배포 관리**: 채널 선택 및 배포 API 완성
- ✅ **비동기 작업 추적**: Job 상태 조회 API 완성

**다음 단계**:
- AI Service, Content Service, Distribution Service와의 완전한 통합 테스트
- End-to-End 시나리오 기반 통합 검증
- 성능 최적화 및 에러 핸들링 강화

---

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

---

## 변경 이력

### v2.0 (2025-10-28) - 🎉 전체 API 구현 완료
- **구현 현황 업데이트**: 9개 → 14개 API (100% 구현 완료!)
- **신규 구현 API 추가 (5개)**:
  1. POST /api/v1/events/{eventId}/ai-recommendations - AI 추천 요청
  2. PUT /api/v1/events/{eventId}/recommendations - AI 추천 선택
  3. PUT /api/v1/events/{eventId}/images/{imageId}/edit - 이미지 편집
  4. PUT /api/v1/events/{eventId}/channels - 배포 채널 선택
  5. PUT /api/v1/events/{eventId} - 이벤트 수정
- **구현률 100% 달성**:
  - Event Creation Flow: 37.5% → 100%
  - Event Management: 66.7% → 100%
  - 모든 카테고리 100% 완성
- **문서 구조 개선**:
  - 미구현 API 계획 섹션 제거
  - 서비스 간 연동 완성 가이드 추가
  - 통합 테스트 시나리오 추가
- **라인 번호 업데이트**: 모든 Controller 메서드의 정확한 라인 번호 반영

### 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)
- 초기 문서 작성
- 설계된 14개 API 목록 정리
- 초기 구현 상태 기록 (7개 API)