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 구현:

@PostMapping("/images/generate")
public ResponseEntity<JobInfo> generateImages(@RequestBody ContentCommand.GenerateImages command)

API 명세:

• operationId: generateImages
• Request Body: GenerateImagesRequest
  • eventDraftId (Long, required)
  • styles (List, optional)
  • platforms (List, optional)
• Response: 202 Accepted → JobResponse

매핑 상태: ✅ 완전 일치

---

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

Controller 구현:

@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 구현:

@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 구현:

@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 구현:

@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 구현:

@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 구현:

@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