feat: 상품 랭킹 API 구현 및 DTO 클래스 추가

Author: rnqhstmd

apps/commerce-api/src/main/java/com/loopers/interfaces/api/ranking/RankingV1ApiSpec.java

@@ -0,0 +1,52 @@
+package com.loopers.interfaces.api.ranking;
+
+import com.loopers.interfaces.api.ApiResponse;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+
+@Tag(name = "Ranking API", description = "상품 랭킹 API")
+public interface RankingV1ApiSpec {
+
+    @Operation(summary = "랭킹 페이지 조회", description = "일간 상품 랭킹을 페이지로 조회합니다.")
+    @ApiResponses(value = {
+            @io.swagger.v3.oas.annotations.responses.ApiResponse(
+                    responseCode = "200",
+                    description = "조회 성공",
+                    content = @Content(schema = @Schema(implementation = RankingV1Dto.RankingPageResponse.class))
+            )
+    })
+    @GetMapping
+    ApiResponse<RankingV1Dto.RankingPageResponse> getRankings(
+            @Parameter(description = "날짜 (yyyyMMdd 형식, 기본값: 오늘)")
+            @RequestParam(required = false) String date,
+
+            @Parameter(description = "페이지 번호 (0부터 시작)")
+            @RequestParam(defaultValue = "0") int page,
+
+            @Parameter(description = "페이지 크기")
+            @RequestParam(defaultValue = "20") int size
+    );
+
+    @Operation(summary = "Top-N 랭킹 조회", description = "오늘의 Top-N 상품을 조회합니다.")
+    @ApiResponses(value = {
+            @io.swagger.v3.oas.annotations.responses.ApiResponse(
+                    responseCode = "200",
+                    description = "조회 성공",
+                    content = @Content(schema = @Schema(implementation = RankingV1Dto.TopNResponse.class))
+            )
+    })
+    @GetMapping("/top")
+    ApiResponse<RankingV1Dto.TopNResponse> getTopN(
+            @Parameter(description = "날짜 (yyyyMMdd 형식, 기본값: 오늘)")
+            @RequestParam(required = false) String date,
+
+            @Parameter(description = "조회할 상위 N개")
+            @RequestParam(defaultValue = "10") int n
+    );
+}

apps/commerce-api/src/main/java/com/loopers/interfaces/api/ranking/RankingV1Controller.java

@@ -0,0 +1,45 @@
+package com.loopers.interfaces.api.ranking;
+
+import com.loopers.application.ranking.RankingCommand;
+import com.loopers.application.ranking.RankingFacade;
+import com.loopers.application.ranking.RankingPageInfo;
+import com.loopers.domain.ranking.RankingInfo;
+import com.loopers.interfaces.api.ApiResponse;
+import lombok.RequiredArgsConstructor;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.time.LocalDate;
+import java.time.format.DateTimeFormatter;
+import java.util.List;
+
+@RestController
+@RequestMapping("/api/v1/rankings")
+@RequiredArgsConstructor
+public class RankingV1Controller implements RankingV1ApiSpec {
+
+    private final RankingFacade rankingFacade;
+
+    private static final DateTimeFormatter DATE_FORMATTER = DateTimeFormatter.ofPattern("yyyyMMdd");
+
+    @Override
+    public ApiResponse<RankingV1Dto.RankingPageResponse> getRankings(String date, int page, int size) {
+        RankingCommand command = RankingCommand.of(date, page, size);
+        RankingPageInfo pageInfo = rankingFacade.getRankingPage(command);
+        return ApiResponse.success(RankingV1Dto.RankingPageResponse.from(pageInfo));
+    }
+
+    @Override
+    public ApiResponse<RankingV1Dto.TopNResponse> getTopN(String date, int n) {
+        LocalDate targetDate = parseDate(date);
+        List<RankingInfo> rankings = rankingFacade.getTopN(targetDate, n);
+        return ApiResponse.success(RankingV1Dto.TopNResponse.of(rankings, targetDate));
+    }
+
+    private LocalDate parseDate(String date) {
+        if (date == null || date.isBlank()) {
+            return LocalDate.now();
+        }
+        return LocalDate.parse(date, DATE_FORMATTER);
+    }
+}

apps/commerce-api/src/main/java/com/loopers/interfaces/api/ranking/RankingV1Dto.java

@@ -0,0 +1,71 @@
+package com.loopers.interfaces.api.ranking;
+
+import com.loopers.application.ranking.RankingPageInfo;
+import com.loopers.domain.ranking.RankingInfo;
+
+import java.time.LocalDate;
+import java.time.format.DateTimeFormatter;
+import java.util.List;
+
+public class RankingV1Dto {
+
+    private static final DateTimeFormatter DATE_FORMATTER = DateTimeFormatter.ofPattern("yyyyMMdd");
+
+    public record RankingPageResponse(
+            List<RankingItemResponse> rankings,
+            String date,
+            int page,
+            int size,
+            Long totalCount,
+            int totalPages
+    ) {
+        public static RankingPageResponse from(RankingPageInfo info) {
+            List<RankingItemResponse> items = info.rankings().stream()
+                    .map(RankingItemResponse::from)
+                    .toList();
+
+            return new RankingPageResponse(
+                    items,
+                    info.date().format(DATE_FORMATTER),
+                    info.page(),
+                    info.size(),
+                    info.totalCount(),
+                    info.totalPages()
+            );
+        }
+    }
+
+    public record RankingItemResponse(
+            Long productId,
+            String productName,
+            Long price,
+            String brandName,
+            Long rank,
+            Double score
+    ) {
+        public static RankingItemResponse from(RankingInfo info) {
+            return new RankingItemResponse(
+                    info.productId(),
+                    info.productName(),
+                    info.price(),
+                    info.brandName(),
+                    info.rank(),
+                    info.score()
+            );
+        }
+    }
+
+    public record TopNResponse(
+            List<RankingItemResponse> rankings,
+            String date,
+            int size
+    ) {
+        public static TopNResponse of(List<RankingInfo> rankings, LocalDate date) {
+            List<RankingItemResponse> items = rankings.stream()
+                    .map(RankingItemResponse::from)
+                    .toList();
+
+            return new TopNResponse(items, date.format(DATE_FORMATTER), items.size());
+        }
+    }
+}