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

Event Service API 매핑표

문서 정보

• 작성일: 2025-10-24
• 최종 수정일: 2025-10-28
• 버전: 2.0
• 작성자: Event Service Team
• 관련 문서:
  • API 설계서
  • Event Service OpenAPI

---

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
• 비즈니스 로직:
  • 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
• 비즈니스 로직:
  • DRAFT 상태만 삭제 가능 검증 (Event.isDeletable())
  • 다른 상태(PUBLISHED, ENDED)는 삭제 불가
  • EventService.deleteEvent() 호출

5. POST /api/v1/events/{eventId}/publish

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

6. POST /api/v1/events/{eventId}/end

• 설명: 이벤트 조기 종료 (PUBLISHED → ENDED)
• 유저스토리: UFR-EVENT-060
• 요청: eventId (UUID)
• 응답: ApiResponse
• 비즈니스 로직:
  • 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
• 비즈니스 로직:
  • 선택한 이미지를 이벤트에 연결
  • 이미지 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)

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)