[volume-10] 랭킹 시스템 구현

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

@@ -2,6 +2,10 @@
 
 import com.loopers.domain.product.Product;
 import com.loopers.domain.product.ProductService;
+import com.loopers.domain.ranking.MvProductRankMonthly;
+import com.loopers.domain.ranking.MvProductRankMonthlyRepository;
+import com.loopers.domain.ranking.MvProductRankWeekly;
+import com.loopers.domain.ranking.MvProductRankWeeklyRepository;
 import com.loopers.infrastructure.ranking.RankingRedisRepository;
 import lombok.RequiredArgsConstructor;
 import org.springframework.data.redis.core.ZSetOperations;
@@ -23,16 +27,29 @@ public class RankingFacade {
 
     private final RankingRedisRepository rankingRedisRepository;
     private final ProductService productService;
+    private final MvProductRankWeeklyRepository mvWeeklyRepository;
+    private final MvProductRankMonthlyRepository mvMonthlyRepository;
 
     /**
-     * 날짜 기반 랭킹 목록을 페이징으로 조회한다.
-     * - ZSET에서 상위 N개 productId + score 조회
-     * - productService.findAllByIds()로 일괄 IN 조회 (N+1 방지)
-     * - ZSET에 있지만 삭제된 상품은 결과에서 제외
+     * period(daily|weekly|monthly) 기반으로 랭킹 목록을 조회한다.
+     * - daily (기본값): Redis ZSET 조회 (date 파라미터 기반)
+     * - weekly: mv_product_rank_weekly 조회
+     * - monthly: mv_product_rank_monthly 조회
      *
-     * @param date yyyyMMdd 형식. null 또는 빈 값이면 오늘 날짜 사용.
+     * @param period "daily" | "weekly" | "monthly". null 또는 기타 값이면 "daily" 로 처리.
+     * @param date   yyyyMMdd 형식. period=daily 일 때만 사용. null 이면 오늘.
      */
-    public List<RankingInfo> findRankings(String date, int page, int size) {
+    public List<RankingInfo> findRankings(String period, String date, int page, int size) {
+        if ("weekly".equalsIgnoreCase(period)) {
+            return findWeeklyRankings(page, size);
+        }
+        if ("monthly".equalsIgnoreCase(period)) {
+            return findMonthlyRankings(page, size);
+        }
+        return findDailyRankings(date, page, size);
+    }
+
+    private List<RankingInfo> findDailyRankings(String date, int page, int size) {
         LocalDate targetDate = (date == null || date.isBlank())
             ? LocalDate.now()
             : LocalDate.parse(date, DATE_FORMATTER);
@@ -63,4 +80,48 @@ public List<RankingInfo> findRankings(String date, int page, int size) {
         }
         return result;
     }
+
+    private List<RankingInfo> findWeeklyRankings(int page, int size) {
+        List<MvProductRankWeekly> rows = mvWeeklyRepository.findTop(page, size);
+        if (rows.isEmpty()) {
+            return List.of();
+        }
+        List<Long> productIds = rows.stream().map(MvProductRankWeekly::getProductId).toList();
+        Map<Long, Product> productMap = productService.findAllByIds(productIds).stream()
+            .collect(Collectors.toMap(Product::getId, Function.identity()));
+
+        List<RankingInfo> result = new ArrayList<>();
+        int baseRank = page * size + 1;
+        for (int i = 0; i < rows.size(); i++) {
+            MvProductRankWeekly row = rows.get(i);
+            Product product = productMap.get(row.getProductId());
+            if (product == null) {
+                continue;
+            }
+            result.add(RankingInfo.of(baseRank + i, product, row.getScore()));
+        }
+        return result;
+    }
+
+    private List<RankingInfo> findMonthlyRankings(int page, int size) {
+        List<MvProductRankMonthly> rows = mvMonthlyRepository.findTop(page, size);
+        if (rows.isEmpty()) {
+            return List.of();
+        }
+        List<Long> productIds = rows.stream().map(MvProductRankMonthly::getProductId).toList();
+        Map<Long, Product> productMap = productService.findAllByIds(productIds).stream()
+            .collect(Collectors.toMap(Product::getId, Function.identity()));
+
+        List<RankingInfo> result = new ArrayList<>();
+        int baseRank = page * size + 1;
+        for (int i = 0; i < rows.size(); i++) {
+            MvProductRankMonthly row = rows.get(i);
+            Product product = productMap.get(row.getProductId());
+            if (product == null) {
+                continue;
+            }
+            result.add(RankingInfo.of(baseRank + i, product, row.getScore()));
+        }
+        return result;
+    }
 }

apps/commerce-api/src/main/java/com/loopers/domain/product/ProductMetrics.java

@@ -6,18 +6,24 @@
 import jakarta.persistence.GenerationType;
 import jakarta.persistence.Id;
 import jakarta.persistence.Table;
+import jakarta.persistence.UniqueConstraint;
 import jakarta.persistence.Version;
 import lombok.Getter;
 
+import java.time.LocalDate;
+
 /**
- * 상품 집계 지표 (product_metrics).
- * like_count는 Kafka 이벤트 소비 후 비동기로 갱신된다 (Eventual Consistency).
- * commerce-api: 읽기 전용 조회 (likeCount 표시용)
- * commerce-streamer: 쓰기 (Kafka Consumer가 upsert)
+ * 일별 상품 집계 지표 (product_metrics).
+ * like_count / order_count 는 해당 날짜(date)의 순증감을 기록한다.
+ * commerce-api: 읽기 전용 조회 (오늘 날짜 기준 likeCount 표시용)
+ * commerce-streamer: 쓰기 (Kafka Consumer가 (product_id, date) 기준 upsert)
  */
 @Getter
 @Entity
-@Table(name = "product_metrics")
+@Table(
+    name = "product_metrics",
+    uniqueConstraints = @UniqueConstraint(columnNames = {"product_id", "date"})
+)
 public class ProductMetrics {
 
     @Id
@@ -27,9 +33,12 @@ public class ProductMetrics {
     @Version
     private Long version;
 
-    @Column(name = "product_id", nullable = false, unique = true)
+    @Column(name = "product_id", nullable = false)
     private Long productId;
 
+    @Column(name = "date", nullable = false)
+    private LocalDate date;
+
     @Column(name = "like_count", nullable = false)
     private int likeCount;
 
@@ -39,8 +48,9 @@ public class ProductMetrics {
     protected ProductMetrics() {
     }
 
-    public ProductMetrics(Long productId, int likeCount) {
+    public ProductMetrics(Long productId, LocalDate date, int likeCount) {
         this.productId = productId;
+        this.date = date;
         this.likeCount = likeCount;
         this.orderCount = 0;
     }

apps/commerce-api/src/main/java/com/loopers/domain/ranking/MvProductRankMonthly.java

@@ -0,0 +1,41 @@
+package com.loopers.domain.ranking;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.Id;
+import jakarta.persistence.Table;
+import lombok.Getter;
+
+import java.time.LocalDateTime;
+
+/**
+ * 월간 랭킹 Materialized View (mv_product_rank_monthly).
+ * Spring Batch MonthlyRankingJob 이 집계한 결과를 조회 전용으로 사용한다.
+ */
+@Getter
+@Entity
+@Table(name = "mv_product_rank_monthly")
+public class MvProductRankMonthly {
+
+    @Id
+    @Column(name = "product_id")
+    private Long productId;
+
+    @Column(name = "like_count", nullable = false)
+    private int likeCount;
+
+    @Column(name = "order_count", nullable = false)
+    private int orderCount;
+
+    @Column(name = "score", nullable = false)
+    private double score;
+
+    @Column(name = "ranking_period", nullable = false)
+    private String rankingPeriod;
+
+    @Column(name = "updated_at", nullable = false)
+    private LocalDateTime updatedAt;
+
+    protected MvProductRankMonthly() {
+    }
+}

apps/commerce-api/src/main/java/com/loopers/domain/ranking/MvProductRankMonthlyRepository.java

@@ -0,0 +1,7 @@
+package com.loopers.domain.ranking;
+
+import java.util.List;
+
+public interface MvProductRankMonthlyRepository {
+    List<MvProductRankMonthly> findTop(int page, int size);
+}

apps/commerce-api/src/main/java/com/loopers/domain/ranking/MvProductRankWeekly.java

@@ -0,0 +1,41 @@
+package com.loopers.domain.ranking;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.Id;
+import jakarta.persistence.Table;
+import lombok.Getter;
+
+import java.time.LocalDateTime;
+
+/**
+ * 주간 랭킹 Materialized View (mv_product_rank_weekly).
+ * Spring Batch WeeklyRankingJob 이 집계한 결과를 조회 전용으로 사용한다.
+ */
+@Getter
+@Entity
+@Table(name = "mv_product_rank_weekly")
+public class MvProductRankWeekly {
+
+    @Id
+    @Column(name = "product_id")
+    private Long productId;
+
+    @Column(name = "like_count", nullable = false)
+    private int likeCount;
+
+    @Column(name = "order_count", nullable = false)
+    private int orderCount;
+
+    @Column(name = "score", nullable = false)
+    private double score;
+
+    @Column(name = "year_month_week", nullable = false)
+    private String yearMonthWeek;
+
+    @Column(name = "updated_at", nullable = false)
+    private LocalDateTime updatedAt;
+
+    protected MvProductRankWeekly() {
+    }
+}

apps/commerce-api/src/main/java/com/loopers/domain/ranking/MvProductRankWeeklyRepository.java

@@ -0,0 +1,7 @@
+package com.loopers.domain.ranking;
+
+import java.util.List;
+
+public interface MvProductRankWeeklyRepository {
+    List<MvProductRankWeekly> findTop(int page, int size);
+}

apps/commerce-api/src/main/java/com/loopers/infrastructure/product/ProductMetricsJpaRepository.java

@@ -3,8 +3,9 @@
 import com.loopers.domain.product.ProductMetrics;
 import org.springframework.data.jpa.repository.JpaRepository;
 
+import java.time.LocalDate;
 import java.util.Optional;
 
 public interface ProductMetricsJpaRepository extends JpaRepository<ProductMetrics, Long> {
-    Optional<ProductMetrics> findByProductId(Long productId);
+    Optional<ProductMetrics> findByProductIdAndDate(Long productId, LocalDate date);
 }

apps/commerce-api/src/main/java/com/loopers/infrastructure/product/ProductMetricsRepositoryImpl.java

@@ -5,6 +5,7 @@
 import lombok.RequiredArgsConstructor;
 import org.springframework.stereotype.Component;
 
+import java.time.LocalDate;
 import java.util.Optional;
 
 @RequiredArgsConstructor
@@ -15,6 +16,6 @@ public class ProductMetricsRepositoryImpl implements ProductMetricsRepository {
 
     @Override
     public Optional<ProductMetrics> findByProductId(Long productId) {
-        return productMetricsJpaRepository.findByProductId(productId);
+        return productMetricsJpaRepository.findByProductIdAndDate(productId, LocalDate.now());
     }
 }

apps/commerce-api/src/main/java/com/loopers/infrastructure/ranking/MvProductRankMonthlyJpaRepository.java

@@ -0,0 +1,10 @@
+package com.loopers.infrastructure.ranking;
+
+import com.loopers.domain.ranking.MvProductRankMonthly;
+import org.springframework.data.domain.Page;
+import org.springframework.data.domain.Pageable;
+import org.springframework.data.jpa.repository.JpaRepository;
+
+public interface MvProductRankMonthlyJpaRepository extends JpaRepository<MvProductRankMonthly, Long> {
+    Page<MvProductRankMonthly> findAllByOrderByScoreDesc(Pageable pageable);
+}

apps/commerce-api/src/main/java/com/loopers/infrastructure/ranking/MvProductRankMonthlyRepositoryImpl.java

@@ -0,0 +1,21 @@
+package com.loopers.infrastructure.ranking;
+
+import com.loopers.domain.ranking.MvProductRankMonthly;
+import com.loopers.domain.ranking.MvProductRankMonthlyRepository;
+import lombok.RequiredArgsConstructor;
+import org.springframework.data.domain.PageRequest;
+import org.springframework.stereotype.Component;
+
+import java.util.List;
+
+@RequiredArgsConstructor
+@Component
+public class MvProductRankMonthlyRepositoryImpl implements MvProductRankMonthlyRepository {
+
+    private final MvProductRankMonthlyJpaRepository jpaRepository;
+
+    @Override
+    public List<MvProductRankMonthly> findTop(int page, int size) {
+        return jpaRepository.findAllByOrderByScoreDesc(PageRequest.of(page, size)).getContent();
+    }
+}

apps/commerce-api/src/main/java/com/loopers/infrastructure/ranking/MvProductRankWeeklyJpaRepository.java

@@ -0,0 +1,10 @@
+package com.loopers.infrastructure.ranking;
+
+import com.loopers.domain.ranking.MvProductRankWeekly;
+import org.springframework.data.domain.Page;
+import org.springframework.data.domain.Pageable;
+import org.springframework.data.jpa.repository.JpaRepository;
+
+public interface MvProductRankWeeklyJpaRepository extends JpaRepository<MvProductRankWeekly, Long> {
+    Page<MvProductRankWeekly> findAllByOrderByScoreDesc(Pageable pageable);
+}

apps/commerce-api/src/main/java/com/loopers/infrastructure/ranking/MvProductRankWeeklyRepositoryImpl.java

@@ -0,0 +1,21 @@
+package com.loopers.infrastructure.ranking;
+
+import com.loopers.domain.ranking.MvProductRankWeekly;
+import com.loopers.domain.ranking.MvProductRankWeeklyRepository;
+import lombok.RequiredArgsConstructor;
+import org.springframework.data.domain.PageRequest;
+import org.springframework.stereotype.Component;
+
+import java.util.List;
+
+@RequiredArgsConstructor
+@Component
+public class MvProductRankWeeklyRepositoryImpl implements MvProductRankWeeklyRepository {
+
+    private final MvProductRankWeeklyJpaRepository jpaRepository;
+
+    @Override
+    public List<MvProductRankWeekly> findTop(int page, int size) {
+        return jpaRepository.findAllByOrderByScoreDesc(PageRequest.of(page, size)).getContent();
+    }
+}

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

@@ -23,26 +23,29 @@ public class RankingV1Controller {
     private final RankingFacade rankingFacade;
 
     /**
-     * 날짜 기반 상품 랭킹 목록을 페이징으로 조회한다.
-     * - date 미입력 시 오늘 날짜 기준
+     * 기간(period) 기반 상품 랭킹 목록을 페이징으로 조회한다.
+     * - period: "daily"(기본) | "weekly" | "monthly"
+     * - date: yyyyMMdd 형식. period=daily 일 때 사용. 미입력 시 오늘 날짜.
      * - page는 0-based
      * - 인증 불필요 (공개 API)
      */
     @GetMapping
     public ApiResponse<RankingV1Dto.RankingPageResponse> getRankings(
+        @RequestParam(required = false) String period,
         @RequestParam(required = false) String date,
         @RequestParam(defaultValue = "0") int page,
         @RequestParam(defaultValue = "20") int size
     ) {
-        String targetDate = (date == null || date.isBlank())
-            ? LocalDate.now().format(DATE_FORMATTER)
-            : date;
+        String resolvedPeriod = (period == null || period.isBlank()) ? "daily" : period;
+        String targetDate = "daily".equalsIgnoreCase(resolvedPeriod)
+            ? (date == null || date.isBlank() ? LocalDate.now().format(DATE_FORMATTER) : date)
+            : null;
 
-        List<RankingInfo> rankings = rankingFacade.findRankings(targetDate, page, size);
+        List<RankingInfo> rankings = rankingFacade.findRankings(resolvedPeriod, targetDate, page, size);
         List<RankingV1Dto.RankingResponse> content = rankings.stream()
             .map(RankingV1Dto.RankingResponse::from)
             .toList();
 
-        return ApiResponse.success(new RankingV1Dto.RankingPageResponse(content, targetDate, page, size));
+        return ApiResponse.success(new RankingV1Dto.RankingPageResponse(content, resolvedPeriod, targetDate, page, size));
     }
 }

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

@@ -30,6 +30,7 @@ public static RankingResponse from(RankingInfo info) {
 
     public record RankingPageResponse(
         List<RankingResponse> content,
+        String period,
         String date,
         int page,
         int size