[Comment]: 상품 도메인 주석 추가 (#163)

* [Comment]: ProductController

* [Comment]: ProductService

* [Comment]: ProductImageService

* [Comment]: ProductSyncService

* [Comment]: FileService

* [Comment]: ProductSearchService

* [Comment]: Product

* [Comment]: event 관련

* [Comment]: mapper, document

* [Comment]: repository

* [Fix]: Payment test 오류 해결

Author: eunchan96

src/main/java/com/backend/domain/product/controller/ApiV1ProductController.java

@@ -32,6 +32,12 @@
 
 import java.util.List;
 
+/**
+ * 상품 관련 REST API 컨트롤러
+ * - 경매 상품의 CRUD 작업을 처리
+ * - RDB와 Elasticsearch 기반 검색 기능 제공
+ * - 멀티파트 파일 업로드를 통한 이미지 처리
+ */
 @RestController
 @RequiredArgsConstructor
 public class ApiV1ProductController implements ApiV1ProductControllerDocs {
@@ -40,6 +46,17 @@ public class ApiV1ProductController implements ApiV1ProductControllerDocs {
     private final ProductMapper productMapper;
     private final ProductSearchService productSearchService;
 
+    /**
+     * 상품 등록
+     * - 상품 정보와 이미지를 함께 업로드하여 새 경매 상품 생성
+     * - 이미지는 최소 1개, 최대 5개까지 업로드 가능
+     * - 상품 생성 시 Elasticsearch에도 자동으로 인덱싱됨
+     *
+     * @param request 상품 등록 요청 정보 (JSON)
+     * @param images 상품 이미지 파일 리스트 (최소 1개, 최대 5개)
+     * @param user 현재 로그인한 사용자 정보
+     * @return 생성된 상품의 상세 정보
+     */
     @PostMapping(consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
     @Transactional
     public RsData<ProductResponse> createProduct(
@@ -54,6 +71,21 @@ public RsData<ProductResponse> createProduct(
         return RsData.created("상품이 등록되었습니다", response);
     }
 
+    /**
+     * 상품 목록 조회 (RDB 기반)
+     * - 다양한 필터 조건으로 상품 검색
+     * - QueryDSL을 사용한 동적 쿼리 생성
+     *
+     * @param page 페이지 번호 (1부터 시작, 기본값: 1)
+     * @param size 페이지 크기 (기본값: 20, 최대: 100)
+     * @param keyword 상품명 검색 키워드
+     * @param category 카테고리 ID 배열 (복수 선택 가능)
+     * @param location 거래 지역 배열 (복수 선택 가능)
+     * @param isDelivery 택배 가능 여부 필터
+     * @param status 경매 상태 (BIDDING, BEFORE_START 등)
+     * @param sort 정렬 기준 (LATEST, PRICE_HIGH, PRICE_LOW, ENDING_SOON, POPULAR)
+     * @return 페이징된 상품 목록
+     */
     @GetMapping
     @Transactional(readOnly = true)
     public RsData<PageDto<ProductListItemDto>> getProducts(
@@ -73,6 +105,12 @@ public RsData<PageDto<ProductListItemDto>> getProducts(
         return RsData.ok("상품 목록이 조회되었습니다", response);
     }
 
+    /**
+     * 상품 목록 조회 (Elasticsearch 기반)
+     * - Elasticsearch의 전문 검색 기능 활용
+     * - 한글 형태소 분석(nori analyzer) 지원
+     * - RDB보다 빠른 검색 성능 제공
+     */
     @GetMapping("/es")
     @Transactional(readOnly = true)
     public RsData<PageDto<ProductListItemDto>> getProductsByElasticsearch(
@@ -92,6 +130,14 @@ public RsData<PageDto<ProductListItemDto>> getProductsByElasticsearch(
         return RsData.ok("상품 목록이 조회되었습니다", response);
     }
 
+    /**
+     * 상품 상세 조회
+     * - 특정 상품의 모든 정보를 조회
+     * - 이미지 목록, 판매자 정보 포함
+     *
+     * @param productId 조회할 상품의 ID
+     * @return 상품 상세 정보
+     */
     @GetMapping("/{productId}")
     @Transactional(readOnly = true)
     public RsData<ProductResponse> getProduct(@PathVariable Long productId) {
@@ -101,6 +147,19 @@ public RsData<ProductResponse> getProduct(@PathVariable Long productId) {
         return RsData.ok("상품이 조회되었습니다", response);
     }
 
+    /**
+     * 상품 수정
+     * - 상품 정보 수정 및 이미지 추가/삭제
+     * - 경매 시작 전에만 수정 가능
+     * - 본인의 상품만 수정 가능
+     *
+     * @param productId 수정할 상품의 ID
+     * @param request 수정할 상품 정보 (변경할 필드만 포함)
+     * @param images 추가할 이미지 파일 (선택)
+     * @param deleteImageIds 삭제할 이미지 ID 리스트 (선택)
+     * @param user 현재 로그인한 사용자
+     * @return 수정된 상품 정보
+     */
     @PutMapping(value = "/{productId}", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
     @Transactional
     public RsData<ProductResponse> modifyProduct(
@@ -121,6 +180,15 @@ public RsData<ProductResponse> modifyProduct(
         return RsData.ok("상품이 수정되었습니다", response);
     }
 
+    /**
+     * 상품 삭제
+     * - 경매 시작 전에만 삭제 가능
+     * - 본인의 상품만 삭제 가능
+     * - 관련된 모든 이미지 파일도 함께 삭제됨
+     *
+     * @param productId 삭제할 상품의 ID
+     * @param user 현재 로그인한 사용자
+     */
     @DeleteMapping("/{productId}")
     @Transactional
     public RsData<Void> deleteProduct(
@@ -137,6 +205,14 @@ public RsData<Void> deleteProduct(
         return RsData.ok("상품이 삭제되었습니다");
     }
 
+    /**
+     * 내 상품 목록 조회 (RDB 기반)
+     * - 로그인한 사용자가 등록한 상품 목록 조회
+     * - 판매 상태별 필터링 가능
+     * - 낙찰자 및 리뷰 정보 포함
+     *
+     * @param status 판매 상태 (SELLING, SOLD, FAILED)
+     */
     @GetMapping("/me")
     @Transactional(readOnly = true)
     public RsData<PageDto<MyProductListItemDto>> getMyProducts(
@@ -153,6 +229,11 @@ public RsData<PageDto<MyProductListItemDto>> getMyProducts(
         return RsData.ok("내 상품 목록이 조회되었습니다", response);
     }
 
+    /**
+     * 내 상품 목록 조회 (Elasticsearch 기반)
+     * - Elasticsearch를 활용한 빠른 조회
+     * - 낙찰자 및 리뷰 정보는 RDB에서 별도 조회
+     */
     @GetMapping("/es/me")
     @Transactional(readOnly = true)
     public RsData<PageDto<MyProductListItemDto>> getMyProductsByElasticsearch(
@@ -169,6 +250,15 @@ public RsData<PageDto<MyProductListItemDto>> getMyProductsByElasticsearch(
         return RsData.ok("내 상품 목록이 조회되었습니다", response);
     }
 
+    /**
+     * 특정 회원의 상품 목록 조회 (RDB 기반)
+     * - 다른 회원이 등록한 상품 목록 조회
+     * - 판매 상태별 필터링 가능
+     * - 리뷰 정보 포함
+     * - 회원 프로필 페이지 등에서 사용
+     *
+     * @param memberId 조회할 회원의 ID
+     */
     @GetMapping("/members/{memberId}")
     @Transactional(readOnly = true)
     public RsData<PageDto<ProductListByMemberItemDto>> getProductsByMember(
@@ -186,6 +276,11 @@ public RsData<PageDto<ProductListByMemberItemDto>> getProductsByMember(
         return RsData.ok("%d번 회원 상품 목록이 조회되었습니다".formatted(memberId), response);
     }
 
+    /**
+     * 특정 회원의 상품 목록 조회 (Elasticsearch 기반)
+     * - Elasticsearch를 활용한 빠른 조회
+     * - 리뷰 정보는 RDB에서 별도 조회
+     */
     @GetMapping("/es/members/{memberId}")
     @Transactional(readOnly = true)
     public RsData<PageDto<ProductListByMemberItemDto>> getProductsByMemberAndElasticsearch(

src/main/java/com/backend/domain/product/document/ProductDocument.java

@@ -10,6 +10,34 @@
 
 import java.time.LocalDateTime;
 
+/**
+ * Elasticsearch 상품 문서
+ * - RDB의 Product 엔티티를 검색용으로 최적화한 문서 구조
+ * - 전문 검색, 복잡한 필터링, 빠른 정렬에 사용
+ * - RDB와 실시간 동기화 (이벤트 기반)
+ *
+ * 인덱스 구성:
+ * - 인덱스명: products
+ * - 설정 파일: elasticsearch/product-settings.json (nori analyzer 설정)
+ * - 매핑 파일: elasticsearch/product-mappings.json (필드 타입 정의)
+ *
+ * 한글 검색 최적화:
+ * - nori_analyzer: 한글 형태소 분석기
+ * - 품사 태그 필터링으로 불필요한 조사/어미 제거
+ * - mixed 모드: 복합명사 분해 및 원형 모두 인덱싱
+ *
+ * 주요 검색 필드:
+ * - productName: 상품명 (text)
+ * - location: 거래 지역 (text)
+ * - category: 카테고리 (keyword, exact match)
+ * - status: 경매 상태 (keyword, exact match)
+ *
+ * 정렬 필드:
+ * - createDate: 최신순
+ * - currentPrice: 가격순
+ * - endTime: 마감 임박순
+ * - bidderCount: 인기순
+ */
 @Document(indexName = "products")
 @Setting(settingPath = "elasticsearch/product-settings.json")
 @Mapping(mappingPath = "elasticsearch/product-mappings.json")
@@ -71,8 +99,20 @@ public class ProductDocument {
 
     @Field(type = FieldType.Date, format = DateFormat.date_hour_minute_second)
     private LocalDateTime createDate;
-    
-    // Entity -> Document 변환
+
+    /**
+     * Entity → Document 변환 (정적 팩토리 메서드)
+     * - RDB에서 조회한 Product를 Elasticsearch 문서로 변환
+     * - 인덱싱 및 재인덱싱 시 사용
+     *
+     * 변환 규칙:
+     * - Enum은 name()으로 변환 (category, deliveryMethod)
+     * - 연관 엔티티는 ID와 주요 필드만 추출 (seller)
+     * - 컬렉션은 제외 (bids, productImages)
+     *
+     * @param product 변환할 상품 엔티티
+     * @return Elasticsearch에 저장할 문서
+     */
     public static ProductDocument fromEntity(Product product) {
         return ProductDocument.builder()
                 .id(String.valueOf(product.getId()))

src/main/java/com/backend/domain/product/entity/Product.java

@@ -115,28 +115,13 @@ public Product(String productName, String description, ProductCategory category,
         }
     }
 
-
-    public void addProductImage(ProductImage productImage) {
-        productImages.add(productImage);
-
-        if (thumbnailUrl == null) {
-            this.thumbnailUrl = productImage.getImageUrl();
-        }
-    }
-
-    public String getThumbnail() {
-        if (thumbnailUrl != null) {
-            return thumbnailUrl;
-        }
-
-        thumbnailUrl = productImages.stream()
-                .findFirst()
-                .map(ProductImage::getImageUrl)
-                .orElse(null);
-
-        return thumbnailUrl;
-    }
-
+    /**
+     * 상품 정보 수정
+     * - null이 아닌 필드만 업데이트
+     * - 경매 시작 전에만 수정 가능 (호출 전에 검증 필요)
+     *
+     * @param validatedRequest 검증된 수정 요청 (변경할 필드만 non-null)
+     */
     public void modify(ProductModifyRequest validatedRequest) {
         if (validatedRequest.name() != null) this.productName = validatedRequest.name();
         if (validatedRequest.description() != null) this.description = validatedRequest.description();
@@ -148,31 +133,52 @@ public void modify(ProductModifyRequest validatedRequest) {
         if (validatedRequest.location() != null) this.location = validatedRequest.location();
     }
 
+    // ======================================= image methods ======================================= //
+    public void addProductImage(ProductImage productImage) {
+        productImages.add(productImage);
+
+        // 첫 번째 이미지는 썸네일로 자동 설정
+        if (thumbnailUrl == null) {
+            this.thumbnailUrl = productImage.getImageUrl();
+        }
+    }
+
     public void deleteProductImage(ProductImage productImage) {
         productImages.remove(productImage);
 
+        // 삭제된 이미지가 썸네일이면 null로 설정
         if (thumbnailUrl.equals(productImage.getImageUrl())) {
             thumbnailUrl = null;
         }
     }
 
-    public void checkActorCanModify(Member actor) {
-        if (!actor.equals(seller)) {
-            throw ProductException.accessModifyForbidden();
+    public String getThumbnail() {
+        if (thumbnailUrl != null) {
+            return thumbnailUrl;
         }
-    }
 
-    public void checkActorCanDelete(Member actor) {
-        if (!actor.equals(seller)) {
-            throw ProductException.accessDeleteForbidden();
-        }
+        // 썸네일이 없으면 첫 번째 이미지 찾아서 설정
+        thumbnailUrl = productImages.stream()
+                .findFirst()
+                .map(ProductImage::getImageUrl)
+                .orElse(null);
+
+        return thumbnailUrl;
     }
 
+    // ======================================= bid methods ======================================= //
+    /**
+     * 낙찰자 조회
+     * - 경매가 종료되고 낙찰 상태일 때만 반환
+     * - 현재 최고가와 동일한 입찰가를 가진 입찰자
+     */
     public Member getBidder() {
+        // 낙찰 상태가 아니거나 아직 종료되지 않았으면 null 반환
         if (!status.equals(AuctionStatus.SUCCESSFUL.getDisplayName()) || endTime.isAfter(LocalDateTime.now())) {
             return null;
         }
 
+        // 현재 최고가와 동일한 입찰을 찾아서 입찰자 반환
         return bids.stream()
 //                    .max(Comparator.comparing(Bid::getBidPrice))
                 .filter(bid -> bid.getBidPrice().equals(currentPrice))
@@ -181,20 +187,48 @@ public Member getBidder() {
                 .orElse(null);
     }
 
+    /**
+     * 입찰 추가 및 입찰자 수 업데이트
+     * - 양방향 관계 설정
+     * - 고유 입찰자 수 자동 계산 (동일 회원의 중복 입찰 제거)
+     */
     public void addBid(Bid bid) {
         bids.add(bid);
 
+        // 중복 제거한 입찰자 수 계산
         int _bidderCount = (int) bids.stream()
                 .map(b -> b.getMember().getId())
                 .distinct()
                 .count();
 
+        // 입찰자 수가 변경된 경우에만 업데이트
         if (_bidderCount != bidderCount) {
             bidderCount = _bidderCount;
         }
     }
 
-    // 테스트 전용 (프로덕션에서는 사용 금지)
+    // ======================================= auth methods ======================================= //
+    // 상품 수정 권한 검증 (판매자 본인만 수정 가능)
+    public void checkActorCanModify(Member actor) {
+        if (!actor.equals(seller)) {
+            throw ProductException.accessModifyForbidden();
+        }
+    }
+
+    // 상품 삭제 권한 검증 (판매자 본인만 삭제 가능)
+    public void checkActorCanDelete(Member actor) {
+        if (!actor.equals(seller)) {
+            throw ProductException.accessDeleteForbidden();
+        }
+    }
+
+    // ======================================= other methods ======================================= //
+    /**
+     * 테스트 전용 빌더
+     * - 프로덕션 코드에서는 사용 금지
+     * - ID를 포함한 모든 필드를 직접 설정 가능
+     * - 단위 테스트에서 목 데이터 생성용
+     */
     @Builder(builderMethodName = "testBuilder", buildMethodName = "testBuild")
     private Product(
             Long id, String productName, String description, ProductCategory category,