From 16466a7475b4c90cff233d5e9077d6f984308774 Mon Sep 17 00:00:00 2001
From: Oh YoungJe <pine7420@naver.com>
Date: Tue, 8 Sep 2026 16:27:24 +0900
Subject: [PATCH 1/2] =?UTF-8?q?[ICC-415]=20=EB=A1=9C=EA=B7=B8=20=EB=B6=84?=
 =?UTF-8?q?=EC=84=9D=ED=95=98=EC=97=AC=20=EC=8B=9D=EB=B3=84=EB=90=9C=20?=
 =?UTF-8?q?=EC=98=A4=EB=A5=98=20=EC=88=98=EC=A0=95=20(#434)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* [ICC-415] 🐛 fix: 메서드 불일치 요청이 500으로 응답되던 문제 수정

@ControllerAdvice 의 @ExceptionHandler 가 Spring 내장
DefaultHandlerExceptionResolver 보다 먼저 돌기 때문에,
HttpRequestMethodNotSupportedException 이 캐치올 Exception 핸들러에
잡혀 405 대신 500 + ERROR 로그로 나가고 있었다.

- HttpRequestMethodNotSupportedException 전용 핸들러 추가 (405 + WARN)
- RFC 9110 이 요구하는 Allow 헤더를 지원 메서드로 채움
- ExceptionMessage.METHOD_NOT_ALLOWED 추가

캐치올 500 ERROR 에 진짜 미처리 예외만 남게 되어,
ERROR 로그 기반 알림의 신뢰도가 올라간다.

* [ICC-415] ⚡ perf: 보류 문항 재생성 병렬화 및 생성 흐름 4단계 구조화

보류 문항 재생성이 직렬이라 건당 40~280초가 그대로 누적됐다.
실측 세션 하나에서 9건이 11분 27초를 먹어 전체 16분 11초 중
대부분을 차지했고, 이 때문에 세션이 스테일 정리 임계를 넘겼다.

- 워커가 heldQueue 를 poll 로 나눠 소비하도록 변경
  (항목 간 순서 의존이 없고 conversation 은 읽기 전용)
- 목표 문항 수 초과 저장은 Semaphore 티켓 선점으로 차단,
  산출 실패 시 반납해 다음 항목이 쓰게 한다
- 동시성 상한을 30 으로 상향
  Vertex 는 generateContent 에 동시성 쿼터를 두지 않고(RPM·TPM 만),
  quizCount 최대가 30 이라 작업 개수가 곧 상한이다
- run() 을 캐시 생성 → 퀴즈 생성 → 평가 → 재생성 4단계로 정리하고
  각 단계에 딸린 메서드를 구역으로 모음

같은 조건에서 재생성 구간이 11분 27초 → 약 3분으로 줄어든다.

* [ICC-415] 🐛 fix: 정리 스케줄러가 진행 중인 생성 세트를 삭제하던 문제 수정

STALE_THRESHOLD_MINUTES 가 10분이라 그보다 오래 걸린 생성이
"방치된 GENERATING"으로 판정돼 삭제됐다. 스케줄러는 DB 행만 지우고
생성 스레드에는 아무 신호도 보내지 않으므로, 세션은 이미 사라진 세트에
저장을 시도하다 finalizePartialSuccess 에서 터졌다.

7일 관측: 세션 40건 중 10분 초과 12건, 그중 11건이 결과물 전손.

- 임계를 15분으로 상향 (세션 시한 10분 + 여유)
- 부하 하네스가 같은 쿼리를 태우므로 Mock 구현도 동기화
- 로그·javadoc·테스트 표기의 "10분"을 함께 정정

세션 시계는 세트 createdAt 보다 늦게 출발하고 스케줄러 판정도
주기(1분)만큼 밀리므로, 두 값을 같게 두면 경계에서 다시 재현된다.
그 근거를 상수 주석에 남겼다.

* [ICC-415] 🔧 chore: 운영에서 무효인 chat-timeout-ms 설정 제거

세션급 시한을 의도한 값이었지만, GeminiClientConfig 가
customHttpClient 를 쓰면 SDK 가 HttpOptions.timeout 을 건너뛰므로
운영 경로에서는 아무 효력이 없었다. 값을 조정해도 동작이 변하지 않아
설정과 실제가 어긋나 있었다.

- q-asker.ai.chat-timeout-ms 및 QAskerAiProperties.chatTimeoutMs 삭제
- test/mock 클라이언트의 httpOptions 도 제거
  (실제 호출을 하지 않는 스텁이라 시한을 걸 대상이 없다)

실효 시한은 OkHttpClient 에 직접 건 connect/read/call 세 계층만 남는다.
다시 HttpOptions.timeout 을 붙이려는 시도를 막도록 경고 주석은 유지.

* [ICC-415] 💡 docs: 커넥션 풀·톰캣 기본값 명시 및 prod keepalive 단축

값을 조정할 때 출발점이 무엇이었는지 보이도록, 지금까지 미설정으로
기본값에 맡기던 항목을 그대로 적어뒀다. 동작은 대부분 동일하다.

- database-config.yml: HikariCP 7.0.2 기본값 명시
  가상 스레드라 요청 동시성엔 상한이 없어 실질 처리량은
  maximum-pool-size(10)가 결정한다는 점, minimum-idle 을 숫자로
  박은 이상 풀을 키울 땐 둘을 함께 올려야 한다는 점을 남김
- app-common.yml: Tomcat 11.0.22 기본값 명시
  가상 스레드가 켜져 있어 threads.max/min-spare 는 적용되지 않는다
- prod 만 keepalive-time 60000 으로 오버라이드 (기본 120000)
  무트래픽 시간대에 DB 가 내려갔을 때의 탐지 지연을 절반으로 좁힌다
- CLAUDE.md 설정 파일 설명과 JUnit 버전 갱신
- Alloy 인스턴스 스펙 표기 정정 (8GB → 10GB)
---
 CLAUDE.md                                     |   8 +-
 app/src/main/resources/config/ai-setting.yml  |   1 -
 app/src/main/resources/config/app-common.yml  |  31 ++
 .../main/resources/config/database-config.yml |  43 +++
 infra/monitoring/docker-compose.yml           |   2 +-
 .../qasker/global/error/ExceptionMessage.java |   1 +
 .../global/error/GlobalExceptionHandler.java  |  21 ++
 .../error/GlobalExceptionHandlerTest.java     |  14 +
 .../qasker/ai/config/GeminiClientConfig.java  |   6 +-
 .../ai/properties/QAskerAiProperties.java     |   3 -
 .../AbstractChunkedQuizOrchestrator.java      | 314 +++++++++---------
 .../MockStaleGenerationRecoveryService.java   |   2 +-
 .../scheduler/StaleGenerationRecovery.java    |   2 +-
 .../StaleGenerationRecoveryScheduler.java     |   2 +-
 .../StaleGenerationRecoveryService.java       |   9 +-
 .../StaleGenerationRecoverySchedulerTest.java |   2 +-
 16 files changed, 290 insertions(+), 171 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 8d5dcbd3..22f1bc05 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -28,7 +28,7 @@
 | 컨테이너          | Jib (Docker)                                                          | 3.5.3          |
 | 포맷터           | Spotless + Google Java Format                                         | 8.8.0 / 1.25.2 |
 | DB 마이그레이션     | Flyway                                                                | (Boot BOM)     |
-| 테스트           | JUnit 5                                                               | (Boot BOM)     |
+| 테스트           | JUnit 5                                                               | 5.14.4         |
 
 ## 명령어 (Scripts)
 
@@ -72,13 +72,13 @@ q-asker/api/
 │       ├── application-test.yml  # test 프로파일 (CI/JUnit, H2 + 더미 Jasypt/OCI)
 │       ├── db/migration/         # Flyway 마이그레이션 SQL (V1~V20)
 │       └── config/               # 분리된 설정 파일들
-│           ├── database-config.yml   # 서버, DB, JPA, 캐시
-│           ├── ai-setting.yml        # Google Gemini AI 설정 (생성/ESSAY 채점/품질 검증 모델, 토큰 단가)
+│           ├── database-config.yml   # DB(HikariCP), JPA, 캐시, Flyway (hikari 블록은 대부분 기본값을 명시만 한 것 — 가상 스레드라 요청 동시성엔 상한이 없어 실질 처리량은 maximum-pool-size(10)가 결정하고, minimum-idle 이 숫자로 박혀 있어 풀을 키울 땐 둘을 함께 올려야 고정 크기 성질이 유지된다. prod 만 keepalive-time 60s 로 오버라이드)
+│           ├── ai-setting.yml        # Google Gemini AI 설정 (생성/ESSAY 채점/품질 검증 모델, 토큰 단가 — 모델을 바꾸면 같은 계층의 price-*-per-1m 도 그 모델 실단가로 함께 고쳐야 GeminiMetricsRecorder 비용 카운터가 맞는다)
 │           ├── spring-security.yml   # JWT, OAuth2, CORS
 │           ├── oci-bucket-config.yml # OCI Object Storage, CDN
 │           ├── jodconverter.yml      # LibreOffice 문서변환
 │           ├── actuator.yml          # Actuator, Prometheus
-│           ├── app-common.yml        # 앱 커스텀 설정
+│           ├── app-common.yml        # 앱 커스텀 설정 + 서버(graceful shutdown, server.tomcat)·멀티파트·가상 스레드 활성화 (tomcat 블록은 전부 기본값을 명시만 한 것 — 가상 스레드가 켜져 있어 threads.max/min-spare 는 적용되지 않는다)
 │           ├── github.yml            # 피드백 → GitHub 이슈 자동 등록 (owner/repo/토큰/라벨)
 │           ├── resilience.yml        # Circuit Breaker
 │           ├── spring-doc.yml        # Swagger/OpenAPI
diff --git a/app/src/main/resources/config/ai-setting.yml b/app/src/main/resources/config/ai-setting.yml
index 29be0245..a61b65f4 100644
--- a/app/src/main/resources/config/ai-setting.yml
+++ b/app/src/main/resources/config/ai-setting.yml
@@ -13,7 +13,6 @@ spring:
 
 q-asker:
   ai:
-    chat-timeout-ms: 500000
     cache-ttl: 15m          # 컨텍스트 캐시 TTL (인터리빙 세션 커버)
     # 스트리밍 시한 계층 (connect < read < call). 안쪽 시한이 바깥보다 짧아야
     # 각 계층이 자기 실패를 자기 이름의 예외로 먼저 잡는다 — 순서가 무너지면 바깥층이
diff --git a/app/src/main/resources/config/app-common.yml b/app/src/main/resources/config/app-common.yml
index b29207da..e24761d1 100644
--- a/app/src/main/resources/config/app-common.yml
+++ b/app/src/main/resources/config/app-common.yml
@@ -24,6 +24,37 @@ q-asker:
 server:
   shutdown: graceful
 
+  # 아래 tomcat 블록은 전부 Spring Boot 4.1.0 / Tomcat 11.0.22 기본값을 그대로 적어둔 것이다.
+  # 동작은 지금과 동일하며, 값을 조정할 때 출발점이 무엇이었는지 보이게 하는 것이 목적.
+  tomcat:
+    # 동시에 수용하는 소켓 커넥션 상한. 초과분은 accept-count 백로그에 쌓이고,
+    # 그마저 차면 OS가 연결을 거부한다.
+    max-connections: 8192
+    accept-count: 100
+
+    threads:
+      # spring.threads.virtual.enabled: true 이면 Boot가 커넥터 executor를 가상 스레드로 교체하므로
+      # 이 두 값은 적용되지 않는다. 가상 스레드를 끄는 순간 되살아난다.
+      max: 200
+      min-spare: 10
+
+    # Boot는 이 둘을 설정하지 않고 Tomcat 기본값에 맡긴다(둘 다 60s).
+    # keep-alive-timeout은 미지정 시 connection-timeout을 따라가므로 함께 움직인다.
+    connection-timeout: 60s
+    keep-alive-timeout: 60s
+    max-keep-alive-requests: 100
+
+    max-http-form-post-size: 2MB
+    max-http-response-header-size: 8KB
+    max-swallow-size: 2MB
+    max-parameter-count: 1000
+    max-part-count: 50
+    max-part-header-size: 512B
+
+    processor-cache: 200
+    background-processor-delay: 10s
+    uri-encoding: UTF-8
+
 spring:
   lifecycle:
     timeout-per-shutdown-phase: 300s
diff --git a/app/src/main/resources/config/database-config.yml b/app/src/main/resources/config/database-config.yml
index 049c8646..49ae6acc 100644
--- a/app/src/main/resources/config/database-config.yml
+++ b/app/src/main/resources/config/database-config.yml
@@ -1,5 +1,40 @@
 # 데이터베이스, JPA, 캐시 설정
 spring:
+  # 아래 hikari 블록은 전부 HikariCP 7.0.2 기본값을 그대로 적어둔 것이다.
+  # 동작은 지금과 동일하며, 값을 조정할 때 출발점이 무엇이었는지 보이게 하는 것이 목적.
+  # (여기에 없는 connection-test-query·connection-init-sql·transaction-isolation·pool-name의
+  #  기본값은 모두 미설정이라 명시할 값이 없다 — JDBC4 isValid 검증, 드라이버 기본 격리수준을 쓴다.)
+  datasource:
+    hikari:
+      # 커넥션 상한. spring.threads.virtual.enabled: true 라 요청 동시성엔 상한이 없으므로,
+      # 부하 시 실질 처리량은 이 값이 결정한다.
+      maximum-pool-size: 10
+      # 기본값은 "maximum-pool-size와 동일"(고정 크기 풀)이다. 여기서 숫자로 박아뒀으므로
+      # maximum-pool-size를 올릴 때 이 값도 함께 올려야 같은 성질이 유지된다.
+      minimum-idle: 10
+
+      # 커넥션 획득 대기 한도. 풀이 마르면 이 시간 뒤 SQLTransientConnectionException.
+      connection-timeout: 30000
+      # 커넥션 유효성 검사 자체의 시한.
+      validation-timeout: 5000
+      # 유휴 커넥션 회수 한도. minimum-idle == maximum-pool-size 인 동안은 회수할 유휴분이
+      # 없으므로 동작하지 않는다.
+      idle-timeout: 600000
+      # 커넥션 최대 수명. DB의 wait_timeout보다 짧게 두어 서버가 먼저 끊는 상황을 피한다.
+      max-lifetime: 1800000
+      # 유휴 커넥션 핑 주기. 자세한 내용은 아래 prod 오버라이드 참고.
+      keepalive-time: 120000
+
+      # 대여 후 반납되지 않는 커넥션 경고 임계. 0이면 누수 탐지를 하지 않는다.
+      leak-detection-threshold: 0
+      # 기동 시 첫 커넥션 확보 실패를 어떻게 다룰지. 양수면 그 시간만큼 재시도한 뒤 기동 실패.
+      initialization-fail-timeout: 1
+
+      auto-commit: true
+      read-only: false
+      register-mbeans: false
+      allow-pool-suspension: false
+      isolate-internal-queries: false
   jpa:
     open-in-view: false
     properties:
@@ -42,6 +77,14 @@ spring:
     type: simple
   datasource:
     driver-class-name: com.mysql.cj.jdbc.Driver
+    hikari:
+      # 유휴 커넥션을 주기적으로 핑(COM_PING)해 죽었으면 즉시 폐기·재생성한다.
+      # 기본값 120000(2분)을 절반으로 줄여, 무트래픽 시간대에 DB가 내려갔을 때의
+      # 장애 탐지 지연을 그만큼 좁힌다. 0으로 끄면 풀이 유휴 커넥션의 생사를 감시하지 않아
+      # max-lifetime(30분) 로테이션이 그 커넥션을 건드릴 때까지 "정상 보유"로 남는다.
+      # 단위는 밀리초(HikariConfig.setKeepaliveTime(long)). 최소 허용값 30000,
+      # max-lifetime보다 작아야 하며 검사 시한은 validation-timeout(5s)을 따른다.
+      keepalive-time: 60000
   jpa:
     hibernate:
       ddl-auto: validate
diff --git a/infra/monitoring/docker-compose.yml b/infra/monitoring/docker-compose.yml
index f06f2a71..ee09ccee 100644
--- a/infra/monitoring/docker-compose.yml
+++ b/infra/monitoring/docker-compose.yml
@@ -1,6 +1,6 @@
 # =============================================================
 # #2 Spring Boot 인스턴스 - Alloy 에이전트
-# OCI ARM 2 OCPU / 8GB | Spring Boot + JODConverter 로그 수집
+# OCI ARM 2 OCPU / 10GB | Spring Boot + JODConverter 로그 수집
 # 기존 Spring Boot docker-compose에 병합 또는 별도 실행
 # =============================================================
 
diff --git a/modules/global/src/main/java/com/icc/qasker/global/error/ExceptionMessage.java b/modules/global/src/main/java/com/icc/qasker/global/error/ExceptionMessage.java
index 5d1a0a59..dcbe08ae 100644
--- a/modules/global/src/main/java/com/icc/qasker/global/error/ExceptionMessage.java
+++ b/modules/global/src/main/java/com/icc/qasker/global/error/ExceptionMessage.java
@@ -10,6 +10,7 @@ public enum ExceptionMessage {
   // ## 공통 (global)
   DEFAULT_ERROR(HttpStatus.INTERNAL_SERVER_ERROR, "서버 오류가 발생했습니다."),
   INVALID_REQUEST(HttpStatus.BAD_REQUEST, "잘못된 요청입니다."),
+  METHOD_NOT_ALLOWED(HttpStatus.METHOD_NOT_ALLOWED, "허용되지 않은 요청 메서드입니다."),
   FILE_SIZE_EXCEEDED(HttpStatus.PAYLOAD_TOO_LARGE, "파일 크기가 제한을 초과했습니다."),
 
   // ## 파일 업로드/변환 (oci, quiz-make, util)
diff --git a/modules/global/src/main/java/com/icc/qasker/global/error/GlobalExceptionHandler.java b/modules/global/src/main/java/com/icc/qasker/global/error/GlobalExceptionHandler.java
index 66b6483f..6c3b081d 100644
--- a/modules/global/src/main/java/com/icc/qasker/global/error/GlobalExceptionHandler.java
+++ b/modules/global/src/main/java/com/icc/qasker/global/error/GlobalExceptionHandler.java
@@ -2,11 +2,14 @@
 
 import io.github.resilience4j.circuitbreaker.CallNotPermittedException;
 import java.util.Objects;
+import java.util.Set;
 import lombok.extern.slf4j.Slf4j;
 import org.apache.catalina.connector.ClientAbortException;
+import org.springframework.http.HttpMethod;
 import org.springframework.http.HttpStatus;
 import org.springframework.http.ResponseEntity;
 import org.springframework.validation.FieldError;
+import org.springframework.web.HttpRequestMethodNotSupportedException;
 import org.springframework.web.bind.MethodArgumentNotValidException;
 import org.springframework.web.bind.annotation.ControllerAdvice;
 import org.springframework.web.bind.annotation.ExceptionHandler;
@@ -77,6 +80,24 @@ public ResponseEntity<CustomErrorResponse> handleMethodArgumentNotValid(
     return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(new CustomErrorResponse(message));
   }
 
+  /**
+   * 경로 매핑은 있으나 HTTP 메서드가 다른 요청(예: POST 전용 /generation 에 GET). 클라이언트 오류이므로 405로 응답한다(미처리 시
+   * catch-all의 500으로 샘 — @ControllerAdvice가 Spring 내장 405 변환보다 먼저 돈다). RFC 9110상 405 응답은 Allow 헤더로
+   * 허용 메서드를 알려야 한다.
+   */
+  @ExceptionHandler(HttpRequestMethodNotSupportedException.class)
+  public ResponseEntity<CustomErrorResponse> handleMethodNotSupported(
+      HttpRequestMethodNotSupportedException e) {
+    log.warn("[허용되지 않은 메서드] {} 요청 거부", e.getMethod());
+
+    ResponseEntity.BodyBuilder builder = ResponseEntity.status(HttpStatus.METHOD_NOT_ALLOWED);
+    Set<HttpMethod> supported = e.getSupportedHttpMethods();
+    if (supported != null && !supported.isEmpty()) {
+      builder.allow(supported.toArray(new HttpMethod[0]));
+    }
+    return builder.body(new CustomErrorResponse(ExceptionMessage.METHOD_NOT_ALLOWED.getMessage()));
+  }
+
   @ExceptionHandler(MaxUploadSizeExceededException.class)
   public ResponseEntity<CustomErrorResponse> handleMaxUploadSizeExceededException(
       MaxUploadSizeExceededException e) {
diff --git a/modules/global/src/test/java/com/icc/qasker/global/error/GlobalExceptionHandlerTest.java b/modules/global/src/test/java/com/icc/qasker/global/error/GlobalExceptionHandlerTest.java
index d30bd71d..5c9f11c6 100644
--- a/modules/global/src/test/java/com/icc/qasker/global/error/GlobalExceptionHandlerTest.java
+++ b/modules/global/src/test/java/com/icc/qasker/global/error/GlobalExceptionHandlerTest.java
@@ -4,6 +4,7 @@
 import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
 import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
 import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.content;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.header;
 import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
 import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
 
@@ -131,6 +132,19 @@ void unhandledException() throws Exception {
         .andExpect(jsonPath("$.message").value(ExceptionMessage.DEFAULT_ERROR.getMessage()));
   }
 
+  @Test
+  @DisplayName("POST 전용 경로에 GET → 405 + Allow 헤더 + WARN 로그 (500 아님)")
+  void methodNotSupported() throws Exception {
+    mockMvc
+        .perform(get("/validate"))
+        .andExpect(status().isMethodNotAllowed())
+        .andExpect(header().string("Allow", "POST"))
+        .andExpect(jsonPath("$.message").value(ExceptionMessage.METHOD_NOT_ALLOWED.getMessage()));
+
+    assertThat(logAppender.list)
+        .anyMatch(e -> e.getLevel() == Level.WARN && e.getFormattedMessage().contains("GET"));
+  }
+
   @Test
   @DisplayName("요청 바디 검증 실패(@NotBlank) → 400 + 필드 오류 메시지 (500 아님)")
   void bodyValidationFails() throws Exception {
diff --git a/modules/quiz-ai/impl/src/main/java/com/icc/qasker/ai/config/GeminiClientConfig.java b/modules/quiz-ai/impl/src/main/java/com/icc/qasker/ai/config/GeminiClientConfig.java
index 314df29d..a8fdef7a 100644
--- a/modules/quiz-ai/impl/src/main/java/com/icc/qasker/ai/config/GeminiClientConfig.java
+++ b/modules/quiz-ai/impl/src/main/java/com/icc/qasker/ai/config/GeminiClientConfig.java
@@ -2,7 +2,6 @@
 
 import com.google.genai.Client;
 import com.google.genai.types.ClientOptions;
-import com.google.genai.types.HttpOptions;
 import com.icc.qasker.ai.properties.QAskerAiProperties;
 import lombok.RequiredArgsConstructor;
 import okhttp3.OkHttpClient;
@@ -40,9 +39,6 @@ public Client googleGenAiClient(GoogleGenAiConnectionProperties properties) {
   @Bean
   @org.springframework.context.annotation.Profile({"test", "mock"})
   public Client googleGenAiClientTest() {
-    return Client.builder()
-        .apiKey("ci-dummy-key")
-        .httpOptions(HttpOptions.builder().timeout(aiProperties.getChatTimeoutMs()).build())
-        .build();
+    return Client.builder().apiKey("ci-dummy-key").build();
   }
 }
diff --git a/modules/quiz-ai/impl/src/main/java/com/icc/qasker/ai/properties/QAskerAiProperties.java b/modules/quiz-ai/impl/src/main/java/com/icc/qasker/ai/properties/QAskerAiProperties.java
index 2502c342..b864083a 100644
--- a/modules/quiz-ai/impl/src/main/java/com/icc/qasker/ai/properties/QAskerAiProperties.java
+++ b/modules/quiz-ai/impl/src/main/java/com/icc/qasker/ai/properties/QAskerAiProperties.java
@@ -10,9 +10,6 @@
 @ConfigurationProperties(prefix = "q-asker.ai")
 public class QAskerAiProperties {
 
-  /** Gemini Chat API 타임아웃 (ms) — q-asker.ai.chat-timeout-ms */
-  private int chatTimeoutMs;
-
   /** 컨텍스트 캐시 TTL — q-asker.ai.cache-ttl. 한 세트 생성 세션(인터리빙 전체)을 커버하고, 종료 시 명시적으로 삭제한다. */
   private Duration cacheTtl;
 
diff --git a/modules/quiz-ai/impl/src/main/java/com/icc/qasker/ai/service/AbstractChunkedQuizOrchestrator.java b/modules/quiz-ai/impl/src/main/java/com/icc/qasker/ai/service/AbstractChunkedQuizOrchestrator.java
index 1258b1cd..3249a174 100644
--- a/modules/quiz-ai/impl/src/main/java/com/icc/qasker/ai/service/AbstractChunkedQuizOrchestrator.java
+++ b/modules/quiz-ai/impl/src/main/java/com/icc/qasker/ai/service/AbstractChunkedQuizOrchestrator.java
@@ -49,8 +49,17 @@
 @Slf4j
 public abstract class AbstractChunkedQuizOrchestrator<T> implements QuizTypeOrchestrator {
 
-  /** 비동기 생성 게이트 검증의 동시 실행 상한(외부 검증 모델 호출 버스트를 제한). */
-  private static final int VERIFY_CONCURRENCY = 8;
+  /**
+   * 비동기 생성 게이트 검증의 동시 실행 상한. Vertex 는 generateContent 에 동시성 쿼터를 두지 않으므로(제한은 RPM·TPM) 작업 개수가 곧 상한이다
+   * — quizCount 최대 30({@code GenerationRequest.DEFAULT_ALLOWED_COUNTS})을 덮어 세마포어가 막지 않게 한다.
+   *
+   * <p>TODO: 이 값은 <b>세션 1건</b> 기준이다. 세마포어·익스큐터가 Session 인스턴스 필드라 동시 생성 요청 수만큼 곱해진다(3요청 → 최대 90). 전역
+   * 상한이 없으므로 동시 생성이 늘면 제한 계층을 추가해야 한다.
+   */
+  private static final int VERIFY_CONCURRENCY = 30;
+
+  /** 보류 문항 재생성의 동시 실행 상한. 보류 큐 최대치(= quizCount)를 덮어 한 라운드에 소진한다. 세션당 기준인 점은 위와 같다. */
+  private static final int REGENERATE_CONCURRENCY = 30;
 
   private final GeminiFileService geminiFileService;
   private final ChatModel chatModel;
@@ -76,25 +85,16 @@ protected AbstractChunkedQuizOrchestrator(
     this.cacheManager = new GeminiContextCacheManager(chatModel, metricsRecorder);
   }
 
-  /** 청크 K(K≥2) 사용자 프롬프트 꼬리에 붙는 타입별 중복 회피 지침 문구. */
   protected abstract String dedupInstruction();
 
-  /** 스트리밍 JSON 배열 요소 타입 — {@link StreamingJsonArrayExtractor} 구성용(제네릭 타입 소거 우회). */
   protected abstract Class<T> elementType();
 
-  /** 응답 JSON 스키마. customInstruction 반영(선지형/서술형별). */
   protected abstract String responseSchema(String customInstruction);
 
-  /**
-   * 파싱된 질문 1개를 저장용 {@link AIProblem}으로 변환한다. 선지형은 선지 정렬을 흡수하고, 서술형은 항등 매핑한다. 저장 순서 = 대화 히스토리 순서
-   * 기준이므로 이 시점에 확정한다.
-   */
   protected abstract AIProblem toProblem(T question, List<Integer> sourcePages);
 
-  /** 이 질문을 채택할지 판단한다. 선지형: 선지 수 ≤ 상한. 서술형: 항상 true. 미달 시 drop. */
   protected abstract boolean accept(T question);
 
-  /** 재생성 응답 텍스트에서 첫 질문을 파싱한다. 구체 응답타입({@code BeanOutputConverter})은 하위가 안다. */
   protected abstract Optional<T> parseFirst(String text);
 
   @Override
@@ -102,46 +102,46 @@ public void generateQuiz(GenerationRequestToAI request) {
     new Session(request).run();
   }
 
-  /**
-   * 한 요청분의 인터리빙 실행 상태. 협력 빈은 바깥 인스턴스에서, 요청별 상태(캐시·대화 스레드·보류 큐·누적 메트릭)는 이 인스턴스에서 관리한다. {@code
-   * generateQuiz} 호출마다 새로 만들어지므로 오케스트레이터 빈은 무상태로 유지된다.
-   */
   private final class Session {
 
-    // 협력 객체·불변 설정 (생성자에서 1회 확정)
+    // 요청 파라미터
     private final GenerationRequestToAI request;
     private final QuizBatchSink sink;
     private final int quizCount;
     private final QuizType quizType;
+    private final String tag = getSupportedType().toString();
     private final String genGuideLine;
+
+    // PDF (외부 자원 핸들)
     private final FileMetadata metadata;
     private final Media pdfMedia;
-    // 컨텍스트 캐시: 전체 지침(문제+해설)+PDF를 1개 캐시. 생성·재생성이 공유한다. 실패 시 null → 폴백.
-    private final CacheRef genCache;
-    // Pass 1 검증 캐시(검증 루브릭+PDF 원문): 세션당 1개. 실패 시 null → 원문 대조 없는 검증.
-    private final CacheRef verifyCache;
-    private final String tag = getSupportedType().toString();
-    private final long startNanos = System.nanoTime();
 
-    // 누적 상태
-    // 멀티턴 대화 스레드 — U/A 턴만 누적. 캐시 사용 시 system·PDF는 캐시에, 폴백 시 각 요청이 phase별 system(+PDF)을 붙인다.
+    // 컨텍스트 캐시 — ① 캐시 생성 단계가 채우고 finally 에서 해제한다
+    private CacheRef genCache;
+    private CacheRef verifyCache;
+
+    // 비동기 검증 인프라
+    private final ExecutorService verifyExecutor = Executors.newVirtualThreadPerTaskExecutor();
+    private final Semaphore verifySlots = new Semaphore(VERIFY_CONCURRENCY);
+    private final List<CompletableFuture<Void>> verifyFutures = new CopyOnWriteArrayList<>();
+
+    // 대화 스레드 — 청크 루프(단일 스레드)만 쓴다
     private final List<Message> conversation = new ArrayList<>();
-    // 생성 게이트에서 미달 판정된 문항의 보류 큐. 여러 검증 워커가 동시에 add 하므로 락프리 동시 큐를 쓰고,
-    // 청크 루프 종료(배리어) 후 단일 스레드에서 FIFO로 1회 재생성 소진한다.
+
+    // 진행 상태 — 검증·재생성 워커가 동시에 갱신한다
     private final Queue<HeldProblem> heldQueue = new ConcurrentLinkedQueue<>();
-    private final DoubleAdder totalCost = new DoubleAdder();
-    private final AtomicLong firstNanos = new AtomicLong(0);
-    private final AtomicLong lastNanos = new AtomicLong(0);
-    // delivered = 검증 통과·저장된 문항 수. submitted = 검증에 제출한(생성) 문항 수(파싱 중단·청크 진행 판단 기준).
     private final AtomicInteger delivered = new AtomicInteger(0);
     private final AtomicInteger submitted = new AtomicInteger(0);
 
-    // 생성 스트림 소비와 게이트 검증을 분리하는 비동기 인프라.
-    // 스트림 콜백은 문항을 verifyExecutor에 제출하고 즉시 리턴한다(스트림 논블로킹).
-    // 워커는 verifySlots로 동시성을 제한한 채 검증→통과: 저장·통지 / 미달: 보류 큐.
-    private final ExecutorService verifyExecutor = Executors.newVirtualThreadPerTaskExecutor();
-    private final Semaphore verifySlots = new Semaphore(VERIFY_CONCURRENCY);
-    private final List<CompletableFuture<Void>> verifyFutures = new CopyOnWriteArrayList<>();
+    // 청크 진행 — ② 퀴즈 생성 단계(단일 스레드)만 쓴다
+    private int chunkTotal;
+    private int chunksDone;
+
+    // 계측
+    private final long startNanos = System.nanoTime();
+    private final AtomicLong firstNanos = new AtomicLong(0);
+    private final AtomicLong lastNanos = new AtomicLong(0);
+    private final DoubleAdder totalCost = new DoubleAdder();
 
     private Session(GenerationRequestToAI request) {
       this.request = request;
@@ -152,79 +152,79 @@ private Session(GenerationRequestToAI request) {
       this.metadata = resolvePdf(request);
       this.pdfMedia =
           new Media(MimeTypeUtils.parseMimeType("application/pdf"), URI.create(metadata.uri()));
-      // PDF + 시스템 가이드라인은 어떤 세션이든 공유하는 캐시, 메인 모델이 사용하는 캐시
-      this.genCache =
-          cacheManager
-              .create(tag, genGuideLine, metadata.uri(), aiProperties.getCacheTtl())
-              .orElse(null);
-      // 검증 모델이 사용하는 캐시
-      this.verifyCache = qualityGate.createPass1Cache(metadata.uri(), quizType.name()).orElse(null);
     }
 
     private void run() {
-      List<Integer> chunkPlan =
-          ChunkPlanner.plan(quizCount, aiProperties.getChunk().getChunkSize());
-      log.info(
-          "{} 문제 수에 맞게 청크 분할 완료: 요청={}문항, chunk-size={}, 청크={}개",
-          tag,
-          quizCount,
-          aiProperties.getChunk().getChunkSize(),
-          chunkPlan.size());
-
-      int chunksDone = 0;
       try {
-        for (int chunkIndex = 0; chunkIndex < chunkPlan.size(); chunkIndex++) {
-          if (submitted.get() >= quizCount) break;
-          int chunkSize = chunkPlan.get(chunkIndex);
-
-          List<AIProblem> generated = runGenerationPhase(chunkIndex, chunkSize);
-
-          if (generated.isEmpty()) {
-            log.warn("{} 청크 #{} 산출물 없음 — 부분 저장·완료.", tag, chunkIndex);
-            break;
-          }
-          chunksDone++;
-        }
-
-        // 배리어: 비동기 검증이 모두 정착해야 heldQueue·delivered가 확정된다.
+        // 1. 캐시 생성
+        createCaches();
+        // 2. 퀴즈 생성 — 문항을 스트림으로 받으며 평가를 비동기로 제출한다
+        generateChunks();
+        // 3. 평가 — 제출된 평가가 모두 정착할 때까지 기다린다
         awaitVerifications();
-
-        // 보류된 미달 문항을 세션 내에서 1회 재생성해 통과분을 채운다(원문 컨텍스트·대화 스레드 활용).
-        processHeldQueue();
+        // 4. 재생성 — 평가에서 탈락한 문항을 1문제씩 다시 만든다
+        regenerateHeld();
       } catch (CustomException e) {
         awaitVerifications();
         if (delivered.get() == 0) throw e;
-        log.warn("{} 인터리빙 도중 비즈니스 오류. {}문항 보존.", tag, delivered.get(), e);
+        log.warn("{} 퀴즈 생성 중 비즈니스 오류. {}문항 보존.", tag, delivered.get(), e);
       } catch (Exception e) {
         awaitVerifications();
         if (delivered.get() == 0) throw new GeminiInfraException("Gemini 인프라 장애", e);
-        log.warn("{} 인터리빙 도중 인프라 오류. {}문항 보존.", tag, delivered.get(), e);
+        log.warn("{} 퀴즈 생성 중 인프라 오류. {}문항 보존.", tag, delivered.get(), e);
         metricsRecorder.recordStreamingTimeout(tag);
       } finally {
-        // 예외로 중단됐어도 인플라이트 검증을 마저 정착시킨 뒤(멱등) 캐시를 삭제한다.
         awaitVerifications();
         verifyExecutor.shutdown();
-        cacheManager.delete(tag, genCache == null ? null : genCache.name());
-        qualityGate.deletePass1Cache(verifyCache);
+        releaseCaches();
       }
+      recordOutcome();
+    }
 
+    // ══════════════════════════════════════════════════════════════════
+    //  1. 캐시 생성
+    // ══════════════════════════════════════════════════════════════════
+    private void createCaches() {
+      this.genCache =
+          cacheManager
+              .create(tag, genGuideLine, metadata.uri(), aiProperties.getCacheTtl())
+              .orElse(null);
+      this.verifyCache = qualityGate.createPass1Cache(metadata.uri(), quizType.name()).orElse(null);
+    }
+
+    private void releaseCaches() {
+      cacheManager.delete(tag, genCache == null ? null : genCache.name());
+      qualityGate.deletePass1Cache(verifyCache);
+    }
+
+    // ══════════════════════════════════════════════════════════════════
+    //  2. 퀴즈 생성
+    // ══════════════════════════════════════════════════════════════════
+    private void generateChunks() {
+      List<Integer> chunkPlan =
+          ChunkPlanner.plan(quizCount, aiProperties.getChunk().getChunkSize());
+      chunkTotal = chunkPlan.size();
       log.info(
-          "{} 청크 생성 완료: 전달={}문항(목표 {}), 배치 완료={}/{}, 총 소요={}ms",
+          "{} 문제 수에 맞게 청크 분할 완료: 요청={}문항, chunk-size={}, 청크={}개",
           tag,
-          delivered.get(),
           quizCount,
-          chunksDone,
-          chunkPlan.size(),
-          (System.nanoTime() - startNanos) / 1_000_000);
+          aiProperties.getChunk().getChunkSize(),
+          chunkTotal);
 
-      Long first = firstNanos.get() == 0 ? null : firstNanos.get();
-      Long last = lastNanos.get() == 0 ? null : lastNanos.get();
-      metricsRecorder.recordRequestDuration(chunksDone, startNanos, first, last, totalCost.sum());
-      metricsRecorder.recordQuizCounts(tag, quizCount, delivered.get(), chunksDone);
+      for (int chunkIndex = 0; chunkIndex < chunkTotal; chunkIndex++) {
+        if (submitted.get() >= quizCount) break;
+
+        List<AIProblem> generated = generateChunk(chunkIndex, chunkPlan.get(chunkIndex));
+
+        if (generated.isEmpty()) {
+          log.warn("{} 청크 #{} 산출물 없음 — 부분 저장·완료.", tag, chunkIndex);
+          break;
+        }
+        chunksDone++;
+      }
     }
 
-    /** 1단계 생성 */
-    private List<AIProblem> runGenerationPhase(int chunkIndex, int chunkSize) {
+    private List<AIProblem> generateChunk(int chunkIndex, int chunkSize) {
       String userPrompt =
           quizType.generateRequestPrompt(
               request.referencePages(), chunkSize, request.customInstruction());
@@ -233,27 +233,20 @@ private List<AIProblem> runGenerationPhase(int chunkIndex, int chunkSize) {
         userPrompt = userPrompt + dedupInstruction();
       }
 
-      // 캐시가 있으면 PDF는 캐시 프리픽스에 있으므로 첨부하지 않는다. 폴백(캐시 없음) 시 첫 사용자 턴에만 첨부한다.
       UserMessage.Builder ub = UserMessage.builder().text(userPrompt);
       if (genCache == null && chunkIndex == 0) {
         ub.media(pdfMedia);
       }
       UserMessage phase1User = ub.build();
 
-      // 캐시 사용 시 system·PDF는 캐시에 있으므로 요청엔 대화 턴만. 폴백 시 전체 지침(문제+해설)을 prepend.
       List<Message> messages = new ArrayList<>();
       if (genCache == null) {
         messages.add(new SystemMessage(genGuideLine));
       }
       messages.addAll(conversation);
       messages.add(phase1User);
-
-      // 전체 스키마(선지별 해설 포함) — 문제·해설을 한 응답에 생성한다. 저장 시 sink가 인라인 해설을 마크다운으로 조립한다.
       String schema = responseSchema(request.customInstruction());
       Prompt prompt = new Prompt(messages, buildOptions(schema, genCache));
-
-      // 이 청크에서 생성된(검증 이전) 문항 — 생성 순서. 대화 히스토리 구성과 청크 진행 판단에 쓴다.
-      // 스트림 콜백(단일 리액터 스레드)에서만 add 하고, streamInto 종료(blockLast) 이후 읽으므로 가시성이 보장된다.
       List<AIProblem> generated = new ArrayList<>();
       StreamingJsonArrayExtractor<T> extractor =
           new StreamingJsonArrayExtractor<>(
@@ -266,9 +259,6 @@ private List<AIProblem> runGenerationPhase(int chunkIndex, int chunkSize) {
                 AIProblem arranged = toProblem(question, metadata.sourcePages());
                 int order = submitted.incrementAndGet();
                 generated.add(arranged);
-
-                // 처음 fast-serve-count개는 생성 게이트 없이 즉시 저장한다(즉석 서빙 — 사후 Pass 2가 판정).
-                // 그 외엔 생성 게이트를 비동기로 제출하고 즉시 리턴한다 — 스트림 소비를 검증이 붙잡지 않는다.
                 if (order <= aiProperties.getFastServeCount()) {
                   verifyFutures.add(submitFastServe(arranged));
                 } else {
@@ -279,13 +269,27 @@ private List<AIProblem> runGenerationPhase(int chunkIndex, int chunkSize) {
 
       streamInto(prompt, extractor, chunkIndex);
 
-      // 어시스턴트 턴 = 이 청크에서 생성된 전체 문항(검증 결과와 무관). 검증을 기다리지 않고 다음 청크의 중복 회피 컨텍스트를 확정한다.
       conversation.add(phase1User);
       conversation.add(new AssistantMessage(serializeProblems(generated)));
       return generated;
     }
 
-    /** 즉석 서빙: 생성 게이트 검증 없이 저장·통지한다. 처음 문항들의 체감 지연(TTFQ)에서 검증 콜 지연을 제거한다. */
+    private void streamInto(
+        Prompt prompt, StreamingJsonArrayExtractor<T> extractor, int chunkIndex) {
+      Flux<ChatResponse> stream = chatModel.stream(prompt);
+      stream
+          .doOnNext(
+              response -> {
+                String text = extractText(response);
+                if (text != null) extractor.feed(text);
+                recordUsage(response, tag + " chunk #" + chunkIndex);
+              })
+          .blockLast();
+    }
+
+    // ══════════════════════════════════════════════════════════════════
+    //  3. 평가
+    // ══════════════════════════════════════════════════════════════════
     private CompletableFuture<Void> submitFastServe(AIProblem problem) {
       return CompletableFuture.runAsync(
           () -> {
@@ -298,11 +302,6 @@ private CompletableFuture<Void> submitFastServe(AIProblem problem) {
           verifyExecutor);
     }
 
-    /**
-     * 생성 게이트 검증을 비동기로 수행한다. 통과·검증불가면 저장·통지하고, 미달(v1)이면 보류 큐에 넣는다(청크 루프 종료 후 1회 재생성).
-     *
-     * <p>저장 순번은 이 워커가 saveProblem을 호출하는 순서 = 검증 통과 순서이므로, 먼저 통과한 문항이 낮은 번호를 받는다.
-     */
     private CompletableFuture<Void> submitVerification(AIProblem problem) {
       return CompletableFuture.runAsync(
           () -> {
@@ -334,7 +333,6 @@ private CompletableFuture<Void> submitVerification(AIProblem problem) {
           verifyExecutor);
     }
 
-    /** 통과 문항을 저장·통지하고 v1 로그를 기록한다. 여러 검증 워커가 동시에 호출하므로 sink는 스레드 안전해야 한다(consumerLock 직렬화). */
     private void store(AIProblem problem, String v1Feedback) {
       int number = sink.saveProblem(problem);
       sink.recordV1(number, problem, v1Feedback);
@@ -348,7 +346,6 @@ private void store(AIProblem problem, String v1Feedback) {
       }
     }
 
-    /** 제출된 모든 비동기 검증이 정착할 때까지 대기한다(멱등 — 여러 번 호출해도 안전). */
     private void awaitVerifications() {
       try {
         CompletableFuture.allOf(verifyFutures.toArray(CompletableFuture[]::new)).join();
@@ -357,60 +354,55 @@ private void awaitVerifications() {
       }
     }
 
-    private void streamInto(
-        Prompt prompt, StreamingJsonArrayExtractor<T> extractor, int chunkIndex) {
-      Flux<ChatResponse> stream = chatModel.stream(prompt);
-      stream
-          .doOnNext(
-              response -> {
-                String text = extractText(response);
-                if (text != null) extractor.feed(text);
-                recordUsage(response, tag + " chunk #" + chunkIndex);
-              })
-          // 대기 상한은 OkHttp 시한(connect/read/call, gemini-http 설정)이 전담한다 — 동기 풀 구조라
-          // blockLast의 Duration은 발화 불능이므로 두지 않는다.
-          .blockLast();
-    }
+    // ══════════════════════════════════════════════════════════════════
+    //  4. 재생성 (1문제씩)
+    // ══════════════════════════════════════════════════════════════════
+    private void regenerateHeld() {
+      if (heldQueue.isEmpty()) {
+        return;
+      }
+      int workers = Math.min(REGENERATE_CONCURRENCY, heldQueue.size());
+      log.info("{} 보류 문항 재생성 시작: {}건 (워커 {})", tag, heldQueue.size(), workers);
 
-    private void recordUsage(ChatResponse response, String label) {
-      if (response.getMetadata().getUsage().getCompletionTokens() > 0) {
-        double cost =
-            metricsRecorder.recordChunkUsage(label, startNanos, response.getMetadata().getUsage());
-        totalCost.add(cost);
+      // 목표 문항 수까지 남은 칸을 티켓으로 나눠 갖는다. 워커가 호출 전에 하나 집고 산출 실패 시 반납해
+      // 다음 항목이 쓰게 한다 — 동시에 돌아도 목표 문항 수를 초과 저장하지 않는다.
+      Semaphore budget = new Semaphore(Math.max(0, quizCount - delivered.get()));
+
+      List<CompletableFuture<Void>> tasks = new ArrayList<>();
+      for (int i = 0; i < workers; i++) {
+        tasks.add(CompletableFuture.runAsync(() -> drainHeldQueue(budget), verifyExecutor));
       }
+      CompletableFuture.allOf(tasks.toArray(CompletableFuture[]::new)).join();
     }
 
-    /**
-     * 보류된 미달 문항을 세션 내에서 1회씩 재생성한다(FR: 1회 캡). 개선본(v2)은 검증 없이 저장하고, 품질 로그엔 v1·v2를 함께 기록한다(사후 Pass 2가
-     * v2를 판정). 재생성 불가→제외. 이미 목표 문항 수를 채웠으면 중단한다.
-     */
-    private void processHeldQueue() {
-      if (heldQueue.isEmpty()) {
-        return;
-      }
-      log.info("{} 보류 문항 재생성 시작: {}건", tag, heldQueue.size());
-      for (HeldProblem held : heldQueue) {
-        if (delivered.get() >= quizCount) {
-          break;
+    private void drainHeldQueue(Semaphore budget) {
+      while (budget.tryAcquire()) {
+        HeldProblem held = heldQueue.poll();
+        if (held == null) {
+          budget.release();
+          return;
         }
+        boolean produced = false;
         try {
           AIProblem v2 = regenerateOne(held);
-          if (v2 == null) {
-            continue;
+          if (v2 != null) {
+            // v2는 검증 없이 저장한다
+            int number = sink.saveProblem(v2);
+            sink.recordV1(number, held.problem(), held.feedback());
+            sink.recordV2(number, v2);
+            delivered.incrementAndGet();
+            produced = true;
           }
-          // v2는 검증 없이 저장한다(사후 Pass 2가 판정). 품질 로그엔 미달 원본(v1)과 개선본(v2)을 함께 기록해 전후 비교를 남긴다.
-          int number = sink.saveProblem(v2);
-          sink.recordV1(number, held.problem(), held.feedback());
-          sink.recordV2(number, v2);
-          delivered.incrementAndGet();
         } catch (Exception e) {
           // 재생성 불가 → 제외(문항 수 축소).
           log.warn("{} 보류 문항 재생성 실패 — 제외", tag, e);
         }
+        if (!produced) {
+          budget.release();
+        }
       }
     }
 
-    /** 보류 문항 1건을 재생성한다. 살아있는 대화 스레드(원문 컨텍스트)에 개선 지시를 얹어 개선 문항 1개를 산출한다. */
     private AIProblem regenerateOne(HeldProblem held) {
       List<Message> messages = new ArrayList<>();
       if (genCache == null) {
@@ -437,9 +429,35 @@ private AIProblem regenerateOne(HeldProblem held) {
       }
       return toProblem(q, metadata.sourcePages());
     }
+
+    // ══════════════════════════════════════════════════════════════════
+    //  계측 (단계 아님 — 각 단계가 호출)
+    // ══════════════════════════════════════════════════════════════════
+    private void recordUsage(ChatResponse response, String label) {
+      if (response.getMetadata().getUsage().getCompletionTokens() > 0) {
+        double cost =
+            metricsRecorder.recordChunkUsage(label, startNanos, response.getMetadata().getUsage());
+        totalCost.add(cost);
+      }
+    }
+
+    private void recordOutcome() {
+      log.info(
+          "{} 청크 생성 완료: 전달={}문항(목표 {}), 배치 완료={}/{}, 총 소요={}ms",
+          tag,
+          delivered.get(),
+          quizCount,
+          chunksDone,
+          chunkTotal,
+          (System.nanoTime() - startNanos) / 1_000_000);
+
+      Long first = firstNanos.get() == 0 ? null : firstNanos.get();
+      Long last = lastNanos.get() == 0 ? null : lastNanos.get();
+      metricsRecorder.recordRequestDuration(chunksDone, startNanos, first, last, totalCost.sum());
+      metricsRecorder.recordQuizCounts(tag, quizCount, delivered.get(), chunksDone);
+    }
   }
 
-  /** PDF 업로드(캐시) 후 FileMetadata를 확보한다. */
   private FileMetadata resolvePdf(GenerationRequestToAI request) {
     String cacheKey =
         geminiFileService.generateCacheKey(request.fileUrl(), request.referencePages());
@@ -464,10 +482,6 @@ private static String extractText(ChatResponse response) {
     return response.getResult().getOutput().getText();
   }
 
-  /**
-   * JSON 응답 옵션을 만든다. cacheName이 있으면 해당 컨텍스트 캐시를 참조한다({@code useCachedContent}는 {@code
-   * cachedContentName}과 함께여야 ChatModel이 실제로 적용한다 — Spring AI 2.0.0의 {@code autoCache*}는 미소비 휴면 옵션).
-   */
   private GoogleGenAiChatOptions buildOptions(String responseSchema, CacheRef cacheRef) {
     GoogleGenAiChatOptions.Builder builder =
         GoogleGenAiChatOptions.builder()
@@ -480,7 +494,6 @@ private GoogleGenAiChatOptions buildOptions(String responseSchema, CacheRef cach
     return builder.build();
   }
 
-  /** 생성 게이트에서 미달 판정돼 보류된 문항(v1)과 개선 피드백. */
   private record HeldProblem(AIProblem problem, String feedback) {}
 
   private String buildRegenerationPrompt(HeldProblem held) {
@@ -493,7 +506,6 @@ private String buildRegenerationPrompt(HeldProblem held) {
     return RegenerationPrompt.forHeldProblem(problemJson, held.feedback());
   }
 
-  /** 생성된 문항을 어시스턴트 턴 JSON으로 직렬화한다({"questions":[...]}). */
   private String serializeProblems(List<AIProblem> problems) {
     try {
       return objectMapper.writeValueAsString(Map.of("questions", problems));
diff --git a/modules/quiz-set/impl/src/main/java/com/icc/qasker/quizset/scheduler/MockStaleGenerationRecoveryService.java b/modules/quiz-set/impl/src/main/java/com/icc/qasker/quizset/scheduler/MockStaleGenerationRecoveryService.java
index bd4682e4..903a8d39 100644
--- a/modules/quiz-set/impl/src/main/java/com/icc/qasker/quizset/scheduler/MockStaleGenerationRecoveryService.java
+++ b/modules/quiz-set/impl/src/main/java/com/icc/qasker/quizset/scheduler/MockStaleGenerationRecoveryService.java
@@ -24,7 +24,7 @@
 @RequiredArgsConstructor
 public class MockStaleGenerationRecoveryService implements StaleGenerationRecovery {
 
-  private static final long STALE_THRESHOLD_MINUTES = 10;
+  private static final long STALE_THRESHOLD_MINUTES = 15;
   private static final List<GenerationStatus> TARGET_STATUSES =
       List.of(GenerationStatus.FAILED, GenerationStatus.GENERATING);
 
diff --git a/modules/quiz-set/impl/src/main/java/com/icc/qasker/quizset/scheduler/StaleGenerationRecovery.java b/modules/quiz-set/impl/src/main/java/com/icc/qasker/quizset/scheduler/StaleGenerationRecovery.java
index 62c07a21..74ce091e 100644
--- a/modules/quiz-set/impl/src/main/java/com/icc/qasker/quizset/scheduler/StaleGenerationRecovery.java
+++ b/modules/quiz-set/impl/src/main/java/com/icc/qasker/quizset/scheduler/StaleGenerationRecovery.java
@@ -6,6 +6,6 @@
  */
 public interface StaleGenerationRecovery {
 
-  /** FAILED 또는 10분 이상 GENERATING 상태로 방치된 ProblemSet을 정리하고 대상 건수를 반환한다. */
+  /** FAILED 또는 15분 이상 GENERATING 상태로 방치된 ProblemSet을 정리하고 대상 건수를 반환한다. */
   int purgeStaleProblemSets();
 }
diff --git a/modules/quiz-set/impl/src/main/java/com/icc/qasker/quizset/scheduler/StaleGenerationRecoveryScheduler.java b/modules/quiz-set/impl/src/main/java/com/icc/qasker/quizset/scheduler/StaleGenerationRecoveryScheduler.java
index 0695dcc6..55b30d19 100644
--- a/modules/quiz-set/impl/src/main/java/com/icc/qasker/quizset/scheduler/StaleGenerationRecoveryScheduler.java
+++ b/modules/quiz-set/impl/src/main/java/com/icc/qasker/quizset/scheduler/StaleGenerationRecoveryScheduler.java
@@ -22,7 +22,7 @@ public class StaleGenerationRecoveryScheduler {
   public void deleteStaleProblemSets() {
     int purged = staleGenerationRecoveryService.purgeStaleProblemSets();
     if (purged > 0) {
-      log.warn("[방치 ProblemSet 정리] FAILED/GENERATING 10분 초과 삭제 count={}", purged);
+      log.warn("[방치 ProblemSet 정리] FAILED/GENERATING 15분 초과 삭제 count={}", purged);
     }
   }
 }
diff --git a/modules/quiz-set/impl/src/main/java/com/icc/qasker/quizset/scheduler/StaleGenerationRecoveryService.java b/modules/quiz-set/impl/src/main/java/com/icc/qasker/quizset/scheduler/StaleGenerationRecoveryService.java
index a3fda028..8f0a41cb 100644
--- a/modules/quiz-set/impl/src/main/java/com/icc/qasker/quizset/scheduler/StaleGenerationRecoveryService.java
+++ b/modules/quiz-set/impl/src/main/java/com/icc/qasker/quizset/scheduler/StaleGenerationRecoveryService.java
@@ -17,13 +17,18 @@
 @RequiredArgsConstructor
 public class StaleGenerationRecoveryService implements StaleGenerationRecovery {
 
-  private static final long STALE_THRESHOLD_MINUTES = 10;
+  /**
+   * 세션 시한(10분)보다 길게 잡는다. 같은 값이면 진행 중인 생성이 저장 직전에 삭제된다 — 스케줄러는 세트 createdAt 기준이고 세션 시계는 PDF 업로드 뒤에
+   * 출발해 항상 늦으며, 주기가 1분이라 판정도 최대 1분 늦게 온다.
+   */
+  private static final long STALE_THRESHOLD_MINUTES = 15;
+
   private static final List<GenerationStatus> TARGET_STATUSES =
       List.of(GenerationStatus.FAILED, GenerationStatus.GENERATING);
 
   private final ProblemSetRepository problemSetRepository;
 
-  /** FAILED 또는 10분 이상 GENERATING 상태로 방치된 ProblemSet을 삭제하고 삭제 건수를 반환한다. */
+  /** FAILED 또는 15분 이상 GENERATING 상태로 방치된 ProblemSet을 삭제하고 삭제 건수를 반환한다. */
   @Override
   @Transactional
   public int purgeStaleProblemSets() {
diff --git a/modules/quiz-set/impl/src/test/java/com/icc/qasker/quizset/scheduler/StaleGenerationRecoverySchedulerTest.java b/modules/quiz-set/impl/src/test/java/com/icc/qasker/quizset/scheduler/StaleGenerationRecoverySchedulerTest.java
index 89e6b962..db6cfeab 100644
--- a/modules/quiz-set/impl/src/test/java/com/icc/qasker/quizset/scheduler/StaleGenerationRecoverySchedulerTest.java
+++ b/modules/quiz-set/impl/src/test/java/com/icc/qasker/quizset/scheduler/StaleGenerationRecoverySchedulerTest.java
@@ -23,7 +23,7 @@ class StaleGenerationRecoverySchedulerTest extends JpaIntegrationTestBase {
   @Autowired private ProblemRepository problemRepository;
 
   @Test
-  @DisplayName("10분 초과 방치 세트 중 FAILED/GENERATING만 삭제되고 COMPLETED는 생존한다")
+  @DisplayName("15분 초과 방치 세트 중 FAILED/GENERATING만 삭제되고 COMPLETED는 생존한다")
   void scheduler_keeps_completed_sets() {
     persistSet("s-failed", GenerationStatus.FAILED);
     persistSet("s-generating", GenerationStatus.GENERATING);

From c89a55f113ff6f52d46412802549a9ca0c32024e Mon Sep 17 00:00:00 2001
From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com>
Date: Tue, 8 Sep 2026 07:27:56 +0000
Subject: [PATCH 2/2] chore: bump version to 3.6.1

---
 build.gradle | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/build.gradle b/build.gradle
index b069060f..760bbaa9 100644
--- a/build.gradle
+++ b/build.gradle
@@ -9,7 +9,7 @@ plugins {
 
 group = "com.icc.qasker"
 
-version = "3.6.0"
+version = "3.6.1"
 
 subprojects {
     tasks.configureEach { task ->