From e2179daaf75c0865c63e25030f51e5c0a22caeec Mon Sep 17 00:00:00 2001 From: merrycoral Date: Tue, 28 Oct 2025 13:22:22 +0900 Subject: [PATCH] =?UTF-8?q?Event=20Service=20API=20=EB=A7=A4=ED=95=91=20?= =?UTF-8?q?=EB=AC=B8=EC=84=9C=20=ED=98=84=ED=96=89=ED=99=94=20(v2.0)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 구현률 100% 달성: 14개 API 전체 구현 완료 - 신규 구현 API 문서화 (5개): * AI 추천 요청/선택 API * 이미지 편집 API * 배포 채널 선택 API * 이벤트 수정 API - 문서 구조 개선: * 미구현 API 계획 섹션 제거 * 서비스 간 연동 가이드 추가 * 통합 테스트 시나리오 추가 - Controller 라인 번호 정확도 향상 - .gitignore에 heap dump 파일 추가 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .gitignore | 2 + develop/dev/event-api-mapping.md | 288 ++++++++++++++++++------------- 2 files changed, 173 insertions(+), 117 deletions(-) diff --git a/.gitignore b/.gitignore index 04ee081..1a93c5a 100644 --- a/.gitignore +++ b/.gitignore @@ -45,3 +45,5 @@ k8s/**/*-local.yaml # Gradle (로컬 환경 설정) gradle.properties +*.hprof +test-data.json diff --git a/develop/dev/event-api-mapping.md b/develop/dev/event-api-mapping.md index 8944c2e..21df3e1 100644 --- a/develop/dev/event-api-mapping.md +++ b/develop/dev/event-api-mapping.md @@ -2,8 +2,8 @@ ## 문서 정보 - **작성일**: 2025-10-24 -- **최종 수정일**: 2025-10-27 -- **버전**: 1.1 +- **최종 수정일**: 2025-10-28 +- **버전**: 2.0 - **작성자**: Event Service Team - **관련 문서**: - [API 설계서](../../design/backend/api/API-설계서.md) @@ -15,16 +15,18 @@ ### 구현 현황 - **설계된 API**: 14개 -- **구현된 API**: 9개 (64.3%) -- **미구현 API**: 5개 (35.7%) +- **구현된 API**: 14개 (100%) ✅ +- **미구현 API**: 0개 (0%) ### 구현률 세부 | 카테고리 | 설계 | 구현 | 미구현 | 구현률 | |---------|------|------|--------|--------| -| 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% | +| 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가 모두 구현되었습니다. --- @@ -39,48 +41,43 @@ --- -### 2.2 Event Creation Flow (구현률 37.5%) +### 2.2 Event Creation Flow (구현률 100% ✅) #### Step 1: 이벤트 목적 선택 | 설계서 API | Controller | 메서드 | 경로 | 구현 여부 | 비고 | |-----------|-----------|--------|------|----------|------| -| 이벤트 목적 선택 | EventController | POST | /api/v1/events/objectives | ✅ 구현 | EventController:55 | +| 이벤트 목적 선택 | EventController | POST | /api/v1/events/objectives | ✅ 구현 | EventController:51 | -#### 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%) +#### Step 2: AI 추천 (구현률 100% ✅) | 설계서 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 연동 필요 | +| 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를 통해 재생성 -**미구현 상세 이유 (이미지 편집)**: -- Content Service의 이미지 재생성 API와 연동 필요 -- 편집된 이미지를 다시 생성하고 CDN에 업로드하는 로직 필요 +#### Step 4: 배포 채널 선택 (구현률 100% ✅) +| 설계서 API | Controller | 메서드 | 경로 | 구현 여부 | 비고 | +|-----------|-----------|--------|------|----------|------| +| 배포 채널 선택 | EventController | PUT | /api/v1/events/{eventId}/channels | ✅ 구현 | EventController:357 | -#### Step 4: 배포 채널 선택 (미구현) -| 설계서 API | Controller | 메서드 | 경로 | 구현 여부 | 미구현 이유 | -|-----------|-----------|--------|------|----------|-----------| -| 배포 채널 선택 | - | PUT | /api/v1/events/{eventId}/channels | ❌ 미구현 | Distribution Service 연동 필요 | - -**미구현 상세 이유**: -- Distribution Service의 채널 목록 검증 로직 필요 -- Event 엔티티의 channels 필드 업데이트 로직은 구현 가능하나, 채널별 검증은 Distribution Service 개발 후 추가 예정 +**구현 내용**: +- 이벤트를 배포할 채널(SMS, KakaoTalk, App Push 등)을 선택 +- Distribution Service와의 연동은 추후 추가 예정 #### Step 5: 최종 승인 및 배포 | 설계서 API | Controller | 메서드 | 경로 | 구현 여부 | 비고 | @@ -94,19 +91,18 @@ --- -### 2.3 Event Management (구현률 66.7%) +### 2.3 Event Management (구현률 100% ✅) | 설계서 API | Controller | 메서드 | 경로 | 구현 여부 | 비고 | |-----------|-----------|--------|------|----------|------| -| 이벤트 수정 | - | PUT | /api/v1/events/{eventId} | ❌ 미구현 | 이유는 아래 참조 | -| 이벤트 삭제 | EventController | DELETE | /api/v1/events/{eventId} | ✅ 구현 | EventController:154 | -| 이벤트 조기 종료 | EventController | POST | /api/v1/events/{eventId}/end | ✅ 구현 | EventController:196 | +| 이벤트 수정 | 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 | -**이벤트 수정 API 미구현 이유**: -- 이벤트 수정은 여러 단계의 데이터를 수정하는 복잡한 로직 -- AI 추천 재선택, 이미지 재생성 등 다른 서비스와의 연동이 필요 -- 우선순위: 신규 이벤트 생성 플로우 완성 후 구현 예정 -- 현재는 DRAFT 상태에서만 삭제 가능하므로 수정 대신 삭제 후 재생성 가능 +**구현 내용**: +- **이벤트 수정**: 기존 이벤트의 정보를 수정합니다. DRAFT 상태만 수정 가능 +- **이벤트 삭제**: DRAFT 상태의 이벤트만 삭제 가능 +- **이벤트 조기 종료**: PUBLISHED 상태의 이벤트를 ENDED 상태로 변경 --- @@ -120,7 +116,7 @@ ## 3. 구현된 API 상세 -### 3.1 EventController (8개 API) +### 3.1 EventController (13개 API) #### 1. POST /api/v1/events/objectives - **설명**: 이벤트 생성의 첫 단계로 목적을 선택 @@ -206,6 +202,56 @@ - 이미지 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 +- **비즈니스 로직**: + - 선택한 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) +- **응답**: ApiResponse +- **비즈니스 로직**: + - 배포 채널(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) @@ -222,102 +268,108 @@ --- -## 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 (설계서에 없음) +## 4. 추가 구현된 API (설계서에 없음) 현재 추가 구현된 API는 없습니다. 모든 구현은 설계서를 기준으로 진행되었습니다. --- -## 6. 다음 단계 +## 5. 다음 단계 -### 6.1 즉시 가능한 작업 +### 5.1 즉시 가능한 작업 1. **서버 시작 테스트**: - PostgreSQL 연결 확인 + - Kafka 연결 확인 + - Redis 연결 확인 - 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} +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 상태 조회) -### 6.2 후속 개발 필요 -1. AI Service 개발 완료 → AI 추천 API 구현 -2. Content Service 개발 완료 → 이미지 편집 API 구현 -3. Distribution Service 개발 완료 → 배포 채널 선택 API 구현 -4. 전체 서비스 연동 → 이벤트 수정 API 구현 +### 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. 개발 우선순위 결정 근거 +### A. 개발 완료 요약 -**현재 구현 범위 선정 이유**: -1. **핵심 생명주기 먼저**: 이벤트 생성, 조회, 삭제, 상태 변경 -2. **서비스 독립성**: 다른 서비스 없이도 Event Service 단독 테스트 가능 -3. **점진적 통합**: 각 서비스 개발 완료 시점에 순차적 통합 -4. **리스크 최소화**: 복잡한 서비스 간 연동은 각 서비스 안정화 후 진행 +**Event Service API 개발 현황**: +- ✅ **전체 API 구현 완료**: 설계된 14개 API 모두 구현 +- ✅ **핵심 생명주기 관리**: 이벤트 생성, 조회, 수정, 삭제, 상태 변경 +- ✅ **AI 추천 플로우**: AI 추천 요청 및 선택 API 완성 +- ✅ **이미지 관리**: 생성, 선택, 편집 API 완성 +- ✅ **배포 관리**: 채널 선택 및 배포 API 완성 +- ✅ **비동기 작업 추적**: Job 상태 조회 API 완성 + +**다음 단계**: +- AI Service, Content Service, Distribution Service와의 완전한 통합 테스트 +- End-to-End 시나리오 기반 통합 검증 +- 성능 최적화 및 에러 핸들링 강화 --- -**문서 버전**: 1.1 -**최종 수정일**: 2025-10-27 +**문서 버전**: 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 추가**: @@ -331,3 +383,5 @@ ### v1.0 (2025-10-24) - 초기 문서 작성 +- 설계된 14개 API 목록 정리 +- 초기 구현 상태 기록 (7개 API)