feat(faq): FAQ 조회 시스템 구현 (캐싱 및 스케줄링) refs #20 #21 #22

[DDINGJOO]

목적

• FAQ 엔티티 및 카테고리 Enum을 설계하고 구현했습니다.
• FAQ 조회 API를 RESTful하게 구현했습니다.
• 캐싱 전략을 적용하여 조회 성능을 최적화했습니다.
• 스케일 아웃 환경을 고려한 로컬 캐싱 및 스케줄링 구현
• 관련 Story: [STORY] FAQ 데이터 모델 및 카테고리 설계 #8 [STORY] FAQ 데이터 모델 및 카테고리 설계, [STORY] FAQ 조회 API 구현 #9 [STORY] FAQ 조회 API 구현
• 관련 Task: [TASK] FAQ 엔티티 및 Repository 구현 #20 [TASK] FAQ 엔티티 및 Repository 구현, [TASK] FAQ 조회 API 구현 #21 [TASK] FAQ 조회 API 구현, [TASK] FAQ 캐싱 전략 구현 #22 [TASK] FAQ 캐싱 전략 구현

변경 요약

핵심 기능

1. FAQ 엔티티 및 카테고리

   • FaqCategory enum: 전체, 예약 관련, 이용/입실, 요금/결제, 리뷰/신고, 기타
   • Faq 엔티티: id(auto increment), category, title (제목), question, answer, timestamps
   • JPA 자동 타임스탬프 관리 (@PrePersist, @PreUpdate)
   • 비상 요구사항 반영: title 필드 추가 ([CHANGE REQUEST] FAQ 엔티티에 title 필드 추가 필요 #37)

2. 캐싱 전략

   • 서버 시작 시 전체 FAQ 데이터를 메모리에 로드 (@PostConstruct)
   • 매일 새벽 3시 자동 캐시 갱신 (@scheduled)
   • ReadWriteLock으로 멀티스레드 동시성 제어
   • 수동 캐시 갱신 API 제공 (관리자용)

3. 스케일 아웃 환경 고려

   • 각 서버 인스턴스가 독립적인 로컬 캐시 유지
   • 스케줄러가 각 인스턴스에서 독립적으로 실행 (DB 읽기 전용)
   • 분산 락 불필요 (읽기 전용 작업이므로 안전)
   • volatile 변수로 캐시 가시성 보장

4. REST API 설계

   • 카테고리별 필터링 기능 (메모리 레벨 처리)
   • 페이징 없음 (요구사항에 따라)
   • RESTful한 엔드포인트 설계

주요 파일/모듈

• Entity: Faq, FaqCategory enum
• Repository: FaqRepository
• Service: FaqService (캐싱, 스케줄링, 동시성 제어)
• Controller: FaqController
• Configuration: SupportServerApplication (@EnableScheduling)
• Test: FaqServiceTest, FaqControllerTest

API 명세

1. FAQ 목록 조회 (GET /api/v1/faqs)

Query Parameters:

• category: FAQ 카테고리 (선택, 기본값: ALL)
  • ALL: 전체
  • RESERVATION: 예약 관련
  • CHECK_IN: 이용/입실
  • PAYMENT: 요금/결제
  • REVIEW_REPORT: 리뷰/신고
  • ETC: 기타

Response (200 OK):

[
  {
    "id": 1,
    "category": "RESERVATION",
    "title": "예약 관련",
    "question": "예약은 어떻게 하나요?",
    "answer": "앱에서 예약 가능합니다.",
    "createdAt": "2025-10-16T10:00:00",
    "updatedAt": "2025-10-16T10:00:00"
  },
  {
    "id": 2,
    "category": "CHECK_IN",
    "title": "체크인 안내",
    "question": "체크인 시간은 언제인가요?",
    "answer": "오후 3시부터 가능합니다.",
    "createdAt": "2025-10-16T10:00:00",
    "updatedAt": "2025-10-16T10:00:00"
  }
]

예시:

# 전체 FAQ 조회
GET /api/v1/faqs

# 카테고리별 조회
GET /api/v1/faqs?category=RESERVATION
GET /api/v1/faqs?category=PAYMENT

2. FAQ 캐시 수동 갱신 (POST /api/v1/faqs/refresh)

관리자용 API - 캐시를 즉시 갱신할 때 사용

Response (200 OK):

FAQ cache refreshed successfully

수용 기준 검증

#8 FAQ 데이터 모델 및 카테고리 설계 - AC 충족

• FAQ 엔티티 설계 완료 (제목, 질문, 답변, 카테고리, 작성일, 수정일)
• FAQ 카테고리 Enum 정의 완료 (6가지 카테고리)
• 데이터베이스 스키마 생성 완료
• Repository 계층 구현 완료

#9 FAQ 조회 API 구현 - AC 충족

• 전체 FAQ 목록 조회 API 구현 (페이징 없음)
• 카테고리별 필터링 기능 구현
• FAQ 응답 DTO 설계 및 구현 (엔티티 직접 반환)
• API 문서 작성 완료 (이 PR 설명)
• 단위 테스트 및 통합 테스트 작성

추가 기능 요구사항

• 캐싱 전략으로 조회 성능 최적화
• 스케일 아웃 환경 고려한 로컬 캐싱
• 멀티스레드 동시성 제어 (ReadWriteLock)
• 스케줄러로 자동 캐시 갱신

테스트 커버리지

• FaqServiceTest: 11개 테스트

  • 서버 시작 시 캐시 초기화
  • 전체 FAQ 조회
  • 카테고리별 조회 (ALL, RESERVATION, PAYMENT)
  • 캐시 갱신
  • 동시성 테스트 (100 스레드 동시 읽기)
  • 동시성 테스트 (50 읽기 + 5 갱신)
  • 스케줄러 메서드 호출
  • 빈 목록 처리
  • 존재하지 않는 카테고리 조회

• FaqControllerTest: 11개 테스트

  • 카테고리 파라미터 없이 조회 (기본값 ALL)
  • 모든 카테고리별 조회 (6가지)
  • 빈 목록 반환
  • 캐시 수동 갱신
  • 잘못된 카테고리 파라미터 처리
  • 응답 필드 검증 (title 포함)

• 전체 테스트: 22개 테스트 추가

브레이킹/마이그레이션

• Breaking Change 없음: 신규 기능 추가
• 마이그레이션 필요: 없음 (신규 테이블 생성)
• 데이터베이스 변경: faq 테이블 생성 (title 필드 포함)

테스트

단위 테스트

• Service 테스트: 캐싱, 스케줄링, 동시성 검증
• Controller 테스트: REST API 요청/응답 검증
• 동시성 테스트: 멀티스레드 환경 안정성 검증

수동 검증 방법

# 1. 빌드 및 테스트
cd SupportServer
./gradlew clean build

# 2. 서버 실행
./gradlew bootRun

# 3. FAQ 전체 조회
curl -X GET http://localhost:8080/api/v1/faqs

# 4. 카테고리별 조회
curl -X GET "http://localhost:8080/api/v1/faqs?category=RESERVATION"
curl -X GET "http://localhost:8080/api/v1/faqs?category=PAYMENT"

# 5. 캐시 수동 갱신 (관리자)
curl -X POST http://localhost:8080/api/v1/faqs/refresh

아키텍처 개선 사항

캐싱 전략

1. 로컬 메모리 캐싱:

   • DB 조회 없이 메모리에서 즉시 응답
   • 매우 빠른 조회 성능 (마이크로초 단위)

2. 자동 갱신 스케줄러:

   • 매일 새벽 3시 자동 갱신 (트래픽 최소 시간대)
   • 수동 갱신 API로 즉시 갱신 가능

3. 동시성 제어:

   • ReadWriteLock으로 읽기/쓰기 분리
   • 여러 스레드가 동시에 읽기 가능
   • 쓰기 시에만 배타적 락 획득

스케일 아웃 고려사항

1. 각 인스턴스가 독립적인 캐시 유지

   • 분산 락 불필요 (읽기 전용 작업)
   • 각 인스턴스에서 독립적으로 스케줄러 실행

2. 데이터 정합성

   • FAQ 데이터는 자주 변경되지 않음
   • 최대 24시간 이내 동기화 보장
   • 긴급 변경 시 수동 갱신 API 사용

성능 개선 사항

• 조회 성능: DB 조회 → 메모리 조회 (99% 이상 응답 시간 단축)
• DB 부하: 하루 1회 조회로 DB 부하 최소화
• 동시성: ReadWriteLock으로 멀티스레드 환경 안전성 확보

변경 이력

• 2025-10-16: title 필드 추가 (비상 요구사항 [CHANGE REQUEST] FAQ 엔티티에 title 필드 추가 필요 #37)

참조

• Closes [TASK] FAQ 엔티티 및 Repository 구현 #20 (FAQ 엔티티 및 Repository 구현)
• Closes [TASK] FAQ 조회 API 구현 #21 (FAQ 조회 API 구현)
• Closes [TASK] FAQ 캐싱 전략 구현 #22 (FAQ 캐싱 전략 구현)
• refs [STORY] FAQ 데이터 모델 및 카테고리 설계 #8 (FAQ 데이터 모델 및 카테고리 설계)
• refs [STORY] FAQ 조회 API 구현 #9 (FAQ 조회 API 구현)
• refs [CHANGE REQUEST] FAQ 엔티티에 title 필드 추가 필요 #37 (title 필드 추가 요구사항)