mirror of
https://github.com/ktds-dg0501/kt-event-marketing.git
synced 2025-12-06 18:06:23 +00:00
5476fe9388
- JWT 토큰에 매장 ID(storeId) 필드 추가 - event-service 구현 (이벤트 생성/조회 API) - hibernate-types 의존성 추가 (UUID 지원) - API 매핑 문서 추가 - IntelliJ 실행 프로파일 추가 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
293 lines
11 KiB
Markdown
293 lines
11 KiB
Markdown
# Event Service API 매핑표
|
|
|
|
## 문서 정보
|
|
- **작성일**: 2025-10-24
|
|
- **버전**: 1.0
|
|
- **작성자**: Event Service Team
|
|
- **관련 문서**:
|
|
- [API 설계서](../../design/backend/api/API-설계서.md)
|
|
- [Event Service OpenAPI](../../design/backend/api/event-service-api.yaml)
|
|
|
|
---
|
|
|
|
## 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<EventDetailResponse>
|
|
- **비즈니스 로직**:
|
|
- 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<Void>
|
|
- **비즈니스 로직**:
|
|
- DRAFT 상태만 삭제 가능 검증 (Event.isDeletable())
|
|
- 다른 상태(PUBLISHED, ENDED)는 삭제 불가
|
|
- EventService.deleteEvent() 호출
|
|
|
|
#### 5. POST /api/events/{eventId}/publish
|
|
- **설명**: 이벤트 배포 (DRAFT → PUBLISHED)
|
|
- **유저스토리**: UFR-EVENT-050
|
|
- **요청**: eventId (UUID)
|
|
- **응답**: ApiResponse<Void>
|
|
- **비즈니스 로직**:
|
|
- Event.publish() 메서드로 상태 전환
|
|
- Distribution Service 호출은 추후 추가 예정
|
|
- EventService.publishEvent() 호출
|
|
|
|
#### 6. POST /api/events/{eventId}/end
|
|
- **설명**: 이벤트 조기 종료 (PUBLISHED → ENDED)
|
|
- **유저스토리**: UFR-EVENT-060
|
|
- **요청**: eventId (UUID)
|
|
- **응답**: ApiResponse<Void>
|
|
- **비즈니스 로직**:
|
|
- 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
|