Merge pull request #381 from BINBEAN777/volume-8

Volume 8

Author: BINBEAN777

apps/commerce-api/src/main/java/com/loopers/application/queue/QueueFacade.java

@@ -0,0 +1,64 @@
+package com.loopers.application.queue;
+
+import com.loopers.domain.queue.EntryTokenStore;
+import com.loopers.domain.queue.WaitingQueueRepository;
+import com.loopers.support.error.CoreException;
+import com.loopers.support.error.ErrorType;
+import lombok.RequiredArgsConstructor;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.stereotype.Component;
+
+import java.util.Optional;
+
+@RequiredArgsConstructor
+@Component
+public class QueueFacade {
+
+    private final WaitingQueueRepository waitingQueueRepository;
+    private final EntryTokenStore entryTokenStore;
+
+    @Value("${loopers.queue.gate.enabled:false}")   // 관문 토글 (기본 꺼짐)
+    private boolean gateEnabled;
+
+    /** 대기열에 진입시키고, 현재 순번/예상 대기시간을 돌려준다. */
+    public QueueInfo enter(Long userId) {
+        waitingQueueRepository.enter(userId);
+        long rank = waitingQueueRepository.findRank(userId).orElse(0L);
+        return QueueInfo.of(rank);
+    }
+
+    /** 현재 순번/예상 대기시간을 조회한다. 큐에 없지만 토큰이 있으면 '내 차례', 둘 다 없으면 404. */
+    public QueueInfo position(Long userId) {
+        Optional<Long> rank = waitingQueueRepository.findRank(userId);
+        if (rank.isPresent()) {
+            return QueueInfo.of(rank.get());   // 아직 대기 중
+        }
+        // 큐에 없음 → 토큰이 있으면 내 차례(입장 허가), 없으면 이탈/미진입(404)
+        return entryTokenStore.find(userId)
+                .map(QueueInfo::admitted)
+                .orElseThrow(() -> new CoreException(ErrorType.NOT_FOUND, "대기열에 없습니다."));
+    }
+
+    /** 주문 API 진입 관문: 토큰을 검증한다. 관문이 꺼져 있으면 그냥 통과. */
+    public void validateEntry(Long userId, String token) {
+        if (!gateEnabled) {
+            return;   // 관문 OFF → 통과 (평소 / Redis 장애 시 bypass)
+        }
+        if (token == null || token.isBlank()) {
+            throw new CoreException(ErrorType.FORBIDDEN, "입장 토큰이 필요합니다.");
+        }
+        String stored = entryTokenStore.find(userId)
+                .orElseThrow(() -> new CoreException(ErrorType.FORBIDDEN, "유효한 입장 토큰이 없습니다."));
+        if (!stored.equals(token)) {
+            throw new CoreException(ErrorType.FORBIDDEN, "입장 토큰이 일치하지 않습니다.");
+        }
+    }
+
+    /** 주문 성공 후 토큰을 소진(삭제)한다. 관문이 꺼져 있으면 아무 것도 하지 않는다. */
+    public void consumeEntry(Long userId) {
+        if (!gateEnabled) {
+            return;
+        }
+        entryTokenStore.remove(userId);
+    }
+}

apps/commerce-api/src/main/java/com/loopers/application/queue/QueueInfo.java

@@ -0,0 +1,19 @@
+package com.loopers.application.queue;
+
+import java.util.Optional;
+
+public record QueueInfo(long position, long estimatedWaitSeconds, Optional<String> token) {
+
+    // Phase 0 처리량 산정 근거: 커넥션풀 50 / 200ms → 250 TPS → 안전마진 70% → 175 TPS
+    private static final long THROUGHPUT_PER_SEC = 175;
+
+    /** 대기 중: 순번으로 예상시간 계산, 토큰 없음. */
+    public static QueueInfo of(long rank) {
+        return new QueueInfo(rank, rank / THROUGHPUT_PER_SEC, Optional.empty());
+    }
+
+    /** 입장 허가(내 차례): 순번 0, 토큰 발급됨. */
+    public static QueueInfo admitted(String token) {
+        return new QueueInfo(0L, 0L, Optional.of(token));
+    }
+}

apps/commerce-api/src/main/java/com/loopers/application/queue/TokenIssueScheduler.java

@@ -0,0 +1,43 @@
+package com.loopers.application.queue;
+
+import com.loopers.domain.queue.EntryTokenStore;
+import com.loopers.domain.queue.WaitingQueueRepository;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.scheduling.annotation.Scheduled;
+import org.springframework.stereotype.Component;
+
+import java.util.List;
+
+@Slf4j
+@RequiredArgsConstructor
+@Component
+@ConditionalOnProperty(prefix = "loopers.queue.scheduler", name = "enabled", havingValue = "true", matchIfMissing = true)
+public class TokenIssueScheduler {
+
+    private final WaitingQueueRepository waitingQueueRepository;
+    private final EntryTokenStore entryTokenStore;
+
+    @Value("${loopers.queue.scheduler.batch-size:18}")
+    private int batchSize;
+
+    /**
+     * 100ms 마다 대기열 앞 N명을 꺼내 입장 토큰을 발급한다.
+     * (Thundering Herd 완화: 1초에 몰지 않고 100ms 단위로 ~18명씩 분산)
+     */
+    @Scheduled(fixedDelayString = "${loopers.queue.scheduler.interval-ms:100}")
+    public void issueTokens() {
+        try {
+            List<Long> admitted = waitingQueueRepository.popMin(batchSize);
+            for (Long userId : admitted) {
+                entryTokenStore.issue(userId);
+            }
+        } catch (Exception e) {
+            // ★ @Scheduled 메서드에서 예외가 밖으로 나가면 이후 실행이 조용히 취소된다.
+            //   반드시 여기서 삼켜서 스케줄러가 계속 돌게 한다.
+            log.error("토큰 발급 스케줄러 실행 중 오류", e);
+        }
+    }
+}

apps/commerce-api/src/main/java/com/loopers/domain/queue/EntryTokenStore.java

@@ -0,0 +1,15 @@
+package com.loopers.domain.queue;
+
+import java.util.Optional;
+
+public interface EntryTokenStore {
+
+    /** userId 에게 입장 토큰을 발급하고, 발급된 토큰 값을 반환한다. TTL 후 자동 만료. */
+    String issue(Long userId);
+
+    /** userId 의 현재 유효한 토큰을 조회한다. 없거나 만료됐으면 empty. */
+    Optional<String> find(Long userId);
+
+    /** 사용 완료된 토큰을 삭제한다. */
+    void remove(Long userId);
+}

apps/commerce-api/src/main/java/com/loopers/domain/queue/WaitingQueueRepository.java

@@ -0,0 +1,19 @@
+package com.loopers.domain.queue;
+
+import java.util.List;
+import java.util.Optional;
+
+public interface WaitingQueueRepository {
+
+    /** 대기열에 진입한다. 이미 대기 중이면 순번을 유지한다(중복 진입 무시). */
+    void enter(Long userId);
+
+    /** 현재 순번(0-based). 대기열에 없으면 empty. */
+    Optional<Long> findRank(Long userId);
+
+    /** 현재 대기 중인 전체 인원. */
+    long size();
+
+    /** 대기열 맨 앞 N명을 꺼낸다(제거 + 반환). 스케줄러가 입장 처리에 사용. */
+    List<Long> popMin(int count);
+}

apps/commerce-api/src/main/java/com/loopers/infrastructure/queue/RedisEntryTokenStore.java

@@ -0,0 +1,51 @@
+package com.loopers.infrastructure.queue;
+
+import com.loopers.config.redis.RedisConfig;
+import com.loopers.domain.queue.EntryTokenStore;
+import org.springframework.beans.factory.annotation.Qualifier;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.data.redis.core.RedisTemplate;
+import org.springframework.stereotype.Repository;
+
+import java.time.Duration;
+import java.util.Optional;
+import java.util.UUID;
+
+@Repository
+public class RedisEntryTokenStore implements EntryTokenStore {
+
+    private static final String TOKEN_KEY_PREFIX = "queue:token:";
+
+    private final RedisTemplate<String, String> redisTemplate;
+    private final Duration ttl;
+
+    public RedisEntryTokenStore(
+            @Qualifier(RedisConfig.REDIS_TEMPLATE_MASTER) RedisTemplate<String, String> redisTemplate,
+            @Value("${loopers.queue.token.ttl-seconds:300}") long ttlSeconds   // 기본 5분, 오버라이드 가능
+    ) {
+        this.redisTemplate = redisTemplate;
+        this.ttl = Duration.ofSeconds(ttlSeconds);
+    }
+
+    @Override
+    public String issue(Long userId) {
+        String token = UUID.randomUUID().toString();
+        // SET queue:token:{userId} {token} EX {ttl}  → TTL 지나면 Redis 가 알아서 삭제
+        redisTemplate.opsForValue().set(key(userId), token, ttl);
+        return token;
+    }
+
+    @Override
+    public Optional<String> find(Long userId) {
+        return Optional.ofNullable(redisTemplate.opsForValue().get(key(userId)));
+    }
+
+    @Override
+    public void remove(Long userId) {
+        redisTemplate.delete(key(userId));
+    }
+
+    private String key(Long userId) {
+        return TOKEN_KEY_PREFIX + userId;
+    }
+}

apps/commerce-api/src/main/java/com/loopers/infrastructure/queue/RedisWaitingQueueRepository.java

@@ -0,0 +1,65 @@
+package com.loopers.infrastructure.queue;
+
+import com.loopers.config.redis.RedisConfig;
+import com.loopers.domain.queue.WaitingQueueRepository;
+import org.springframework.beans.factory.annotation.Qualifier;
+import org.springframework.data.redis.core.RedisTemplate;
+import org.springframework.data.redis.core.ZSetOperations;
+import org.springframework.stereotype.Repository;
+
+import java.util.List;
+import java.util.Objects;
+import java.util.Optional;
+import java.util.Set;
+
+@Repository
+public class RedisWaitingQueueRepository implements WaitingQueueRepository {
+
+    private static final String WAITING_QUEUE_KEY = "queue:waiting";
+
+    // 순서(순번)는 단일 기준점에서만 정해야 하므로, 쓰기/읽기 모두 마스터 템플릿을 쓴다.
+    // (Replica 로 읽으면 복제 지연 때문에 순번이 뒤처지거나 토큰을 놓칠 수 있다.)
+    private final RedisTemplate<String, String> redisTemplate;
+
+    public RedisWaitingQueueRepository(
+            @Qualifier(RedisConfig.REDIS_TEMPLATE_MASTER) RedisTemplate<String, String> redisTemplate
+    ) {
+        this.redisTemplate = redisTemplate;
+    }
+
+    @Override
+    public void enter(Long userId) {
+        // ZADD NX: 이미 대기 중이면 score(진입시각)를 덮어쓰지 않는다 → 최초 순번 유지(중복 진입 무시)
+        redisTemplate.opsForZSet()
+                .addIfAbsent(WAITING_QUEUE_KEY, String.valueOf(userId), System.currentTimeMillis());
+    }
+
+    @Override
+    public Optional<Long> findRank(Long userId) {
+        // ZRANK: score 오름차순에서 몇 번째인지(0-based). 없으면 null → empty
+        Long rank = redisTemplate.opsForZSet().rank(WAITING_QUEUE_KEY, String.valueOf(userId));
+        return Optional.ofNullable(rank);
+    }
+
+    @Override
+    public long size() {
+        // ZCARD: 대기열 전체 인원. 키가 없으면 null 이므로 0 으로 보정
+        Long count = redisTemplate.opsForZSet().zCard(WAITING_QUEUE_KEY);
+        return count == null ? 0L : count;
+    }
+
+    @Override
+    public List<Long> popMin(int count) {
+        // ZPOPMIN: score 가 가장 낮은(=먼저 온) N명을 꺼내면서 동시에 제거한다 (atomic)
+        Set<ZSetOperations.TypedTuple<String>> popped =
+                redisTemplate.opsForZSet().popMin(WAITING_QUEUE_KEY, count);
+        if (popped == null) {
+            return List.of();
+        }
+        return popped.stream()
+                .map(ZSetOperations.TypedTuple::getValue)
+                .filter(Objects::nonNull)
+                .map(Long::valueOf)
+                .toList();
+    }
+}

apps/commerce-api/src/main/java/com/loopers/interfaces/api/order/OrderV1ApiSpec.java

@@ -8,5 +8,5 @@
 public interface OrderV1ApiSpec {
 
     @Operation(summary = "주문 생성", description = "여러 상품을 한 번에 주문한다. 재고 부족 시 전체 실패(All-or-Nothing).")
-    ApiResponse<OrderV1Dto.OrderResponse> createOrder(Long userId, OrderV1Dto.OrderRequest request);
+    ApiResponse<OrderV1Dto.OrderResponse> createOrder(Long userId, String entryToken, OrderV1Dto.OrderRequest request);
 }

apps/commerce-api/src/main/java/com/loopers/interfaces/api/order/OrderV1Controller.java

@@ -2,6 +2,7 @@
 
 import com.loopers.application.order.OrderFacade;
 import com.loopers.application.order.OrderInfo;
+import com.loopers.application.queue.QueueFacade;
 import com.loopers.interfaces.api.ApiResponse;
 import com.loopers.support.error.CoreException;
 import com.loopers.support.error.ErrorType;
@@ -14,22 +15,30 @@
 public class OrderV1Controller implements OrderV1ApiSpec {
 
     private final OrderFacade orderFacade;
+    private final QueueFacade queueFacade;
 
     @PostMapping
     @Override
     public ApiResponse<OrderV1Dto.OrderResponse> createOrder(
             @RequestHeader(value = "X-Loopers-UserId", required = false) Long userId,
+            @RequestHeader(value = "X-Entry-Token", required = false) String entryToken,
             @RequestBody OrderV1Dto.OrderRequest request
     ) {
         // ① 인증 식별자 확인 (헤더 필수)
         if (userId == null) {
             throw new CoreException(ErrorType.BAD_REQUEST, "X-Loopers-UserId 헤더가 필요합니다.");
         }
 
-        // ② 헤더 userId + 바디 request 를 합쳐 응용 입력(OrderCriteria)으로 변환 → Facade 호출
+        // ② 대기열 관문: 입장 토큰 검증 (관문이 꺼져 있으면 통과)
+        queueFacade.validateEntry(userId, entryToken);
+
+        // ③ 헤더 userId + 바디 request 를 합쳐 응용 입력(OrderCriteria)으로 변환 → Facade 호출
         OrderInfo info = orderFacade.placeOrder(request.toCriteria(userId));
 
-        // ③ 응용 출력(OrderInfo) → API 응답(OrderResponse) 으로 변환
+        // ④ 주문 성공 후 입장 토큰 소진(삭제)
+        queueFacade.consumeEntry(userId);
+
+        // ⑤ 응용 출력(OrderInfo) → API 응답(OrderResponse) 으로 변환
         return ApiResponse.success(OrderV1Dto.OrderResponse.from(info));
     }
 }

apps/commerce-api/src/main/java/com/loopers/interfaces/api/queue/QueueV1ApiSpec.java

@@ -0,0 +1,15 @@
+package com.loopers.interfaces.api.queue;
+
+import com.loopers.interfaces.api.ApiResponse;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+
+@Tag(name = "Queue V1 API", description = "주문 대기열 관련 API")
+public interface QueueV1ApiSpec {
+
+    @Operation(summary = "대기열 진입", description = "대기열에 진입하고 현재 순번과 예상 대기시간을 반환한다.")
+    ApiResponse<QueueV1Dto.EnterResponse> enter(Long userId);
+
+    @Operation(summary = "순번 조회", description = "현재 순번과 예상 대기시간을 반환한다. 대기열에 없으면 404.")
+    ApiResponse<QueueV1Dto.PositionResponse> position(Long userId);
+}