[Spring Boot] 가상계좌 입금기한 만료 자동 처리 스케줄러 구현 ♩

[Spring Boot] 가상계좌 입금기한 만료 자동 처리 스케줄러 구현기

카마 프로젝트에 무통장입금(가상계좌)을 붙인 지는 좀 됐는데, 정작 "입금기한 지나면 어떻게 되는가"는 스코프 밖으로 남겨뒀었다. 가상계좌만 발급해두고 아무도 입금을 안 하면, 주문은 영원히 PENDING으로 남고 재고도 계속 묶여있는 상태였던 것. 이번에 입금기한 만료 자동 처리 스케줄러를 붙여서 이 구멍을 메웠다.

---

📝 개요

목표는 간단하다. vbankDueDate(입금기한)가 지났는데도 여전히 PENDING 상태인 주문을 매시간 스캔해서, 자동으로 취소 처리하고 재고를 복구하는 것. 기존에 이미 상품 할인 만료 / 장바구니 만료를 처리하던 DiscountScheduler가 있어서, 그 패턴을 그대로 참고했다.

🤔 설계 결정

새로 짜기 전에 기존 cancelOrder()(사용자가 직접 취소하는 API)를 다시 들여다봤는데, 이게 하려는 일이랑 거의 똑같더라. "주문을 취소 상태로 바꾸고, 재고를 복구하고, 포트원에 취소 요청을 보낸다" — 유일한 차이는 누가/왜 취소하는지뿐이었다. 그래서 완전히 새로 짜는 대신, 취소 사유를 하나 추가하고 재고 복구 로직을 공용 메서드로 뽑아서 재사용하는 방향으로 갔다.

사용자가 취소한 건지 시스템이 자동으로 만료시킨 건지 구분이 안 되면, 나중에 주문 목록을 볼 때 헷갈린다. 그래서 CancelReason에 VBANK_EXPIRED라는 사유를 별도로 추가했다.

🛠️ 구현 흐름

① CancelReason에 만료 전용 사유 추가:

VBANK_EXPIRED("입금기한 만료"),

② OrderRepository에 "입금기한 지난 PENDING 주문"을 조회하는 쿼리 추가. 재고 복구를 위해 orderItems까지 fetch join으로 한 번에 끌고 온다:

@Query("""
    select distinct o from Order o
    join fetch o.orderItems oi
    join fetch oi.productVariant
    where o.status = :status
    and o.vbankDueDate < :now
""")
List<Order> findExpiredVirtualAccountOrders(
        @Param("status") OrderStatus status,
        @Param("now") LocalDateTime now
);

③ OrderCommandService에 만료 처리 메서드 추가. 이 과정에서 cancelOrder() 안에 있던 "재고 복구용 잔여수량 캡쳐 + 재고 복구" 로직이 완전히 똑같이 필요하다는 걸 발견해서, 아예 공용 private 메서드 두 개로 뽑아 cancelOrder()도 같이 재사용하도록 리팩토링했다:

private Map<Long, Long> captureRemainingQuantities(Order order) {
    Map<Long, Long> remainingByItemId = new HashMap<>();
    for (OrderItem item : order.getOrderItems()) {
        long remainingQuantity = item.getQuantity() - item.getCancelledQuantity();
        if (remainingQuantity > 0) {
            remainingByItemId.put(item.getId(), remainingQuantity);
        }
    }
    return remainingByItemId;
}

private void restoreStock(Order order, Map<Long, Long> remainingByItemId) {
    for (OrderItem item : order.getOrderItems()) {
        Long remainingQuantity = remainingByItemId.get(item.getId());
        if (remainingQuantity == null) continue;
        productStockRepository
                .findByProductVariant_Id(item.getProductVariant().getId())
                .ifPresent(stock -> stock.increase(remainingQuantity));
    }
}

@Transactional
public int expireVirtualAccountOrders() {
    LocalDateTime now = LocalDateTime.now();
    List<Order> expiredOrders = orderRepository.findExpiredVirtualAccountOrders(OrderStatus.PENDING, now);

    for (Order order : expiredOrders) {
        Map<Long, Long> remainingByItemId = captureRemainingQuantities(order);
        order.cancel(CancelReason.VBANK_EXPIRED);

        if (order.getImpUid() != null) {
            portOneClient.cancelPayment(order.getImpUid(), CancelReason.VBANK_EXPIRED.getDescription());
        }

        restoreStock(order, remainingByItemId);
    }

    return expiredOrders.size();
}

④ DiscountScheduler 와 같은 패키지에 VirtualAccountScheduler를 새로 만들고, 매시 정각에 실행되도록 cron을 걸었다:

@Scheduled(cron = "0 0 * * * *")
public void expireOverdueVirtualAccountOrders() {
    int expiredCount = orderCommandService.expireVirtualAccountOrders();
    log.info("[가상계좌 만료 스케줄러] 만료 처리: {}건", expiredCount);
}

🧪 테스트 계획

Mockito로 단위 테스트 작성. 입금기한 지난 PENDING 주문 하나를 만들어두고 expireVirtualAccountOrders()를 호출한 뒤, ① 리턴값(처리 건수), ② 주문 상태가 CANCELLED로 전환됐는지, ③ 사유가 VBANK_EXPIRED로 저장됐는지, ④ 재고가 주문 수량만큼 정확히 복구됐는지, ⑤ 포트원 cancelPayment()가 호출됐는지 이렇게 다섯 가지를 검증했다.

---

🐛 헷갈렸던 것들 & 트러블슈팅

쿼리에 select distinct를 왜 붙여야 하는지 처음엔 감이 안 왔다. 알고 보니 join fetch로 컬렉션(orderItems)을 같이 가져오면, SQL 레벨에서는 조인이라 주문 하나에 아이템이 2개면 결과도 2줄이 되어버린다. distinct 없이 그냥 List로 받으면 같은 주문이 리스트에 중복으로 들어가서, 이미 취소된 주문을 또 취소하려다가 예외가 터질 뻔했다. distinct는 SQL의 중복 제거가 아니라 "JPA가 루트 엔티티 기준으로 중복 제거해준다"는 개념으로 이해하니 맞아떨어졌다.

재고 복구 로직에서도 순서가 왜 중요한지 헷갈렸었다. captureRemainingQuantities()를 꼭 order.cancel() 호출 전에 실행해야 하는데, 이유는 cancel()이 내부적으로 cancelledQuantity를 이미 다 채워버려서, 그 이후엔 "얼마나 남아있었는지" 정보 자체가 사라지기 때문이었다. 먼저 스냅샷을 떠두고, 상태를 바꾸고, 그 스냅샷으로 복구하는 순서가 필수였던 것.

그럼 같은 패턴을 부분취소(cancelOrderItem())에도 적용할 수 있지 않을까 싶었는데, 이건 아니었다. cancelOrder()류는 "남은 걸 전부" 취소해서 quantity - cancelledQuantity 계산이 곧 취소량과 일치하지만, cancelOrderItem()은 호출하는 쪽이 임의로 지정한 부분 수량만 취소하는 거라 같은 계산식을 쓰면 재고가 과다 복구되는 버그로 이어진다. 표로 정리하면 이렇다:

구분	cancelOrder() / expireVirtualAccountOrders()	cancelOrderItem()
취소 범위	남은 수량 전체	호출자가 지정한 일부 수량
취소량 계산	quantity - cancelledQuantity (계산해야 앎)	command.cancelQuantity() (이미 알고 있음)
재고 복구 방식	캡쳐 → 취소 → 복구 (3단계)	받은 값 그대로 취소·복구에 재사용 (2단계)

---

🧩 마무리 정리

새 기능처럼 보였지만 실제로는 기존 취소 로직을 스케줄러가 대신 트리거하는 것에 가까웠다. 덕분에 완전히 새로 짜기보다는 기존 코드에서 진짜 중복(재고 복구 로직)을 찾아서 공용화하는 리팩토링까지 같이 할 수 있었고, 반대로 겉보기엔 비슷해도 절대 합치면 안 되는 로직(cancelOrderItem)도 구분해내는 연습이 됐다. 이걸로 카마 프로젝트의 기능 개발 파트는 일단 마무리 — 다음은 Swagger 정리, AOP 로깅, Docker+CI/CD로 넘어갈 차례다.