Feat/이미지 관련 기능 구현

build.gradle

@@ -49,6 +49,11 @@ dependencies {
 
     implementation 'org.springframework.boot:spring-boot-starter-webflux'
 
+    // AWS SDK v2 for S3
+    implementation platform('software.amazon.awssdk:bom:2.21.0')
+    implementation 'software.amazon.awssdk:s3'
+    implementation 'software.amazon.awssdk:auth'
+
     // 스웨거
     implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.8.6'
 

src/main/java/com/pinHouse/server/core/config/S3Config.java

@@ -0,0 +1,38 @@
+package com.pinHouse.server.core.config;
+
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import software.amazon.awssdk.auth.credentials.AwsBasicCredentials;
+import software.amazon.awssdk.auth.credentials.StaticCredentialsProvider;
+import software.amazon.awssdk.regions.Region;
+import software.amazon.awssdk.services.s3.S3Client;
+
+/**
+ * AWS S3 클라이언트 설정 클래스
+ */
+@Configuration
+public class S3Config {
+
+    @Value("${aws.s3.region}")
+    private String region;
+
+    @Value("${aws.s3.access-key}")
+    private String accessKey;
+
+    @Value("${aws.s3.secret-key}")
+    private String secretKey;
+
+    /**
+     * S3Client Bean 생성
+     */
+    @Bean
+    public S3Client s3Client() {
+        AwsBasicCredentials credentials = AwsBasicCredentials.create(accessKey, secretKey);
+
+        return S3Client.builder()
+                .region(Region.of(region))
+                .credentialsProvider(StaticCredentialsProvider.create(credentials))
+                .build();
+    }
+}

src/main/java/com/pinHouse/server/core/exception/code/DiagnosisErrorCode.java

@@ -12,7 +12,7 @@ public enum DiagnosisErrorCode implements ErrorCode {
     // ========================
     // 400 Bad Request
     // ========================
-    BAD_REQUEST_TYPE(400_000,HttpStatus.BAD_REQUEST,"진단 입력 파라미터가 잘못되었습니다");
+    BAD_REQUEST_TYPE(400_000, HttpStatus.BAD_REQUEST, "진단 입력 파라미터가 잘못되었습니다"),
 
     // ========================
     // 401 Unauthorized
@@ -25,6 +25,7 @@ public enum DiagnosisErrorCode implements ErrorCode {
     // ========================
     // 404 Not Found
     // ========================
+    NOT_FOUND_DIAGNOSIS(404_001, HttpStatus.NOT_FOUND, "진단 기록을 찾을 수 없습니다");
 
 
     /**

src/main/java/com/pinHouse/server/core/exception/code/ImageErrorCode.java

@@ -0,0 +1,44 @@
+package com.pinHouse.server.core.exception.code;
+
+import com.pinHouse.server.core.response.response.ErrorCode;
+import lombok.Getter;
+import lombok.RequiredArgsConstructor;
+import org.springframework.http.HttpStatus;
+
+/**
+ * 이미지 관련 예외처리 클래스입니다.
+ */
+@Getter
+@RequiredArgsConstructor
+public enum ImageErrorCode implements ErrorCode {
+
+    // ========================
+    // 400 Bad Request
+    // ========================
+    INVALID_FILE_TYPE(400_301, HttpStatus.BAD_REQUEST, "지원하지 않는 이미지 형식입니다. (jpg, jpeg, png, gif만 가능)"),
+    INVALID_FILE_EXTENSION(400_302, HttpStatus.BAD_REQUEST, "파일 확장자가 유효하지 않습니다."),
+    FILE_SIZE_EXCEEDED(400_303, HttpStatus.BAD_REQUEST, "파일 크기가 5MB를 초과합니다."),
+    INVALID_FILE_NAME(400_304, HttpStatus.BAD_REQUEST, "파일명이 유효하지 않습니다."),
+
+    // ========================
+    // 500 Internal Server Error
+    // ========================
+    S3_PRESIGNED_URL_GENERATION_FAILED(500_301, HttpStatus.INTERNAL_SERVER_ERROR, "이미지 업로드 URL 생성에 실패했습니다."),
+    S3_CLIENT_ERROR(500_302, HttpStatus.INTERNAL_SERVER_ERROR, "S3 서버와 통신 중 오류가 발생했습니다.");
+
+    /**
+     * 에러 코드 (고유값)
+     */
+    private final Integer code;
+
+    /**
+     * HTTP 상태 코드
+     */
+    private final HttpStatus httpStatus;
+
+    /**
+     * 에러 메시지
+     */
+    private final String message;
+
+}

src/main/java/com/pinHouse/server/platform/diagnostic/diagnosis/application/dto/DiagnosisRecommendationGroup.java

@@ -0,0 +1,25 @@
+package com.pinHouse.server.platform.diagnostic.diagnosis.application.dto;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import lombok.Builder;
+
+import java.util.List;
+
+@Builder
+@Schema(name = "[응답][진단] 추천 그룹", description = "추천 임대 유형을 공고 유형별로 묶은 정보")
+public record DiagnosisRecommendationGroup(
+
+        @Schema(description = "공고 유형", example = "통합공공임대")
+        String noticeType,
+
+        @Schema(description = "추천 공급 유형 리스트", example = "[\"청년 특별공급\", \"신혼부부 특별공급\"]")
+        List<String> supplyTypes
+) {
+
+    public static DiagnosisRecommendationGroup of(String noticeType, List<String> supplyTypes) {
+        return DiagnosisRecommendationGroup.builder()
+                .noticeType(noticeType)
+                .supplyTypes(supplyTypes)
+                .build();
+    }
+}

src/main/java/com/pinHouse/server/platform/diagnostic/diagnosis/application/dto/DiagnosisResponseV2.java

@@ -0,0 +1,59 @@
+package com.pinHouse.server.platform.diagnostic.diagnosis.application.dto;
+
+import com.pinHouse.server.platform.diagnostic.rule.domain.entity.EvaluationContext;
+import com.pinHouse.server.platform.diagnostic.rule.domain.entity.SupplyRentalCandidate;
+import io.swagger.v3.oas.annotations.media.Schema;
+import lombok.Builder;
+
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+@Builder
+@Schema(name = "[응답][진단] 청약 진단 결과 v2", description = "추천 임대주택을 공고 유형별로 그룹화한 응답")
+public record DiagnosisResponseV2(
+
+        @Schema(description = "최종 자격 여부 (추천 임대주택이 있는지 여부)", example = "true")
+        boolean eligible,
+
+        @Schema(description = "최종 요약 메시지", example = "추천 임대주택이 있습니다")
+        String decisionMessage,
+
+        @Schema(description = "추천 임대주택 후보 그룹", example = "[{\"noticeType\":\"통합공공임대\",\"supplyTypes\":[\"청년 특별공급\",\"신혼부부 특별공급\"]}]")
+        List<DiagnosisRecommendationGroup> recommended
+) {
+
+    public static DiagnosisResponseV2 from(EvaluationContext context) {
+        List<SupplyRentalCandidate> candidates = context.getCurrentCandidates();
+
+        if (candidates.isEmpty()) {
+            return DiagnosisResponseV2.builder()
+                    .eligible(false)
+                    .decisionMessage("모든 조건 미충족")
+                    .recommended(List.of())
+                    .build();
+        }
+
+        Map<String, List<String>> grouped = new LinkedHashMap<>();
+
+        for (SupplyRentalCandidate candidate : candidates) {
+            String noticeType = candidate.noticeType().getValue();
+            String supplyType = candidate.supplyType().getValue();
+            grouped.computeIfAbsent(noticeType, k -> new ArrayList<>());
+            if (!grouped.get(noticeType).contains(supplyType)) {
+                grouped.get(noticeType).add(supplyType);
+            }
+        }
+
+        List<DiagnosisRecommendationGroup> groups = grouped.entrySet().stream()
+                .map(e -> DiagnosisRecommendationGroup.of(e.getKey(), e.getValue()))
+                .toList();
+
+        return DiagnosisResponseV2.builder()
+                .eligible(true)
+                .decisionMessage("추천 임대주택이 있습니다")
+                .recommended(groups)
+                .build();
+    }
+}

src/main/java/com/pinHouse/server/platform/diagnostic/diagnosis/application/service/DiagnosisService.java

@@ -3,6 +3,7 @@
 import com.pinHouse.server.platform.diagnostic.diagnosis.application.dto.DiagnosisDetailResponse;
 import com.pinHouse.server.platform.diagnostic.diagnosis.application.dto.DiagnosisRequest;
 import com.pinHouse.server.platform.diagnostic.diagnosis.application.dto.DiagnosisResponse;
+import com.pinHouse.server.platform.diagnostic.diagnosis.application.dto.DiagnosisResponseV2;
 import com.pinHouse.server.platform.diagnostic.diagnosis.application.usecase.DiagnosisUseCase;
 import com.pinHouse.server.platform.diagnostic.diagnosis.domain.repository.DiagnosisJpaRepository;
 import com.pinHouse.server.platform.diagnostic.rule.domain.entity.EvaluationContext;
@@ -58,6 +59,17 @@ public DiagnosisResponse diagnose(UUID userId, DiagnosisRequest request) {
         return DiagnosisResponse.from(context);
     }
 
+    @Override
+    @Transactional
+    public DiagnosisResponseV2 diagnoseV2(UUID userId, DiagnosisRequest request) {
+        User user = userService.loadUser(userId);
+        var diagnosis = Diagnosis.of(user, request);
+        Diagnosis entity = repository.save(diagnosis);
+
+        EvaluationContext context = ruleChain.evaluateAll(entity);
+        return DiagnosisResponseV2.from(context);
+    }
+
     /**
      * 나의 최근 청약진단 상세 조회 (입력 정보 + 결과)
      * @param userId    유저ID
@@ -86,4 +98,20 @@ public DiagnosisDetailResponse getDiagnoseDetail(UUID userId) {
         return DiagnosisDetailResponse.from(context);
     }
 
+    @Override
+    @Transactional(readOnly = true)
+    public DiagnosisResponseV2 getDiagnoseSummaryV2(UUID userId) {
+        User user = userService.loadUser(userId);
+
+        Diagnosis diagnosis = repository.findTopByUserOrderByCreatedAtDesc(user)
+                .orElse(null);
+
+        if (diagnosis == null) {
+            return null;
+        }
+
+        EvaluationContext context = ruleChain.evaluateAll(diagnosis);
+        return DiagnosisResponseV2.from(context);
+    }
+
 }

src/main/java/com/pinHouse/server/platform/diagnostic/diagnosis/application/usecase/DiagnosisUseCase.java

@@ -3,6 +3,7 @@
 import com.pinHouse.server.platform.diagnostic.diagnosis.application.dto.DiagnosisDetailResponse;
 import com.pinHouse.server.platform.diagnostic.diagnosis.application.dto.DiagnosisRequest;
 import com.pinHouse.server.platform.diagnostic.diagnosis.application.dto.DiagnosisResponse;
+import com.pinHouse.server.platform.diagnostic.diagnosis.application.dto.DiagnosisResponseV2;
 
 import java.util.UUID;
 
@@ -11,7 +12,13 @@ public interface DiagnosisUseCase {
     /// 청약 진단하기 (결과만 반환)
     DiagnosisResponse diagnose(UUID userId, DiagnosisRequest request);
 
+    /// 청약 진단하기 v2 (그룹화 응답)
+    DiagnosisResponseV2 diagnoseV2(UUID userId, DiagnosisRequest request);
+
     /// 최근 진단 상세 조회하기 (입력 정보 + 결과)
     DiagnosisDetailResponse getDiagnoseDetail(UUID userId);
 
+    /// 청약 진단 결과 v2 (추천 그룹화)
+    DiagnosisResponseV2 getDiagnoseSummaryV2(UUID userId);
+
 }

src/main/java/com/pinHouse/server/platform/diagnostic/diagnosis/presentation/DiagnosisApi.java

@@ -4,6 +4,7 @@
 import com.pinHouse.server.core.response.response.ApiResponse;
 import com.pinHouse.server.platform.diagnostic.diagnosis.application.dto.DiagnosisDetailResponse;
 import com.pinHouse.server.platform.diagnostic.diagnosis.application.dto.DiagnosisResponse;
+import com.pinHouse.server.platform.diagnostic.diagnosis.application.dto.DiagnosisResponseV2;
 import com.pinHouse.server.platform.diagnostic.diagnosis.application.usecase.DiagnosisUseCase;
 import com.pinHouse.server.platform.diagnostic.diagnosis.presentation.swagger.DiagnosisApiSpec;
 import com.pinHouse.server.platform.diagnostic.diagnosis.application.dto.DiagnosisRequest;
@@ -13,7 +14,7 @@
 import org.springframework.web.bind.annotation.*;
 
 @RestController
-@RequestMapping("/v1/diagnosis")
+@RequestMapping({"/v1/diagnosis", "/v2/diagnosis"})
 @RequiredArgsConstructor
 public class DiagnosisApi implements DiagnosisApiSpec {
 
@@ -36,6 +37,20 @@ public ApiResponse<DiagnosisResponse> diagnosis(@AuthenticationPrincipal Princip
         return ApiResponse.ok(response);
     }
 
+    /**
+     * 청약 진단 v2 (추천 그룹화 응답)
+     */
+    @PostMapping(path = "", params = "v=2")
+    public ApiResponse<DiagnosisResponseV2> diagnosisV2(@AuthenticationPrincipal PrincipalDetails principalDetails,
+                                                   @RequestBody DiagnosisRequest request) {
+
+        /// 서비스
+        DiagnosisResponseV2 response = service.diagnoseV2(principalDetails.getId(), request);
+
+        /// 리턴
+        return ApiResponse.ok(response);
+    }
+
     /**
      * 최근 진단 결과 상세 조회 (입력 정보 + 결과)
      *
@@ -52,4 +67,14 @@ public ApiResponse<DiagnosisDetailResponse> getLatestDiagnosis(@AuthenticationPr
         /// 리턴
         return ApiResponse.ok(response);
     }
+
+    /**
+     * 최근 진단 결과 v2 (추천 그룹화)
+     */
+    @GetMapping(path = "/latest", params = "v=2")
+    @CheckLogin
+    public ApiResponse<DiagnosisResponseV2> getLatestDiagnosisV2(@AuthenticationPrincipal PrincipalDetails principalDetails) {
+        DiagnosisResponseV2 response = service.getDiagnoseSummaryV2(principalDetails.getId());
+        return ApiResponse.ok(response);
+    }
 }

src/main/java/com/pinHouse/server/platform/diagnostic/diagnosis/presentation/swagger/DiagnosisApiSpec.java

@@ -4,6 +4,7 @@
 import com.pinHouse.server.platform.diagnostic.diagnosis.application.dto.DiagnosisDetailResponse;
 import com.pinHouse.server.platform.diagnostic.diagnosis.application.dto.DiagnosisRequest;
 import com.pinHouse.server.platform.diagnostic.diagnosis.application.dto.DiagnosisResponse;
+import com.pinHouse.server.platform.diagnostic.diagnosis.application.dto.DiagnosisResponseV2;
 import com.pinHouse.server.security.oauth2.domain.PrincipalDetails;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.tags.Tag;
@@ -20,10 +21,23 @@ public interface DiagnosisApiSpec {
     ApiResponse<DiagnosisResponse> diagnosis(@AuthenticationPrincipal PrincipalDetails principalDetails,
                                              @RequestBody DiagnosisRequest requestDTO);
 
+    @Operation(
+            summary = "청약 진단 API v2",
+            description = "청약 진단을 수행하고 추천 결과를 공고 유형별로 그룹화한 v2 응답을 반환합니다."
+    )
+    ApiResponse<DiagnosisResponseV2> diagnosisV2(@AuthenticationPrincipal PrincipalDetails principalDetails,
+                                             @RequestBody DiagnosisRequest requestDTO);
+
     @Operation(
             summary = "최근 진단 결과 상세 조회 API",
             description = "사용자의 최근 진단 결과를 입력 정보와 함께 상세하게 조회합니다."
     )
     ApiResponse<DiagnosisDetailResponse> getLatestDiagnosis(@AuthenticationPrincipal PrincipalDetails principalDetails);
 
+    @Operation(
+            summary = "최근 진단 결과 조회 API v2",
+            description = "추천 임대주택을 공고 유형별로 그룹화하여 반환합니다."
+    )
+    ApiResponse<DiagnosisResponseV2> getLatestDiagnosisV2(@AuthenticationPrincipal PrincipalDetails principalDetails);
+
 }

src/main/java/com/pinHouse/server/platform/home/application/dto/HomeNoticeListResponse.java

@@ -12,6 +12,9 @@ public record HomeNoticeListResponse(
         @Schema(description = "공통 지역", example = "성남시")
         String region,
 
+        @Schema(description = "목록 설명/출처", example = "진단 기반 추천")
+        String title,
+
         @Schema(description = "공고 목록")
         List<HomeNoticeResponse> content,