[FEAT] 이미지 저장·조회·교체 API 구현 이미지 다중 처리 로직 구현 (#50)

[99hyuk]

📌 관련 이슈

• closed: [FEAT] 여러 이미지 등록, 조회 구현 #50

✨ PR 세부 내용

1. 주요 변경 사항

1. 단일 image 테이블 도입
   • Guesthouse, Room, Review의 이미지를 (owner_type, owner_id) 로 구분해 한 곳에서 통합 관리
   • 이미지는 객체 소유자 타입 ownerType + 객체 PK ownerId로 구분
2. 배치 업로드 & 자동 정렬 순서 부여
   • Presigned-URL API, 이미지 API 에서 다중 파일명 한 번에 발급
   • 이미지 등록 시 owner별로 그룹핑 후 입력된 순서대로 sort 배정(서버에서 자동 부여)
   • 썸네일은 맨 첫번째로 등록된 이미지가 썸네일이 되도록 지정
3. 이미지 메타 CRUD API
   • POST /images : 한 번에 여러 이미지 등록 가능
   • PUT /images/{ownerType}/{ownerId} : 전체 교체(교체 시 사용되지 않는 S3 객체·DB 레코드 삭제 + 새 이미지 일괄 저장)
   • GET /images : 특정 객체의 이미지 조회 가능. 기존 조회에서 이미지 조회도 같이 하도록 수정해서 딱히 필요는 없음
   • 등록 및 수정 시 한 번에 여러 이미지 등록 가능하도록 batch 처리
4. 생성 API에서 PK(id) 반환
   • 게스트하우스, 객실, 리뷰 생성 시 모두 고유 Id(PK) 반환
   • 반환된 id -> 이미지 등록 시 ownerId에 매핑하여 작동 가능
5. 조회 API에 이미지 합치기
   • 게스트하우스, 객실, 리뷰, 예약 조회 시 관련 이미지도 함께 조회하도록 전반적인 조회 로직 수정
   • 상세 조회
     • 게스트하우스: 모든 이미지 URL 리스트
     • 각 Room: 첫 번째 이미지(썸네일) 1장
   • 홈/검색 리스트: 각 게스트하우스 대표 이미지 1장 포함
   • 객실 상세: 해당 룸의 모든 이미지 URL 리스트
   • 내 예약 목록: 각 예약의 룸별 첫 번째 이미지 1장
6. S3 키 네이밍·정리
   • 객체 키: UUID_ownerType_ownerId_yyyyMMdd… 형식으로 고유 생성
     • s3 구조 관리 및 파일명 중복 막기 위해 uuid + 이미지 소유 테이블 + 테이블 Id + 날짜 조합으로 고유 키 생성
   • 교체·차등 업데이트 시 사용되지 않은 S3 객체는 DeleteObjects 로 일괄 삭제
7. S3 presignedURL
   • presignedURL 파일 형식 입력 및 업로드 제한 삭제
   • presiginedURL API 발급 시 (기존) presignedURL만 제공 -> (변경 후) 원본 파일명, 이미지 URL, presignedURL 모두 제공하여 편의성 증대
   • (기존) 한번에 presignedURL 한 개만 발급 가능 -> (변경 후) 한번에 복수의 presigned-url 발급 가능
8. Swagger/OpenAPI 문서 정리
   • /images 엔드포인트 전체 스펙 추가 및 예시 개선
   • Presigned-URL 쿼리 파라미터(멀티값) 설명 보강
   • 영어 태그 삭제 및 파편하된 태그 통합으로 전반적인 스웨거 가독성 증대
9. 코드 리팩토링
   • 엔티티/DTO에서 구 imageUrl: String 필드 제거, List<String> imageUrls 또는 대표 이미지 필드(첫번째 업로드 이미지)로 대체
   • 각종 불필요한 코드 리팩토링

---

2. 검토 체크리스트 (추가 고려 사항)

• 테스트 보강
  • 배치 등록·정렬 로직, 교체·삭제 흐름에 대한 단위/통합 테스트
  • 잘못된 ownerType/ownerId 처리(404), 중복 업로드(409) 등 예외 시나리오 검증
• 퍼포먼스 검토
  • 대량 조회 시 N+1 방지(이미지 일괄 조회) 확인
  • 이미지 리스트 페이징 필요성 검토
• 모니터링·알림
  • S3 삭제 실패 모니터링
  • 이미지 테이블 크기 및 사용량 경고 설정

✅ 체크리스트

• 빌드 및 테스트 통과
• 주요 기능 정상 동작