feature: 상품 랭킹 API 구현

- `RankingFacade` 및 `RankingService` 추가로 상품 랭킹 조회 로직 구현
- Redis 기반 랭킹 데이터 처리 및 상품 상세 정보 매핑 지원
- `RankingV1Controller`와 `RankingV1ApiSpec` 추가로 REST API 제공
- `RankingV1Dto`와 `RankingInfo` 구현으로 응답 데이터 구조화

Author: yeonjiyeon

apps/commerce-api/src/main/java/com/loopers/application/rank/RankingFacade.java

@@ -0,0 +1,42 @@
+package com.loopers.application.rank;
+
+import com.loopers.domain.product.Product;
+import com.loopers.domain.product.ProductService;
+import com.loopers.domain.rank.RankingService;
+import java.util.List;
+import java.util.Map;
+import java.util.stream.Collectors;
+import java.util.stream.IntStream;
+import lombok.RequiredArgsConstructor;
+import org.springframework.stereotype.Component;
+
+@RequiredArgsConstructor
+@Component
+public class RankingFacade {
+
+  private final RankingService rankingService;
+  private final ProductService productService;
+
+  public List<RankingInfo> getTopRankings(String date, int page, int size) {
+    List<Long> productIds = rankingService.getTopRankingIds(date, page, size);
+
+    if (productIds.isEmpty()) {
+      return List.of();
+    }
+
+    List<Product> products = productService.getProducts(productIds);
+    Map<Long, Product> productMap = products.stream()
+        .collect(Collectors.toMap(Product::getId, p -> p));
+
+    return IntStream.range(0, productIds.size())
+        .mapToObj(i -> {
+          Long productId = productIds.get(i);
+          Product product = productMap.get(productId);
+
+          int currentRank = ((page - 1) * size) + i + 1;
+
+          return RankingInfo.of(product, currentRank);
+        })
+        .toList();
+  }
+}

apps/commerce-api/src/main/java/com/loopers/application/rank/RankingInfo.java

@@ -0,0 +1,22 @@
+package com.loopers.application.rank;
+
+import com.loopers.domain.product.Product;
+
+public record RankingInfo(
+    Long productId,
+    String productName,
+    Long price,
+    int stock,
+    int currentRank
+) {
+
+  public static RankingInfo of(Product product, int currentRank) {
+    return new RankingInfo(
+        product.getId(),
+        product.getName(),
+        product.getPrice().getValue(),
+        product.getStock(),
+        currentRank
+    );
+  }
+}

apps/commerce-api/src/main/java/com/loopers/domain/rank/RankingService.java

@@ -0,0 +1,30 @@
+package com.loopers.domain.rank;
+
+import java.util.List;
+import java.util.Set;
+import lombok.RequiredArgsConstructor;
+import org.springframework.data.redis.core.RedisTemplate;
+import org.springframework.stereotype.Component;
+
+@Component
+@RequiredArgsConstructor
+public class RankingService {
+
+  private final RedisTemplate<String, String> redisTemplate;
+
+  public List<Long> getTopRankingIds(String date, int page, int size) {
+    String key = "ranking:all:" + date;
+    int start = (page - 1) * size;
+    int end = start + size - 1;
+
+    Set<String> rankedIds = redisTemplate.opsForZSet().reverseRange(key, start, end);
+
+    if (rankedIds == null || rankedIds.isEmpty()) {
+      return List.of();
+    }
+
+    return rankedIds.stream()
+        .map(Long::valueOf)
+        .toList();
+  }
+}

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

@@ -0,0 +1,19 @@
+package com.loopers.interfaces.api.rank;
+
+import com.loopers.interfaces.api.ApiResponse;
+import com.loopers.interfaces.api.rank.RankingV1Dto.RankingResponse;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import java.util.List;
+
+@Tag(name = "Ranking API", description = "실시간 상품 랭킹 관련 API 입니다.")
+public interface RankingV1ApiSpec {
+
+  @Operation(summary = "실시간 랭킹 조회", description = "특정 날짜의 인기 상품 랭킹을 조회합니다.")
+  ApiResponse<List<RankingResponse>> getRankings(
+      @Parameter(description = "조회 날짜 (yyyyMMdd)", example = "20251225") String date,
+      @Parameter(description = "페이지 번호") int page,
+      @Parameter(description = "페이지 크기") int size
+  );
+}

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

@@ -0,0 +1,35 @@
+package com.loopers.interfaces.api.rank;
+
+import com.loopers.application.rank.RankingFacade;
+import com.loopers.application.rank.RankingInfo;
+import com.loopers.interfaces.api.ApiResponse;
+import com.loopers.interfaces.api.rank.RankingV1Dto.RankingResponse;
+import java.util.List;
+import lombok.RequiredArgsConstructor;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+
+@RequiredArgsConstructor
+@RestController
+@RequestMapping("/api/v1/rankings")
+public class RankingV1Controller implements RankingV1ApiSpec {
+
+  private final RankingFacade rankingFacade;
+
+  @GetMapping
+  @Override
+  public ApiResponse<List<RankingResponse>> getRankings(
+      @RequestParam(value = "date") String date,
+      @RequestParam(value = "page", defaultValue = "1") int page,
+      @RequestParam(value = "size", defaultValue = "20") int size
+  ) {
+    List<RankingInfo> infos = rankingFacade.getTopRankings(date, page, size);
+    List<RankingV1Dto.RankingResponse> response = infos.stream()
+        .map(RankingV1Dto.RankingResponse::from)
+        .toList();
+
+    return ApiResponse.success(response);
+  }
+}

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

@@ -0,0 +1,25 @@
+package com.loopers.interfaces.api.rank;
+
+import com.loopers.application.rank.RankingInfo;
+
+public record RankingV1Dto() {
+
+  public record RankingResponse(
+      Long productId,
+      String productName,
+      Long price,
+      int stock,
+      int currentRank
+  ) {
+
+    public static RankingResponse from(RankingInfo info) {
+      return new RankingResponse(
+          info.productId(),
+          info.productName(),
+          info.price(),
+          info.stock(),
+          info.currentRank()
+          );
+    }
+  }
+}