feat: 홈 화면 도서 선별 로직 구현

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

@@ -4,17 +4,18 @@ import org.springframework.data.domain.Page
 import org.springframework.data.domain.Pageable
 import org.springframework.stereotype.Service
 import org.yapp.apis.auth.dto.request.UserBooksByIsbnsRequest
+import org.yapp.apis.book.dto.request.UpsertUserBookRequest
 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.apis.home.dto.response.UserHomeResponse
 import org.yapp.domain.userbook.BookStatus
 import org.yapp.domain.userbook.UserBook
 import org.yapp.domain.userbook.UserBookDomainService
 import org.yapp.domain.userbook.UserBookSortType
-import java.util.UUID
-
+import org.yapp.domain.userbook.vo.UserBookWithLastRecordVO
+import java.util.*
 
 @Service
 class UserBookService(
@@ -42,7 +43,6 @@ class UserBookService(
             )
     }
 
-
     fun findAllByUserIdAndBookIsbnIn(userBooksByIsbnsRequest: UserBooksByIsbnsRequest): List<UserBookResponse> {
         val userBooks = userBookDomainService.findAllByUserIdAndBookIsbnIn(
             userBooksByIsbnsRequest.validUserId(),
@@ -51,6 +51,55 @@ class UserBookService(
         return userBooks.map { UserBookResponse.from(it) }
     }
 
+    fun findRecentReadingBooksForHome(userId: UUID, limit: Int): UserHomeResponse {
+        val fetchLimit = maxOf(limit * 2, 10)
+        val allUserBookVoInfos = userBookDomainService.findRecentReadingBooksWithLastRecord(userId, fetchLimit)
+        val selectedBooks = selectBooksByPriority(allUserBookVoInfos, limit)
+
+        return UserHomeResponse.from(selectedBooks)
+    }
+
+    private fun selectBooksByPriority(
+        allBooks: List<UserBookWithLastRecordVO>,
+        targetLimit: Int
+    ): List<UserBookWithLastRecordVO> {
+        if (allBooks.isEmpty()) return emptyList()
+
+        val result = mutableListOf<UserBookWithLastRecordVO>()
+        val usedBookIds = mutableSetOf<UUID>()
+
+        val readingBooks = allBooks
+            .filter { it.status == BookStatus.READING }
+            .sortedByDescending { it.lastRecordedAt }
+
+        val readingSelected = readingBooks.take(targetLimit)
+        result.addAll(readingSelected)
+        usedBookIds.addAll(readingSelected.map { it.id.value })
+
+        if (result.size < targetLimit) {
+            val remainingSlots = targetLimit - result.size
+            val completedBooks = allBooks
+                .filter { it.status == BookStatus.COMPLETED && !usedBookIds.contains(it.id.value) }
+                .sortedByDescending { it.lastRecordedAt }
+
+            val completedSelected = completedBooks.take(remainingSlots)
+            result.addAll(completedSelected)
+            usedBookIds.addAll(completedSelected.map { it.id.value })
+        }
+
+        if (result.size < targetLimit) {
+            val remainingSlots = targetLimit - result.size
+            val remainingBooks = allBooks
+                .filter { !usedBookIds.contains(it.id.value) }
+                .sortedByDescending { it.lastRecordedAt }
+
+            val remainingSelected = remainingBooks.take(remainingSlots)
+            result.addAll(remainingSelected)
+        }
+
+        return result
+    }
+
     private fun findUserBooksByDynamicCondition(
         userId: UUID,
         status: BookStatus?,

apis/src/main/kotlin/org/yapp/apis/home/controller/HomeController.kt

@@ -0,0 +1,25 @@
+package org.yapp.apis.home.controller
+
+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.RequestMapping
+import org.springframework.web.bind.annotation.RestController
+import org.yapp.apis.home.dto.response.UserHomeResponse
+import org.yapp.apis.home.usecase.HomeUseCase
+import java.util.*
+
+@RestController
+@RequestMapping("/api/home")
+class HomeController(
+    private val homeUseCase: HomeUseCase
+) : HomeControllerApi {
+
+    @GetMapping
+    override fun getUserHomeData(
+        @AuthenticationPrincipal userId: UUID
+    ): ResponseEntity<UserHomeResponse> {
+        val homeData = homeUseCase.getUserHomeData(userId)
+        return ResponseEntity.ok(homeData)
+    }
+}

apis/src/main/kotlin/org/yapp/apis/home/controller/HomeControllerApi.kt

@@ -0,0 +1,48 @@
+package org.yapp.apis.home.controller
+
+import io.swagger.v3.oas.annotations.Operation
+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 org.springframework.http.ResponseEntity
+import org.springframework.security.core.annotation.AuthenticationPrincipal
+import org.springframework.web.bind.annotation.GetMapping
+import org.springframework.web.bind.annotation.RequestMapping
+import org.yapp.apis.home.dto.response.UserHomeResponse
+import org.yapp.globalutils.exception.ErrorResponse
+import java.util.*
+
+@Tag(name = "Home", description = "홈 화면 관련 API")
+@RequestMapping("/api/home")
+interface HomeControllerApi {
+
+    @Operation(
+        summary = "홈 화면 데이터 조회",
+        description = "사용자의 홈 화면에 필요한 데이터를 조회합니다. 요즘 읽는 책 목록을 우선순위에 따라 최대 3권까지 반환합니다."
+    )
+    @ApiResponses(
+        value = [
+            ApiResponse(
+                responseCode = "200",
+                description = "홈 화면 데이터 조회 성공",
+                content = [Content(schema = Schema(implementation = UserHomeResponse::class))]
+            ),
+            ApiResponse(
+                responseCode = "400",
+                description = "잘못된 요청",
+                content = [Content(schema = Schema(implementation = ErrorResponse::class))]
+            ),
+            ApiResponse(
+                responseCode = "404",
+                description = "사용자를 찾을 수 없음",
+                content = [Content(schema = Schema(implementation = ErrorResponse::class))]
+            )
+        ]
+    )
+    @GetMapping
+    fun getUserHomeData(
+        @AuthenticationPrincipal userId: UUID
+    ): ResponseEntity<UserHomeResponse>
+} 

apis/src/main/kotlin/org/yapp/apis/home/dto/response/UserHomeResponse.kt

@@ -0,0 +1,39 @@
+package org.yapp.apis.home.dto.response
+
+import org.yapp.domain.userbook.vo.UserBookWithLastRecordVO
+import java.time.LocalDateTime
+import java.util.*
+
+data class UserHomeResponse private constructor(
+    val recentBooks: List<RecentBookResponse>
+) {
+    data class RecentBookResponse(
+        val userBookId: UUID,
+        val title: String,
+        val author: String,
+        val publisher: String,
+        val coverImageUrl: String,
+        val lastRecordedAt: LocalDateTime?
+    ) {
+        companion object {
+            fun from(userBookInfo: UserBookWithLastRecordVO): RecentBookResponse {
+                return RecentBookResponse(
+                    userBookId = userBookInfo.id.value,
+                    title = userBookInfo.title,
+                    author = userBookInfo.author,
+                    publisher = userBookInfo.publisher,
+                    coverImageUrl = userBookInfo.coverImageUrl,
+                    lastRecordedAt = userBookInfo.lastRecordedAt
+                )
+            }
+        }
+    }
+
+    companion object {
+        fun from(recentBooks: List<UserBookWithLastRecordVO>): UserHomeResponse {
+            return UserHomeResponse(
+                recentBooks = recentBooks.map { RecentBookResponse.from(it) }
+            )
+        }
+    }
+}

apis/src/main/kotlin/org/yapp/apis/home/usecase/HomeUseCase.kt

@@ -0,0 +1,17 @@
+package org.yapp.apis.home.usecase
+
+import org.springframework.transaction.annotation.Transactional
+import org.yapp.apis.book.service.UserBookService
+import org.yapp.apis.home.dto.response.*
+import org.yapp.globalutils.annotation.UseCase
+import java.util.*
+
+@UseCase
+@Transactional(readOnly = true)
+class HomeUseCase(
+    private val userBookService: UserBookService
+) {
+    fun getUserHomeData(userId: UUID): UserHomeResponse {
+        return userBookService.findRecentReadingBooksForHome(userId, 3)
+    }
+}

apis/src/main/kotlin/org/yapp/apis/readingrecord/service/ReadingRecordService.kt

@@ -6,17 +6,15 @@ import org.springframework.stereotype.Service
 import org.yapp.apis.book.service.UserBookService
 import org.yapp.apis.readingrecord.dto.request.CreateReadingRecordRequest
 import org.yapp.apis.readingrecord.dto.response.ReadingRecordResponse
-import org.yapp.domain.book.BookDomainService
 import org.yapp.domain.readingrecord.ReadingRecordDomainService
 import org.yapp.domain.readingrecord.ReadingRecordSortType
-import java.util.UUID
+import java.util.*
 
 
 @Service
 class ReadingRecordService(
     private val readingRecordDomainService: ReadingRecordDomainService,
     private val userBookService: UserBookService,
-    private val bookDomainService: BookDomainService
 ) {
 
     fun createReadingRecord(
@@ -26,7 +24,6 @@ class ReadingRecordService(
     ): ReadingRecordResponse {
         userBookService.validateUserBookExists(userId, userBookId)
 
-
         val readingRecordInfoVO = readingRecordDomainService.createReadingRecord(
             userBookId = userBookId,
             pageNumber = request.validPageNumber(),

domain/src/main/kotlin/org/yapp/domain/readingrecord/ReadingRecord.kt

@@ -15,8 +15,6 @@ data class ReadingRecord private constructor(
     val updatedAt: LocalDateTime? = null,
     val deletedAt: LocalDateTime? = null,
 ) {
-
-
     companion object {
         fun create(
             userBookId: UUID,

domain/src/main/kotlin/org/yapp/domain/userbook/UserBookDomainService.kt

@@ -6,6 +6,7 @@ import org.yapp.domain.userbook.vo.UserBookInfoVO
 import org.yapp.domain.userbook.vo.UserBookStatusCountsVO
 import org.yapp.globalutils.annotation.DomainService
 import java.util.UUID
+import org.yapp.domain.userbook.vo.UserBookWithLastRecordVO
 
 @DomainService
 class UserBookDomainService(
@@ -69,4 +70,15 @@ class UserBookDomainService(
     fun findByIdAndUserId(userBookId: UUID, userId: UUID): UserBook? {
         return userBookRepository.findByIdAndUserId(userBookId, userId)
     }
+
+    fun findRecentReadingBooksWithLastRecord(userId: UUID, limit: Int): List<UserBookWithLastRecordVO> {
+        val userBooksWithLastRecord = userBookRepository.findUserBooksWithLastRecord(userId, limit)
+
+        return userBooksWithLastRecord.map { (userBook, lastRecordedAt) ->
+            UserBookWithLastRecordVO.newInstance(
+                userBook = userBook,
+                lastRecordedAt = lastRecordedAt
+            )
+        }
+    }
 }

domain/src/main/kotlin/org/yapp/domain/userbook/UserBookRepository.kt

@@ -2,6 +2,7 @@ package org.yapp.domain.userbook
 
 import org.springframework.data.domain.Page
 import org.springframework.data.domain.Pageable
+import java.time.LocalDateTime
 import java.util.UUID
 
 
@@ -26,4 +27,5 @@ interface UserBookRepository {
 
     fun countUserBooksByStatus(userId: UUID, status: BookStatus): Long
 
+    fun findUserBooksWithLastRecord(userId: UUID, limit: Int): List<Pair<UserBook, LocalDateTime>>
 }

domain/src/main/kotlin/org/yapp/domain/userbook/vo/UserBookWithLastRecordVO.kt

@@ -0,0 +1,52 @@
+package org.yapp.domain.userbook.vo
+
+import org.yapp.domain.userbook.BookStatus
+import org.yapp.domain.userbook.UserBook
+import java.time.LocalDateTime
+
+data class UserBookWithLastRecordVO private constructor(
+    val id: UserBook.Id,
+    val userId: UserBook.UserId,
+    val bookId: UserBook.BookId,
+    val bookIsbn: UserBook.BookIsbn,
+    val coverImageUrl: String,
+    val publisher: String,
+    val title: String,
+    val author: String,
+    val status: BookStatus,
+    val createdAt: LocalDateTime,
+    val updatedAt: LocalDateTime,
+    val lastRecordedAt: LocalDateTime
+) {
+    init {
+        require(coverImageUrl.isNotBlank()) { "표지 이미지 URL은 비어 있을 수 없습니다." }
+        require(publisher.isNotBlank()) { "출판사는 비어 있을 수 없습니다." }
+        require(title.isNotBlank()) { "도서 제목은 비어 있을 수 없습니다." }
+        require(author.isNotBlank()) { "저자는 비어 있을 수 없습니다." }
+        require(!createdAt.isAfter(updatedAt)) {
+            "생성일(createdAt)은 수정일(updatedAt)보다 이후일 수 없습니다."
+        }
+    }
+
+    companion object {
+        fun newInstance(
+            userBook: UserBook,
+            lastRecordedAt: LocalDateTime
+        ): UserBookWithLastRecordVO {
+            return UserBookWithLastRecordVO(
+                id = userBook.id,
+                userId = userBook.userId,
+                bookId = userBook.bookId,
+                bookIsbn = userBook.bookIsbn,
+                coverImageUrl = userBook.coverImageUrl,
+                publisher = userBook.publisher,
+                title = userBook.title,
+                author = userBook.author,
+                status = userBook.status,
+                createdAt = userBook.createdAt ?: throw IllegalStateException("createdAt은 null일 수 없습니다."),
+                updatedAt = userBook.updatedAt ?: throw IllegalStateException("updatedAt은 null일 수 없습니다."),
+                lastRecordedAt = lastRecordedAt
+            )
+        }
+    }
+} 

infra/src/main/kotlin/org/yapp/infra/userbook/repository/JpaUserBookQuerydslRepository.kt

@@ -1,5 +1,6 @@
 package org.yapp.infra.userbook.repository
 
+import com.querydsl.core.Tuple
 import org.springframework.data.domain.Page
 import org.springframework.data.domain.Pageable
 import org.yapp.domain.userbook.BookStatus
@@ -19,4 +20,9 @@ interface JpaUserBookQuerydslRepository {
         userId: UUID,
         status: BookStatus
     ): Long
+
+    fun findUserBooksWithLastRecord(
+        userId: UUID,
+        limit: Int
+    ): List<Tuple>
 }