refactor: 알라딘 외부 검색 API 호출 시 totalResult를 200개로 제한, lastPage 컬럼 값 추가 (#89)

* [BOOK-249] fix: apis,infra - 200개 요청 제한 및 lastPage 컬럼 값 추가(#88)

* [BOOK-249] refactor: apis,infra 코드리뷰 반영 (#88)

Author: minwoo1999

apis/src/main/kotlin/org/yapp/apis/book/dto/response/BookSearchResponse.kt

@@ -19,12 +19,6 @@ data class BookSearchResponse private constructor(
     @field:Schema(description = "검색 결과 제목", example = "데미안")
     val title: String?,
 
-    @field:Schema(
-        description = "검색 결과 링크",
-        example = "http://www.aladin.co.kr/shop/wsarch.aspx?SearchTarget=Book&query=%EC%95%84%EB%B0%94%EC%9D%98+%ED%95%B4%EB%B0%A9%EC%9D%BC%EC%A7%80&partner=openAPI"
-    )
-    val link: String?,
-
     @field:Schema(description = "출간일", example = "2025-07-30")
     val pubDate: String?,
 
@@ -46,6 +40,9 @@ data class BookSearchResponse private constructor(
     @field:Schema(description = "검색 카테고리 이름", example = "소설/시/희곡")
     val searchCategoryName: String?,
 
+    @field:Schema(description = "마지막 페이지 여부", example = "false")
+    val lastPage: Boolean,
+
     @field:Schema(description = "검색된 책 목록")
     val books: List<BookSummary>
 ) {
@@ -54,26 +51,27 @@ data class BookSearchResponse private constructor(
     }
 
     companion object {
-        fun from(response: AladinSearchResponse): BookSearchResponse {
+        fun of(response: AladinSearchResponse, isLastPage: Boolean): BookSearchResponse { // Added isLastPage parameter
             return BookSearchResponse(
                 version = response.version,
                 title = response.title,
-                link = response.link,
                 pubDate = response.pubDate,
                 totalResults = response.totalResults,
                 startIndex = response.startIndex,
                 itemsPerPage = response.itemsPerPage,
                 query = response.query,
                 searchCategoryId = response.searchCategoryId,
                 searchCategoryName = response.searchCategoryName,
+                lastPage = isLastPage,
                 books = response.item.map {
                     BookSummary.of(
                         isbn = it.isbn,
                         isbn13 = it.isbn13,
                         title = it.title,
                         author = AuthorExtractor.extractAuthors(it.author),
                         publisher = it.publisher,
-                        coverImageUrl = it.cover
+                        coverImageUrl = it.cover,
+                        link = it.link
                     )
                 }
             )
@@ -101,6 +99,12 @@ data class BookSearchResponse private constructor(
         )
         val coverImageUrl: String,
 
+        @field:Schema(
+            description = "알라딘 도서 상세 페이지 링크",
+            example = "http://www.aladin.co.kr/shop/wproduct.aspx?ItemId=3680175"
+        )
+        val link: String, // Added link field
+
         @field:Schema(description = "사용자의 책 상태", example = "BEFORE_REGISTRATION")
         val userBookStatus: BookStatus
     ) {
@@ -115,7 +119,8 @@ data class BookSearchResponse private constructor(
                 title: String?,
                 author: String?,
                 publisher: String?,
-                coverImageUrl: String
+                coverImageUrl: String,
+                link: String // Added link
             ): BookSummary {
                 require(!title.isNullOrBlank()) { "Title is required" }
 
@@ -126,6 +131,7 @@ data class BookSearchResponse private constructor(
                     author = author,
                     publisher = publisher?.let { BookDataValidator.removeParenthesesFromPublisher(it) },
                     coverImageUrl = coverImageUrl,
+                    link = link,
                     userBookStatus = BookStatus.BEFORE_REGISTRATION
                 )
             }

apis/src/main/kotlin/org/yapp/apis/book/exception/BookErrorCode.kt

@@ -9,9 +9,10 @@ enum class BookErrorCode(
     private val message: String
 ) : BaseErrorCode {
 
-    /* 500 INTERNAL_SERVER_ERROR */
-    ALADIN_API_SEARCH_FAILED(HttpStatus.INTERNAL_SERVER_ERROR, "BOOK_500_01", "알라딘 도서 검색 API 호출에 실패했습니다."),
-    ALADIN_API_LOOKUP_FAILED(HttpStatus.INTERNAL_SERVER_ERROR, "BOOK_500_02", "알라딘 도서 상세 조회 API 호출에 실패했습니다.");
+    /* 403 FORBIDDEN */
+    ALADIN_API_SEARCH_FAILED(HttpStatus.FORBIDDEN, "BOOK_403_01", "알라딘 도서 검색 API 호출에 실패했습니다."),
+    ALADIN_API_LOOKUP_FAILED(HttpStatus.FORBIDDEN, "BOOK_403_02", "알라딘 도서 상세 조회 API 호출에 실패했습니다."),
+    ALADIN_API_RESULT_LIMIT(HttpStatus.FORBIDDEN, "BOOK_403_03", "검색 결과가 200개를 초과하여 모든 결과를 조회했습니다.");
 
     override fun getHttpStatus(): HttpStatus = httpStatus
     override fun getCode(): String = code

apis/src/main/kotlin/org/yapp/apis/book/service/AladinBookQueryService.kt

@@ -22,6 +22,7 @@ class AladinBookQueryService(
     private val aladinApi: AladinApi
 ) : BookQueryService {
     private val log = KotlinLogging.logger {}
+    private val MAX_ALADIN_RESULTS = 200 // Added constant
 
     override fun searchBooks(request: BookSearchRequest): BookSearchResponse {
         log.info { "Service - Converting BookSearchRequest to AladinBookSearchRequest and calling Aladin API for book search." }
@@ -50,23 +51,33 @@ class AladinBookQueryService(
             validIsbn13?.let { item.copy(isbn13 = it) }
         }
 
+        val cappedTotalResults = minOf(response.totalResults ?: 0, MAX_ALADIN_RESULTS)
+        val currentFetchedCount = (request.start ?: 1) * (response.itemsPerPage ?: 0)
+
+        if (currentFetchedCount > MAX_ALADIN_RESULTS) {
+            throw BookException(
+                BookErrorCode.ALADIN_API_RESULT_LIMIT
+            )
+        }
+
+        val isLastPage = currentFetchedCount >= cappedTotalResults
+
         val filteredResponse = AladinSearchResponse(
             version = response.version,
             title = response.title,
             link = response.link,
             pubDate = response.pubDate,
-            totalResults = transformedItems.size,
+            totalResults = response.totalResults,
             startIndex = response.startIndex,
             itemsPerPage = response.itemsPerPage,
             query = response.query,
             searchCategoryId = response.searchCategoryId,
             searchCategoryName = response.searchCategoryName,
             item = transformedItems
         )
-
         log.info { "After filtering - Full Response: $filteredResponse" }
 
-        return BookSearchResponse.from(filteredResponse)
+        return BookSearchResponse.of(filteredResponse, isLastPage) // Passed isLastPage
     }
 
     override fun getBookDetail(request: BookDetailRequest): BookDetailResponse {

apis/src/main/kotlin/org/yapp/apis/readingrecord/controller/ReadingRecordController.kt

@@ -15,6 +15,7 @@ import org.springframework.web.bind.annotation.RequestMapping
 import org.springframework.web.bind.annotation.RequestParam
 import org.springframework.web.bind.annotation.RestController
 import org.yapp.apis.readingrecord.dto.request.CreateReadingRecordRequest
+import org.yapp.apis.readingrecord.dto.response.ReadingRecordPageResponse // Added import
 import org.yapp.apis.readingrecord.dto.response.ReadingRecordResponse
 import org.yapp.apis.readingrecord.usecase.ReadingRecordUseCase
 import org.yapp.domain.readingrecord.ReadingRecordSortType
@@ -61,7 +62,7 @@ class ReadingRecordController(
         @RequestParam(required = false) sort: ReadingRecordSortType?,
         @PageableDefault(size = 10, sort = ["createdAt"], direction = Sort.Direction.DESC)
         pageable: Pageable
-    ): ResponseEntity<Page<ReadingRecordResponse>> {
+    ): ResponseEntity<ReadingRecordPageResponse> {
         val response = readingRecordUseCase.getReadingRecordsByUserBookId(
             userId = userId,
             userBookId = userBookId,

apis/src/main/kotlin/org/yapp/apis/readingrecord/controller/ReadingRecordControllerApi.kt

@@ -16,6 +16,7 @@ import org.springframework.http.ResponseEntity
 import org.springframework.security.core.annotation.AuthenticationPrincipal
 import org.springframework.web.bind.annotation.*
 import org.yapp.apis.readingrecord.dto.request.CreateReadingRecordRequest
+import org.yapp.apis.readingrecord.dto.response.ReadingRecordPageResponse
 import org.yapp.apis.readingrecord.dto.response.ReadingRecordResponse
 import org.yapp.apis.readingrecord.dto.response.SeedStatsResponse
 import org.yapp.domain.readingrecord.ReadingRecordSortType
@@ -105,7 +106,7 @@ interface ReadingRecordControllerApi {
         @RequestParam(required = false) @Parameter(description = "정렬 방식 (PAGE_NUMBER_ASC, PAGE_NUMBER_DESC, CREATED_DATE_ASC, CREATED_DATE_DESC)") sort: ReadingRecordSortType?,
         @PageableDefault(size = 10, sort = ["createdAt"], direction = Sort.Direction.DESC)
         @Parameter(description = "페이지네이션 정보 (페이지 번호, 페이지 크기, 정렬 방식)") pageable: Pageable
-    ): ResponseEntity<Page<ReadingRecordResponse>>
+    ): ResponseEntity<ReadingRecordPageResponse>
 
     @Operation(
         summary = "씨앗 통계 조회",

apis/src/main/kotlin/org/yapp/apis/readingrecord/dto/response/ReadingRecordPageResponse.kt

@@ -0,0 +1,37 @@
+package org.yapp.apis.readingrecord.dto.response
+
+import io.swagger.v3.oas.annotations.media.Schema
+import org.springframework.data.domain.Page
+
+@Schema(
+    name = "ReadingRecordPageResponse",
+    description = "독서 기록 페이징 조회 응답"
+)
+data class ReadingRecordPageResponse private constructor(
+    @field:Schema(description = "마지막 페이지 여부", example = "false")
+    val lastPage: Boolean,
+
+    @field:Schema(description = "총 결과 개수", example = "42")
+    val totalResults: Int,
+
+    @field:Schema(description = "현재 페이지 번호 (0부터 시작)", example = "0")
+    val startIndex: Int,
+
+    @field:Schema(description = "한 페이지당 아이템 개수", example = "10")
+    val itemsPerPage: Int,
+
+    @field:Schema(description = "독서 기록 목록")
+    val readingRecords: List<ReadingRecordResponse>
+) {
+    companion object {
+        fun from(page: Page<ReadingRecordResponse>): ReadingRecordPageResponse {
+            return ReadingRecordPageResponse(
+                lastPage = page.isLast,
+                totalResults = page.totalElements.toInt(),
+                startIndex = page.number,
+                itemsPerPage = page.size,
+                readingRecords = page.content
+            )
+        }
+    }
+}

apis/src/main/kotlin/org/yapp/apis/readingrecord/usecase/ReadingRecordUseCase.kt

@@ -5,6 +5,7 @@ import org.springframework.data.domain.Pageable
 import org.springframework.transaction.annotation.Transactional
 import org.yapp.apis.book.service.UserBookService
 import org.yapp.apis.readingrecord.dto.request.CreateReadingRecordRequest
+import org.yapp.apis.readingrecord.dto.response.ReadingRecordPageResponse // Added import
 import org.yapp.apis.readingrecord.dto.response.ReadingRecordResponse
 import org.yapp.apis.readingrecord.dto.response.SeedStatsResponse
 import org.yapp.apis.readingrecord.service.ReadingRecordService
@@ -55,15 +56,16 @@ class ReadingRecordUseCase(
         userBookId: UUID,
         sort: ReadingRecordSortType?,
         pageable: Pageable
-    ): Page<ReadingRecordResponse> {
+    ): ReadingRecordPageResponse {
         userService.validateUserExists(userId)
         userBookService.validateUserBookExists(userBookId, userId)
 
-        return readingRecordService.getReadingRecordsByDynamicCondition(
+        val page = readingRecordService.getReadingRecordsByDynamicCondition( // Stored in a variable
             userBookId = userBookId,
             sort = sort,
             pageable = pageable
         )
+        return ReadingRecordPageResponse.from(page) // Converted to new DTO
     }
 
     fun getSeedStats(