[Volume 5] 상품 목록 조회 성능, 좋아요 수 정렬 구조 개선 및 캐시 적용

CLAUDE.md

@@ -119,7 +119,115 @@ Infrastructure Layer (RepositoryImpl, JpaRepository, Converter)
 - AI는 제안만 가능, 임의 판단 금지
 - 중간 결과 보고 및 개발자 개입 허용
 
+### 의사결정 체크포인트 (필수)
+AI는 아래 시점마다 **반드시 멈추고 개발자에게 승인을 요청**한다. 승인 없이 다음 단계로 진행 금지.
+
+1. **기능 단위 구현 시작 전**: 구현할 내용, 영향 범위, 예상 파일 목록을 보고하고 승인 대기
+2. **설계 방향 결정 시**: 복수 대안이 존재하는 경우 각 대안의 트레이드오프를 제시하고 선택 요청
+3. **기존 코드 수정 시**: 수정 대상 파일과 변경 이유를 명시하고 승인 대기
+4. **테스트 전략 결정 시**: 단위/통합/E2E 중 어떤 테스트를 어떻게 작성할지 제안 후 승인 대기
+
+### 대안 제시 원칙 (필수)
+구현 방식을 결정해야 하는 모든 시점에서 AI는 **독단적으로 선택하지 않는다**.
+반드시 **최소 2개 이상의 대안**을 제시하고 개발자가 선택한 뒤에만 구현을 시작한다.
+
+#### 대안 제시가 필요한 시점
+- 라이브러리/프레임워크 선택 (예: SQL vs QueryDSL, Redis vs in-memory)
+- 구현 패턴 선택 (예: switch vs enum Strategy, 인터페이스 vs 추상 클래스)
+- 데이터 저장 방식 선택 (예: SQL 스크립트 vs CommandLineRunner vs TestFixture)
+- 캐시/동시성/트랜잭션 전략 선택
+- 테스트 방식 선택 (예: Mockito vs TestContainers, 단위 vs 통합)
+- 기타 "어떻게 구현할까"라는 질문이 생기는 모든 순간
+
+#### 대안 제시 형식
+```
+구현 방식을 결정해야 합니다. 아래 대안 중 선택해주세요.
+
+**A: [방법명]**
+- 방식: ...
+- 장점: ...
+- 단점: ...
+
+**B: [방법명]**
+- 방식: ...
+- 장점: ...
+- 단점: ...
+
+(필요 시 C도 추가)
+
+어떤 방식으로 진행할까요?
+```
+
+#### 금지 행동
+- ❌ 대안 제시 없이 AI가 판단한 "더 나은" 방법을 바로 구현하는 행위
+- ❌ 대안을 설명하면서 동시에 구현을 시작하는 행위
+- ❌ "A 방식으로 진행하겠습니다"처럼 AI가 선택을 결론 짓는 행위
+
+### 과정 기록 원칙 (필수)
+
+모든 설계 결정, 실험 과정, 테스트 결과는 **`.idea/volume-{N}-discussion.md`에 기록**한다.
+파일이 없으면 대화 시작 시 생성. 파일이 있으면 기존 내용에 **추가(append)**.
+
+#### 기록 대상 (반드시 기록)
+- 설계 방향 선택, 라이브러리/전략 결정, 트레이드오프 논의
+- 구현 방식 변경 및 변경 이유
+- **테스트 실행 결과** (PASS/FAIL, 수치, EXPLAIN 결과 등) — 결정의 근거로 반드시 첨부
+- 단계적 접근에서 각 단계의 결과와 다음 단계로 넘어간 이유
+- 기각된 대안과 기각 이유
+- **테스트 코드가 이후 삭제/변경되더라도 당시의 실행 기록과 의사결정은 반드시 유지**
+
+#### 기록 형식
+```markdown
+## [날짜] 주제
+
+### 상황
+현재 문제 또는 목표
+
+### 실험/테스트 기록
+- 시도한 방법: ...
+- 실행 결과: (수치, EXPLAIN 출력, 테스트 PASS/FAIL 등)
+- 관찰: ...
+
+### 선택지 비교
+| 항목 | 방법 A | 방법 B |
+|------|--------|--------|
+| 성능 | ... | ... |
+| 복잡도 | ... | ... |
+
+### 결정
+- 선택: 방법 A
+- 이유: (테스트 결과 기반으로 구체적으로)
+
+### 기각된 대안
+- 방법 B: 기각 이유 (근거 포함)
+
+### 다음 단계
+- ...
+```
+
+#### 단계적 구현 원칙
+- 기술 도입은 **가장 단순한 것부터 시작해 점진적으로 고도화**한다
+- 각 단계에서 테스트로 효과를 검증한 뒤 다음 단계로 진행
+- 예: 캐시 → (1) Spring 기본 캐시(in-memory) → (2) TTL 제어 → (3) Redis 분산 캐시
+- 각 단계의 한계를 직접 확인하고 기록한 뒤 다음 단계로 이동
+
+### 커밋 단위 원칙 (필수)
+- **1 논리 단위 = 1 커밋**: 기능 하나, 리팩토링 하나, 테스트 추가 하나를 각각 별도 커밋
+- 금지: 여러 기능/도메인/레이어 변경을 하나의 커밋에 혼합
+- 커밋 메시지 형식: `type(scope): 설명` (예: `feat(product): 상품 목록 인덱스 추가`)
+- 커밋 타이밍: AI가 자의적으로 커밋 실행 금지. 커밋 시점 시 커밋 메세지만 전달.
+
+**커밋 단위 예시 (올바른 분리)**
+```
+feat(product): products 테이블 복합 인덱스 추가
+feat(product): 상품 목록 조회 QueryDSL 필터/정렬 구현
+test(product): 상품 목록 조회 통합 테스트 추가
+feat(cache): 상품 상세 Redis 캐시 적용
+feat(cache): 상품 목록 Redis 캐시 적용
+```
+
 ### Never Do (절대 금지)
+- ❌ 코드에 불필요한 주석 작성 금지 — 로직이 자명하지 않은 경우에만 작성. 클래스/메서드 설명 주석, Phase 설명 주석, 한계 설명 주석 등 코드로 표현 가능한 내용은 모두 금지
 - ❌ 실제 동작하지 않는 코드 작성 금지
 - ❌ null-safety 위반 금지 (Optional 활용)
 - ❌ println 코드 남기지 말 것 (`@Slf4j` 사용)

apps/commerce-api/src/main/java/com/loopers/application/like/LikeApp.java

@@ -5,6 +5,8 @@
 import com.loopers.domain.like.LikeRepository;
 import com.loopers.domain.like.LikeService;
 import lombok.RequiredArgsConstructor;
+import org.springframework.cache.annotation.CacheEvict;
+import org.springframework.cache.annotation.Caching;
 import org.springframework.data.domain.Page;
 import org.springframework.data.domain.Pageable;
 import org.springframework.stereotype.Component;
@@ -17,12 +19,20 @@ public class LikeApp {
     private final LikeService likeService;
     private final LikeRepository likeRepository;
 
+    @Caching(evict = {
+        @CacheEvict(value = "product",  key = "#productId"),
+        @CacheEvict(value = "products", allEntries = true)
+    })
     @Transactional
     public LikeInfo addLike(Long memberId, String productId) {
         LikeModel like = likeService.addLike(memberId, productId);
         return LikeInfo.from(like);
     }
 
+    @Caching(evict = {
+        @CacheEvict(value = "product",  key = "#productId"),
+        @CacheEvict(value = "products", allEntries = true)
+    })
     @Transactional
     public void removeLike(Long memberId, String productId) {
         likeService.removeLike(memberId, productId);

apps/commerce-api/src/main/java/com/loopers/application/product/ProductApp.java

@@ -1,12 +1,16 @@
 package com.loopers.application.product;
 
+import com.loopers.domain.common.cursor.CursorPageResult;
 import com.loopers.domain.product.ProductModel;
 import com.loopers.domain.product.ProductRepository;
 import com.loopers.domain.product.ProductService;
 import com.loopers.domain.product.vo.ProductId;
 import com.loopers.support.error.CoreException;
 import com.loopers.support.error.ErrorType;
 import lombok.RequiredArgsConstructor;
+import org.springframework.cache.annotation.CacheEvict;
+import org.springframework.cache.annotation.Cacheable;
+import org.springframework.cache.annotation.Caching;
 import org.springframework.data.domain.Page;
 import org.springframework.data.domain.Pageable;
 import org.springframework.stereotype.Component;
@@ -20,6 +24,7 @@ public class ProductApp {
 
     private final ProductService productService;
     private final ProductRepository productRepository;
+    private final ProductCacheStore productCacheStore;
 
     @Transactional
     public ProductInfo createProduct(String productId, String brandId, String productName, BigDecimal price, int stockQuantity) {
@@ -29,27 +34,45 @@ public ProductInfo createProduct(String productId, String brandId, String produc
 
     @Transactional(readOnly = true)
     public ProductInfo getProduct(String productId) {
-        ProductModel product = productRepository.findByProductId(new ProductId(productId))
-                .orElseThrow(() -> new CoreException(ErrorType.NOT_FOUND, "해당 ID의 상품이 존재하지 않습니다."));
-        return ProductInfo.from(product);
+        return productCacheStore.get(productId).orElseGet(() -> {
+            ProductModel product = productRepository.findByProductId(new ProductId(productId))
+                    .orElseThrow(() -> new CoreException(ErrorType.NOT_FOUND, "해당 ID의 상품이 존재하지 않습니다."));
+            ProductInfo info = ProductInfo.from(product);
+            productCacheStore.put(productId, info);
+            return info;
+        });
     }
 
+    @CacheEvict(value = "products", allEntries = true)
     @Transactional
     public ProductInfo updateProduct(String productId, String productName, BigDecimal price, int stockQuantity) {
         ProductModel product = productService.updateProduct(productId, productName, price, stockQuantity);
-        return ProductInfo.from(product);
+        ProductInfo info = ProductInfo.from(product);
+        productCacheStore.put(productId, info);
+        return info;
     }
 
+    @Caching(evict = {
+        @CacheEvict(value = "product",  key = "#productId"),
+        @CacheEvict(value = "products", allEntries = true)
+    })
     @Transactional
     public void deleteProduct(String productId) {
         productService.deleteProduct(productId);
     }
 
+    @Cacheable(value = "products", key = "#brandId + ':' + #sortBy + ':' + #pageable.pageNumber + ':' + #pageable.pageSize")
     @Transactional(readOnly = true)
     public Page<ProductInfo> getProducts(String brandId, String sortBy, Pageable pageable) {
         return productService.getProducts(brandId, sortBy, pageable).map(ProductInfo::from);
     }
 
+    @Transactional(readOnly = true)
+    public CursorPageResult<ProductInfo> getProductsByCursor(String brandId, String sortBy, String cursor, int size) {
+        Long refBrandId = productService.resolveRefBrandId(brandId);
+        return productRepository.findProductsByCursor(refBrandId, sortBy, cursor, size).map(ProductInfo::from);
+    }
+
     @Transactional(readOnly = true)
     public ProductInfo getProductByRefId(Long id) {
         ProductModel product = productRepository.findById(id)

apps/commerce-api/src/main/java/com/loopers/application/product/ProductCacheStore.java

@@ -0,0 +1,48 @@
+package com.loopers.application.product;
+
+import org.springframework.data.redis.connection.RedisConnectionFactory;
+import org.springframework.data.redis.core.RedisTemplate;
+import org.springframework.data.redis.serializer.GenericJackson2JsonRedisSerializer;
+import org.springframework.data.redis.serializer.RedisSerializer;
+import org.springframework.data.redis.serializer.StringRedisSerializer;
+import org.springframework.stereotype.Component;
+
+import java.util.Optional;
+import java.util.concurrent.TimeUnit;
+
+@Component
+public class ProductCacheStore {
+
+    private static final String KEY_PREFIX = "product::";
+    private static final long TTL_SECONDS = 60;
+
+    private final RedisTemplate<String, byte[]> redisTemplate;
+    private final GenericJackson2JsonRedisSerializer serializer;
+
+    public ProductCacheStore(RedisConnectionFactory redisConnectionFactory) {
+        this.serializer = new GenericJackson2JsonRedisSerializer();
+        this.redisTemplate = buildRedisTemplate(redisConnectionFactory);
+    }
+
+    public Optional<ProductInfo> get(String productId) {
+        byte[] bytes = redisTemplate.opsForValue().get(KEY_PREFIX + productId);
+        if (bytes == null) {
+            return Optional.empty();
+        }
+        return Optional.of((ProductInfo) serializer.deserialize(bytes));
+    }
+
+    public void put(String productId, ProductInfo productInfo) {
+        byte[] bytes = serializer.serialize(productInfo);
+        redisTemplate.opsForValue().set(KEY_PREFIX + productId, bytes, TTL_SECONDS, TimeUnit.SECONDS);
+    }
+
+    private RedisTemplate<String, byte[]> buildRedisTemplate(RedisConnectionFactory connectionFactory) {
+        RedisTemplate<String, byte[]> template = new RedisTemplate<>();
+        template.setConnectionFactory(connectionFactory);
+        template.setKeySerializer(new StringRedisSerializer());
+        template.setValueSerializer(RedisSerializer.byteArray());
+        template.afterPropertiesSet();
+        return template;
+    }
+}

apps/commerce-api/src/main/java/com/loopers/application/product/ProductFacade.java

@@ -2,6 +2,7 @@
 
 import com.loopers.application.brand.BrandApp;
 import com.loopers.application.brand.BrandInfo;
+import com.loopers.domain.common.cursor.CursorPageResult;
 import lombok.RequiredArgsConstructor;
 import org.springframework.data.domain.Page;
 import org.springframework.data.domain.Pageable;
@@ -40,6 +41,11 @@ public Page<ProductInfo> getProducts(String brandId, String sortBy, Pageable pag
         return products.map(this::enrichProductInfo);
     }
 
+    public CursorPageResult<ProductInfo> getProductsByCursor(String brandId, String sortBy, String cursor, int size) {
+        CursorPageResult<ProductInfo> result = productApp.getProductsByCursor(brandId, sortBy, cursor, size);
+        return result.map(this::enrichProductInfo);
+    }
+
     public ProductInfo getProductByRefId(Long id) {
         ProductInfo product = productApp.getProductByRefId(id);
         return enrichProductInfo(product);

apps/commerce-api/src/main/java/com/loopers/domain/common/cursor/CursorPageResult.java

@@ -0,0 +1,20 @@
+package com.loopers.domain.common.cursor;
+
+import java.util.List;
+import java.util.function.Function;
+
+public record CursorPageResult<T>(
+        List<T> items,
+        String nextCursor,
+        boolean hasNext,
+        int size
+) {
+    public <R> CursorPageResult<R> map(Function<T, R> mapper) {
+        return new CursorPageResult<>(
+                items.stream().map(mapper).toList(),
+                nextCursor,
+                hasNext,
+                size
+        );
+    }
+}

apps/commerce-api/src/main/java/com/loopers/domain/like/LikeService.java

@@ -9,6 +9,7 @@
 import com.loopers.support.error.ErrorType;
 import lombok.RequiredArgsConstructor;
 import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
 
 @Service
 @RequiredArgsConstructor
@@ -17,6 +18,7 @@ public class LikeService {
     private final LikeRepository likeRepository;
     private final ProductRepository productRepository;
 
+    @Transactional
     public LikeModel addLike(Long memberId, String productId) {
         // 상품 존재 확인
         ProductModel product = productRepository.findByProductId(new ProductId(productId))
@@ -45,6 +47,7 @@ public LikeModel addLike(Long memberId, String productId) {
                 });
     }
 
+    @Transactional
     public void removeLike(Long memberId, String productId) {
         // 상품 존재 확인
         ProductModel product = productRepository.findByProductId(new ProductId(productId))

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

@@ -19,7 +19,17 @@
 import java.math.BigDecimal;
 
 @Entity
-@Table(name = "products")
+@Table(
+    name = "products",
+    indexes = {
+        // Q1 likes_desc: 브랜드 필터 + 좋아요 내림차순 + 최신순 보조 정렬
+        @Index(name = "idx_products_brand_like",   columnList = "ref_brand_id, like_count DESC, deleted_at"),
+        // Q2 latest: 브랜드 필터 + 최신순
+        @Index(name = "idx_products_brand_latest", columnList = "ref_brand_id, updated_at DESC, deleted_at"),
+        // Q3 price_asc: 브랜드 필터 + 가격 오름차순
+        @Index(name = "idx_products_brand_price",  columnList = "ref_brand_id, price, deleted_at")
+    }
+)
 @Getter
 public class ProductModel extends BaseEntity {
 

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

@@ -1,5 +1,6 @@
 package com.loopers.domain.product;
 
+import com.loopers.domain.common.cursor.CursorPageResult;
 import com.loopers.domain.product.vo.ProductId;
 import org.springframework.data.domain.Page;
 import org.springframework.data.domain.Pageable;
@@ -16,6 +17,8 @@ public interface ProductRepository {
 
     Page<ProductModel> findProducts(Long refBrandId, String sortBy, Pageable pageable);
 
+    CursorPageResult<ProductModel> findProductsByCursor(Long refBrandId, String sortBy, String cursor, int size);
+
     /**
      * 재고를 차감합니다. 재고가 부족하면 false를 반환합니다.
      * 동시성 제어를 위해 조건부 UPDATE를 사용합니다.

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

@@ -56,14 +56,17 @@ public void deleteProduct(String productId) {
         productRepository.save(product);
     }
 
-    public Page<ProductModel> getProducts(String brandId, String sortBy, Pageable pageable) {
-        // brandId가 제공되면 Brand PK로 변환
-        Long refBrandId = null;
-        if (brandId != null && !brandId.isBlank()) {
-            BrandModel brand = brandRepository.findByBrandId(new BrandId(brandId))
-                    .orElseThrow(() -> new CoreException(ErrorType.NOT_FOUND, "해당 ID의 브랜드가 존재하지 않습니다."));
-            refBrandId = brand.getId();
+    public Long resolveRefBrandId(String brandId) {
+        if (brandId == null || brandId.isBlank()) {
+            return null;
         }
+        BrandModel brand = brandRepository.findByBrandId(new BrandId(brandId))
+                .orElseThrow(() -> new CoreException(ErrorType.NOT_FOUND, "해당 ID의 브랜드가 존재하지 않습니다."));
+        return brand.getId();
+    }
+
+    public Page<ProductModel> getProducts(String brandId, String sortBy, Pageable pageable) {
+        Long refBrandId = resolveRefBrandId(brandId);
         return productRepository.findProducts(refBrandId, sortBy, pageable);
     }