refactor: 배송 완료 처리 로직 개선 및 비동기 처리 도입 (WR9-142)

- 개별 트랜잭션 적용으로 편지 처리 안정성 향상
  - 각 편지마다 독립적인 트랜잭션(REQUIRES_NEW) 설정
  - 한 편지 처리 실패가 다른 편지에 영향을 주지 않도록 격리

- CompletableFuture 기반 비동기 처리 구현
  - 병렬 처리를 통한 성능 개선
  - 작업 결과 추적 및 성공/실패 통계 수집 기능 추가

- 전용 TaskExecutor 설정으로 효율적인 리소스 관리
  - CPU 코어 수 기반 동적 스레드 풀 설정
  - 과부하 방지를 위한 CallerRunsPolicy 도입
  - AsyncConfig 클래스 분리로 설정 모듈화

- 예외 처리 및 로깅 강화
  - 상세한 예외 정보 기록으로 문제 진단 용이
  - 전체 처리 과정 및 결과에 대한 로깅 개선

Author: Kojinyoung7220

src/main/java/io/crops/warmletter/domain/letter/entity/Letter.java

@@ -32,7 +32,10 @@ public class Letter extends BaseTimeEntity {
     @Enumerated(EnumType.STRING)
     private Category category;       // 편지 분류 (enum: 쿠폰, 응원, 그외 등)
 
+    @Column(length = 50)
     private String title;            // 제목
+
+    @Column(length = 1000)
     private String content;          // 내용
 
     @Enumerated(EnumType.STRING)

src/main/java/io/crops/warmletter/global/config/AsyncConfig.java

@@ -0,0 +1,32 @@
+package io.crops.warmletter.global.config;
+
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.core.task.AsyncTaskExecutor;
+import org.springframework.scheduling.concurrent.ThreadPoolTaskExecutor;
+
+import java.util.concurrent.ThreadPoolExecutor;
+
+@Configuration
+public class AsyncConfig {
+
+    @Bean
+    public AsyncTaskExecutor deliveryTaskExecutor() {
+        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
+
+        int corePoolSize = Runtime.getRuntime().availableProcessors() * 2;
+
+        executor.setCorePoolSize(corePoolSize);              // CPU 코어 수 * 2
+        executor.setMaxPoolSize(corePoolSize * 2);           // 부하가 높을 때 확장 가능한 여유
+        executor.setQueueCapacity(corePoolSize * 4);         // 처리 대기열 크기
+        executor.setKeepAliveSeconds(60);                    // 유휴 스레드 유지 시간
+        executor.setThreadNamePrefix("delivery-async-");
+
+        // 대기열이 가득 찼을 때 CallerRunsPolicy를 사용하여
+        // 호출 스레드에서 작업 실행 (시스템 과부하 방지)
+        executor.setRejectedExecutionHandler(new ThreadPoolExecutor.CallerRunsPolicy());
+
+        executor.initialize();
+        return executor;
+    }
+}

src/main/java/io/crops/warmletter/global/schedule/DeliverySchedule.java

@@ -3,22 +3,25 @@
 import io.crops.warmletter.domain.letter.entity.Letter;
 import io.crops.warmletter.domain.letter.enums.Status;
 import io.crops.warmletter.domain.letter.repository.LetterRepository;
-import io.crops.warmletter.domain.member.repository.MemberRepository;
 import io.crops.warmletter.domain.timeline.dto.request.NotificationRequest;
 import io.crops.warmletter.domain.timeline.dto.response.LetterAlarmResponse;
 import io.crops.warmletter.domain.timeline.enums.AlarmType;
-import io.crops.warmletter.domain.timeline.facade.NotificationFacade;
-import jakarta.transaction.Transactional;
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
+import org.springframework.beans.factory.annotation.Qualifier;
 import org.springframework.context.ApplicationEventPublisher;
 import org.springframework.context.annotation.Configuration;
+import org.springframework.core.task.AsyncTaskExecutor;
 import org.springframework.scheduling.annotation.Scheduled;
+import org.springframework.transaction.annotation.Propagation;
+import org.springframework.transaction.annotation.Transactional;
 
 import java.time.LocalDateTime;
 import java.time.format.DateTimeFormatter;
+import java.util.ArrayList;
 import java.util.List;
 import java.util.Map;
+import java.util.concurrent.CompletableFuture;
 import java.util.stream.Collectors;
 
 @Slf4j
@@ -27,51 +30,85 @@
 public class DeliverySchedule {
 
     private final LetterRepository letterRepository;
-
     private final ApplicationEventPublisher notificationPublisher;
+    @Qualifier("deliveryTaskExecutor")
+    private final AsyncTaskExecutor taskExecutor;
 
-    @Transactional
     @Scheduled(cron = "0 */1 * * * *", zone = "Asia/Seoul")
     public void processDeliveryCompletion() {
         String currentTime = LocalDateTime.now().format(DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"));
         log.info("--------- 배송 완료 처리 시작: {} ---------", currentTime);
 
         LocalDateTime now = LocalDateTime.now();
 
-        // 배송 완료 조건을 만족하는 편지 목록 조회 (배송 중이면서 배송 완료 시간이 현재보다 이전인 편지)
+        // 배송 완료 조건을 만족하는 편지 목록 조회
         List<Letter> lettersToComplete = letterRepository.findByStatusAndDeliveryCompletedAtLessThanEqual(
                 Status.IN_DELIVERY, now);
-        // lettersToComplete 조건을 만족하는 편지를 보낸 사람의 zipCode 조회
+
+        // zipCode 조회
         List<LetterAlarmResponse> zipCodeData = letterRepository.findZipCodeByLettersToComplete(now);
         Map<Long, String> senderZipCodes = zipCodeData.stream()
                 .collect(Collectors.toMap(
                         LetterAlarmResponse::getWriterId,
                         LetterAlarmResponse::getZipCode,
-                        (existingZipCode, newZipCode) -> existingZipCode  // 중복 키 발생 시 기존 값 사용
+                        (existingZipCode, newZipCode) -> existingZipCode
                 ));
 
         if (!lettersToComplete.isEmpty()) {
             log.info("배송 완료 처리할 편지 수: {}", lettersToComplete.size());
 
-            // 각 편지의 상태를 DELIVERED로 변경
+            // 결과 추적을 위한 CompletableFuture 목록
+            List<CompletableFuture<Boolean>> futures = new ArrayList<>();
+
+            // 각 편지를 비동기적으로 처리
             for (Letter letter : lettersToComplete) {
-                letter.updateStatus(Status.DELIVERED);
-                log.info("편지 ID: {} 배송 완료 처리됨", letter.getId());
-                // 도착 알림 전송
-                notificationPublisher.publishEvent(NotificationRequest.builder()
-                        .senderZipCode(senderZipCodes.get(letter.getWriterId()))
-                        .receiverId(letter.getReceiverId())
-                        .alarmType(AlarmType.LETTER)
-                        .data(letter.getId().toString())
-                        .build());
+                CompletableFuture<Boolean> future = CompletableFuture.supplyAsync(() -> {
+                    try {
+                        processLetter(letter, senderZipCodes.get(letter.getWriterId()));
+                        log.info("편지 ID: {} 배송 완료 처리됨", letter.getId());
+                        return true;
+                    } catch (Exception e) {
+                        log.error("편지 ID: {} 배송 완료 처리 실패: {}", letter.getId(), e.getMessage(), e);
+                        return false;
+                    }
+                }, taskExecutor);
+
+                futures.add(future);
             }
 
-            // 변경사항 저장
-            letterRepository.saveAll(lettersToComplete);
-            log.info("총 {}개의 편지 배송 완료 처리됨", lettersToComplete.size());
+            // 모든 비동기 작업 완료 대기 (옵션)
+            CompletableFuture.allOf(futures.toArray(new CompletableFuture[0])).join();
+
+            // 성공/실패 편지 수 계산
+            long successCount = futures.stream().filter(f -> {
+                try {
+                    return f.get();
+                } catch (Exception e) {
+                    return false;
+                }
+            }).count();
+
+            log.info("총 {}개 중 {}개의 편지 배송 완료 처리 성공", lettersToComplete.size(), successCount);
         } else {
             log.info("배송 완료 처리할 편지가 없습니다.");
         }
         log.info("--------- 배송 완료 처리 완료 ---------");
     }
+
+    @Transactional(propagation = Propagation.REQUIRES_NEW)
+    public void processLetter(Letter letter, String senderZipCode) {
+        // 편지 상태 업데이트
+        letter.updateStatus(Status.DELIVERED);
+        letterRepository.save(letter);
+
+        // 알림 전송
+        if (letter.getReceiverId() != null && senderZipCode != null) {
+            notificationPublisher.publishEvent(NotificationRequest.builder()
+                    .senderZipCode(senderZipCode)
+                    .receiverId(letter.getReceiverId())
+                    .alarmType(AlarmType.LETTER)
+                    .data(letter.getId().toString())
+                    .build());
+        }
+    }
 }