v 3.1.0

CLAUDE.md

@@ -2,32 +2,33 @@
 
 ## 프로젝트 개요
 
-문서(PDF, PPT, DOCX)를 업로드하면 Google Gemini AI가 자동으로 퀴즈를 생성하는 Spring Boot 기반 백엔드 API 서버. SSE를 통한 실시간 생성 스트리밍, 퀴즈 세트 관리, 풀이 히스토리 기록을 지원한다.
+문서(PDF, PPT, DOCX)를 업로드하면 Google Gemini AI가 자동으로 퀴즈를 생성하는 Spring Boot 기반 백엔드 API 서버. SSE를 통한 실시간 생성
+스트리밍, 퀴즈 세트 관리, 풀이 히스토리 기록을 지원한다.
 
 ## 기술 스택
 
-| 분류 | 기술 | 버전 |
-|---|---|---|
-| 언어 | Java | 21 |
-| 프레임워크 | Spring Boot | 3.5.8 |
-| AI | Spring AI (Google Gemini via Vertex AI) | 1.1.2 |
-| ORM | Spring Data JPA + Hibernate | (Boot BOM) |
-| DB | MySQL | - |
-| 인증 | JWT (Auth0 java-jwt 4.5.0) + OAuth2 Client | - |
-| 클라우드 | OCI Java SDK (Object Storage) + Cloudflare CDN + Google Cloud Storage | 3.80.3 |
-| 문서변환 | JODConverter (LibreOffice) | 4.4.9 |
-| PDF 처리 | Apache PDFBox | 3.0.3 |
-| 모니터링 | Micrometer + Prometheus + Actuator | (Boot BOM) |
-| 장애격리 | Resilience4j (Circuit Breaker) | 2.3.0 |
-| Rate Limiting | Bucket4j + Caffeine | 8.16.1 |
-| API 문서 | SpringDoc OpenAPI (Swagger UI) | 2.8.8 |
-| 암호화 | Jasypt | 3.0.5 |
-| ID 난독화 | Hashids | 1.0.3 |
-| 빌드 | Gradle (Groovy DSL) | 8.14.3 |
-| 컨테이너 | Jib (Docker) | 3.4.0 |
-| 포맷터 | Spotless + Google Java Format | 7.0.4 / 1.25.2 |
-| DB 마이그레이션 | Flyway | (Boot BOM) |
-| 테스트 | JUnit 5 | (Boot BOM) |
+| 분류            | 기술                                                                    | 버전             |
+|---------------|-----------------------------------------------------------------------|----------------|
+| 언어            | Java                                                                  | 21             |
+| 프레임워크         | Spring Boot                                                           | 3.5.8          |
+| AI            | Spring AI (Google Gemini via Vertex AI)                               | 1.1.2          |
+| ORM           | Spring Data JPA + Hibernate                                           | (Boot BOM)     |
+| DB            | MySQL                                                                 | -              |
+| 인증            | JWT (Auth0 java-jwt 4.5.0) + OAuth2 Client                            | -              |
+| 클라우드          | OCI Java SDK (Object Storage) + Cloudflare CDN + Google Cloud Storage | 3.80.3         |
+| 문서변환          | JODConverter (LibreOffice)                                            | 4.4.9          |
+| PDF 처리        | Apache PDFBox                                                         | 3.0.3          |
+| 모니터링          | Micrometer + Prometheus + Actuator                                    | (Boot BOM)     |
+| 장애격리          | Resilience4j (Circuit Breaker)                                        | 2.3.0          |
+| Rate Limiting | Bucket4j + Caffeine                                                   | 8.16.1         |
+| API 문서        | SpringDoc OpenAPI (Swagger UI)                                        | 2.8.8          |
+| 암호화           | Jasypt                                                                | 3.0.5          |
+| ID 난독화        | Hashids                                                               | 1.0.3          |
+| 빌드            | Gradle (Groovy DSL)                                                   | 8.14.3         |
+| 컨테이너          | Jib (Docker)                                                          | 3.4.0          |
+| 포맷터           | Spotless + Google Java Format                                         | 7.0.4 / 1.25.2 |
+| DB 마이그레이션     | Flyway                                                                | (Boot BOM)     |
+| 테스트           | JUnit 5                                                               | (Boot BOM)     |
 
 ## 명령어 (Scripts)
 
@@ -67,15 +68,15 @@ q-asker/api/
 │       ├── application.yml       # 설정 진입점 (config/ import)
 │       ├── application-secrets.yml  # 암호화된 시크릿
 │       └── config/               # 분리된 설정 파일들
-│           ├── server.yml        # 서버, DB, JPA, 캐시
-│           ├── ai.yml            # Google Gemini AI 설정
-│           ├── security.yml      # JWT, OAuth2, CORS
-│           ├── aws.yml           # OCI Object Storage, CDN
-│           ├── jodconverter.yml  # LibreOffice 문서변환
-│           ├── monitoring.yml    # Actuator, Prometheus
-│           ├── q-asker.yml       # 앱 커스텀 설정
-│           ├── resilience4j.yml  # Circuit Breaker
-│           └── springdoc.yml     # Swagger/OpenAPI
+│           ├── database-config.yml   # 서버, DB, JPA, 캐시
+│           ├── ai-setting.yml        # Google Gemini AI 설정
+│           ├── spring-security.yml   # JWT, OAuth2, CORS
+│           ├── oci-bucket-config.yml # OCI Object Storage, CDN
+│           ├── jodconverter.yml      # LibreOffice 문서변환
+│           ├── actuator.yml          # Actuator, Prometheus
+│           ├── app-common.yml        # 앱 커스텀 설정
+│           ├── resilience.yml        # Circuit Breaker
+│           └── spring-doc.yml        # Swagger/OpenAPI
 ├── modules/
 │   ├── global/                   # 공통 (BaseEntity, ApiResponse, GlobalExceptionHandler)
 │   ├── auth/     (api + impl)    # 인증 (JWT, OAuth2, RateLimitFilter)
@@ -110,54 +111,32 @@ q-asker/api/
 - 프로파일: `local` (개발), `prod` (운영)
 - Actuator 포트: 9090 (서비스 포트와 분리)
 - Virtual Threads 활성화 (`spring.threads.virtual.enabled: true`)
-- OCI Object Storage: `~/.oci/config` 파일 기반 인증, `OCI_NAMESPACE`, `OCI_IMAGE_BUCKET_NAME`, `OCI_PDF_BUCKET_NAME` 환경변수
+- OCI Object Storage: `~/.oci/config` 파일 기반 인증, `OCI_NAMESPACE`, `OCI_IMAGE_BUCKET_NAME`,
+  `OCI_PDF_BUCKET_NAME` 환경변수
 - Google Cloud: Vertex AI + GCS (ADC 인증)
-  - `spring.ai.google.genai.project-id`: GCP 프로젝트 ID
-  - `spring.ai.google.genai.location`: GCP 엔드포인트 (현재: `global`)
-  - `GCS_BUCKET_NAME`: GCS 버킷 이름 (기본값: `q-asker-ai-files`)
-  - 로컬: `gcloud auth application-default login`, 프로덕션: 서비스 계정
+    - `spring.ai.google.genai.project-id`: GCP 프로젝트 ID
+    - `spring.ai.google.genai.location`: GCP 엔드포인트 (현재: `global`)
+    - `GCS_BUCKET_NAME`: GCS 버킷 이름 (기본값: `q-asker-ai-files`)
+    - 로컬: `gcloud auth application-default login`, 프로덕션: 서비스 계정
 - DDoS 방어: Cloudflare Free (`api.q-asker.com`만 프록시 활성화)
 - SSL/HTTPS: Cloudflare (Universal SSL) → Nginx (Origin CA TLS), Full (Strict) 모드
-  - Origin 인증서: Cloudflare Origin CA (15년 유효)
-  - 인증서 경로: `/etc/ssl/cloudflare/api.q-asker.com.pem`, `.key`
-  - OCI NSG: 80/443 인바운드 Cloudflare IP 대역만 허용
+    - Origin 인증서: Cloudflare Origin CA (15년 유효)
+    - 인증서 경로: `/etc/ssl/cloudflare/api.q-asker.com.pem`, `.key`
+    - OCI NSG: 80/443 인바운드 Cloudflare IP 대역만 허용
 
 ## 개발 도구 및 설정
 
 - **빌드**: Gradle 8.14.3 (Groovy DSL)
 - **JDK**: 21 (Gradle Toolchain 자동 관리)
 - **포맷터**: Spotless + Google Java Format 1.25.2
-  - `./gradlew spotlessApply` — 포맷 적용
-  - `./gradlew spotlessCheck` — 포맷 검증
+    - `./gradlew spotlessApply` — 포맷 적용
+    - `./gradlew spotlessCheck` — 포맷 검증
 - **Git Hooks** (`.githooks/`)
-  - `prepare-commit-msg` — 브랜치에서 JIRA 티켓(`[A-Z]+-[0-9]+`) 감지하여 커밋 메시지 접두사 자동 추가
-  - `pre-commit` — `spotlessCheck` 실행, 위반 시 커밋 차단
-  - `pre-push` — `spotlessCheck` 실행, 위반 시 푸시 차단
+    - `prepare-commit-msg` — 브랜치에서 JIRA 티켓(`[A-Z]+-[0-9]+`) 감지하여 커밋 메시지 접두사 자동 추가
+    - `pre-commit` — `spotlessCheck` 실행, 위반 시 커밋 차단
+    - `pre-push` — `spotlessCheck` 실행, 위반 시 푸시 차단
 - **CI/CD**: GitHub Actions
-  - `ci-check-code-convention.yml` — PR 포맷 검증
-  - `ci-auto-version-bump.yml` — 자동 버전 범프
-  - `ci-update-api-docs.yml` — OpenAPI 스펙 자동 갱신
-  - `cd-prod_deploy.yml` — 운영 배포
-
-## gstack
-
-- 모든 웹 브라우징은 gstack의 `/browse` 스킬을 사용한다. `mcp__claude-in-chrome__*` 도구는 사용하지 않는다.
-- 사용 가능한 스킬: `/office-hours`, `/plan-ceo-review`, `/plan-eng-review`, `/plan-design-review`, `/design-consultation`, `/design-shotgun`, `/design-html`, `/review`, `/ship`, `/land-and-deploy`, `/canary`, `/benchmark`, `/browse`, `/connect-chrome`, `/qa`, `/qa-only`, `/design-review`, `/setup-browser-cookies`, `/setup-deploy`, `/retro`, `/investigate`, `/document-release`, `/codex`, `/cso`, `/autoplan`, `/careful`, `/freeze`, `/guard`, `/unfreeze`, `/gstack-upgrade`, `/learn`
-
-## Skill routing
-
-When the user's request matches an available skill, ALWAYS invoke it using the Skill
-tool as your FIRST action. Do NOT answer directly, do NOT use other tools first.
-The skill has specialized workflows that produce better results than ad-hoc answers.
-
-Key routing rules:
-- Product ideas, "is this worth building", brainstorming → invoke office-hours
-- Bugs, errors, "why is this broken", 500 errors → invoke investigate
-- Ship, deploy, push, create PR → invoke ship
-- QA, test the site, find bugs → invoke qa
-- Code review, check my diff → invoke review
-- Update docs after shipping → invoke document-release
-- Weekly retro → invoke retro
-- Design system, brand → invoke design-consultation
-- Visual audit, design polish → invoke design-review
-- Architecture review → invoke plan-eng-review
+    - `ci-check-code-convention.yml` — PR 포맷 검증
+    - `ci-auto-version-bump.yml` — 자동 버전 범프
+    - `ci-update-api-docs.yml` — OpenAPI 스펙 자동 갱신
+    - `cd-prod_deploy.yml` — 운영 배포

app/src/main/resources/config/app-common.yml

@@ -11,7 +11,7 @@ q-asker:
   file-validation:
     max-file-name-length: 255
     allowed-extensions: application/pdf,application/vnd.openxmlformats-officedocument.presentationml.presentation,application/vnd.openxmlformats-officedocument.wordprocessingml.document,application/vnd.ms-powerpoint
-    max-file-size: 36_700_160
+    max-file-size: 52_428_800
 
 server:
   shutdown: graceful

build.gradle

@@ -22,7 +22,7 @@ plugins {
 group = "com.icc.qasker"
 // 프로젝트 버전 (Docker 이미지 태그, 배포 아티팩트 버전에 사용)
 // 예: jib으로 빌드하면 Docker 이미지에 "1.7.0" 태그가 붙음
-version = "3.0.6"
+version = "3.1.0"
 
 // Git hooks 경로를 .githooks/로 자동 설정
 // 예: ./gradlew build 실행 시 자동으로 git config core.hooksPath .githooks 적용

modules/quiz-make/impl/build.gradle

@@ -65,4 +65,14 @@ dependencies {
     // 예: 서버 기동 후 /swagger-ui/index.html 접속하면 API 목록·테스트 UI가 제공됨
     implementation "org.springdoc:springdoc-openapi-starter-webmvc-ui:2.8.8"
 
+    // ────────────────────────────────
+    // 테스트
+    // ────────────────────────────────
+    testImplementation "org.springframework.boot:spring-boot-starter-test"
+    testImplementation platform("org.junit:junit-bom:5.12.2")
+    testRuntimeOnly "org.junit.platform:junit-platform-launcher"
+}
+
+test {
+    useJUnitPlatform()
 }

modules/quiz-make/impl/src/main/java/com/icc/qasker/quizmake/service/generation/GenerationCommandServiceImpl.java

@@ -95,7 +95,7 @@ private void processGenerationAsync(
     GenerationRequestToAI requestToAI =
         GenerationRequestToAI.builder()
             .fileUrl(request.uploadedUrl())
-            .strategyValue(request.quizType().name())
+            .strategyValue(request.quizType().toAiStrategyName())
             .language(request.language().name())
             .quizCount(request.quizCount())
             .referencePages(request.pageNumbers())
@@ -113,7 +113,9 @@ private void processGenerationAsync(
 
                     // 2. 선택지 셔플
                     QuizType quizType = request.quizType();
-                    if (quizType == QuizType.MULTIPLE || quizType == QuizType.BLANK) {
+                    if (quizType == QuizType.MULTIPLE
+                        || quizType == QuizType.BLANK
+                        || quizType == QuizType.REAL_BLANK) {
                       for (var quiz : problemSet.getQuiz()) {
                         if (!CollectionUtils.isEmpty(quiz.getSelections())) {
                           List<SelectionsOfAI> shuffled = new ArrayList<>(quiz.getSelections());

modules/quiz-make/impl/src/test/java/com/icc/qasker/quizmake/service/generation/GenerationCommandServiceImplTest.java

@@ -0,0 +1,122 @@
+package com.icc.qasker.quizmake.service.generation;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.anyInt;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.timeout;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+import com.icc.qasker.ai.dto.GenerationRequestToAI;
+import com.icc.qasker.global.component.HashUtil;
+import com.icc.qasker.quizmake.SseNotificationService;
+import com.icc.qasker.quizmake.adapter.AIServerAdapter;
+import com.icc.qasker.quizmake.dto.ferequest.GenerationRequest;
+import com.icc.qasker.quizmake.dto.ferequest.enums.Language;
+import com.icc.qasker.quizset.QuizCommandService;
+import com.icc.qasker.quizset.QuizQueryService;
+import com.icc.qasker.quizset.dto.ferequest.enums.QuizType;
+import java.util.List;
+import java.util.UUID;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+import org.mockito.ArgumentCaptor;
+
+class GenerationCommandServiceImplTest {
+
+  private AIServerAdapter aiServerAdapter;
+  private SseNotificationService notificationService;
+  private QuizCommandService quizCommandService;
+  private QuizQueryService quizQueryService;
+  private HashUtil hashUtil;
+  private GenerationResultRecorder resultRecorder;
+  private GenerationCommandServiceImpl service;
+
+  @BeforeEach
+  void setUp() {
+    aiServerAdapter = mock(AIServerAdapter.class);
+    notificationService = mock(SseNotificationService.class);
+    quizCommandService = mock(QuizCommandService.class);
+    quizQueryService = mock(QuizQueryService.class);
+    hashUtil = mock(HashUtil.class);
+    resultRecorder = mock(GenerationResultRecorder.class);
+
+    when(quizCommandService.initProblemSet(any(), any(), any(), anyInt(), any(), any(), any()))
+        .thenReturn(1L);
+
+    service =
+        new GenerationCommandServiceImpl(
+            aiServerAdapter,
+            notificationService,
+            quizCommandService,
+            quizQueryService,
+            hashUtil,
+            resultRecorder);
+  }
+
+  @Test
+  @DisplayName("REAL_BLANK 요청은 DB에는 REAL_BLANK 그대로 저장한다")
+  void real_blank_request_persists_real_blank_to_db() {
+    GenerationRequest request = request(QuizType.REAL_BLANK);
+
+    service.triggerGeneration("user-1", request);
+
+    verify(quizCommandService, timeout(2000))
+        .initProblemSet(
+            eq("user-1"), any(), any(), anyInt(), eq(QuizType.REAL_BLANK), any(), any());
+  }
+
+  @Test
+  @DisplayName("REAL_BLANK 요청은 AI 서버에 strategyValue=BLANK로 전달한다")
+  void real_blank_request_calls_ai_with_blank_strategy() {
+    GenerationRequest request = request(QuizType.REAL_BLANK);
+
+    service.triggerGeneration("user-1", request);
+
+    ArgumentCaptor<GenerationRequestToAI> captor =
+        ArgumentCaptor.forClass(GenerationRequestToAI.class);
+    verify(aiServerAdapter, timeout(2000)).streamRequest(captor.capture());
+    assertThat(captor.getValue().strategyValue()).isEqualTo("BLANK");
+  }
+
+  @Test
+  @DisplayName("BLANK 요청은 AI 서버에 strategyValue=BLANK로 전달한다 (회귀 방지)")
+  void blank_request_calls_ai_with_blank_strategy() {
+    GenerationRequest request = request(QuizType.BLANK);
+
+    service.triggerGeneration("user-1", request);
+
+    ArgumentCaptor<GenerationRequestToAI> captor =
+        ArgumentCaptor.forClass(GenerationRequestToAI.class);
+    verify(aiServerAdapter, timeout(2000)).streamRequest(captor.capture());
+    assertThat(captor.getValue().strategyValue()).isEqualTo("BLANK");
+  }
+
+  @Test
+  @DisplayName("MULTIPLE 요청은 AI 서버에 strategyValue=MULTIPLE로 전달한다 (회귀 방지)")
+  void multiple_request_calls_ai_with_multiple_strategy() {
+    GenerationRequest request = request(QuizType.MULTIPLE);
+
+    service.triggerGeneration("user-1", request);
+
+    ArgumentCaptor<GenerationRequestToAI> captor =
+        ArgumentCaptor.forClass(GenerationRequestToAI.class);
+    verify(aiServerAdapter, timeout(2000)).streamRequest(captor.capture());
+    assertThat(captor.getValue().strategyValue()).isEqualTo("MULTIPLE");
+  }
+
+  private GenerationRequest request(QuizType quizType) {
+    return new GenerationRequest(
+        null,
+        UUID.randomUUID().toString(),
+        "https://example.com/file.pdf",
+        "title",
+        5,
+        quizType,
+        List.of(1, 2),
+        Language.KO);
+  }
+}

modules/quiz-set/api/build.gradle

@@ -20,4 +20,15 @@ dependencies {
     // Spring WebMVC: SseEmitter 등 웹 관련 타입 제공
     // 예: GenerationService 인터페이스에서 SseEmitter 반환 타입 사용
     implementation "org.springframework:spring-webmvc"
+
+    // ────────────────────────────────
+    // 테스트
+    // ────────────────────────────────
+    testImplementation "org.springframework.boot:spring-boot-starter-test"
+    testImplementation platform("org.junit:junit-bom:5.12.2")
+    testRuntimeOnly "org.junit.platform:junit-platform-launcher"
+}
+
+test {
+    useJUnitPlatform()
 }

modules/quiz-set/api/src/main/java/com/icc/qasker/quizset/dto/ferequest/enums/QuizType.java

@@ -3,6 +3,11 @@
 public enum QuizType {
   MULTIPLE,
   BLANK,
+  REAL_BLANK,
   OX,
-  ESSAY
+  ESSAY;
+
+  public String toAiStrategyName() {
+    return this == REAL_BLANK ? BLANK.name() : name();
+  }
 }

modules/quiz-set/api/src/test/java/com/icc/qasker/quizset/dto/ferequest/enums/QuizTypeTest.java

@@ -0,0 +1,39 @@
+package com.icc.qasker.quizset.dto.ferequest.enums;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+class QuizTypeTest {
+
+  @Test
+  @DisplayName("REAL_BLANK는 AI 전략 이름을 BLANK로 매핑한다")
+  void real_blank_maps_to_blank() {
+    assertThat(QuizType.REAL_BLANK.toAiStrategyName()).isEqualTo("BLANK");
+  }
+
+  @Test
+  @DisplayName("BLANK는 자기 자신의 이름을 그대로 반환한다")
+  void blank_keeps_own_name() {
+    assertThat(QuizType.BLANK.toAiStrategyName()).isEqualTo("BLANK");
+  }
+
+  @Test
+  @DisplayName("MULTIPLE은 자기 자신의 이름을 그대로 반환한다")
+  void multiple_keeps_own_name() {
+    assertThat(QuizType.MULTIPLE.toAiStrategyName()).isEqualTo("MULTIPLE");
+  }
+
+  @Test
+  @DisplayName("OX는 자기 자신의 이름을 그대로 반환한다")
+  void ox_keeps_own_name() {
+    assertThat(QuizType.OX.toAiStrategyName()).isEqualTo("OX");
+  }
+
+  @Test
+  @DisplayName("ESSAY는 자기 자신의 이름을 그대로 반환한다")
+  void essay_keeps_own_name() {
+    assertThat(QuizType.ESSAY.toAiStrategyName()).isEqualTo("ESSAY");
+  }
+}