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

Event Service API 매핑표

문서 정보

• 작성일: 2025-10-24
• 버전: 1.0
• 작성자: Event Service Team
• 관련 문서:
  • API 설계서
  • Event Service OpenAPI

---

1. 매핑 현황 요약

구현 현황

• 설계된 API: 14개
• 구현된 API: 7개 (50.0%)
• 미구현 API: 7개 (50.0%)

구현률 세부

카테고리	설계	구현	미구현	구현률
Dashboard & Event List	2	2	0	100%
Event Creation Flow	8	1	7	12.5%
Event Management	3	3	0	100%
Job Status	1	1	0	100%

---

2. 상세 매핑표

2.1 Dashboard & Event List (구현률 100%)

설계서 API	Controller	메서드	경로	구현 여부	비고
이벤트 목록 조회	EventController	GET	/api/events	✅ 구현	EventController:84
이벤트 상세 조회	EventController	GET	/api/events/{eventId}	✅ 구현	EventController:130

---

2.2 Event Creation Flow (구현률 12.5%)

Step 1: 이벤트 목적 선택

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

Step 2: AI 추천 (미구현)

설계서 API	Controller	메서드	경로	구현 여부	미구현 이유
AI 추천 요청	-	POST	/api/events/{eventId}/ai-recommendations	❌ 미구현	AI Service 연동 필요
AI 추천 선택	-	PUT	/api/events/{eventId}/recommendations	❌ 미구현	AI Service 연동 필요

미구현 상세 이유:

• Kafka Topic ai-event-generation-job 발행 로직 필요
• AI Service와의 연동이 선행되어야 함
• 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 연동 필요

미구현 상세 이유:

• Kafka Topic image-generation-job 발행 로직 필요
• Content Service와의 연동이 선행되어야 함
• Redis에서 생성된 이미지 URL을 읽어오는 로직 필요
• 이미지 편집은 Content Service의 이미지 재생성 API와 연동 필요

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

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

미구현 상세 이유:

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

Step 5: 최종 승인 및 배포

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

구현 내용:

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

---

2.3 Event Management (구현률 100%)

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

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

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

---

2.4 Job Status (구현률 100%)

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

---

3. 구현된 API 상세

3.1 EventController (6개 API)

1. POST /api/events/objectives

• 설명: 이벤트 생성의 첫 단계로 목적을 선택
• 유저스토리: UFR-EVENT-020
• 요청: SelectObjectiveRequest (objective)
• 응답: EventCreatedResponse (eventId, status, objective, createdAt)
• 비즈니스 로직:
  • Long userId/storeId를 UUID로 변환하여 Event 엔티티 생성
  • 초기 상태는 DRAFT
  • EventService.createEvent() 호출

2. GET /api/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/events/{eventId}

• 설명: 특정 이벤트의 상세 정보 조회
• 유저스토리: UFR-EVENT-060
• 요청: eventId (UUID)
• 응답: EventDetailResponse (이벤트 정보 + 생성된 이미지 + AI 추천)
• 비즈니스 로직:
  • Long userId를 UUID로 변환
  • 사용자 소유 이벤트만 조회 가능 (보안)
  • EventService.getEvent() 호출

4. DELETE /api/events/{eventId}

• 설명: 이벤트 삭제 (DRAFT 상태만 가능)
• 유저스토리: UFR-EVENT-070
• 요청: eventId (UUID)
• 응답: ApiResponse
• 비즈니스 로직:
  • DRAFT 상태만 삭제 가능 검증 (Event.isDeletable())
  • 다른 상태(PUBLISHED, ENDED)는 삭제 불가
  • EventService.deleteEvent() 호출

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

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

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

• 설명: 이벤트 조기 종료 (PUBLISHED → ENDED)
• 유저스토리: UFR-EVENT-060
• 요청: eventId (UUID)
• 응답: ApiResponse
• 비즈니스 로직:
  • Event.end() 메서드로 상태 전환
  • PUBLISHED 상태만 종료 가능
  • EventService.endEvent() 호출

---

3.2 JobController (1개 API)

1. GET /api/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/events/{eventId}/ai-recommendations - AI 추천 요청
• PUT /api/events/{eventId}/recommendations - AI 추천 선택

개발 선행 조건:

1. AI Service 개발 완료
2. Kafka Topic ai-event-generation-job 설정
3. Redis 캐시 연동 구현

---

4.2 우선순위 2 (Content Service 연동)

• POST /api/events/{eventId}/images - 이미지 생성 요청
• PUT /api/events/{eventId}/images/{imageId}/select - 이미지 선택
• PUT /api/events/{eventId}/images/{imageId}/edit - 이미지 편집

개발 선행 조건:

1. Content Service 개발 완료
2. Kafka Topic image-generation-job 설정
3. Redis 캐시 연동 구현
4. CDN (Azure Blob Storage) 연동

---

4.3 우선순위 3 (Distribution Service 연동)

• PUT /api/events/{eventId}/channels - 배포 채널 선택

개발 선행 조건:

1. Distribution Service 개발 완료
2. 채널별 검증 로직 구현
3. POST /api/events/{eventId}/publish API에 Distribution Service 동기 호출 추가

---

4.4 우선순위 4 (이벤트 수정)

• PUT /api/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/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}

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.0 최종 수정일: 2025-10-24 작성자: Event Service Team