feat(report): 신고 조회 및 검색 API 구현, 성능 최적화 refs #17 #29

[DDINGJOO]

목적

• 신고 시스템의 핵심 기능인 신고 조회 및 관리 API를 구현하고, 성능 최적화를 위한 캐싱 및 커서 기반 페이징 처리를 적용했습니다.
• 관련 Story: [STORY] 게시글 신고 기능 #4 [STORY] 게시글 신고 기능, [STORY] 프로필 신고 기능 #5 [STORY] 프로필 신고 기능, [STORY] 신고 조회 및 관리 #6 [STORY] 신고 조회 및 관리, [STORY] 신고 시스템 확장 기능 구현 #29 [STORY] 신고 시스템 확장 기능 구현
• 관련 Task: [TASK] 프로필 신고 API 구현 #16 [TASK] 프로필 신고 API 구현, [TASK] 신고 조회 API 구현 #17 [TASK] 신고 조회 API 구현

변경 요약

핵심 기능

1. 신고 검색 및 조회 API 구현 ([STORY] 신고 조회 및 관리 #6, [TASK] 신고 조회 API 구현 #17)

   • 필터링: 상태, 카테고리 타입(ReferenceType), 신고 카테고리
   • 정렬: 상태별, 신고일별 (ASC/DESC)
   • 커서 기반 페이징 처리로 대용량 데이터 성능 최적화
   • 신고 상세 조회 API

2. 신고 상태 변경 관리 ([STORY] 신고 조회 및 관리 #6)

   • 승인(APPROVED), 거절(REJECTED), 검토 시작(REVIEWING), 보류(PENDING), 철회(WITHDRAWN)
   • 상태 변경 시 ReportHistory 자동 생성으로 이력 추적

3. 성능 최적화

   • ReportCategory 인메모리 캐싱: DB 조회 대비 32~52배 성능 향상
   • QueryDSL 기반 동적 쿼리: 타입 안전성과 유연한 필터링
   • 커서 페이징: 오프셋 페이징 대비 deep pagination 성능 우수

4. 객체지향 설계 개선 (리팩토링)

   • Report 엔티티가 상태 변경 책임과 ReportHistory 생성 책임 담당
   • 양방향 관계 설정으로 Cascade 자동 저장
   • 서비스 레이어는 엔티티 메서드 호출로 간소화

주요 파일/모듈

• DTO: ReportSearchRequest, ReportResponse, CursorPageResponse
• Repository: ReportRepositoryCustom, ReportRepositoryImpl (QueryDSL)
• Service: ReportService, ReportServiceImpl
• Controller: ReportController, CacheManagementController
• Entity: Report (리팩토링), ReportCategory
• Utils: ReportCategoryCache, InMemoryReportCategoryCache
• Config: QueryDslConfig
• AOP: PerformanceMonitoringAspect

수용 기준 검증

#6 신고 조회 및 관리 - AC 충족

• 신고 목록을 조회할 수 있다 (페이징 지원 - 커서 기반)
• 신고 상세 정보를 조회할 수 있다
• 신고 카테고리별 필터링이 가능하다 (게시글, 프로필, 비즈니스)
• 신고 처리 상태를 확인할 수 있다
• 상태별 정렬 및 신고일별 정렬 지원

추가 기능 요구사항

• 신고 상태 변경 API (승인, 거절, 검토 시작, 보류, 철회)
• ReportHistory 자동 생성 (상태 변경 시)
• 관리자/신고자 정보 추적

성능 요구사항

• 카테고리 캐싱 성능: DB 조회 대비 52배 향상 (단일 스레드)
• 동시성 환경 성능: DB 조회 대비 32.65배 향상 (10 스레드)
• 커서 기반 페이징으로 대용량 데이터 조회 성능 확보

설계 품질

• 객체지향 원칙 준수 (엔티티 책임 분리)
• 단일 책임 원칙: Report 엔티티가 상태 변경과 히스토리 생성 담당
• DRY 원칙: changeStatus() 메서드로 중복 제거

성능 테스트 결과

1. 카테고리 캐싱 vs DB 조회 (단일 스레드, 10,000회 조회)

=== Results ===
Cache Method: 13ms
DB Method: 676ms
Speedup: 52.00x
Time Saved: 663ms

2. 동시성 환경 (10 스레드, 각 1,000회 조회)

=== Concurrent Results ===
Cache Method: 20ms
DB Method: 653ms
Speedup: 32.65x

3. 테스트 커버리지

• 전체 테스트: 215+ 테스트 통과
• 커버리지: 98% 이상
• 테스트 종류:
  • DTO 테스트: 22개
  • Repository 테스트: 12개 (QueryDSL)
  • Service 테스트: 17개
  • Entity 테스트: 19개
  • 성능 테스트: 2개

상세 결과는 docs/테스트 결과 _2025_10_16.html 참조

브레이킹/마이그레이션

• 스키마 변경 없음: 기존 테이블 구조 유지
• 엔티티 메서드 시그니처 변경:
  • approve(), reject(), startReview() 등 상태 변경 메서드에 adminId, comment, historyIdGenerator 파라미터 추가
  • 기존 호출 코드 업데이트 필요 (서비스 레이어에서 처리됨)
• 호환성: 이전 버전과 호환 불가 (엔티티 메서드 변경)

테스트

단위 테스트

• DTO 레이어: 검증 로직, 기본값, Entity ↔ DTO 변환
• Repository 레이어: QueryDSL 동적 쿼리, 필터링, 정렬, 커서 페이징
• Service 레이어: 비즈니스 로직, 예외 처리, 히스토리 자동 생성 검증
• Entity 레이어: 상태 변경, 히스토리 생성, 양방향 관계, 예외 처리

통합 테스트

• Repository 통합 테스트: 실제 H2 DB 환경에서 QueryDSL 쿼리 검증
• 성능 테스트: 캐시 vs DB, 단일 스레드 vs 멀티 스레드

수동 검증 방법

# 1. 빌드 및 테스트 실행
./gradlew clean build

# 2. 성능 테스트 실행
./gradlew test --tests "com.teambind.supportserver.report.performance.ReportCategoryPerformanceTest"

# 3. 테스트 커버리지 확인
./gradlew jacocoTestReport
open build/reports/jacoco/test/html/index.html

향후 작업 (Out of Scope)

본 PR에서는 다음 기능은 구현하지 않으며, 추후 별도 이슈로 진행 예정:

#29 신고 시스템 확장 기능

• 신고 통계 집계 (ReportStatisticsService)
• 자동 제재 로직 (SanctionService)
• 관리자 알림 발송

기타

• 게시글 신고 API ([STORY] 게시글 신고 기능 #4) - 별도 PR 예정
• 프로필 신고 API ([STORY] 프로필 신고 기능 #5, [TASK] 프로필 신고 API 구현 #16) - 별도 PR 예정
• Kafka 이벤트 발행 ([TASK] Kafka Producer 설정 및 이벤트 스키마 정의 #18) - 별도 PR 예정

참고: ReportStatisticsService.java, SanctionService.java는 인터페이스만 정의되어 있으며, 구현체는 #29 완료 후 추가 예정

참조

• Closes [TASK] 신고 조회 API 구현 #17 (신고 조회 API 구현)
• refs [STORY] 게시글 신고 기능 #4 (게시글 신고 기능)
• refs [STORY] 프로필 신고 기능 #5 (프로필 신고 기능)
• refs [STORY] 신고 조회 및 관리 #6 (신고 조회 및 관리)
• refs [TASK] 프로필 신고 API 구현 #16 (프로필 신고 API 구현)
• refs [STORY] 신고 시스템 확장 기능 구현 #29 (신고 시스템 확장 기능 구현)
• 테스트 결과: docs/테스트 결과 _2025_10_16.html
• 성능 테스트 코드: ReportCategoryPerformanceTest.java