Merge remote-tracking branch 'origin/feat/dev_251201' into feat/dev_251201

src/main/java/com/kamco/cd/kamcoback/code/CommonCodeApiController.java

@@ -1,5 +1,6 @@
 package com.kamco.cd.kamcoback.code;
 
+import com.kamco.cd.kamcoback.code.config.CommonCodeCacheManager;
 import com.kamco.cd.kamcoback.code.dto.CommonCodeDto;
 import com.kamco.cd.kamcoback.code.service.CommonCodeService;
 import com.kamco.cd.kamcoback.common.enums.DetectionClassification;
@@ -34,6 +35,7 @@ import org.springframework.web.bind.annotation.RestController;
 public class CommonCodeApiController {
 
   private final CommonCodeService commonCodeService;
+  private final CommonCodeCacheManager commonCodeCacheManager;
 
   @Operation(summary = "목록 조회", description = "모든 공통코드 조회")
   @ApiResponses(
@@ -243,4 +245,40 @@ public class CommonCodeApiController {
       @RequestParam String code) {
     return ApiResponseDto.okObject(commonCodeService.getCodeCheckDuplicate(parentId, code));
   }
+
+  @Operation(summary = "캐시 갱신", description = "공통코드 캐시를 갱신합니다. 공통코드 설정 변경 후 호출해주세요.")
+  @ApiResponses(
+      value = {
+        @ApiResponse(
+            responseCode = "200",
+            description = "캐시 갱신 성공",
+            content =
+                @Content(
+                    mediaType = "application/json",
+                    schema = @Schema(implementation = String.class))),
+        @ApiResponse(responseCode = "500", description = "서버 오류", content = @Content)
+      })
+  @PostMapping("/cache/refresh")
+  public ApiResponseDto<String> refreshCommonCodeCache() {
+    commonCodeCacheManager.refreshCommonCodeCache();
+    return ApiResponseDto.ok("공통코드 캐시가 갱신되었습니다.");
+  }
+
+  @Operation(summary = "캐시 상태 확인", description = "Redis에 캐시된 공통코드 개수를 확인합니다.")
+  @ApiResponses(
+      value = {
+        @ApiResponse(
+            responseCode = "200",
+            description = "캐시 상태 조회 성공",
+            content =
+                @Content(
+                    mediaType = "application/json",
+                    schema = @Schema(implementation = Integer.class))),
+        @ApiResponse(responseCode = "500", description = "서버 오류", content = @Content)
+      })
+  @GetMapping("/cache/status")
+  public ApiResponseDto<Integer> getCommonCodeCacheStatus() {
+    int count = commonCodeCacheManager.getCachedCommonCodeCount();
+    return ApiResponseDto.ok(count);
+  }
 }

src/main/java/com/kamco/cd/kamcoback/code/config/CommonCodeCacheManager.java

@@ -0,0 +1,131 @@
+package com.kamco.cd.kamcoback.code.config;
+
+import com.kamco.cd.kamcoback.code.dto.CommonCodeDto.Basic;
+import com.kamco.cd.kamcoback.code.service.CommonCodeService;
+import java.util.List;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.boot.context.event.ApplicationReadyEvent;
+import org.springframework.cache.CacheManager;
+import org.springframework.context.event.EventListener;
+import org.springframework.stereotype.Component;
+
+/**
+ * 공통코드 캐시 관리 및 초기화 클래스
+ *
+ * <p>애플리케이션 시작 시 공통코드를 Redis 캐시에 미리 로드하고, 캐시 갱신을 관리합니다.
+ * 기존 Redis 데이터와의 호환성 문제로 인한 간헐적 오류를 방지합니다.
+ */
+@Slf4j
+@Component
+@RequiredArgsConstructor
+public class CommonCodeCacheManager {
+
+  private final CommonCodeService commonCodeService;
+  private final CacheManager cacheManager;
+
+  public static final String COMMON_CODES_CACHE_NAME = "commonCodes";
+
+  /**
+   * 애플리케이션 시작 완료 후 공통코드를 Redis 캐시에 미리 로드
+   *
+   * <p>이 메서드는 Spring 애플리케이션이 완전히 시작된 후에 자동으로 실행되며, 공통코드 데이터를 Redis
+   * 캐시에 미리 로드하여 초기 조회 시 성능을 최적화합니다. 기존 캐시 데이터 호환성 문제를 대비하여 먼저
+   * 캐시를 초기화한 후 재로드합니다.
+   */
+  @EventListener(ApplicationReadyEvent.class)
+  public void initializeCommonCodeCache() {
+    try {
+      log.info("=== 공통코드 캐시 초기화 시작 ===");
+
+      // 1. 기존 캐시 데이터 호환성 문제 방지: 먼저 캐시 전체 초기화
+      try {
+        clearCommonCodeCache();
+        log.debug("✓ 기존 캐시 데이터 정리 완료 (호환성 문제 방지)");
+      } catch (Exception clearEx) {
+        log.debug("기존 캐시 초기화 중 예외 (무시됨): {}", clearEx.getMessage());
+      }
+
+      // 2. DB에서 새로운 데이터 로드 (캐시 미스 상태)
+      List<Basic> allCommonCodes = commonCodeService.getFindAll();
+      log.info(
+        "✓ 공통코드 {}개를 DB에서 로드하고 Redis 캐시에 저장했습니다.",
+        allCommonCodes.size());
+
+      // 3. 로그 출력 (DEBUG 레벨)
+      if (log.isDebugEnabled()) {
+        allCommonCodes.forEach(
+          code ->
+            log.debug(
+              "  - [{}] {} (ID: {})",
+              code.getCode(),
+              code.getName(),
+              code.getId()));
+      }
+
+      log.info("=== 공통코드 캐시 초기화 완료 ===");
+    } catch (Exception e) {
+      log.warn(
+        "공통코드 캐시 초기화 중 오류 발생했습니다. 캐시 없이 계속 진행합니다. "
+          + "(첫 번째 조회 시 DB에서 로드되고 캐시됩니다.)",
+        e);
+    }
+  }
+
+  /**
+   * 공통코드 캐시 전체 초기화 (수동 갱신)
+   *
+   * <p>공통코드 설정이 변경되었을 때 호출하여 캐시를 강제로 갱신합니다.
+   */
+  public void refreshCommonCodeCache() {
+    try {
+      log.info("공통코드 캐시 갱신 시작...");
+
+      // 기존 캐시 제거
+      clearCommonCodeCache();
+
+      // 새로운 데이터 로드
+      List<Basic> allCommonCodes = commonCodeService.getFindAll();
+
+      log.info("✓ 공통코드 캐시가 {}개 항목으로 갱신되었습니다.", allCommonCodes.size());
+    } catch (Exception e) {
+      log.error("공통코드 캐시 갱신 중 오류 발생", e);
+      throw new RuntimeException("공통코드 캐시 갱신 실패", e);
+    }
+  }
+
+  /**
+   * 공통코드 캐시 초기화 (삭제)
+   *
+   * <p>공통코드 캐시를 비우고 다음 조회 시 DB에서 새로 로드하도록 합니다.
+   */
+  public void clearCommonCodeCache() {
+    try {
+      var cache = cacheManager.getCache(COMMON_CODES_CACHE_NAME);
+      if (cache != null) {
+        cache.clear();
+        log.info("✓ 공통코드 캐시가 초기화되었습니다.");
+      }
+    } catch (Exception e) {
+      log.warn("공통코드 캐시 초기화 중 예외 발생 (무시됨): {}", e.getMessage());
+      // 무시하고 계속 진행 - 캐시 초기화 실패가 시스템 전체를 중단시키지 않도록
+    }
+  }
+
+  /**
+   * 캐시 상태 확인
+   *
+   * <p>현재 Redis 캐시에 저장된 공통코드의 개수를 반환합니다. 캐시 미스 상태인 경우 DB에서 새로 로드합니다.
+   *
+   * @return 캐시에 있는 공통코드 개수
+   */
+  public int getCachedCommonCodeCount() {
+    try {
+      List<Basic> cachedCodes = commonCodeService.getFindAll();
+      return cachedCodes.size();
+    } catch (Exception e) {
+      log.warn("캐시 상태 확인 중 오류 발생: {}", e.getMessage());
+      return 0;
+    }
+  }
+}