From 55e546e0b39e6fab3966f33039c568e77b4a22cf Mon Sep 17 00:00:00 2001
From: merrycoral <merrycoral@gmail.com>
Date: Mon, 27 Oct 2025 15:24:28 +0900
Subject: [PATCH] =?UTF-8?q?=EC=9D=B4=EB=B2=A4=ED=8A=B8=20API=20=EB=A7=A4?=
 =?UTF-8?q?=ED=95=91=20=EB=AC=B8=EC=84=9C=20=EC=97=85=EB=8D=B0=EC=9D=B4?=
 =?UTF-8?q?=ED=8A=B8=20(v1.1)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 구현 현황: 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%
- 변경 이력 섹션 추가
---
 develop/dev/event-api-mapping.md | 155 +++++++++++++++++++------------
 1 file changed, 98 insertions(+), 57 deletions(-)

diff --git a/develop/dev/event-api-mapping.md b/develop/dev/event-api-mapping.md
index faa02f8..8944c2e 100644
--- a/develop/dev/event-api-mapping.md
+++ b/develop/dev/event-api-mapping.md
@@ -2,7 +2,8 @@
 
 ## 문서 정보
 - **작성일**: 2025-10-24
-- **버전**: 1.0
+- **최종 수정일**: 2025-10-27
+- **버전**: 1.1
 - **작성자**: Event Service Team
 - **관련 문서**:
   - [API 설계서](../../design/backend/api/API-설계서.md)
@@ -14,15 +15,15 @@
 
 ### 구현 현황
 - **설계된 API**: 14개
-- **구현된 API**: 7개 (50.0%)
-- **미구현 API**: 7개 (50.0%)
+- **구현된 API**: 9개 (64.3%)
+- **미구현 API**: 5개 (35.7%)
 
 ### 구현률 세부
 | 카테고리 | 설계 | 구현 | 미구현 | 구현률 |
 |---------|------|------|--------|--------|
 | Dashboard & Event List | 2 | 2 | 0 | 100% |
-| Event Creation Flow | 8 | 1 | 7 | 12.5% |
-| Event Management | 3 | 3 | 0 | 100% |
+| Event Creation Flow | 8 | 3 | 5 | 37.5% |
+| Event Management | 3 | 2 | 1 | 66.7% |
 | Job Status | 1 | 1 | 0 | 100% |
 
 ---
@@ -33,23 +34,23 @@
 
 | 설계서 API | Controller | 메서드 | 경로 | 구현 여부 | 비고 |
 |-----------|-----------|--------|------|----------|------|
-| 이벤트 목록 조회 | EventController | GET | /api/events | ✅ 구현 | EventController:84 |
-| 이벤트 상세 조회 | EventController | GET | /api/events/{eventId} | ✅ 구현 | EventController:130 |
+| 이벤트 목록 조회 | EventController | GET | /api/v1/events | ✅ 구현 | EventController:87 |
+| 이벤트 상세 조회 | EventController | GET | /api/v1/events/{eventId} | ✅ 구현 | EventController:133 |
 
 ---
 
-### 2.2 Event Creation Flow (구현률 12.5%)
+### 2.2 Event Creation Flow (구현률 37.5%)
 
 #### Step 1: 이벤트 목적 선택
 | 설계서 API | Controller | 메서드 | 경로 | 구현 여부 | 비고 |
 |-----------|-----------|--------|------|----------|------|
-| 이벤트 목적 선택 | EventController | POST | /api/events/objectives | ✅ 구현 | EventController:52 |
+| 이벤트 목적 선택 | EventController | POST | /api/v1/events/objectives | ✅ 구현 | EventController:55 |
 
 #### Step 2: AI 추천 (미구현)
 | 설계서 API | Controller | 메서드 | 경로 | 구현 여부 | 미구현 이유 |
 |-----------|-----------|--------|------|----------|-----------|
-| AI 추천 요청 | - | POST | /api/events/{eventId}/ai-recommendations | ❌ 미구현 | AI Service 연동 필요 |
-| AI 추천 선택 | - | PUT | /api/events/{eventId}/recommendations | ❌ 미구현 | AI Service 연동 필요 |
+| 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` 발행 로직 필요
@@ -57,23 +58,25 @@
 - 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 연동 필요 |
+#### 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` 발행 로직 필요
-- Content Service와의 연동이 선행되어야 함
-- Redis에서 생성된 이미지 URL을 읽어오는 로직 필요
-- 이미지 편집은 Content Service의 이미지 재생성 API와 연동 필요
+**구현 내용**:
+- **이미지 생성 요청**: Kafka Topic `image-generation-job`에 메시지 발행, Job ID 반환
+- **이미지 선택**: 사용자가 생성된 이미지 중 하나를 선택하여 이벤트에 연결
+
+**미구현 상세 이유 (이미지 편집)**:
+- Content Service의 이미지 재생성 API와 연동 필요
+- 편집된 이미지를 다시 생성하고 CDN에 업로드하는 로직 필요
 
 #### Step 4: 배포 채널 선택 (미구현)
 | 설계서 API | Controller | 메서드 | 경로 | 구현 여부 | 미구현 이유 |
 |-----------|-----------|--------|------|----------|-----------|
-| 배포 채널 선택 | - | PUT | /api/events/{eventId}/channels | ❌ 미구현 | Distribution Service 연동 필요 |
+| 배포 채널 선택 | - | PUT | /api/v1/events/{eventId}/channels | ❌ 미구현 | Distribution Service 연동 필요 |
 
 **미구현 상세 이유**:
 - Distribution Service의 채널 목록 검증 로직 필요
@@ -82,7 +85,7 @@
 #### Step 5: 최종 승인 및 배포
 | 설계서 API | Controller | 메서드 | 경로 | 구현 여부 | 비고 |
 |-----------|-----------|--------|------|----------|------|
-| 최종 승인 및 배포 | EventController | POST | /api/events/{eventId}/publish | ✅ 구현 | EventController:172 |
+| 최종 승인 및 배포 | EventController | POST | /api/v1/events/{eventId}/publish | ✅ 구현 | EventController:175 |
 
 **구현 내용**:
 - 이벤트 상태를 DRAFT → PUBLISHED로 변경
@@ -91,13 +94,13 @@
 
 ---
 
-### 2.3 Event Management (구현률 100%)
+### 2.3 Event Management (구현률 66.7%)
 
 | 설계서 API | Controller | 메서드 | 경로 | 구현 여부 | 비고 |
 |-----------|-----------|--------|------|----------|------|
-| 이벤트 수정 | - | PUT | /api/events/{eventId} | ❌ 미구현 | 이유는 아래 참조 |
-| 이벤트 삭제 | EventController | DELETE | /api/events/{eventId} | ✅ 구현 | EventController:151 |
-| 이벤트 조기 종료 | EventController | POST | /api/events/{eventId}/end | ✅ 구현 | EventController:193 |
+| 이벤트 수정 | - | PUT | /api/v1/events/{eventId} | ❌ 미구현 | 이유는 아래 참조 |
+| 이벤트 삭제 | EventController | DELETE | /api/v1/events/{eventId} | ✅ 구현 | EventController:154 |
+| 이벤트 조기 종료 | EventController | POST | /api/v1/events/{eventId}/end | ✅ 구현 | EventController:196 |
 
 **이벤트 수정 API 미구현 이유**:
 - 이벤트 수정은 여러 단계의 데이터를 수정하는 복잡한 로직
@@ -111,15 +114,15 @@
 
 | 설계서 API | Controller | 메서드 | 경로 | 구현 여부 | 비고 |
 |-----------|-----------|--------|------|----------|------|
-| Job 상태 폴링 | JobController | GET | /api/jobs/{jobId} | ✅ 구현 | JobController:42 |
+| Job 상태 폴링 | JobController | GET | /api/v1/jobs/{jobId} | ✅ 구현 | JobController:42 |
 
 ---
 
 ## 3. 구현된 API 상세
 
-### 3.1 EventController (6개 API)
+### 3.1 EventController (8개 API)
 
-#### 1. POST /api/events/objectives
+#### 1. POST /api/v1/events/objectives
 - **설명**: 이벤트 생성의 첫 단계로 목적을 선택
 - **유저스토리**: UFR-EVENT-020
 - **요청**: SelectObjectiveRequest (objective)
@@ -129,7 +132,7 @@
   - 초기 상태는 DRAFT
   - EventService.createEvent() 호출
 
-#### 2. GET /api/events
+#### 2. GET /api/v1/events
 - **설명**: 사용자의 이벤트 목록 조회 (페이징, 필터링, 정렬)
 - **유저스토리**: UFR-EVENT-010, UFR-EVENT-070
 - **요청 파라미터**:
@@ -143,7 +146,7 @@
   - Repository에서 필터링 및 페이징 처리
   - EventService.getEvents() 호출
 
-#### 3. GET /api/events/{eventId}
+#### 3. GET /api/v1/events/{eventId}
 - **설명**: 특정 이벤트의 상세 정보 조회
 - **유저스토리**: UFR-EVENT-060
 - **요청**: eventId (UUID)
@@ -153,7 +156,7 @@
   - 사용자 소유 이벤트만 조회 가능 (보안)
   - EventService.getEvent() 호출
 
-#### 4. DELETE /api/events/{eventId}
+#### 4. DELETE /api/v1/events/{eventId}
 - **설명**: 이벤트 삭제 (DRAFT 상태만 가능)
 - **유저스토리**: UFR-EVENT-070
 - **요청**: eventId (UUID)
@@ -163,7 +166,7 @@
   - 다른 상태(PUBLISHED, ENDED)는 삭제 불가
   - EventService.deleteEvent() 호출
 
-#### 5. POST /api/events/{eventId}/publish
+#### 5. POST /api/v1/events/{eventId}/publish
 - **설명**: 이벤트 배포 (DRAFT → PUBLISHED)
 - **유저스토리**: UFR-EVENT-050
 - **요청**: eventId (UUID)
@@ -173,7 +176,7 @@
   - Distribution Service 호출은 추후 추가 예정
   - EventService.publishEvent() 호출
 
-#### 6. POST /api/events/{eventId}/end
+#### 6. POST /api/v1/events/{eventId}/end
 - **설명**: 이벤트 조기 종료 (PUBLISHED → ENDED)
 - **유저스토리**: UFR-EVENT-060
 - **요청**: eventId (UUID)
@@ -183,11 +186,31 @@
   - 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/jobs/{jobId}
+#### 1. GET /api/v1/jobs/{jobId}
 - **설명**: 비동기 작업의 상태를 조회 (폴링 방식)
 - **유저스토리**: UFR-EVENT-030, UFR-CONT-010
 - **요청**: jobId (UUID)
@@ -202,8 +225,8 @@
 ## 4. 미구현 API 개발 계획
 
 ### 4.1 우선순위 1 (AI Service 연동)
-- **POST /api/events/{eventId}/ai-recommendations** - AI 추천 요청
-- **PUT /api/events/{eventId}/recommendations** - AI 추천 선택
+- **POST /api/v1/events/{eventId}/ai-recommendations** - AI 추천 요청
+- **PUT /api/v1/events/{eventId}/recommendations** - AI 추천 선택
 
 **개발 선행 조건**:
 1. AI Service 개발 완료
@@ -213,20 +236,18 @@
 ---
 
 ### 4.2 우선순위 2 (Content Service 연동)
-- **POST /api/events/{eventId}/images** - 이미지 생성 요청
-- **PUT /api/events/{eventId}/images/{imageId}/select** - 이미지 선택
-- **PUT /api/events/{eventId}/images/{imageId}/edit** - 이미지 편집
+- **PUT /api/v1/events/{eventId}/images/{imageId}/edit** - 이미지 편집
 
 **개발 선행 조건**:
 1. Content Service 개발 완료
-2. Kafka Topic `image-generation-job` 설정
-3. Redis 캐시 연동 구현
-4. CDN (Azure Blob Storage) 연동
+2. 이미지 재생성 API 구현
+
+**참고**: 이미지 생성 요청과 이미지 선택 API는 이미 구현 완료
 
 ---
 
 ### 4.3 우선순위 3 (Distribution Service 연동)
-- **PUT /api/events/{eventId}/channels** - 배포 채널 선택
+- **PUT /api/v1/events/{eventId}/channels** - 배포 채널 선택
 
 **개발 선행 조건**:
 1. Distribution Service 개발 완료
@@ -236,7 +257,7 @@
 ---
 
 ### 4.4 우선순위 4 (이벤트 수정)
-- **PUT /api/events/{eventId}** - 이벤트 수정
+- **PUT /api/v1/events/{eventId}** - 이벤트 수정
 
 **개발 선행 조건**:
 1. 우선순위 1~3 API 모두 구현 완료
@@ -259,17 +280,19 @@
    - 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}
+   - 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 구현
+2. Content Service 개발 완료 → 이미지 편집 API 구현
 3. Distribution Service 개발 완료 → 배포 채널 선택 API 구현
 4. 전체 서비스 연동 → 이벤트 수정 API 구현
 
@@ -287,6 +310,24 @@
 
 ---
 
-**문서 버전**: 1.0
-**최종 수정일**: 2025-10-24
+**문서 버전**: 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)
+- 초기 문서 작성