feat: BookDetailResponse에 사용자 도서 상태 및 페이지 정보 추가 (#72)

* [BOOK-207] refactor: domain, apis - BookDetailRequest 및 AladinApiHelper 코드 정리 및 개선

* [BOOK-207] refactor: apis - AladinBookQueryService에서 Companion 객체 사용 제거 및 import 정리

* [BOOK-207] fix: apis, infra - AladinBookLookupRequest 패키지 변경 및 import 정리

* [BOOK-207] chore: apis - BookDetailResponse에서 불필요한 주석 제거 및 코드 정리

* [BOOK-207] chore: apis - Swagger UI 경로를 /swagger-ui로 변경

* [BOOK-207] feat: apis - Aladin API Manager 클래스 추가

* [BOOK-207] feat: apis - AladinBookQueryService 클래스 추가 및 BookQueryService 인터페이스를 sealed로 변경, 불필요한 상수 제거

* [BOOK-207] feat: apis, infra - AladinBookLookupRequest 및 AladinBookSearchRequest의 메서드 이름 변경 및 파라미터 정리

* [BOOK-207] refactor: apis - getBookDetail 메서드에 userId 파라미터 추가 및 관련 검증 로직 구현

* [BOOK-207] feat: apis - BookUseCase에 AladinBookQueryService 주입을 위한 Qualifier 추가

* [BOOK-207] refactor: apis - BookDetailRequest 및 BookSearchRequest의 필드 이름 변경 및 유효성 검증 메시지 수정

* [BOOK-207] refactor: apis - Aladin API 관련 예외 처리 추가 및 AladinApiManager 클래스 제거

* [BOOK-207] refactor: domain, infra - UserBookRepository 및 관련 클래스에서 findByIdAndUserId 메서드를 existsByIdAndUserId로 변경하여 존재 여부 확인 로직 개선

* [BOOK-207] refactor: global-utils - RegexUtils.kt에서 이메일 및 프로필 이미지 URL 패턴 제거하고 ISBN13 패턴 추가

* [BOOK-207] feat: infra - Aladin API 응답을 위한 AladinDetailResponse 및 AladinSearchResponse 데이터 클래스 추가

* [BOOK-207] chore: apis - AladinBookQueryService의 getBookDetail 메서드에서 변수 이름을 변경

* [BOOK-207] fix: infra - 중복된 필드 제거

* [BOOK-207] feat: global-utils - ISBN10을 ISBN13으로 변환하는 IsbnConverter 객체 추가

* [BOOK-207] refactor: infra - AladinRestClient에서 addCommonQueryParams 메서드 위치 변경 및 대소문자 수정

* [BOOK-207] refactor: apis - BookDetailResponse 및 BookSearchResponse 데이터 클래스의 필드 정리 및 ISBN 처리 로직 개선

* [BOOK-207] refactor: apis - BookCreateRequest에서 ISBN 처리 로직을 개선하여 ISBN13만 사용하도록 변경

* [BOOK-207] refactor: infra - AladinDetailResponse 및 AladinSearchResponse의 isbn13 필드를 nullable로 변경

* [BOOK-207] delete: infra - AladinResponseBase.kt 파일 삭제

* [BOOK-207] refactor: apis - BookUseCase에서 사용자 책 상태를 병합하는 로직 추가 및 코드 정리

* [BOOK-207] fix: infra - 중복된 필드 제거

* [BOOK-207] feat: apis - AuthorExtractor 객체 추가 및 BookDetailResponse에서 저자 처리 로직 개선

* [BOOK-207] feat: apis - NicknameGenerator 객체 추가하여 랜덤한 닉네임 생성 기능 구현

* [BOOK-207] refactor: apis, global-utils - IsbnConverter 클래스를 apis 패키지로 이동하고 관련된 코드 정리

* [BOOK-207] feat: apis - 책 관련 요청 데이터 클래스에 Swagger 스키마 및 유효성 검사 추가

* [BOOK-207] feat: apis - BookDetailResponse에 사용자 책 상태 추가 및 UserBookService에 상태 조회 기능 구현

* [BOOK-207] feat: domain - 사용자 책 정보를 조회하는 기능 추가 및 예외 처리 구현

* [BOOK-207] fix: apis, domain - 사용자 책 상태 조회 기능을 nullable로 변경하고 관련 로직 수정

* [BOOK-207] chore: domain - 불필요한 import문 제거

* [BOOK-207] feat: global-utils, infra - 책 표지 크기 열거형 추가 및 AladinBookLookupRequest, AladinBookSearchRequest에서 사용

* [BOOK-207] refactor: apis - BookCreateRequest 및 BookDetailResponse에서 cover 필드 이름을 coverImageUrl로 변경

* [BOOK-207] refactor: apis - UserBookRegisterRequest에서 bookStatus를 nullable로 변경하고 관련 메서드 수정

* [BOOK-207] refactor: apis - BookSearchResponse에서 저자 정보를 AuthorExtractor를 통해 추출하도록 수정

* [BOOK-207] refactor: domain, apis, infra - ReadingRecordService에서 UserBookService 의존성 제거 및 예외 처리 로직 개선

* [BOOK-207] chore: apis - CreateReadingRecordRequest에 Swagger 예제 추가 및 설명 수정

* [BOOK-207] fix: apis - ReadingRecordUseCase에서 userBookService의 매개변수 순서 수정

* [BOOK-207] refactor: infra - 생성자 호출 named parameter 형식으로 변경

* [BOOK-207] refactor: apis - converImageUrl validation 추가

* [BOOK-207] fix: apis - emotionTags 필드 스웨거 설명 수정

* [BOOK-207] refactor: apis - BookDetailResponse에서 기본 페이지 수 상수 추가 및 totalPage 기본값 수정

* [BOOK-207] refactor: apis - 서비스 클래스에 @validated 및 @Valid 어노테이션 추가하여 유효성 검사 적용

* [BOOK-207] fix: apis - 컨트롤러의 dto를 바로 받는 메서드의 경우 @Valid 어노테이션 제거

Author: move-hoon

apis/src/main/kotlin/org/yapp/apis/auth/service/TokenService.kt

@@ -1,6 +1,8 @@
 package org.yapp.apis.auth.service
 
+import jakarta.validation.Valid
 import org.springframework.stereotype.Service
+import org.springframework.validation.annotation.Validated
 import org.yapp.apis.auth.dto.request.TokenGenerateRequest
 import org.yapp.apis.auth.dto.request.TokenRefreshRequest
 import org.yapp.apis.auth.dto.response.RefreshTokenResponse
@@ -9,14 +11,15 @@ import org.yapp.domain.token.TokenDomainRedisService
 import java.util.*
 
 @Service
+@Validated
 class TokenService(
     private val tokenDomainRedisService: TokenDomainRedisService,
 ) {
     fun deleteRefreshTokenByToken(token: String) {
         tokenDomainRedisService.deleteRefreshTokenByToken(token)
     }
 
-    fun saveRefreshToken(tokenGenerateRequest: TokenGenerateRequest): RefreshTokenResponse {
+    fun saveRefreshToken(@Valid tokenGenerateRequest: TokenGenerateRequest): RefreshTokenResponse {
         val token = tokenDomainRedisService.saveRefreshToken(
             tokenGenerateRequest.validUserId(),
             tokenGenerateRequest.validRefreshToken(),

apis/src/main/kotlin/org/yapp/apis/auth/service/UserAuthService.kt

@@ -1,6 +1,8 @@
 package org.yapp.apis.auth.service
 
+import jakarta.validation.Valid
 import org.springframework.stereotype.Service
+import org.springframework.validation.annotation.Validated
 import org.yapp.apis.auth.dto.request.FindOrCreateUserRequest
 import org.yapp.apis.auth.dto.request.FindUserIdentityRequest
 import org.yapp.apis.auth.dto.response.CreateUserResponse
@@ -13,6 +15,7 @@ import org.yapp.domain.user.vo.UserIdentityVO
 import java.util.*
 
 @Service
+@Validated
 class UserAuthService(
     private val userDomainService: UserDomainService
 ) {
@@ -33,12 +36,12 @@ class UserAuthService(
         }
     }
 
-    fun findUserIdentityByUserId(findUserIdentityRequest: FindUserIdentityRequest): UserAuthInfoResponse {
+    fun findUserIdentityByUserId(@Valid findUserIdentityRequest: FindUserIdentityRequest): UserAuthInfoResponse {
         val userIdentity = userDomainService.findUserIdentityById(findUserIdentityRequest.validUserId())
         return UserAuthInfoResponse.from(userIdentity)
     }
 
-    fun findOrCreateUser(findOrCreateUserRequest: FindOrCreateUserRequest): CreateUserResponse {
+    fun findOrCreateUser(@Valid findOrCreateUserRequest: FindOrCreateUserRequest): CreateUserResponse {
         userDomainService.findUserByProviderTypeAndProviderId(
             findOrCreateUserRequest.validProviderType(),
             findOrCreateUserRequest.validProviderId()

apis/src/main/kotlin/org/yapp/apis/book/constant/BookQueryServiceQualifier.kt

@@ -45,7 +45,7 @@ class BookController(
         @AuthenticationPrincipal userId: UUID,
         @Valid @ModelAttribute request: BookDetailRequest
     ): ResponseEntity<BookDetailResponse> {
-        val response = bookUseCase.getBookDetail(request)
+        val response = bookUseCase.getBookDetail(request, userId)
         return ResponseEntity.ok(response)
     }
 

apis/src/main/kotlin/org/yapp/apis/book/controller/BookController.kt

@@ -1,38 +1,96 @@
 package org.yapp.apis.book.dto.request
 
+import io.swagger.v3.oas.annotations.media.Schema
+import jakarta.validation.constraints.Max
+import jakarta.validation.constraints.Min
 import jakarta.validation.constraints.NotBlank
 import jakarta.validation.constraints.Size
 import org.yapp.apis.book.dto.response.BookDetailResponse
 
+@Schema(
+    title = "책 생성 요청",
+    description = "시스템에 새로운 책 정보를 생성하는 요청 (주로 내부 API에서 사용)"
+)
 data class BookCreateRequest private constructor(
     @field:NotBlank(message = "ISBN은 필수입니다.")
+    @Schema(
+        description = "책의 13자리 ISBN 코드",
+        example = "9788932473901",
+        required = true,
+        minLength = 13,
+        maxLength = 13
+    )
     val isbn: String? = null,
 
     @field:NotBlank(message = "제목은 필수입니다.")
+    @field:Size(max = 500, message = "제목은 500자 이내여야 합니다.")
+    @Schema(
+        description = "책 제목",
+        example = "해리 포터와 마법사의 돌",
+        required = true,
+        maxLength = 500
+    )
     val title: String? = null,
 
     @field:NotBlank(message = "저자는 필수입니다.")
+    @field:Size(max = 200, message = "저자는 200자 이내여야 합니다.")
+    @Schema(
+        description = "저자명 (여러 저자인 경우 쉼표로 구분)",
+        example = "J.K. 롤링",
+        required = true,
+        maxLength = 200
+    )
     val author: String? = null,
 
     @field:NotBlank(message = "출판사는 필수입니다.")
+    @field:Size(max = 200, message = "출판사는 200자 이내여야 합니다.")
+    @Schema(
+        description = "출판사명",
+        example = "문학수첩",
+        required = true,
+        maxLength = 200
+    )
     val publisher: String? = null,
 
+    @field:Min(value = 1000, message = "출간연도는 1000년 이후여야 합니다.")
+    @field:Max(value = 2100, message = "출간연도는 2100년 이전이어야 합니다.")
+    @Schema(
+        description = "출간연도 (4자리 년도)",
+        example = "2000",
+        minimum = "1000",
+        maximum = "2100"
+    )
     val publicationYear: Int? = null,
 
     @field:Size(max = 2048, message = "표지 URL은 2048자 이내여야 합니다.")
-    val coverImageUrl: String,
+    @field:NotBlank(message = "표지 이미지 URL은 필수입니다.")
+    @Schema(
+        description = "책 표지 이미지 URL",
+        example = "https://image.aladin.co.kr/product/123/45/cover/1234567890123.jpg",
+        required = true,
+        maxLength = 2048,
+        format = "uri"
+    )
+    val coverImageUrl: String? = null,
 
+    @field:Size(max = 2000, message = "책 설명은 2000자 이내여야 합니다.")
+    @Schema(
+        description = "책 소개 및 줄거리",
+        example = "11살 해리 포터는 이모네 집에서 갖은 구박을 당하며 지낸다...",
+        maxLength = 2000
+    )
     val description: String? = null
 ) {
     fun validIsbn(): String = isbn!!
     fun validTitle(): String = title!!
     fun validAuthor(): String = author!!
     fun validPublisher(): String = publisher!!
+    fun validCoverImageUrl(): String = coverImageUrl!!
 
     companion object {
 
         fun from(bookDetail: BookDetailResponse): BookCreateRequest {
-            val finalIsbn = bookDetail.isbn ?: bookDetail.isbn13
+            val finalIsbn = bookDetail.isbn13
             ?: throw IllegalArgumentException("ISBN이 존재하지 않습니다.")
 
             return BookCreateRequest(
@@ -41,7 +99,7 @@ data class BookCreateRequest private constructor(
                 author = bookDetail.author,
                 publisher = bookDetail.publisher,
                 publicationYear = parsePublicationYear(bookDetail.pubDate),
-                coverImageUrl = bookDetail.cover,
+                coverImageUrl = bookDetail.coverImageUrl,
                 description = bookDetail.description,
             )
         }

apis/src/main/kotlin/org/yapp/apis/book/dto/request/BookCreateRequest.kt

@@ -1,38 +1,38 @@
 package org.yapp.apis.book.dto.request
 
+import io.swagger.v3.oas.annotations.media.Schema
 import jakarta.validation.constraints.NotBlank
-import jakarta.validation.constraints.Pattern // Pattern 어노테이션 추가
+import jakarta.validation.constraints.Pattern
 import org.yapp.globalutils.util.RegexUtils
-import org.yapp.infra.external.aladin.dto.AladinBookLookupRequest
 
+@Schema(
+    title = "책 상세 정보 요청",
+    description = "특정 ISBN을 통한 책 상세 정보 조회 요청"
+)
 data class BookDetailRequest private constructor(
-    @field:NotBlank(message = "아이템 ID는 필수입니다.")
+    @field:NotBlank(message = "ISBN은 비어 있을 수 없습니다.")
     @field:Pattern(
-        regexp = RegexUtils.NOT_BLANK_AND_NOT_NULL_STRING_PATTERN,
-        message = "아이템 ID는 유효한 ISBN 형식이 아닙니다."
+        regexp = RegexUtils.ISBN13_PATTERN,
+        message = "유효한 13자리 ISBN 형식이 아닙니다."
     )
-    val itemId: String? = null,
-    val itemIdType: String? = "ISBN",
-    val optResult: List<String>? = null
+    @Schema(
+        description = "조회할 책의 13자리 ISBN 코드",
+        example = "9788932473901",
+        required = true,
+        pattern = "\\d{13}",
+        minLength = 13,
+        maxLength = 13
+    )
+    val isbn: String? = null,
 ) {
-
-    fun validIsbn(): String = itemId!!
-
-
-    fun toAladinRequest(): AladinBookLookupRequest {
-        return AladinBookLookupRequest.create(
-            itemId = this.itemId!!,
-            itemIdType = this.itemIdType ?: "ISBN",
-            optResult = this.optResult
-        )
-    }
+    fun validIsbn(): String = isbn!!
 
     companion object {
-        fun of(isbn: String?, optResult: List<String>? = null): BookDetailRequest {
+        fun from(
+            isbn: String?,
+        ): BookDetailRequest {
             return BookDetailRequest(
-                itemId = isbn,
-                itemIdType = "ISBN",
-                optResult = optResult
+                isbn = isbn,
             )
         }
     }

apis/src/main/kotlin/org/yapp/apis/book/dto/request/BookDetailRequest.kt

@@ -1,31 +1,73 @@
 package org.yapp.apis.book.dto.request
 
-import org.yapp.infra.external.aladin.dto.AladinBookSearchRequest
-
+import io.swagger.v3.oas.annotations.media.Schema
+import jakarta.validation.constraints.Max
+import jakarta.validation.constraints.Min
+import jakarta.validation.constraints.NotBlank
 
+@Schema(
+    title = "책 검색 요청",
+    description = "알라딘 API를 통한 책 검색 요청 정보"
+)
 data class BookSearchRequest private constructor(
+    @field:NotBlank(message = "검색어는 필수입니다.")
+    @Schema(
+        description = "검색할 키워드 (제목, 저자, 출판사 등)",
+        example = "해리포터",
+        required = true
+    )
     val query: String? = null,
+
+    @Schema(
+        description = "검색 유형",
+        example = "Title",
+        allowableValues = ["Title", "Author", "Publisher", "Keyword"],
+        defaultValue = "Keyword"
+    )
     val queryType: String? = null,
+
+    @Schema(
+        description = "검색 대상",
+        example = "Book",
+        allowableValues = ["Book", "Foreign", "Music", "DVD"],
+        defaultValue = "Book"
+    )
     val searchTarget: String? = null,
+
+    @field:Min(value = 1, message = "최대 결과 수는 1 이상이어야 합니다.")
+    @field:Max(value = 100, message = "최대 결과 수는 100 이하여야 합니다.")
+    @Schema(
+        description = "한 번에 가져올 최대 결과 수 (1-100)",
+        example = "10",
+        minimum = "1",
+        maximum = "100",
+        defaultValue = "10"
+    )
     val maxResults: Int? = null,
+
+    @field:Min(value = 1, message = "시작 인덱스는 1 이상이어야 합니다.")
+    @Schema(
+        description = "검색 시작 인덱스 (페이징)",
+        example = "1",
+        minimum = "1",
+        defaultValue = "1"
+    )
     val start: Int? = null,
+
+    @Schema(
+        description = "정렬 방식",
+        example = "Accuracy",
+        allowableValues = ["Accuracy", "PublishTime", "Title", "SalesPoint"],
+        defaultValue = "Accuracy"
+    )
     val sort: String? = null,
-    val cover: String? = null,
+
+    @Schema(
+        description = "카테고리 ID (0: 전체)",
+        example = "0",
+        defaultValue = "0"
+    )
     val categoryId: Int? = null
 ) {
-
     fun validQuery(): String = query!!
-    fun toAladinRequest(): AladinBookSearchRequest {
-
-        return AladinBookSearchRequest.create(
-            query = this.validQuery(),
-            queryType = this.queryType,
-            searchTarget = this.searchTarget,
-            maxResults = this.maxResults,
-            start = this.start,
-            sort = this.sort,
-            cover = this.cover,
-            categoryId = this.categoryId
-        )
-    }
 }