feat: 독서기록 API 기능 구현

apis/src/main/kotlin/org/yapp/apis/auth/dto/request/DeleteTokenRequest.kt

@@ -8,7 +8,7 @@ import org.yapp.apis.auth.dto.response.RefreshTokenResponse
     name = "DeleteTokenRequest",
     description = "Request DTO for deleting a refresh token"
 )
-data class DeleteTokenRequest(
+data class DeleteTokenRequest private constructor(
     @field:NotBlank(message = "Refresh token must not be blank.")
     @Schema(description = "Refresh token to be deleted", example = "eyJhbGciOiJIUz...")
     val refreshToken: String? = null

apis/src/main/kotlin/org/yapp/apis/auth/dto/request/FindUserIdentityRequest.kt

@@ -9,7 +9,7 @@ import java.util.*
     name = "FindUserIdentityRequest",
     description = "Request DTO to retrieve user identity information using userId"
 )
-data class FindUserIdentityRequest(
+data class FindUserIdentityRequest private constructor(
     @Schema(
         description = "User ID (UUID format)",
         example = "a1b2c3d4-e5f6-7890-1234-56789abcdef0"

apis/src/main/kotlin/org/yapp/apis/auth/dto/request/TokenGenerateRequest.kt

@@ -9,7 +9,7 @@ import java.util.*
     name = "TokenGenerateRequest",
     description = "DTO containing information required to save the generated refresh token"
 )
-data class TokenGenerateRequest(
+data class TokenGenerateRequest private constructor(
     @field:NotNull(message = "userId must not be null")
     @Schema(description = "User ID", example = "f6b7d490-1b1a-4b9f-8e8e-27f8e3a5dafa")
     val userId: UUID? = null,

apis/src/main/kotlin/org/yapp/apis/auth/dto/request/UserBooksByIsbnsRequest.kt

@@ -9,7 +9,7 @@ import java.util.UUID
     name = "UserBooksByIsbnsRequest",
     description = "Request DTO for finding user books by user ID and a list of ISBNs"
 )
-data class UserBooksByIsbnsRequest(
+data class UserBooksByIsbnsRequest private constructor(
     @Schema(
         description = "사용자 ID",
         example = "1"

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

@@ -1,7 +1,6 @@
 package org.yapp.apis.book.controller
 
 import jakarta.validation.Valid
-import org.springframework.data.domain.Page
 import org.springframework.data.domain.Pageable
 import org.springframework.data.domain.Sort
 import org.springframework.data.web.PageableDefault
@@ -23,6 +22,7 @@ import org.yapp.apis.book.dto.response.UserBookPageResponse
 import org.yapp.apis.book.dto.response.UserBookResponse
 import org.yapp.apis.book.usecase.BookUseCase
 import org.yapp.domain.userbook.BookStatus
+import org.yapp.domain.userbook.UserBookSortType
 import java.util.UUID
 
 @RestController
@@ -62,7 +62,7 @@ class BookController(
     override fun getUserLibraryBooks(
         @AuthenticationPrincipal userId: UUID,
         @RequestParam(required = false) status: BookStatus?,
-        @RequestParam(required = false) sort: String?,
+        @RequestParam(required = false) sort: UserBookSortType?,
         @PageableDefault(size = 10, sort = ["createdAt"], direction = Sort.Direction.DESC)
         pageable: Pageable
     ): ResponseEntity<UserBookPageResponse> {

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

@@ -27,6 +27,7 @@ import org.yapp.apis.book.dto.response.BookSearchResponse
 import org.yapp.apis.book.dto.response.UserBookPageResponse
 import org.yapp.apis.book.dto.response.UserBookResponse
 import org.yapp.domain.userbook.BookStatus
+import org.yapp.domain.userbook.UserBookSortType
 import org.yapp.globalutils.exception.ErrorResponse
 import java.util.UUID
 
@@ -140,7 +141,7 @@ interface BookControllerApi {
     fun getUserLibraryBooks(
         @AuthenticationPrincipal userId: UUID,
         @RequestParam(required = false) status: BookStatus?,
-        @RequestParam(required = false) sort: String?,
+        @RequestParam(required = false) sort: UserBookSortType?,
         @PageableDefault(size = 10, sort = ["createdAt"], direction = Sort.Direction.DESC)
         pageable: Pageable
     ): ResponseEntity<UserBookPageResponse>

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

@@ -25,7 +25,7 @@ data class BookDetailResponse private constructor(
     val cover: String,
     val categoryId: Int?,
     val categoryName: String?,
-    val publisher: String
+    val publisher: String,
 ) {
     companion object {
 

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

@@ -0,0 +1,16 @@
+package org.yapp.apis.book.exception
+
+import org.springframework.http.HttpStatus
+import org.yapp.globalutils.exception.BaseErrorCode
+
+enum class UserBookErrorCode(
+    private val status: HttpStatus,
+    private val code: String,
+    private val message: String
+) : BaseErrorCode {
+    USER_BOOK_NOT_FOUND(HttpStatus.NOT_FOUND, "USER_BOOK_001", "사용자의 책을 찾을 수 없습니다.");
+
+    override fun getHttpStatus(): HttpStatus = status
+    override fun getCode(): String = code
+    override fun getMessage(): String = message
+}

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

@@ -0,0 +1,8 @@
+package org.yapp.apis.book.exception
+
+import org.yapp.globalutils.exception.CommonException
+
+class UserBookNotFoundException(
+    errorCode: UserBookErrorCode,
+    message: String? = null
+) : CommonException(errorCode, message)

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

@@ -7,10 +7,12 @@ import org.yapp.apis.auth.dto.request.UserBooksByIsbnsRequest
 import org.yapp.apis.book.dto.response.UserBookPageResponse
 import org.yapp.apis.book.dto.response.UserBookResponse
 import org.yapp.apis.book.dto.request.UpsertUserBookRequest
+import org.yapp.apis.book.exception.UserBookErrorCode
+import org.yapp.apis.book.exception.UserBookNotFoundException
 import org.yapp.domain.userbook.BookStatus
+import org.yapp.domain.userbook.UserBook
 import org.yapp.domain.userbook.UserBookDomainService
-import org.yapp.domain.userbook.vo.UserBookInfoVO
-import org.yapp.domain.userbook.vo.UserBookStatusCountsVO
+import org.yapp.domain.userbook.UserBookSortType
 import java.util.UUID
 
 
@@ -21,6 +23,7 @@ class UserBookService(
     fun upsertUserBook(upsertUserBookRequest: UpsertUserBookRequest): UserBookResponse {
         val userBookInfoVO = userBookDomainService.upsertUserBook(
             upsertUserBookRequest.validUserId(),
+            upsertUserBookRequest.validBookId(),
             upsertUserBookRequest.validBookIsbn(),
             upsertUserBookRequest.validBookTitle(),
             upsertUserBookRequest.validBookAuthor(),
@@ -31,13 +34,15 @@ class UserBookService(
         return UserBookResponse.from(userBookInfoVO)
     }
 
-    fun findAllUserBooks(userId: UUID): List<UserBookResponse> {
-        val userBooks: List<UserBookInfoVO> = userBookDomainService.findAllUserBooks(userId)
-        return userBooks.map { userBook: UserBookInfoVO ->
-            UserBookResponse.from(userBook)
-        }
+    fun validateUserBookExists(userId: UUID, userBookId: UUID): UserBook {
+        return userBookDomainService.findByIdAndUserId(userBookId, userId)
+            ?: throw UserBookNotFoundException(
+                UserBookErrorCode.USER_BOOK_NOT_FOUND,
+                "User book not found with id: $userBookId and userId: $userId"
+            )
     }
 
+
     fun findAllByUserIdAndBookIsbnIn(userBooksByIsbnsRequest: UserBooksByIsbnsRequest): List<UserBookResponse> {
         val userBooks = userBookDomainService.findAllByUserIdAndBookIsbnIn(
             userBooksByIsbnsRequest.validUserId(),
@@ -49,7 +54,7 @@ class UserBookService(
     private fun findUserBooksByDynamicCondition(
         userId: UUID,
         status: BookStatus?,
-        sort: String?,
+        sort: UserBookSortType?,
         pageable: Pageable
     ): Page<UserBookResponse> {
         val page = userBookDomainService.findUserBooksByDynamicCondition(userId, status, sort, pageable)
@@ -59,7 +64,7 @@ class UserBookService(
     fun findUserBooksByDynamicConditionWithStatusCounts(
         userId: UUID,
         status: BookStatus?,
-        sort: String?,
+        sort: UserBookSortType?,
         pageable: Pageable
     ): UserBookPageResponse {
         val userBookResponsePage = findUserBooksByDynamicCondition(userId, status, sort, pageable)

apis/src/main/kotlin/org/yapp/apis/book/usecase/BookUseCase.kt

@@ -20,6 +20,7 @@ import org.yapp.apis.book.service.BookManagementService
 import org.yapp.apis.book.service.BookQueryService
 import org.yapp.apis.book.service.UserBookService
 import org.yapp.domain.userbook.BookStatus
+import org.yapp.domain.userbook.UserBookSortType
 import org.yapp.globalutils.annotation.UseCase
 import java.util.UUID
 
@@ -63,7 +64,7 @@ class BookUseCase(
         val upsertUserBookRequest = UpsertUserBookRequest.of(
             userId = userId,
             bookCreateResponse,
-            status = request.bookStatus
+            status = request.bookStatus,
         )
         val userBookResponse = userBookService.upsertUserBook(upsertUserBookRequest)
 
@@ -73,7 +74,7 @@ class BookUseCase(
     fun getUserLibraryBooks(
         userId: UUID,
         status: BookStatus?,
-        sort: String?,
+        sort: UserBookSortType?,
         pageable: Pageable
     ): UserBookPageResponse {
         userAuthService.validateUserExists(userId)

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

@@ -0,0 +1,60 @@
+package org.yapp.apis.readingrecord.controller
+
+import org.springframework.data.domain.Page
+import org.springframework.data.domain.Pageable
+import org.springframework.data.domain.Sort
+import org.springframework.data.web.PageableDefault
+import org.springframework.http.HttpStatus
+import org.springframework.http.ResponseEntity
+import org.springframework.security.core.annotation.AuthenticationPrincipal
+import org.springframework.web.bind.annotation.GetMapping
+import org.springframework.web.bind.annotation.PathVariable
+import org.springframework.web.bind.annotation.PostMapping
+import org.springframework.web.bind.annotation.RequestBody
+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.ReadingRecordResponse
+import org.yapp.apis.readingrecord.usecase.ReadingRecordUseCase
+import org.yapp.domain.readingrecord.ReadingRecordSortType
+import java.util.UUID
+import jakarta.validation.Valid
+
+@RestController
+@RequestMapping("/api/v1/reading-records")
+class ReadingRecordController(
+    private val readingRecordUseCase: ReadingRecordUseCase
+) : ReadingRecordControllerApi {
+
+    @PostMapping("/{userBookId}")
+    override fun createReadingRecord(
+        @AuthenticationPrincipal userId: UUID,
+        @PathVariable userBookId: UUID,
+        @Valid @RequestBody request: CreateReadingRecordRequest
+    ): ResponseEntity<ReadingRecordResponse> {
+        val response = readingRecordUseCase.createReadingRecord(
+            userId = userId,
+            userBookId = userBookId,
+            request = request
+        )
+        return ResponseEntity.status(HttpStatus.CREATED).body(response)
+    }
+
+    @GetMapping("/{userBookId}")
+    override fun getReadingRecords(
+        @AuthenticationPrincipal userId: UUID,
+        @PathVariable userBookId: UUID,
+        @RequestParam(required = false) sort: ReadingRecordSortType?,
+        @PageableDefault(size = 10, sort = ["createdAt"], direction = Sort.Direction.DESC)
+        pageable: Pageable
+    ): ResponseEntity<Page<ReadingRecordResponse>> {
+        val response = readingRecordUseCase.getReadingRecordsByUserBookId(
+            userId = userId,
+            userBookId = userBookId,
+            sort = sort,
+            pageable = pageable
+        )
+        return ResponseEntity.ok(response)
+    }
+}

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

@@ -0,0 +1,89 @@
+package org.yapp.apis.readingrecord.controller
+
+import io.swagger.v3.oas.annotations.Operation
+import io.swagger.v3.oas.annotations.Parameter
+import io.swagger.v3.oas.annotations.media.Content
+import io.swagger.v3.oas.annotations.media.Schema
+import io.swagger.v3.oas.annotations.responses.ApiResponse
+import io.swagger.v3.oas.annotations.responses.ApiResponses
+import io.swagger.v3.oas.annotations.tags.Tag
+import jakarta.validation.Valid
+import org.springframework.data.domain.Page
+import org.springframework.data.domain.Pageable
+import org.springframework.data.domain.Sort
+import org.springframework.data.web.PageableDefault
+import org.springframework.http.ResponseEntity
+import org.springframework.security.core.annotation.AuthenticationPrincipal
+import org.springframework.web.bind.annotation.GetMapping
+import org.springframework.web.bind.annotation.PathVariable
+import org.springframework.web.bind.annotation.PostMapping
+import org.springframework.web.bind.annotation.RequestBody
+import org.springframework.web.bind.annotation.RequestMapping
+import org.springframework.web.bind.annotation.RequestParam
+import org.yapp.apis.readingrecord.dto.request.CreateReadingRecordRequest
+import org.yapp.apis.readingrecord.dto.response.ReadingRecordResponse
+import org.yapp.domain.readingrecord.ReadingRecordSortType
+import org.yapp.globalutils.exception.ErrorResponse
+import java.util.UUID
+
+@Tag(name = "Reading Records", description = "독서 기록 관련 API")
+@RequestMapping("/api/v1/reading-records")
+interface ReadingRecordControllerApi {
+
+    @Operation(
+        summary = "독서 기록 생성",
+        description = "사용자의 책에 대한 독서 기록을 생성합니다."
+    )
+    @ApiResponses(
+        value = [
+            ApiResponse(
+                responseCode = "201",
+                description = "독서 기록 생성 성공",
+                content = [Content(schema = Schema(implementation = ReadingRecordResponse::class))]
+            ),
+            ApiResponse(
+                responseCode = "400",
+                description = "잘못된 요청",
+                content = [Content(schema = Schema(implementation = ErrorResponse::class))]
+            ),
+            ApiResponse(
+                responseCode = "404",
+                description = "사용자 또는 책을 찾을 수 없음",
+                content = [Content(schema = Schema(implementation = ErrorResponse::class))]
+            )
+        ]
+    )
+    @PostMapping("/{userBookId}")
+    fun createReadingRecord(
+        @AuthenticationPrincipal @Parameter(description = "인증된 사용자 ID") userId: UUID,
+        @PathVariable @Parameter(description = "독서 기록을 생성할 사용자 책 ID") userBookId: UUID,
+        @Valid @RequestBody @Parameter(description = "독서 기록 생성 요청 객체") request: CreateReadingRecordRequest
+    ): ResponseEntity<ReadingRecordResponse>
+
+    @Operation(
+        summary = "독서 기록 목록 조회",
+        description = "사용자의 책에 대한 독서 기록을 페이징하여 조회합니다. 정렬은 페이지 번호 또는 최신 등록순으로 가능합니다."
+    )
+    @ApiResponses(
+        value = [
+            ApiResponse(
+                responseCode = "200",
+                description = "독서 기록 목록 조회 성공",
+                content = [Content(schema = Schema(implementation = ReadingRecordResponse::class))]
+            ),
+            ApiResponse(
+                responseCode = "404",
+                description = "사용자 또는 책을 찾을 수 없음",
+                content = [Content(schema = Schema(implementation = ErrorResponse::class))]
+            )
+        ]
+    )
+    @GetMapping("/{userBookId}")
+    fun getReadingRecords(
+        @AuthenticationPrincipal @Parameter(description = "인증된 사용자 ID") userId: UUID,
+        @PathVariable @Parameter(description = "독서 기록을 조회할 사용자 책 ID") userBookId: UUID,
+        @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>>
+}

apis/src/main/kotlin/org/yapp/apis/readingrecord/dto/request/CreateReadingRecordRequest.kt

@@ -0,0 +1,35 @@
+package org.yapp.apis.readingrecord.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
+
+
+@Schema(description = "독서 기록 생성 요청")
+data class CreateReadingRecordRequest private constructor(
+    @field:Min(1, message = "페이지 번호는 1 이상이어야 합니다.")
+    @field:Max(9999, message = "페이지 번호는 9999 이하여야 합니다.")
+    @Schema(description = "현재 읽은 페이지 번호", example = "42", required = true)
+    val pageNumber: Int? = null,
+
+    @field:NotBlank(message = "기억에 남는 문장은 필수입니다.")
+    @field:Size(max = 1000, message = "기억에 남는 문장은 1000자를 초과할 수 없습니다.")
+    @Schema(description = "기억에 남는 문장", example = "이것은 기억에 남는 문장입니다.", required = true)
+    val quote: String? = null,
+
+    @field:NotBlank(message = "감상평은 필수입니다.")
+    @field:Size(max = 1000, message = "감상평은 1000자를 초과할 수 없습니다.")
+    @Schema(description = "감상평", example = "이 책은 매우 인상적이었습니다.", required = true)
+    val review: String? = null,
+
+    @field:Size(max = 3, message = "감정 태그는 최대 3개까지 가능합니다.")
+    @Schema(description = "감정 태그 목록 (최대 3개)", example = "[\"감동적\", \"슬픔\", \"희망\"]")
+    val emotionTags: List<@Size(max = 10, message = "감정 태그는 10자를 초과할 수 없습니다.") String> = emptyList()
+) {
+    fun validPageNumber(): Int = pageNumber!!
+    fun validQuote(): String = quote!!
+    fun validReview(): String = review!!
+    fun validEmotionTags(): List<String> = emotionTags
+}