feat: 랭킹 조회 API에 기간별 지원 추가

Author: rnqhstmd

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

@@ -13,7 +13,7 @@
 @Tag(name = "Ranking API", description = "상품 랭킹 API")
 public interface RankingV1ApiSpec {
 
-    @Operation(summary = "랭킹 페이지 조회", description = "일간 상품 랭킹을 페이지로 조회합니다.")
+    @Operation(summary = "랭킹 페이지 조회", description = "일간/주간/월간 상품 랭킹을 페이지로 조회합니다.")
     @ApiResponses(value = {
             @io.swagger.v3.oas.annotations.responses.ApiResponse(
                     responseCode = "200",
@@ -26,14 +26,17 @@ ApiResponse<RankingV1Dto.RankingPageResponse> getRankings(
             @Parameter(description = "날짜 (yyyyMMdd 형식, 기본값: 오늘)")
             @RequestParam(required = false) String date,
 
+            @Parameter(description = "기간 (daily, weekly, monthly)")
+            @RequestParam(defaultValue = "daily") String period,
+
             @Parameter(description = "페이지 번호 (0부터 시작)")
             @RequestParam(defaultValue = "0") int page,
 
             @Parameter(description = "페이지 크기")
             @RequestParam(defaultValue = "20") int size
     );
 
-    @Operation(summary = "Top-N 랭킹 조회", description = "오늘의 Top-N 상품을 조회합니다.")
+    @Operation(summary = "Top-N 랭킹 조회", description = "일간/주간/월간 Top-N 상품을 조회합니다.")
     @ApiResponses(value = {
             @io.swagger.v3.oas.annotations.responses.ApiResponse(
                     responseCode = "200",
@@ -46,6 +49,9 @@ ApiResponse<RankingV1Dto.TopNResponse> getTopN(
             @Parameter(description = "날짜 (yyyyMMdd 형식, 기본값: 오늘)")
             @RequestParam(required = false) String date,
 
+            @Parameter(description = "기간 (daily, weekly, monthly)")
+            @RequestParam(defaultValue = "daily") String period,
+
             @Parameter(description = "조회할 상위 N개")
             @RequestParam(defaultValue = "10") int n
     );

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

@@ -4,6 +4,7 @@
 import com.loopers.application.ranking.RankingFacade;
 import com.loopers.application.ranking.RankingPageInfo;
 import com.loopers.domain.ranking.RankingInfo;
+import com.loopers.domain.ranking.RankingPeriod;
 import com.loopers.interfaces.api.ApiResponse;
 import lombok.RequiredArgsConstructor;
 import org.springframework.web.bind.annotation.RequestMapping;
@@ -23,17 +24,18 @@ public class RankingV1Controller implements RankingV1ApiSpec {
     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);
+    public ApiResponse<RankingV1Dto.RankingPageResponse> getRankings(String date, String period, int page, int size) {
+        RankingCommand command = RankingCommand.of(date, period, page, size);
         RankingPageInfo pageInfo = rankingFacade.getRankingPage(command);
         return ApiResponse.success(RankingV1Dto.RankingPageResponse.from(pageInfo));
     }
 
     @Override
-    public ApiResponse<RankingV1Dto.TopNResponse> getTopN(String date, int n) {
+    public ApiResponse<RankingV1Dto.TopNResponse> getTopN(String date, String period, int n) {
         LocalDate targetDate = parseDate(date);
-        List<RankingInfo> rankings = rankingFacade.getTopN(targetDate, n);
-        return ApiResponse.success(RankingV1Dto.TopNResponse.of(rankings, targetDate));
+        RankingPeriod rankingPeriod = parsePeriod(period);
+        List<RankingInfo> rankings = rankingFacade.getTopN(targetDate, rankingPeriod, n);
+        return ApiResponse.success(RankingV1Dto.TopNResponse.of(rankings, targetDate, rankingPeriod));
     }
 
     private LocalDate parseDate(String date) {
@@ -42,4 +44,15 @@ private LocalDate parseDate(String date) {
         }
         return LocalDate.parse(date, DATE_FORMATTER);
     }
+
+    private RankingPeriod parsePeriod(String period) {
+        if (period == null || period.isBlank()) {
+            return RankingPeriod.DAILY;
+        }
+        try {
+            return RankingPeriod.valueOf(period.toUpperCase());
+        } catch (IllegalArgumentException e) {
+            return RankingPeriod.DAILY;
+        }
+    }
 }

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

@@ -2,6 +2,7 @@
 
 import com.loopers.application.ranking.RankingPageInfo;
 import com.loopers.domain.ranking.RankingInfo;
+import com.loopers.domain.ranking.RankingPeriod;
 
 import java.time.LocalDate;
 import java.time.format.DateTimeFormatter;
@@ -14,6 +15,7 @@ public class RankingV1Dto {
     public record RankingPageResponse(
             List<RankingItemResponse> rankings,
             String date,
+            String period,
             int page,
             int size,
             Long totalCount,
@@ -27,6 +29,7 @@ public static RankingPageResponse from(RankingPageInfo info) {
             return new RankingPageResponse(
                     items,
                     info.date().format(DATE_FORMATTER),
+                    info.period().name().toLowerCase(),
                     info.page(),
                     info.size(),
                     info.totalCount(),
@@ -58,14 +61,24 @@ public static RankingItemResponse from(RankingInfo info) {
     public record TopNResponse(
             List<RankingItemResponse> rankings,
             String date,
+            String period,
             int size
     ) {
-        public static TopNResponse of(List<RankingInfo> rankings, LocalDate date) {
+        public static TopNResponse of(List<RankingInfo> rankings, LocalDate date, RankingPeriod period) {
             List<RankingItemResponse> items = rankings.stream()
                     .map(RankingItemResponse::from)
                     .toList();
 
-            return new TopNResponse(items, date.format(DATE_FORMATTER), items.size());
+            return new TopNResponse(
+                    items,
+                    date.format(DATE_FORMATTER),
+                    period.name().toLowerCase(),
+                    items.size()
+            );
+        }
+
+        public static TopNResponse of(List<RankingInfo> rankings, LocalDate date) {
+            return of(rankings, date, RankingPeriod.DAILY);
         }
     }
 }