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

# Content Service API 매핑표

**작성일**: 2025-10-24
**서비스**: content-service
**비교 대상**: ContentController.java ↔ content-service-api.yaml

## 1. API 매핑 테이블

| No | Controller 메서드 | HTTP 메서드 | 경로 | API 명세 operationId | 유저스토리 | 구현 상태 | 비고 |
|----|------------------|-------------|------|---------------------|-----------|-----------|------|
| 1 | generateImages | POST | /content/images/generate | generateImages | US-CT-001 | ✅ 구현완료 | 이미지 생성 요청, Job ID 즉시 반환 |
| 2 | getJobStatus | GET | /content/images/jobs/{jobId} | getImageGenerationStatus | US-CT-001 | ✅ 구현완료 | Job 상태 폴링용 |
| 3 | getContentByEventId | GET | /content/events/{eventDraftId} | getContentByEventId | US-CT-002 | ✅ 구현완료 | 이벤트 콘텐츠 조회 |
| 4 | getImages | GET | /content/events/{eventDraftId}/images | getImages | US-CT-003 | ✅ 구현완료 | 이미지 목록 조회 (스타일/플랫폼 필터링 지원) |
| 5 | getImageById | GET | /content/images/{imageId} | getImageById | US-CT-003 | ✅ 구현완료 | 특정 이미지 상세 조회 |
| 6 | deleteImage | DELETE | /content/images/{imageId} | deleteImage | US-CT-004 | ⚠️ TODO | 이미지 삭제 (미구현) |
| 7 | regenerateImage | POST | /content/images/{imageId}/regenerate | regenerateImage | US-CT-005 | ✅ 구현완료 | 이미지 재생성 요청 |

## 2. API 상세 비교

### 2.1. POST /content/images/generate (이미지 생성 요청)

**Controller 구현**:
```java
@PostMapping("/images/generate")
public ResponseEntity<JobInfo> generateImages(@RequestBody ContentCommand.GenerateImages command)
```

**API 명세**:
- operationId: `generateImages`
- Request Body: `GenerateImagesRequest`
  - eventDraftId (Long, required)
  - styles (List<String>, optional)
  - platforms (List<String>, optional)
- Response: 202 Accepted → `JobResponse`

**매핑 상태**: ✅ 완전 일치

---

### 2.2. GET /content/images/jobs/{jobId} (Job 상태 조회)

**Controller 구현**:
```java
@GetMapping("/images/jobs/{jobId}")
public ResponseEntity<JobInfo> getJobStatus(@PathVariable String jobId)
```

**API 명세**:
- operationId: `getImageGenerationStatus`
- Path Parameter: `jobId` (String, required)
- Response: 200 OK → `JobResponse`

**매핑 상태**: ✅ 완전 일치

---

### 2.3. GET /content/events/{eventDraftId} (이벤트 콘텐츠 조회)

**Controller 구현**:
```java
@GetMapping("/events/{eventDraftId}")
public ResponseEntity<ContentInfo> getContentByEventId(@PathVariable Long eventDraftId)
```

**API 명세**:
- operationId: `getContentByEventId`
- Path Parameter: `eventDraftId` (Long, required)
- Response: 200 OK → `ContentResponse`

**매핑 상태**: ✅ 완전 일치

---

### 2.4. GET /content/events/{eventDraftId}/images (이미지 목록 조회)

**Controller 구현**:
```java
@GetMapping("/events/{eventDraftId}/images")
public ResponseEntity<List<ImageInfo>> getImages(
    @PathVariable Long eventDraftId,
    @RequestParam(required = false) String style,
    @RequestParam(required = false) String platform)
```

**API 명세**:
- operationId: `getImages`
- Path Parameter: `eventDraftId` (Long, required)
- Query Parameters:
  - style (String, optional)
  - platform (String, optional)
- Response: 200 OK → Array of `ImageResponse`

**매핑 상태**: ✅ 완전 일치

---

### 2.5. GET /content/images/{imageId} (이미지 상세 조회)

**Controller 구현**:
```java
@GetMapping("/images/{imageId}")
public ResponseEntity<ImageInfo> getImageById(@PathVariable Long imageId)
```

**API 명세**:
- operationId: `getImageById`
- Path Parameter: `imageId` (Long, required)
- Response: 200 OK → `ImageResponse`

**매핑 상태**: ✅ 완전 일치

---

### 2.6. DELETE /content/images/{imageId} (이미지 삭제)

**Controller 구현**:
```java
@DeleteMapping("/images/{imageId}")
public ResponseEntity<Void> deleteImage(@PathVariable Long imageId) {
    // TODO: 이미지 삭제 기능 구현 필요
    throw new UnsupportedOperationException("이미지 삭제 기능은 아직 구현되지 않았습니다");
}
```

**API 명세**:
- operationId: `deleteImage`
- Path Parameter: `imageId` (Long, required)
- Response: 204 No Content

**매핑 상태**: ⚠️ **메서드 선언만 존재, 실제 로직 미구현**

**미구현 사유**:
- Phase 3 작업 범위는 JPA → Redis 전환
- 이미지 삭제 기능은 향후 구현 예정
- API 명세와 Controller 시그니처는 일치하나 내부 로직은 UnsupportedOperationException 발생

---

### 2.7. POST /content/images/{imageId}/regenerate (이미지 재생성)

**Controller 구현**:
```java
@PostMapping("/images/{imageId}/regenerate")
public ResponseEntity<JobInfo> regenerateImage(
    @PathVariable Long imageId,
    @RequestBody(required = false) ContentCommand.RegenerateImage requestBody)
```

**API 명세**:
- operationId: `regenerateImage`
- Path Parameter: `imageId` (Long, required)
- Request Body: `RegenerateImageRequest` (optional)
  - style (String, optional)
  - platform (String, optional)
- Response: 202 Accepted → `JobResponse`

**매핑 상태**: ✅ 완전 일치

---

## 3. 추가된 API 분석

**결과**: API 명세에 없는 추가 API는 **존재하지 않음**

- Controller에 구현된 모든 7개 엔드포인트는 API 명세서(content-service-api.yaml)에 정의되어 있음
- API 명세서의 모든 6개 경로(7개 operation)가 Controller에 구현되어 있음

## 4. 구현 상태 요약

### 4.1. 구현 완료 (6개)
1. ✅ POST /content/images/generate - 이미지 생성 요청
2. ✅ GET /content/images/jobs/{jobId} - Job 상태 조회
3. ✅ GET /content/events/{eventDraftId} - 이벤트 콘텐츠 조회
4. ✅ GET /content/events/{eventDraftId}/images - 이미지 목록 조회
5. ✅ GET /content/images/{imageId} - 이미지 상세 조회
6. ✅ POST /content/images/{imageId}/regenerate - 이미지 재생성

### 4.2. 미구현 (1개)
1. ⚠️ DELETE /content/images/{imageId} - 이미지 삭제
   - **사유**: Phase 3은 JPA → Redis 전환 작업만 포함
   - **향후 계획**: Phase 4 또는 추후 기능 개발 단계에서 구현 예정
   - **현재 동작**: `UnsupportedOperationException` 발생

## 5. 검증 결과

### ✅ API 명세 준수도: 85.7% (6/7 구현)

- API 설계서와 Controller 구현이 **완전히 일치**함
- 모든 경로, HTTP 메서드, 파라미터 타입이 명세와 동일
- Response 타입도 명세의 스키마 정의와 일치
- 미구현 1건은 명시적으로 TODO 주석으로 표시되어 추후 구현 가능

### 권장 사항

1. **DELETE /content/images/{imageId} 구현 완료**
   - ImageWriter 포트에 deleteImage 메서드 추가
   - RedisGateway 및 MockRedisGateway에 구현
   - Service 레이어 생성 (DeleteImageService)
   - Controller의 TODO 제거

2. **통합 테스트 작성**
   - 모든 구현된 API에 대한 통합 테스트 추가
   - Mock 환경에서 전체 플로우 검증

3. **API 문서 동기화 유지**
   - 향후 API 변경 시 명세서와 Controller 동시 업데이트
   - OpenAPI Spec 자동 검증 도구 도입 고려

---

**문서 작성자**: Claude
**검증 완료**: 2025-10-24