shared-dg05-dodari/kt-event-marketing
7
0
Fork 0
mirror of https://github.com/ktds-dg0501/kt-event-marketing.git synced 2025-12-06 10:46:23 +00:00
Code Issues Packages Projects Releases Wiki Activity

이벤트 API 매핑 문서 업데이트 (v1.1)

Browse Source 
- 구현 현황: 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%
- 변경 이력 섹션 추가
This commit is contained in:
merrycoral 2025-10-27 15:24:28 +09:00
parent 42f0665f5e
commit 55e546e0b3
1 changed files with 98 additions and 57 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

155
develop/dev/event-api-mapping.md
View File

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