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

Event Service API 매핑표

문서 정보

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

---

1. 매핑 현황 요약

구현 현황

• 설계된 API: 14개
• 구현된 API: 9개 (64.3%)
• 미구현 API: 5개 (35.7%)

구현률 세부

카테고리	설계	구현	미구현	구현률
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%

---

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 (구현률 37.5%)

Step 1: 이벤트 목적 선택

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

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%)

설계서 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에 메시지 발행, Job ID 반환
• 이미지 선택: 사용자가 생성된 이미지 중 하나를 선택하여 이벤트에 연결

미구현 상세 이유 (이미지 편집):

• Content Service의 이미지 재생성 API와 연동 필요
• 편집된 이미지를 다시 생성하고 CDN에 업로드하는 로직 필요

Step 4: 배포 채널 선택 (미구현)

설계서 API	Controller	메서드	경로	구현 여부	미구현 이유
배포 채널 선택	-	PUT	/api/v1/events/{eventId}/channels	❌ 미구현	Distribution Service 연동 필요

미구현 상세 이유:

• Distribution Service의 채널 목록 검증 로직 필요
• Event 엔티티의 channels 필드 업데이트 로직은 구현 가능하나, 채널별 검증은 Distribution Service 개발 후 추가 예정

Step 5: 최종 승인 및 배포

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

구현 내용:

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

---

2.3 Event Management (구현률 66.7%)

설계서 API	Controller	메서드	경로	구현 여부	비고
이벤트 수정	-	PUT	/api/v1/events/{eventId}	❌ 미구현	이유는 아래 참조
이벤트 삭제	EventController	DELETE	/api/v1/events/{eventId}	✅ 구현	EventController:154
이벤트 조기 종료	EventController	POST	/api/v1/events/{eventId}/end	✅ 구현	EventController:196

이벤트 수정 API 미구현 이유:

• 이벤트 수정은 여러 단계의 데이터를 수정하는 복잡한 로직
• AI 추천 재선택, 이미지 재생성 등 다른 서비스와의 연동이 필요
• 우선순위: 신규 이벤트 생성 플로우 완성 후 구현 예정
• 현재는 DRAFT 상태에서만 삭제 가능하므로 수정 대신 삭제 후 재생성 가능

---

2.4 Job Status (구현률 100%)

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

---

3. 구현된 API 상세

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

---

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 개발 계획

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

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

---

6. 다음 단계

6.1 즉시 가능한 작업

1. 서버 시작 테스트:

   • PostgreSQL 연결 확인
   • 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}

6.2 후속 개발 필요

1. AI Service 개발 완료 → AI 추천 API 구현
2. Content Service 개발 완료 → 이미지 편집 API 구현
3. Distribution Service 개발 완료 → 배포 채널 선택 API 구현
4. 전체 서비스 연동 → 이벤트 수정 API 구현

---

부록

A. 개발 우선순위 결정 근거

현재 구현 범위 선정 이유:

1. 핵심 생명주기 먼저: 이벤트 생성, 조회, 삭제, 상태 변경
2. 서비스 독립성: 다른 서비스 없이도 Event Service 단독 테스트 가능
3. 점진적 통합: 각 서비스 개발 완료 시점에 순차적 통합
4. 리스크 최소화: 복잡한 서비스 간 연동은 각 서비스 안정화 후 진행

---

문서 버전: 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)

• 초기 문서 작성