온보딩 테스트 조회 API를 구현한다. (#74)

earlgrey02 · web-flow · commit 037564ff37cb · 2025-08-06T12:47:39.000+09:00
diff --git a/api/src/main/kotlin/com/gotchai/api/global/config/SecurityConfig.kt b/api/src/main/kotlin/com/gotchai/api/global/config/SecurityConfig.kt
@@ -37,8 +37,11 @@ class SecurityConfig {
             }
             authorizeHttpRequests {
                 it
-                    .requestMatchers(HttpMethod.GET, "/ping")
-                    .permitAll()
+                    .requestMatchers(
+                        HttpMethod.GET,
+                        "/ping",
+                        "/api/v1/onboarding/**"
+                    ).permitAll()
                     .requestMatchers(
                         HttpMethod.POST,
                         "/api/v1/auth/login/**",
diff --git a/api/src/main/kotlin/com/gotchai/api/presentation/v1/onboarding/OnboardingController.kt b/api/src/main/kotlin/com/gotchai/api/presentation/v1/onboarding/OnboardingController.kt
@@ -0,0 +1,17 @@
+package com.gotchai.api.presentation.v1.onboarding
+
+import com.gotchai.api.global.annotation.ApiV1Controller
+import com.gotchai.api.presentation.v1.exam.response.ExamResponse
+import com.gotchai.domain.onboarding.port.`in`.OnboardingQueryUseCase
+import org.springframework.web.bind.annotation.GetMapping
+
+@ApiV1Controller
+class OnboardingController(
+    private val onboardingQueryUseCase: OnboardingQueryUseCase
+) {
+    @GetMapping("/onboarding/exams")
+    fun getOnboardingExam(): ExamResponse =
+        onboardingQueryUseCase
+            .getOnboardingExam()
+            .let { ExamResponse.from(it) }
+}
diff --git a/api/src/test/kotlin/com/gotchai/api/presentation/v1/exam/ExamControllerTest.kt b/api/src/test/kotlin/com/gotchai/api/presentation/v1/exam/ExamControllerTest.kt
@@ -13,11 +13,11 @@ import com.gotchai.api.presentation.v1.exam.response.GetExamParticipantCountResp
 import com.gotchai.api.util.document
 import com.gotchai.api.util.expectError
 import com.gotchai.api.util.paramDesc
+import com.gotchai.domain.exam.exception.ExamNotFoundException
 import com.gotchai.domain.exam.port.`in`.ExamQueryUseCase
 import com.gotchai.domain.fixture.ID
 import com.gotchai.domain.fixture.createExam
 import com.gotchai.domain.fixture.createGetExamResult
-import com.gotchai.domain.global.exception.NotFoundDataException
 import com.ninjasquad.springmockk.MockkBean
 import io.mockk.every
 import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest
@@ -97,7 +97,7 @@ class ExamControllerTest : ControllerTest() {
             }
 
             context("조회하려는 테스트가 존재하지 않는 경우") {
-                every { examQueryUseCase.getExamById(any()) } throws NotFoundDataException()
+                every { examQueryUseCase.getExamById(any()) } throws ExamNotFoundException()
 
                 it("상태 코드 404와 ErrorResponse를 반환한다.") {
                     webClient
diff --git a/api/src/test/kotlin/com/gotchai/api/presentation/v1/onboarding/OnboardingControllerTest.kt b/api/src/test/kotlin/com/gotchai/api/presentation/v1/onboarding/OnboardingControllerTest.kt
@@ -0,0 +1,61 @@
+package com.gotchai.api.presentation.v1.onboarding
+
+import com.gotchai.api.common.ControllerTest
+import com.gotchai.api.docs.errorResponseFields
+import com.gotchai.api.docs.examResponseFields
+import com.gotchai.api.global.dto.ApiResponse
+import com.gotchai.api.presentation.v1.exam.response.ExamResponse
+import com.gotchai.api.util.document
+import com.gotchai.api.util.expectError
+import com.gotchai.domain.exam.entity.ExamType
+import com.gotchai.domain.exam.exception.ExamNotFoundException
+import com.gotchai.domain.fixture.createExam
+import com.gotchai.domain.onboarding.port.`in`.OnboardingQueryUseCase
+import com.ninjasquad.springmockk.MockkBean
+import io.mockk.every
+import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest
+import org.springframework.test.web.reactive.server.expectBody
+
+@WebMvcTest(OnboardingController::class)
+class OnboardingControllerTest : ControllerTest() {
+    @MockkBean
+    private lateinit var onboardingQueryUseCase: OnboardingQueryUseCase
+
+    init {
+        describe("getOnboardingExam()은") {
+            context("온보딩 테스트가 존재하는 경우") {
+                every { onboardingQueryUseCase.getOnboardingExam() } returns createExam(type = ExamType.ONBOARDING)
+
+                it("상태 코드 200과 ExamResponse를 반환한다.") {
+                    webClient
+                        .get()
+                        .uri("/api/v1/onboarding/exams")
+                        .exchange()
+                        .expectStatus()
+                        .isOk
+                        .expectBody<ApiResponse<ExamResponse>>()
+                        .document("온보딩 테스트 조회 성공(200)") {
+                            responseBody(examResponseFields)
+                        }
+                }
+            }
+
+            context("온보딩 테스트가 존재하지 않는 경우") {
+                every { onboardingQueryUseCase.getOnboardingExam() } throws ExamNotFoundException()
+
+                it("상태 코드 404와 ErrorResponse를 반환한다.") {
+                    webClient
+                        .get()
+                        .uri("/api/v1/onboarding/exams")
+                        .exchange()
+                        .expectStatus()
+                        .isNotFound
+                        .expectError()
+                        .document("온보딩 테스트 조회 실패(404)") {
+                            responseBody(errorResponseFields)
+                        }
+                }
+            }
+        }
+    }
+}
diff --git a/api/src/testFixtures/kotlin/com/gotchai/api/common/ControllerTest.kt b/api/src/testFixtures/kotlin/com/gotchai/api/common/ControllerTest.kt
@@ -1,6 +1,5 @@
 package com.gotchai.api.common
 
-import com.gotchai.api.config.SecurityTestConfig
 import com.gotchai.domain.fixture.createUser
 import com.gotchai.domain.global.security.GotchaiAuthentication
 import io.kotest.core.extensions.Extension
@@ -12,13 +11,13 @@ import org.springframework.boot.test.autoconfigure.restdocs.AutoConfigureRestDoc
 import org.springframework.restdocs.RestDocumentationContextProvider
 import org.springframework.restdocs.webtestclient.WebTestClientRestDocumentation
 import org.springframework.security.core.context.SecurityContextHolder
+import org.springframework.security.test.web.servlet.request.SecurityMockMvcRequestPostProcessors.csrf
 import org.springframework.security.test.web.servlet.setup.SecurityMockMvcConfigurers.springSecurity
-import org.springframework.test.context.ContextConfiguration
 import org.springframework.test.web.servlet.client.MockMvcWebTestClient
+import org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post
 import org.springframework.web.context.WebApplicationContext
 
 @AutoConfigureRestDocs
-@ContextConfiguration(classes = [SecurityTestConfig::class])
 abstract class ControllerTest : DescribeSpec() {
     override fun extensions(): List<Extension> = listOf(SpringExtension)
 
@@ -36,6 +35,7 @@ abstract class ControllerTest : DescribeSpec() {
         MockMvcWebTestClient
             .bindToApplicationContext(webApplicationContext)
             .apply(springSecurity())
+            .defaultRequest(post("/**").with(csrf()))
             .configureClient()
             .filter(WebTestClientRestDocumentation.documentationConfiguration(restDocumentationContextProvider))
             .build()
diff --git a/api/src/testFixtures/kotlin/com/gotchai/api/config/SecurityTestConfig.kt b/api/src/testFixtures/kotlin/com/gotchai/api/config/SecurityTestConfig.kt
diff --git a/api/src/testFixtures/kotlin/com/gotchai/api/docs/BadgeDocs.kt b/api/src/testFixtures/kotlin/com/gotchai/api/docs/BadgeDocs.kt
@@ -19,7 +19,7 @@ val badgeResponseFields =
 
 val getMyBadgeListResponseFields =
     listFieldsOf(
-        description = "뱃지 리스트",
+        "list" bodyDesc "뱃지 리스트",
         GetMyBadgeResponse::id bodyDesc "식별자",
         GetMyBadgeResponse::examId bodyDesc "테스트 식별자",
         GetMyBadgeResponse::name bodyDesc "이름",
diff --git a/api/src/testFixtures/kotlin/com/gotchai/api/docs/ExamDocs.kt b/api/src/testFixtures/kotlin/com/gotchai/api/docs/ExamDocs.kt
@@ -7,9 +7,8 @@ import com.gotchai.api.util.bodyDesc
 import com.gotchai.api.util.fieldsOf
 import com.gotchai.api.util.listFieldsOf
 
-val examListResponseFields =
-    listFieldsOf(
-        description = "테스트 리스트",
+val examResponseFields =
+    fieldsOf(
         ExamResponse::id bodyDesc "식별자",
         ExamResponse::title bodyDesc "제목",
         ExamResponse::subTitle bodyDesc "부제목",
@@ -21,6 +20,12 @@ val examListResponseFields =
         ExamResponse::createdAt bodyDesc "생성 날짜"
     )
 
+val examListResponseFields =
+    listFieldsOf(
+        "list" bodyDesc "테스트 리스트",
+        *examResponseFields.toTypedArray()
+    )
+
 val examDetailResponseFields =
     fieldsOf(
         ExamDetailResponse::id bodyDesc "식별자",
diff --git a/api/src/testFixtures/kotlin/com/gotchai/api/docs/QuizDocs.kt b/api/src/testFixtures/kotlin/com/gotchai/api/docs/QuizDocs.kt
@@ -4,19 +4,18 @@ import com.gotchai.api.presentation.v1.quiz.request.GradeQuizRequest
 import com.gotchai.api.presentation.v1.quiz.response.GradeQuizResponse
 import com.gotchai.api.presentation.v1.quiz.response.QuizDetailResponse
 import com.gotchai.api.presentation.v1.quiz.response.QuizPickResponse
-import com.gotchai.api.util.arrayFieldsOf
 import com.gotchai.api.util.bodyDesc
 import com.gotchai.api.util.fieldsOf
+import com.gotchai.api.util.listFieldsOf
 
 val quizDetailResponseFields =
     fieldsOf(
         QuizDetailResponse::id bodyDesc "퀴즈 식별자",
         QuizDetailResponse::contents bodyDesc "퀴즈 내용",
         QuizDetailResponse::createdAt bodyDesc "생성 날짜"
     ) +
-        arrayFieldsOf(
-            "quizPicks",
-            "퀴즈 선택지 목록",
+        listFieldsOf(
+            "quizPicks" bodyDesc "퀴즈 선택지 목록",
             QuizPickResponse::id bodyDesc "선택지 식별자",
             QuizPickResponse::contents bodyDesc "선택지 내용"
         )
diff --git a/api/src/testFixtures/kotlin/com/gotchai/api/fixture/ExamFixture.kt b/api/src/testFixtures/kotlin/com/gotchai/api/fixture/ExamFixture.kt
@@ -4,5 +4,5 @@ import com.gotchai.api.presentation.v1.exam.response.GetExamParticipantCountResp
 
 const val PARTICIPANT_COUNT = 1
 
-fun createExamGetParticipantCount(participantCount: Int = PARTICIPANT_COUNT): GetExamParticipantCountResponse =
+fun createExamGetParticipantCountResponse(participantCount: Int = PARTICIPANT_COUNT): GetExamParticipantCountResponse =
     GetExamParticipantCountResponse(participantCount = participantCount)
diff --git a/api/src/testFixtures/kotlin/com/gotchai/api/util/RestDocsUtil.kt b/api/src/testFixtures/kotlin/com/gotchai/api/util/RestDocsUtil.kt
@@ -24,20 +24,12 @@ infix fun String.paramDesc(description: String): ParameterDescriptor =
     parameterWithName(this)
         .description(description)
 
-fun fieldsOf(vararg field: FieldDescriptor): List<FieldDescriptor> = field.asList()
+fun fieldsOf(vararg fields: FieldDescriptor): List<FieldDescriptor> = fields.asList()
 
 fun listFieldsOf(
-    description: String,
-    vararg field: FieldDescriptor
-): List<FieldDescriptor> =
-    field.map { "list[].${it.path}" bodyDesc it.description as String } + ("list" bodyDesc description)
-
-fun arrayFieldsOf(
-    arrayName: String,
-    description: String,
-    vararg field: FieldDescriptor
-): List<FieldDescriptor> =
-    field.map { "$arrayName[].${it.path}" bodyDesc it.description as String } + (arrayName bodyDesc description)
+    listField: FieldDescriptor,
+    vararg fields: FieldDescriptor
+): List<FieldDescriptor> = fields.map { "${listField.path}[].${it.path}" bodyDesc it.description as String } + listField
 
 fun <T> BodySpec<T, *>.document(
     identifier: String,
diff --git a/domain/src/main/kotlin/com/gotchai/domain/exam/adapter/in/ExamQueryService.kt b/domain/src/main/kotlin/com/gotchai/domain/exam/adapter/in/ExamQueryService.kt
@@ -2,6 +2,8 @@ package com.gotchai.domain.exam.adapter.`in`
 
 import com.gotchai.domain.exam.dto.result.GetExamResult
 import com.gotchai.domain.exam.entity.Exam
+import com.gotchai.domain.exam.entity.ExamType
+import com.gotchai.domain.exam.exception.ExamNotFoundException
 import com.gotchai.domain.exam.port.`in`.ExamQueryUseCase
 import com.gotchai.domain.exam.port.out.ExamQueryPort
 import com.gotchai.domain.exam.port.out.ExamResultQueryPort
@@ -14,9 +16,9 @@ class ExamQueryService(
     private val examResultQueryPort: ExamResultQueryPort,
     private val quizQueryPort: QuizQueryPort
 ) : ExamQueryUseCase {
-    override fun getExamById(examId: Long): GetExamResult {
-        val exam = examQueryPort.getExamById(examId)
-        val quizzes = quizQueryPort.getQuizzesByExamId(examId)
+    override fun getExamById(id: Long): GetExamResult {
+        val exam = examQueryPort.getExamById(id) ?: throw ExamNotFoundException()
+        val quizzes = quizQueryPort.getQuizzesByExamId(id)
 
         return GetExamResult.of(exam, quizzes.map { it.id })
     }
@@ -28,7 +30,7 @@ class ExamQueryService(
         return exams
     }
 
-    override fun getExamParticipantCountById(id: Long): Int = examResultQueryPort.countExamResultsByExamId(id)
+    override fun getExams(): List<Exam> = examQueryPort.getExamsByTypeNot(ExamType.ONBOARDING)
 
-    override fun getExams(): List<Exam> = examQueryPort.getExams()
+    override fun getExamParticipantCountById(id: Long): Int = examResultQueryPort.countExamResultsByExamId(id)
 }
diff --git a/domain/src/main/kotlin/com/gotchai/domain/exam/entity/Exam.kt b/domain/src/main/kotlin/com/gotchai/domain/exam/entity/Exam.kt
@@ -11,6 +11,7 @@ data class Exam(
     val backgroundImage: String,
     val iconImage: String,
     val theme: String,
+    val type: ExamType,
     val createdAt: LocalDateTime
 ) {
     data class Creation(
@@ -20,6 +21,7 @@ data class Exam(
         val prompt: String,
         val backgroundImage: String,
         val iconImage: String,
-        val theme: String
+        val theme: String,
+        val type: ExamType
     )
 }
diff --git a/domain/src/main/kotlin/com/gotchai/domain/exam/entity/ExamType.kt b/domain/src/main/kotlin/com/gotchai/domain/exam/entity/ExamType.kt
@@ -0,0 +1,6 @@
+package com.gotchai.domain.exam.entity
+
+enum class ExamType {
+    NORMAL,
+    ONBOARDING
+}
diff --git a/domain/src/main/kotlin/com/gotchai/domain/exam/exception/ExamNotFoundException.kt b/domain/src/main/kotlin/com/gotchai/domain/exam/exception/ExamNotFoundException.kt
@@ -0,0 +1,7 @@
+package com.gotchai.domain.exam.exception
+
+import com.gotchai.domain.global.exception.ServerException
+
+class ExamNotFoundException(
+    override val message: String = "존재하지 않는 테스트입니다."
+) : ServerException(status = 404, message)
diff --git a/domain/src/main/kotlin/com/gotchai/domain/exam/port/in/ExamQueryUseCase.kt b/domain/src/main/kotlin/com/gotchai/domain/exam/port/in/ExamQueryUseCase.kt
@@ -4,7 +4,7 @@ import com.gotchai.domain.exam.dto.result.GetExamResult
 import com.gotchai.domain.exam.entity.Exam
 
 interface ExamQueryUseCase {
-    fun getExamById(examId: Long): GetExamResult
+    fun getExamById(id: Long): GetExamResult
 
     fun getExamsByUserId(userId: Long): List<Exam>
 
diff --git a/domain/src/main/kotlin/com/gotchai/domain/exam/port/out/ExamQueryPort.kt b/domain/src/main/kotlin/com/gotchai/domain/exam/port/out/ExamQueryPort.kt
@@ -1,11 +1,14 @@
 package com.gotchai.domain.exam.port.out
 
 import com.gotchai.domain.exam.entity.Exam
+import com.gotchai.domain.exam.entity.ExamType
 
 interface ExamQueryPort {
-    fun getExamById(examId: Long): Exam
+    fun getExamById(id: Long): Exam?
 
-    fun getExams(): List<Exam>
+    fun getExamByType(type: ExamType): Exam?
+
+    fun getExamsByTypeNot(type: ExamType): List<Exam>
 
     fun getExamsByInIn(ids: Collection<Long>): List<Exam>
 }
diff --git a/domain/src/main/kotlin/com/gotchai/domain/onboarding/adapter/in/OnboardingQueryService.kt b/domain/src/main/kotlin/com/gotchai/domain/onboarding/adapter/in/OnboardingQueryService.kt
@@ -0,0 +1,16 @@
+package com.gotchai.domain.onboarding.adapter.`in`
+
+import com.gotchai.domain.exam.entity.Exam
+import com.gotchai.domain.exam.entity.ExamType
+import com.gotchai.domain.exam.exception.ExamNotFoundException
+import com.gotchai.domain.exam.port.out.ExamQueryPort
+import com.gotchai.domain.onboarding.port.`in`.OnboardingQueryUseCase
+import org.springframework.stereotype.Service
+
+@Service
+class OnboardingQueryService(
+    private val examQueryPort: ExamQueryPort
+) : OnboardingQueryUseCase {
+    override fun getOnboardingExam(): Exam =
+        examQueryPort.getExamByType(ExamType.ONBOARDING) ?: throw ExamNotFoundException()
+}
diff --git a/domain/src/main/kotlin/com/gotchai/domain/onboarding/port/in/OnboardingQueryUseCase.kt b/domain/src/main/kotlin/com/gotchai/domain/onboarding/port/in/OnboardingQueryUseCase.kt
@@ -0,0 +1,7 @@
+package com.gotchai.domain.onboarding.port.`in`
+
+import com.gotchai.domain.exam.entity.Exam
+
+interface OnboardingQueryUseCase {
+    fun getOnboardingExam(): Exam
+}
diff --git a/domain/src/main/kotlin/com/gotchai/domain/quiz/adapter/in/QuizCommandService.kt b/domain/src/main/kotlin/com/gotchai/domain/quiz/adapter/in/QuizCommandService.kt
@@ -23,7 +23,7 @@ class QuizCommandService(
         userId: Long
     ): QuizPickResult {
         val quizPick =
-            quizPickQueryPort.getQuizPickBy(quizPickId)
+            quizPickQueryPort.getQuizPickById(quizPickId)
                 ?: throw QuizPickNotFoundException()
 
         val examHistory = QuizHistory.from(userId, examId, quizPick)
diff --git a/domain/src/main/kotlin/com/gotchai/domain/quiz/port/out/QuizPickQueryPort.kt b/domain/src/main/kotlin/com/gotchai/domain/quiz/port/out/QuizPickQueryPort.kt
@@ -3,7 +3,7 @@ package com.gotchai.domain.quiz.port.out
 import com.gotchai.domain.quiz.entity.QuizPick
 
 interface QuizPickQueryPort {
-    fun getQuizPickBy(quizPickId: Long): QuizPick?
+    fun getQuizPickById(id: Long): QuizPick?
 
     fun getQuizPicksByQuizId(quizId: Long): List<QuizPick>
 }
diff --git a/domain/src/testFixtures/kotlin/com/gotchai/domain/fixture/ExamFixture.kt b/domain/src/testFixtures/kotlin/com/gotchai/domain/fixture/ExamFixture.kt
diff --git a/storage/rdb/src/main/kotlin/com/gotchai/storage/rdb/exam/adapter/out/ExamQueryAdapter.kt b/storage/rdb/src/main/kotlin/com/gotchai/storage/rdb/exam/adapter/out/ExamQueryAdapter.kt
diff --git a/storage/rdb/src/main/kotlin/com/gotchai/storage/rdb/exam/entity/ExamEntity.kt b/storage/rdb/src/main/kotlin/com/gotchai/storage/rdb/exam/entity/ExamEntity.kt
diff --git a/storage/rdb/src/main/kotlin/com/gotchai/storage/rdb/exam/repository/ExamJpaRepository.kt b/storage/rdb/src/main/kotlin/com/gotchai/storage/rdb/exam/repository/ExamJpaRepository.kt
diff --git a/storage/rdb/src/main/kotlin/com/gotchai/storage/rdb/quiz/adapter/out/QuizPickQueryAdapter.kt b/storage/rdb/src/main/kotlin/com/gotchai/storage/rdb/quiz/adapter/out/QuizPickQueryAdapter.kt
