[volume-10] Spring Batch 기반 주간/월간 랭킹 시스템 구현 - 윤유탁

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

@@ -2,12 +2,18 @@
 
 import com.loopers.domain.PageResult;
 import com.loopers.domain.ranking.ProductRanking;
+import com.loopers.domain.ranking.RankingPeriod;
 
+import java.time.LocalDate;
 import java.util.Optional;
 
 public interface RankingQueryService {
 
-    PageResult<ProductRanking> getDailyRanking(String date, int page, int size);
+    /**
+     * period 에 따라 일간(Redis) / 주간/월간(MV) 랭킹을 반환한다.
+     * Controller 는 이 단일 진입점만 사용한다.
+     */
+    PageResult<ProductRanking> getRanking(RankingPeriod period, LocalDate baseDate, int page, int size);
 
     Optional<Long> getProductDailyRank(Long productId, String date);
 }

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

@@ -0,0 +1,4 @@
+package com.loopers.domain.ranking;
+
+public interface MonthlyRankingRepository extends PeriodRankingRepository {
+}

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

@@ -0,0 +1,20 @@
+package com.loopers.domain.ranking;
+
+import java.util.List;
+
+public interface PeriodRankingRepository {
+
+    /**
+     * 특정 기간 키(예: "2026-W15", "2026-04") 의 랭킹을 offset/limit 기반으로 조회한다.
+     *
+     * @param periodKey 주간이면 "2026-W15", 월간이면 "2026-04"
+     * @param offset    건너뛸 row 수 (0부터 시작)
+     * @param limit     가져올 row 수
+     */
+    List<ProductRanking> findTopN(String periodKey, long offset, int limit);
+
+    /**
+     * 해당 기간에 저장된 전체 row 수. MV 는 TOP 100 만 저장되므로 최대 100.
+     */
+    long countByPeriod(String periodKey);
+}

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

@@ -0,0 +1,7 @@
+package com.loopers.domain.ranking;
+
+public enum RankingPeriod {
+    DAILY,
+    WEEKLY,
+    MONTHLY
+}

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

@@ -0,0 +1,4 @@
+package com.loopers.domain.ranking;
+
+public interface WeeklyRankingRepository extends PeriodRankingRepository {
+}

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

@@ -0,0 +1,45 @@
+package com.loopers.infrastructure.ranking;
+
+import com.loopers.domain.ranking.MonthlyRankingRepository;
+import com.loopers.domain.ranking.ProductRanking;
+import lombok.RequiredArgsConstructor;
+import org.springframework.jdbc.core.JdbcTemplate;
+import org.springframework.stereotype.Component;
+
+import java.util.List;
+
+@Component
+@RequiredArgsConstructor
+public class MonthlyRankingRepositoryImpl implements MonthlyRankingRepository {
+
+    private static final String SELECT_SQL =
+        "SELECT product_id, score, ranking_position "
+            + "FROM mv_product_rank_monthly "
+            + "WHERE year_month_key = ? "
+            + "ORDER BY ranking_position "
+            + "LIMIT ? OFFSET ?";
+
+    private static final String COUNT_SQL =
+        "SELECT COUNT(*) FROM mv_product_rank_monthly WHERE year_month_key = ?";
+
+    private final JdbcTemplate jdbcTemplate;
+
+    @Override
+    public List<ProductRanking> findTopN(String periodKey, long offset, int limit) {
+        return jdbcTemplate.query(
+            SELECT_SQL,
+            (rs, rowNum) -> new ProductRanking(
+                rs.getLong("product_id"),
+                rs.getDouble("score"),
+                rs.getLong("ranking_position")
+            ),
+            periodKey, limit, offset
+        );
+    }
+
+    @Override
+    public long countByPeriod(String periodKey) {
+        Long count = jdbcTemplate.queryForObject(COUNT_SQL, Long.class, periodKey);
+        return count != null ? count : 0L;
+    }
+}

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

@@ -2,13 +2,20 @@
 
 import com.loopers.application.ranking.RankingQueryService;
 import com.loopers.domain.PageResult;
+import com.loopers.domain.ranking.MonthlyRankingRepository;
+import com.loopers.domain.ranking.PeriodRankingRepository;
 import com.loopers.domain.ranking.ProductRanking;
-import com.loopers.support.redis.RankingKeyConstants;
+import com.loopers.domain.ranking.RankingPeriod;
 import com.loopers.domain.ranking.RankingRepository;
+import com.loopers.domain.ranking.WeeklyRankingRepository;
+import com.loopers.support.redis.RankingKeyConstants;
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.stereotype.Component;
 
+import java.time.LocalDate;
+import java.time.format.DateTimeFormatter;
+import java.time.temporal.IsoFields;
 import java.util.Collections;
 import java.util.List;
 import java.util.Optional;
@@ -18,10 +25,33 @@
 @Component
 public class RankingQueryServiceImpl implements RankingQueryService {
 
+    private static final DateTimeFormatter DAY_FORMAT = DateTimeFormatter.ofPattern("uuuuMMdd");
+
     private final RankingRepository rankingRepository;
+    private final WeeklyRankingRepository weeklyRankingRepository;
+    private final MonthlyRankingRepository monthlyRankingRepository;
+
+    @Override
+    public PageResult<ProductRanking> getRanking(RankingPeriod period, LocalDate baseDate, int page, int size) {
+        return switch (period) {
+            case DAILY -> getDailyRankingFromRedis(baseDate.format(DAY_FORMAT), page, size);
+            case WEEKLY -> getPeriodRanking(weeklyRankingRepository, toYearWeek(baseDate), page, size);
+            case MONTHLY -> getPeriodRanking(monthlyRankingRepository, toYearMonth(baseDate), page, size);
+        };
+    }
 
     @Override
-    public PageResult<ProductRanking> getDailyRanking(String date, int page, int size) {
+    public Optional<Long> getProductDailyRank(Long productId, String date) {
+        try {
+            String key = RankingKeyConstants.dayKey(date);
+            return rankingRepository.getRank(key, productId);
+        } catch (Exception e) {
+            log.warn("[Ranking] Redis 순위 조회 실패, empty 반환: {}", e.getMessage());
+            return Optional.empty();
+        }
+    }
+
+    private PageResult<ProductRanking> getDailyRankingFromRedis(String date, int page, int size) {
         try {
             String key = RankingKeyConstants.dayKey(date);
             long start = (long) page * size;
@@ -38,14 +68,25 @@ public PageResult<ProductRanking> getDailyRanking(String date, int page, int siz
         }
     }
 
-    @Override
-    public Optional<Long> getProductDailyRank(Long productId, String date) {
-        try {
-            String key = RankingKeyConstants.dayKey(date);
-            return rankingRepository.getRank(key, productId);
-        } catch (Exception e) {
-            log.warn("[Ranking] Redis 순위 조회 실패, empty 반환: {}", e.getMessage());
-            return Optional.empty();
-        }
+    private PageResult<ProductRanking> getPeriodRanking(
+        PeriodRankingRepository repository, String periodKey, int page, int size
+    ) {
+        // 주간/월간은 "정확성 > 실시간성" 원칙. Daily(Redis) 의 graceful degradation 과 달리
+        // DB 조회 실패는 그대로 전파하여 사용자/운영자에게 장애를 숨기지 않는다.
+        long offset = (long) page * size;
+        List<ProductRanking> rankings = repository.findTopN(periodKey, offset, size);
+        long totalElements = repository.countByPeriod(periodKey);
+        int totalPages = totalElements == 0 ? 0 : (int) Math.ceil((double) totalElements / size);
+        return new PageResult<>(rankings, page, size, totalElements, totalPages);
+    }
+
+    private static String toYearWeek(LocalDate date) {
+        int year = date.get(IsoFields.WEEK_BASED_YEAR);
+        int week = date.get(IsoFields.WEEK_OF_WEEK_BASED_YEAR);
+        return String.format("%04d-W%02d", year, week);
+    }
+
+    private static String toYearMonth(LocalDate date) {
+        return String.format("%04d-%02d", date.getYear(), date.getMonthValue());
     }
 }

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

@@ -0,0 +1,45 @@
+package com.loopers.infrastructure.ranking;
+
+import com.loopers.domain.ranking.ProductRanking;
+import com.loopers.domain.ranking.WeeklyRankingRepository;
+import lombok.RequiredArgsConstructor;
+import org.springframework.jdbc.core.JdbcTemplate;
+import org.springframework.stereotype.Component;
+
+import java.util.List;
+
+@Component
+@RequiredArgsConstructor
+public class WeeklyRankingRepositoryImpl implements WeeklyRankingRepository {
+
+    private static final String SELECT_SQL =
+        "SELECT product_id, score, ranking_position "
+            + "FROM mv_product_rank_weekly "
+            + "WHERE year_week = ? "
+            + "ORDER BY ranking_position "
+            + "LIMIT ? OFFSET ?";
+
+    private static final String COUNT_SQL =
+        "SELECT COUNT(*) FROM mv_product_rank_weekly WHERE year_week = ?";
+
+    private final JdbcTemplate jdbcTemplate;
+
+    @Override
+    public List<ProductRanking> findTopN(String periodKey, long offset, int limit) {
+        return jdbcTemplate.query(
+            SELECT_SQL,
+            (rs, rowNum) -> new ProductRanking(
+                rs.getLong("product_id"),
+                rs.getDouble("score"),
+                rs.getLong("ranking_position")
+            ),
+            periodKey, limit, offset
+        );
+    }
+
+    @Override
+    public long countByPeriod(String periodKey) {
+        Long count = jdbcTemplate.queryForObject(COUNT_SQL, Long.class, periodKey);
+        return count != null ? count : 0L;
+    }
+}

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

@@ -0,0 +1,70 @@
+package com.loopers.infrastructure.ranking.schema;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.Id;
+import jakarta.persistence.IdClass;
+import jakarta.persistence.Index;
+import jakarta.persistence.Table;
+
+import java.io.Serializable;
+import java.time.Instant;
+import java.util.Objects;
+
+/**
+ * {@code mv_product_rank_monthly} schema-only 매핑.
+ *
+ * <p>runtime 쿼리는 {@code MonthlyRankingRepositoryImpl} 이 JdbcTemplate 으로 수행한다.
+ * 현재 프로젝트는 {@code ddl-auto} 로 DDL 을 관리한다. {@code sql/V12} 는 Flyway 이관 시 참조 스키마.
+ *
+ * <p><b>WARNING</b>: commerce-batch 쪽 Entity, 이 Entity, 참조 SQL 세 곳에서 같은 테이블을 각자 정의한다.
+ * {@link WeeklyRankingMvSchema} 의 WARNING 참조. {@code year_month_key} 네이밍 근거는
+ * commerce-batch 쪽 {@code MonthlyRankingMvSchema} 주석 참조.
+ */
+@Entity
+@Table(
+    name = "mv_product_rank_monthly",
+    indexes = @Index(
+        name = "idx_mv_product_rank_monthly_position",
+        columnList = "year_month_key, ranking_position"
+    )
+)
+@IdClass(MonthlyRankingMvSchema.PK.class)
+public class MonthlyRankingMvSchema {
+
+    @Id
+    @Column(name = "year_month_key", nullable = false, length = 7)
+    private String yearMonth;
+
+    @Id
+    @Column(name = "product_id", nullable = false)
+    private Long productId;
+
+    @Column(name = "ranking_position", nullable = false)
+    private long rankingPosition;
+
+    @Column(name = "score", nullable = false)
+    private double score;
+
+    @Column(name = "created_at", nullable = false)
+    private Instant createdAt;
+
+    protected MonthlyRankingMvSchema() {}
+
+    public static class PK implements Serializable {
+        private String yearMonth;
+        private Long productId;
+
+        @Override
+        public boolean equals(Object o) {
+            if (this == o) return true;
+            if (!(o instanceof PK pk)) return false;
+            return Objects.equals(yearMonth, pk.yearMonth) && Objects.equals(productId, pk.productId);
+        }
+
+        @Override
+        public int hashCode() {
+            return Objects.hash(yearMonth, productId);
+        }
+    }
+}

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

@@ -0,0 +1,72 @@
+package com.loopers.infrastructure.ranking.schema;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.Id;
+import jakarta.persistence.IdClass;
+import jakarta.persistence.Index;
+import jakarta.persistence.Table;
+
+import java.io.Serializable;
+import java.time.Instant;
+import java.util.Objects;
+
+/**
+ * {@code mv_product_rank_weekly} schema-only 매핑.
+ *
+ * <p>runtime 쿼리는 {@code WeeklyRankingRepositoryImpl} 이 JdbcTemplate 으로 수행한다.
+ * 이 클래스는 Hibernate {@code ddl-auto} 가 동일 테이블을 생성할 수 있게 구조만 선언한다.
+ *
+ * <p>현재 프로젝트는 Flyway 를 쓰지 않고 {@code ddl-auto} 로 DDL 을 관리한다.
+ * {@code sql/V10__create_mv_product_rank_weekly.sql} 은 Flyway 이관 시 참조 스키마로 준비된 파일.
+ *
+ * <p><b>WARNING — 3중 정의 주의</b>: 이 Entity 와 (1) commerce-batch 의 동명 Entity, (2) 참조 SQL 이
+ * 같은 테이블을 각자 정의한다. 컬럼/인덱스 변경 시 세 곳을 함께 수정해야 drift 를 막을 수 있다.
+ */
+@Entity
+@Table(
+    name = "mv_product_rank_weekly",
+    indexes = @Index(
+        name = "idx_mv_product_rank_weekly_position",
+        columnList = "year_week, ranking_position"
+    )
+)
+@IdClass(WeeklyRankingMvSchema.PK.class)
+public class WeeklyRankingMvSchema {
+
+    @Id
+    @Column(name = "year_week", nullable = false, length = 10)
+    private String yearWeek;
+
+    @Id
+    @Column(name = "product_id", nullable = false)
+    private Long productId;
+
+    @Column(name = "ranking_position", nullable = false)
+    private long rankingPosition;
+
+    @Column(name = "score", nullable = false)
+    private double score;
+
+    @Column(name = "created_at", nullable = false)
+    private Instant createdAt;
+
+    protected WeeklyRankingMvSchema() {}
+
+    public static class PK implements Serializable {
+        private String yearWeek;
+        private Long productId;
+
+        @Override
+        public boolean equals(Object o) {
+            if (this == o) return true;
+            if (!(o instanceof PK pk)) return false;
+            return Objects.equals(yearWeek, pk.yearWeek) && Objects.equals(productId, pk.productId);
+        }
+
+        @Override
+        public int hashCode() {
+            return Objects.hash(yearWeek, productId);
+        }
+    }
+}