Merge pull request 'test' (#343 ) from test into main

Reviewed-on: #343
feat(admin-character-list): 캐릭터 검색결과
2025-09-18 19:25:50 +00:00 · 2025-09-18 19:58:12 +09:00 · 2025-09-18 19:29:34 +09:00 · 2025-09-18 18:04:59 +09:00 · 2025-09-16 06:11:32 +00:00 · 2025-09-15 16:00:09 +09:00
23 changed files with 1091 additions and 25 deletions
--- a/src/main/kotlin/kr/co/vividnext/sodalive/admin/chat/character/AdminChatCharacterController.kt
+++ b/src/main/kotlin/kr/co/vividnext/sodalive/admin/chat/character/AdminChatCharacterController.kt
@@ -3,9 +3,11 @@ package kr.co.vividnext.sodalive.admin.chat.character
 import com.amazonaws.services.s3.model.ObjectMetadata
 import com.fasterxml.jackson.databind.ObjectMapper
 import kr.co.vividnext.sodalive.admin.chat.character.dto.ChatCharacterRegisterRequest
+import kr.co.vividnext.sodalive.admin.chat.character.dto.ChatCharacterSearchListPageResponse
 import kr.co.vividnext.sodalive.admin.chat.character.dto.ChatCharacterUpdateRequest
 import kr.co.vividnext.sodalive.admin.chat.character.dto.ExternalApiResponse
 import kr.co.vividnext.sodalive.admin.chat.character.service.AdminChatCharacterService
+import kr.co.vividnext.sodalive.admin.chat.original.service.AdminOriginalWorkService
 import kr.co.vividnext.sodalive.aws.s3.S3Uploader
 import kr.co.vividnext.sodalive.chat.character.CharacterType
 import kr.co.vividnext.sodalive.chat.character.service.ChatCharacterService
@@ -37,6 +39,7 @@ class AdminChatCharacterController(
    private val service: ChatCharacterService,
    private val adminService: AdminChatCharacterService,
    private val s3Uploader: S3Uploader,
+    private val originalWorkService: AdminOriginalWorkService,

    @Value("\${weraser.api-key}")
    private val apiKey: String,
@@ -68,6 +71,26 @@ class AdminChatCharacterController(
        ApiResponse.ok(response)
    }

+    /**
+     * 캐릭터 검색(관리자)
+     * - 이름/설명/MBTI/태그 기준 부분 검색, 활성 캐릭터만 대상
+     * - 페이징 지원: page, size 파라미터 사용
+     */
+    @GetMapping("/search")
+    fun searchCharacters(
+        @RequestParam("searchTerm") searchTerm: String,
+        @RequestParam(defaultValue = "0") page: Int,
+        @RequestParam(defaultValue = "20") size: Int
+    ) = run {
+        val pageable = adminService.createDefaultPageRequest(page, size)
+        val resultPage = adminService.searchCharacters(searchTerm, pageable, imageHost)
+        val response = ChatCharacterSearchListPageResponse(
+            totalCount = resultPage.totalElements,
+            content = resultPage.content
+        )
+        ApiResponse.ok(response)
+    }
+
    /**
     * 캐릭터 상세 정보 조회 API
     *
@@ -137,6 +160,11 @@ class AdminChatCharacterController(
        chatCharacter.imagePath = imagePath
        service.saveChatCharacter(chatCharacter)

+        // 4. 원작 연결: originalWorkId가 있으면 서비스 계층을 통해 배정
+        if (request.originalWorkId != null) {
+            originalWorkService.assignOneCharacter(request.originalWorkId, chatCharacter.id!!)
+        }
+
        ApiResponse.ok(null)
    }

@@ -247,7 +275,8 @@ class AdminChatCharacterController(
        val hasDbOnlyChanges =
            request.originalTitle != null ||
                request.originalLink != null ||
-                request.characterType != null
+                request.characterType != null ||
+                request.originalWorkId != null

        if (!hasChangedData && !hasImage && !hasDbOnlyChanges) {
            throw SodaException("변경된 데이터가 없습니다.")
@@ -286,6 +315,12 @@ class AdminChatCharacterController(
            request = request
        )

+        // 원작 연결: originalWorkId가 있으면 서비스 계층을 통해 배정
+        if (request.originalWorkId != null) {
+            // 서비스에서 유효성 검증 및 저장까지 처리
+            originalWorkService.assignOneCharacter(request.originalWorkId, request.id)
+        }
+
        ApiResponse.ok(null)
    }

--- a/src/main/kotlin/kr/co/vividnext/sodalive/admin/chat/character/dto/ChatCharacterDetailResponse.kt
+++ b/src/main/kotlin/kr/co/vividnext/sodalive/admin/chat/character/dto/ChatCharacterDetailResponse.kt
@@ -2,6 +2,10 @@ package kr.co.vividnext.sodalive.admin.chat.character.dto

 import kr.co.vividnext.sodalive.chat.character.ChatCharacter

+/**
+ * 관리자 캐릭터 상세 응답 DTO
+ * - 원작이 연결되어 있으면 원작 요약 정보(originalWork)를 함께 반환한다.
+ */
 data class ChatCharacterDetailResponse(
    val id: Long,
    val characterUUID: String,
@@ -24,7 +28,8 @@ data class ChatCharacterDetailResponse(
    val relationships: List<RelationshipResponse>,
    val personalities: List<PersonalityResponse>,
    val backgrounds: List<BackgroundResponse>,
-    val memories: List<MemoryResponse>
+    val memories: List<MemoryResponse>,
+    val originalWork: OriginalWorkBriefResponse? // 추가: 원작 요약 정보
 ) {
    companion object {
        fun from(chatCharacter: ChatCharacter, imageHost: String = ""): ChatCharacterDetailResponse {
@@ -34,6 +39,20 @@ data class ChatCharacterDetailResponse(
                chatCharacter.imagePath ?: ""
            }

+            val ow = chatCharacter.originalWork
+            val originalWorkBrief = ow?.let {
+                val owImage = if (it.imagePath != null && imageHost.isNotEmpty()) {
+                    "$imageHost/${it.imagePath}"
+                } else {
+                    it.imagePath
+                }
+                OriginalWorkBriefResponse(
+                    id = it.id!!,
+                    imageUrl = owImage,
+                    title = it.title
+                )
+            }
+
            return ChatCharacterDetailResponse(
                id = chatCharacter.id!!,
                characterUUID = chatCharacter.characterUUID,
@@ -71,7 +90,8 @@ data class ChatCharacterDetailResponse(
                },
                memories = chatCharacter.memories.map {
                    MemoryResponse(it.title, it.content, it.emotion)
-                }
+                },
+                originalWork = originalWorkBrief
            )
        }
    }
@@ -101,3 +121,12 @@ data class RelationshipResponse(
    val relationshipType: String,
    val currentStatus: String
 )
+
+/**
+ * 원작 요약 응답 DTO(관리자 캐릭터 상세용)
+ */
+data class OriginalWorkBriefResponse(
+    val id: Long,
+    val imageUrl: String?,
+    val title: String
+)
--- a/src/main/kotlin/kr/co/vividnext/sodalive/admin/chat/character/dto/ChatCharacterDto.kt
+++ b/src/main/kotlin/kr/co/vividnext/sodalive/admin/chat/character/dto/ChatCharacterDto.kt
@@ -40,6 +40,7 @@ data class ChatCharacterRegisterRequest(
    @JsonProperty("appearance") val appearance: String?,
    @JsonProperty("originalTitle") val originalTitle: String? = null,
    @JsonProperty("originalLink") val originalLink: String? = null,
+    @JsonProperty("originalWorkId") val originalWorkId: Long? = null,
    @JsonProperty("characterType") val characterType: String? = null,
    @JsonProperty("tags") val tags: List<String> = emptyList(),
    @JsonProperty("hobbies") val hobbies: List<String> = emptyList(),
@@ -75,6 +76,7 @@ data class ChatCharacterUpdateRequest(
    @JsonProperty("appearance") val appearance: String? = null,
    @JsonProperty("originalTitle") val originalTitle: String? = null,
    @JsonProperty("originalLink") val originalLink: String? = null,
+    @JsonProperty("originalWorkId") val originalWorkId: Long? = null,
    @JsonProperty("characterType") val characterType: String? = null,
    @JsonProperty("isActive") val isActive: Boolean? = null,
    @JsonProperty("tags") val tags: List<String>? = null,
--- a/src/main/kotlin/kr/co/vividnext/sodalive/admin/chat/character/dto/ChatCharacterSearchListPageResponse.kt
+++ b/src/main/kotlin/kr/co/vividnext/sodalive/admin/chat/character/dto/ChatCharacterSearchListPageResponse.kt
@@ -0,0 +1,9 @@
+package kr.co.vividnext.sodalive.admin.chat.character.dto
+
+/**
+ * 캐릭터 검색 결과 페이지 응답 DTO
+ */
+data class ChatCharacterSearchListPageResponse(
+    val totalCount: Long,
+    val content: List<ChatCharacterListResponse>
+)
--- a/src/main/kotlin/kr/co/vividnext/sodalive/admin/chat/character/dto/OriginalWorkChatCharacterResponse.kt
+++ b/src/main/kotlin/kr/co/vividnext/sodalive/admin/chat/character/dto/OriginalWorkChatCharacterResponse.kt
@@ -3,16 +3,16 @@ package kr.co.vividnext.sodalive.admin.chat.character.dto
 import kr.co.vividnext.sodalive.chat.character.ChatCharacter

 /**
- * 캐릭터 검색 결과 응답 DTO
+ * 원작 연결된 캐릭터 결과 응답 DTO
 */
-data class ChatCharacterSearchResponse(
+data class OriginalWorkChatCharacterResponse(
    val id: Long,
    val name: String,
    val imagePath: String?
 ) {
    companion object {
-        fun from(character: ChatCharacter, imageHost: String): ChatCharacterSearchResponse {
-            return ChatCharacterSearchResponse(
+        fun from(character: ChatCharacter, imageHost: String): OriginalWorkChatCharacterResponse {
+            return OriginalWorkChatCharacterResponse(
                id = character.id!!,
                name = character.name,
                imagePath = character.imagePath?.let { "$imageHost/$it" }
@@ -22,9 +22,9 @@ data class ChatCharacterSearchResponse(
 }

 /**
- * 캐릭터 검색 결과 페이지 응답 DTO
+ * 원작 연결된 캐릭터 결과 페이지 응답 DTO
 */
-data class ChatCharacterSearchListPageResponse(
+data class OriginalWorkChatCharacterListPageResponse(
    val totalCount: Long,
-    val content: List<ChatCharacterSearchResponse>
+    val content: List<OriginalWorkChatCharacterResponse>
 )
--- a/src/main/kotlin/kr/co/vividnext/sodalive/admin/chat/character/service/AdminChatCharacterService.kt
+++ b/src/main/kotlin/kr/co/vividnext/sodalive/admin/chat/character/service/AdminChatCharacterService.kt
@@ -3,7 +3,6 @@ package kr.co.vividnext.sodalive.admin.chat.character.service
 import kr.co.vividnext.sodalive.admin.chat.character.dto.ChatCharacterDetailResponse
 import kr.co.vividnext.sodalive.admin.chat.character.dto.ChatCharacterListPageResponse
 import kr.co.vividnext.sodalive.admin.chat.character.dto.ChatCharacterListResponse
-import kr.co.vividnext.sodalive.admin.chat.character.dto.ChatCharacterSearchResponse
 import kr.co.vividnext.sodalive.chat.character.repository.ChatCharacterRepository
 import kr.co.vividnext.sodalive.common.SodaException
 import org.springframework.data.domain.Page
@@ -65,20 +64,15 @@ class AdminChatCharacterService(
    }

    /**
-     * 캐릭터 검색 (이름, 설명, MBTI, 태그 기반)
-     *
-     * @param searchTerm 검색어
-     * @param pageable 페이징 정보
-     * @param imageHost 이미지 호스트 URL
-     * @return 검색된 캐릭터 목록 (페이징)
+     * 캐릭터 검색 (이름, 설명, MBTI, 태그 기반) - 페이징 (기존 사용처 호환용)
     */
    @Transactional(readOnly = true)
    fun searchCharacters(
        searchTerm: String,
        pageable: Pageable,
        imageHost: String = ""
-    ): Page<ChatCharacterSearchResponse> {
+    ): Page<ChatCharacterListResponse> {
        val characters = chatCharacterRepository.searchCharacters(searchTerm, pageable)
-        return characters.map { ChatCharacterSearchResponse.from(it, imageHost) }
+        return characters.map { ChatCharacterListResponse.from(it, imageHost) }
    }
 }
--- a/src/main/kotlin/kr/co/vividnext/sodalive/admin/chat/original/AdminOriginalWorkController.kt
+++ b/src/main/kotlin/kr/co/vividnext/sodalive/admin/chat/original/AdminOriginalWorkController.kt
@@ -0,0 +1,199 @@
+package kr.co.vividnext.sodalive.admin.chat.original
+
+import com.amazonaws.services.s3.model.ObjectMetadata
+import com.fasterxml.jackson.databind.ObjectMapper
+import kr.co.vividnext.sodalive.admin.chat.character.dto.OriginalWorkChatCharacterListPageResponse
+import kr.co.vividnext.sodalive.admin.chat.character.dto.OriginalWorkChatCharacterResponse
+import kr.co.vividnext.sodalive.admin.chat.original.dto.OriginalWorkAssignCharactersRequest
+import kr.co.vividnext.sodalive.admin.chat.original.dto.OriginalWorkPageResponse
+import kr.co.vividnext.sodalive.admin.chat.original.dto.OriginalWorkRegisterRequest
+import kr.co.vividnext.sodalive.admin.chat.original.dto.OriginalWorkResponse
+import kr.co.vividnext.sodalive.admin.chat.original.dto.OriginalWorkUpdateRequest
+import kr.co.vividnext.sodalive.admin.chat.original.service.AdminOriginalWorkService
+import kr.co.vividnext.sodalive.aws.s3.S3Uploader
+import kr.co.vividnext.sodalive.common.ApiResponse
+import kr.co.vividnext.sodalive.common.SodaException
+import kr.co.vividnext.sodalive.utils.generateFileName
+import org.springframework.beans.factory.annotation.Value
+import org.springframework.security.access.prepost.PreAuthorize
+import org.springframework.web.bind.annotation.DeleteMapping
+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.PutMapping
+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.RequestPart
+import org.springframework.web.bind.annotation.RestController
+import org.springframework.web.multipart.MultipartFile
+
+/**
+ * 원작(오리지널 작품) 관리자 API
+ * - 원작 등록/수정/삭제
+ * - 원작과 캐릭터 연결(배정) 및 해제
+ */
+@RestController
+@RequestMapping("/admin/chat/original")
+@PreAuthorize("hasRole('ADMIN')")
+class AdminOriginalWorkController(
+    private val originalWorkService: AdminOriginalWorkService,
+    private val s3Uploader: S3Uploader,
+    @Value("\${cloud.aws.s3.bucket}")
+    private val s3Bucket: String,
+    @Value("\${cloud.aws.cloud-front.host}")
+    private val imageHost: String
+) {
+
+    /**
+     * 원작 등록
+     * - 이미지 파일과 JSON 요청을 멀티파트로 받는다.
+     */
+    @PostMapping("/register")
+    fun register(
+        @RequestPart("image") image: MultipartFile,
+        @RequestPart("request") requestString: String
+    ) = run {
+        val objectMapper = ObjectMapper()
+        val request = objectMapper.readValue(requestString, OriginalWorkRegisterRequest::class.java)
+
+        // 서비스 계층을 통해 원작을 생성
+        val saved = originalWorkService.createOriginalWork(request)
+
+        // 이미지 업로드 후 이미지 경로 업데이트
+        val imagePath = uploadImage(saved.id!!, image)
+        originalWorkService.updateOriginalWorkImage(saved.id!!, imagePath)
+
+        ApiResponse.ok(null)
+    }
+
+    /**
+     * 원작 수정
+     * - 이미지가 있으면 교체, 없으면 유지
+     */
+    @PutMapping("/update")
+    fun update(
+        @RequestPart(value = "image", required = false) image: MultipartFile?,
+        @RequestPart("request") requestString: String
+    ) = run {
+        val objectMapper = ObjectMapper()
+        val request = objectMapper.readValue(requestString, OriginalWorkUpdateRequest::class.java)
+
+        // 이미지가 전달된 경우 먼저 업로드하여 경로를 생성
+        val imagePath = if (image != null && !image.isEmpty) {
+            uploadImage(request.id, image)
+        } else {
+            null
+        }
+
+        originalWorkService.updateOriginalWork(request, imagePath)
+        ApiResponse.ok(null)
+    }
+
+    /**
+     * 원작 삭제
+     */
+    @DeleteMapping("/{id}")
+    fun delete(@PathVariable id: Long) = run {
+        originalWorkService.deleteOriginalWork(id)
+        ApiResponse.ok(null)
+    }
+
+    /**
+     * 원작 목록(페이징)
+     */
+    @GetMapping("/list")
+    fun list(
+        @RequestParam(defaultValue = "0") page: Int,
+        @RequestParam(defaultValue = "20") size: Int
+    ) = run {
+        val pageRes = originalWorkService.getOriginalWorkPage(page, size)
+        val content = pageRes.content.map { OriginalWorkResponse.from(it, imageHost) }
+        ApiResponse.ok(OriginalWorkPageResponse(totalCount = pageRes.totalElements, content = content))
+    }
+
+    /**
+     * 원작 검색(관리자)
+     * - 제목/콘텐츠타입/카테고리 기준 부분 검색, 소프트 삭제 제외
+     * - 페이징 제거: 전체 목록 반환
+     */
+    @GetMapping("/search")
+    fun search(
+        @RequestParam("searchTerm") searchTerm: String
+    ) = run {
+        val list = originalWorkService.searchOriginalWorksAll(searchTerm)
+        val content = list.map { OriginalWorkResponse.from(it, imageHost) }
+        ApiResponse.ok(content)
+    }
+
+    /**
+     * 원작 상세
+     */
+    @GetMapping("/{id}")
+    fun detail(@PathVariable id: Long) = run {
+        ApiResponse.ok(OriginalWorkResponse.from(originalWorkService.getOriginalWork(id), imageHost))
+    }
+
+    /**
+     * 원작에 기존 캐릭터들을 배정
+     * - 캐릭터는 하나의 원작에만 속하므로, 해당 캐릭터들의 originalWork를 이 원작으로 설정
+     */
+    @PostMapping("/{id}/assign-characters")
+    fun assignCharacters(
+        @PathVariable id: Long,
+        @RequestBody body: OriginalWorkAssignCharactersRequest
+    ) = run {
+        originalWorkService.assignCharacters(id, body.characterIds)
+        ApiResponse.ok(null)
+    }
+
+    /**
+     * 원작에서 캐릭터들 해제
+     * - 캐릭터들의 originalWork를 null로 설정
+     */
+    @PostMapping("/{id}/unassign-characters")
+    fun unassignCharacters(
+        @PathVariable id: Long,
+        @RequestBody body: OriginalWorkAssignCharactersRequest
+    ) = run {
+        originalWorkService.unassignCharacters(id, body.characterIds)
+        ApiResponse.ok(null)
+    }
+
+    /**
+     * 관리자용: 지정 원작에 속한 캐릭터 목록 페이징 조회
+     * - 활성 캐릭터만 포함
+     * - 응답 항목: 캐릭터 이미지(URL), 이름
+     */
+    @GetMapping("/{id}/characters")
+    fun listCharactersOfOriginal(
+        @PathVariable id: Long,
+        @RequestParam(defaultValue = "0") page: Int,
+        @RequestParam(defaultValue = "20") size: Int
+    ) = run {
+        val pageRes = originalWorkService.getCharactersOfOriginalWorkPage(id, page, size)
+        val content = pageRes.content.map { OriginalWorkChatCharacterResponse.from(it, imageHost) }
+        ApiResponse.ok(
+            OriginalWorkChatCharacterListPageResponse(
+                totalCount = pageRes.totalElements,
+                content = content
+            )
+        )
+    }
+
+    /** 이미지 업로드 공통 처리 */
+    private fun uploadImage(originalWorkId: Long, image: MultipartFile): String {
+        try {
+            val metadata = ObjectMetadata()
+            metadata.contentLength = image.size
+            return s3Uploader.upload(
+                inputStream = image.inputStream,
+                bucket = s3Bucket,
+                filePath = "originals/$originalWorkId/${generateFileName(prefix = "original")}",
+                metadata = metadata
+            )
+        } catch (e: Exception) {
+            throw SodaException("이미지 저장에 실패했습니다: ${e.message}")
+        }
+    }
+}
--- a/src/main/kotlin/kr/co/vividnext/sodalive/admin/chat/original/dto/OriginalWorkDtos.kt
+++ b/src/main/kotlin/kr/co/vividnext/sodalive/admin/chat/original/dto/OriginalWorkDtos.kt
@@ -0,0 +1,95 @@
+package kr.co.vividnext.sodalive.admin.chat.original.dto
+
+import com.fasterxml.jackson.annotation.JsonProperty
+import kr.co.vividnext.sodalive.chat.original.OriginalWork
+
+/**
+ * 원작 등록 요청 DTO
+ */
+data class OriginalWorkRegisterRequest(
+    @JsonProperty("title") val title: String,
+    @JsonProperty("contentType") val contentType: String,
+    @JsonProperty("category") val category: String,
+    @JsonProperty("isAdult") val isAdult: Boolean = false,
+    @JsonProperty("description") val description: String = "",
+    @JsonProperty("originalWork") val originalWork: String? = null,
+    @JsonProperty("originalLink") val originalLink: String? = null,
+    @JsonProperty("writer") val writer: String? = null,
+    @JsonProperty("studio") val studio: String? = null,
+    @JsonProperty("originalLinks") val originalLinks: List<String>? = null,
+    @JsonProperty("tags") val tags: List<String>? = null
+)
+
+/**
+ * 원작 수정 요청 DTO (부분 수정 가능)
+ */
+data class OriginalWorkUpdateRequest(
+    @JsonProperty("id") val id: Long,
+    @JsonProperty("title") val title: String? = null,
+    @JsonProperty("contentType") val contentType: String? = null,
+    @JsonProperty("category") val category: String? = null,
+    @JsonProperty("isAdult") val isAdult: Boolean? = null,
+    @JsonProperty("description") val description: String? = null,
+    @JsonProperty("originalWork") val originalWork: String? = null,
+    @JsonProperty("originalLink") val originalLink: String? = null,
+    @JsonProperty("writer") val writer: String? = null,
+    @JsonProperty("studio") val studio: String? = null,
+    @JsonProperty("originalLinks") val originalLinks: List<String>? = null,
+    @JsonProperty("tags") val tags: List<String>? = null
+)
+
+/**
+ * 원작 상세/목록 응답 DTO
+ */
+data class OriginalWorkResponse(
+    val id: Long,
+    val title: String,
+    val contentType: String,
+    val category: String,
+    val isAdult: Boolean,
+    val description: String,
+    val originalWork: String?,
+    val originalLink: String?,
+    val writer: String?,
+    val studio: String?,
+    val originalLinks: List<String>,
+    val tags: List<String>,
+    val imageUrl: String?
+) {
+    companion object {
+        fun from(entity: OriginalWork, imageHost: String = ""): OriginalWorkResponse {
+            val fullImagePath = if (entity.imagePath != null && imageHost.isNotEmpty()) {
+                "$imageHost/${entity.imagePath}"
+            } else {
+                entity.imagePath
+            }
+            return OriginalWorkResponse(
+                id = entity.id!!,
+                title = entity.title,
+                contentType = entity.contentType,
+                category = entity.category,
+                isAdult = entity.isAdult,
+                description = entity.description,
+                originalWork = entity.originalWork,
+                originalLink = entity.originalLink,
+                writer = entity.writer,
+                studio = entity.studio,
+                originalLinks = entity.originalLinks.map { it.url },
+                tags = entity.tagMappings.map { it.tag.tag },
+                imageUrl = fullImagePath
+            )
+        }
+    }
+}
+
+data class OriginalWorkPageResponse(
+    val totalCount: Long,
+    val content: List<OriginalWorkResponse>
+)
+
+/**
+ * 원작-캐릭터 연결/해제 요청 DTO
+ */
+data class OriginalWorkAssignCharactersRequest(
+    @JsonProperty("characterIds") val characterIds: List<Long>
+)
--- a/src/main/kotlin/kr/co/vividnext/sodalive/admin/chat/original/service/AdminOriginalWorkService.kt
+++ b/src/main/kotlin/kr/co/vividnext/sodalive/admin/chat/original/service/AdminOriginalWorkService.kt
@@ -0,0 +1,213 @@
+package kr.co.vividnext.sodalive.admin.chat.original.service
+
+import kr.co.vividnext.sodalive.admin.chat.original.dto.OriginalWorkRegisterRequest
+import kr.co.vividnext.sodalive.admin.chat.original.dto.OriginalWorkUpdateRequest
+import kr.co.vividnext.sodalive.chat.character.ChatCharacter
+import kr.co.vividnext.sodalive.chat.character.repository.ChatCharacterRepository
+import kr.co.vividnext.sodalive.chat.original.OriginalWork
+import kr.co.vividnext.sodalive.chat.original.OriginalWorkRepository
+import kr.co.vividnext.sodalive.chat.original.OriginalWorkTag
+import kr.co.vividnext.sodalive.chat.original.OriginalWorkTagMapping
+import kr.co.vividnext.sodalive.chat.original.repository.OriginalWorkTagRepository
+import kr.co.vividnext.sodalive.common.SodaException
+import org.springframework.data.domain.Page
+import org.springframework.data.domain.PageRequest
+import org.springframework.data.domain.Sort
+import org.springframework.stereotype.Service
+import org.springframework.transaction.annotation.Transactional
+
+/**
+ * 원작(오리지널 작품) 관련 관리자 서비스
+ * - 컨트롤러와 레포지토리 사이의 서비스 계층으로 DB 접근을 캡슐화한다.
+ */
+@Service
+class AdminOriginalWorkService(
+    private val originalWorkRepository: OriginalWorkRepository,
+    private val chatCharacterRepository: ChatCharacterRepository,
+    private val originalWorkTagRepository: OriginalWorkTagRepository
+) {
+
+    /** 원작 등록 (중복 제목 방지 포함) */
+    @Transactional
+    fun createOriginalWork(request: OriginalWorkRegisterRequest): OriginalWork {
+        originalWorkRepository.findByTitleAndIsDeletedFalse(request.title)?.let {
+            throw SodaException("동일한 제목의 원작이 이미 존재합니다: ${request.title}")
+        }
+        val entity = OriginalWork(
+            title = request.title,
+            contentType = request.contentType,
+            category = request.category,
+            isAdult = request.isAdult,
+            description = request.description,
+            originalWork = request.originalWork,
+            originalLink = request.originalLink,
+            writer = request.writer,
+            studio = request.studio
+        )
+        // 링크 리스트 생성
+        request.originalLinks?.filter { it.isNotBlank() }?.forEach { link ->
+            entity.originalLinks.add(kr.co.vividnext.sodalive.chat.original.OriginalWorkLink(url = link, originalWork = entity))
+        }
+        // 태그 매핑 생성 (기존 태그 재사용)
+        request.tags?.let { tags ->
+            val normalized = tags.map { it.trim() }.filter { it.isNotBlank() }.toSet()
+            normalized.forEach { t ->
+                val tagEntity = originalWorkTagRepository.findByTag(t) ?: originalWorkTagRepository.save(OriginalWorkTag(t))
+                entity.tagMappings.add(OriginalWorkTagMapping(originalWork = entity, tag = tagEntity))
+            }
+        }
+        return originalWorkRepository.save(entity)
+    }
+
+    /** 원작 수정 (이미지 경로 포함 선택적 변경) */
+    @Transactional
+    fun updateOriginalWork(request: OriginalWorkUpdateRequest, imagePath: String? = null): OriginalWork {
+        val ow = originalWorkRepository.findByIdAndIsDeletedFalse(request.id)
+            .orElseThrow { SodaException("해당 원작을 찾을 수 없습니다") }
+
+        request.title?.let { ow.title = it }
+        request.contentType?.let { ow.contentType = it }
+        request.category?.let { ow.category = it }
+        request.isAdult?.let { ow.isAdult = it }
+        request.description?.let { ow.description = it }
+        request.originalWork?.let { ow.originalWork = it }
+        request.originalLink?.let { ow.originalLink = it }
+        request.writer?.let { ow.writer = it }
+        request.studio?.let { ow.studio = it }
+        // 링크 리스트가 전달되면 기존 것을 교체
+        request.originalLinks?.let { links ->
+            ow.originalLinks.clear()
+            links.filter { it.isNotBlank() }.forEach { link ->
+                ow.originalLinks.add(kr.co.vividnext.sodalive.chat.original.OriginalWorkLink(url = link, originalWork = ow))
+            }
+        }
+        // 태그 변경사항만 반영 (요청이 null이면 변경 없음)
+        request.tags?.let { tags ->
+            val normalized = tags.map { it.trim() }.filter { it.isNotBlank() }.toSet()
+            val current = ow.tagMappings.map { it.tag.tag }.toSet()
+            val toAdd = normalized.minus(current)
+            val toRemove = current.minus(normalized)
+
+            if (toRemove.isNotEmpty()) {
+                val itr = ow.tagMappings.iterator()
+                while (itr.hasNext()) {
+                    val m = itr.next()
+                    if (toRemove.contains(m.tag.tag)) {
+                        itr.remove() // orphanRemoval=true로 매핑 삭제
+                    }
+                }
+            }
+            if (toAdd.isNotEmpty()) {
+                toAdd.forEach { t ->
+                    val tagEntity = originalWorkTagRepository.findByTag(t) ?: originalWorkTagRepository.save(OriginalWorkTag(t))
+                    ow.tagMappings.add(OriginalWorkTagMapping(originalWork = ow, tag = tagEntity))
+                }
+            }
+        }
+        if (imagePath != null) {
+            ow.imagePath = imagePath
+        }
+        return originalWorkRepository.save(ow)
+    }
+
+    /** 원작 이미지 경로만 별도 갱신 */
+    @Transactional
+    fun updateOriginalWorkImage(originalWorkId: Long, imagePath: String): OriginalWork {
+        val ow = originalWorkRepository.findByIdAndIsDeletedFalse(originalWorkId)
+            .orElseThrow { SodaException("해당 원작을 찾을 수 없습니다") }
+        ow.imagePath = imagePath
+        return originalWorkRepository.save(ow)
+    }
+
+    /** 원작 삭제 (소프트 삭제) */
+    @Transactional
+    fun deleteOriginalWork(id: Long) {
+        val ow = originalWorkRepository.findByIdAndIsDeletedFalse(id)
+            .orElseThrow { SodaException("해당 원작을 찾을 수 없습니다: $id") }
+        ow.isDeleted = true
+        originalWorkRepository.save(ow)
+    }
+
+    /** 원작 상세 조회 (소프트 삭제 제외) */
+    @Transactional(readOnly = true)
+    fun getOriginalWork(id: Long): OriginalWork {
+        return originalWorkRepository.findByIdAndIsDeletedFalse(id)
+            .orElseThrow { SodaException("해당 원작을 찾을 수 없습니다") }
+    }
+
+    /** 원작 페이징 조회 */
+    @Transactional(readOnly = true)
+    fun getOriginalWorkPage(page: Int, size: Int): Page<OriginalWork> {
+        val safePage = if (page < 0) 0 else page
+        val safeSize = when {
+            size <= 0 -> 20
+            size > 100 -> 100
+            else -> size
+        }
+        val pageable = PageRequest.of(safePage, safeSize, Sort.by("createdAt").descending())
+        return originalWorkRepository.findByIsDeletedFalse(pageable)
+    }
+
+    /** 지정 원작에 속한 활성 캐릭터 페이징 조회 (최신순) */
+    @Transactional(readOnly = true)
+    fun getCharactersOfOriginalWorkPage(originalWorkId: Long, page: Int, size: Int): Page<ChatCharacter> {
+        // 원작 존재 및 소프트 삭제 여부 확인
+        originalWorkRepository.findByIdAndIsDeletedFalse(originalWorkId)
+            .orElseThrow { SodaException("해당 원작을 찾을 수 없습니다") }
+
+        val safePage = if (page < 0) 0 else page
+        val safeSize = when {
+            size <= 0 -> 20
+            size > 100 -> 100
+            else -> size
+        }
+        val pageable = PageRequest.of(safePage, safeSize, Sort.by("createdAt").descending())
+        return chatCharacterRepository.findByOriginalWorkIdAndIsActiveTrue(originalWorkId, pageable)
+    }
+
+    /** 원작 검색 (제목/콘텐츠타입/카테고리, 소프트 삭제 제외) - 무페이징 */
+    @Transactional(readOnly = true)
+    fun searchOriginalWorksAll(searchTerm: String): List<OriginalWork> {
+        return originalWorkRepository.searchNoPaging(searchTerm)
+    }
+
+    /** 원작에 기존 캐릭터들을 배정 */
+    @Transactional
+    fun assignCharacters(originalWorkId: Long, characterIds: List<Long>) {
+        val ow = originalWorkRepository.findByIdAndIsDeletedFalse(originalWorkId)
+            .orElseThrow { SodaException("해당 원작을 찾을 수 없습니다") }
+        if (characterIds.isEmpty()) return
+        val characters = chatCharacterRepository.findByIdInAndIsActiveTrue(characterIds)
+        characters.forEach { it.originalWork = ow }
+        chatCharacterRepository.saveAll(characters)
+    }
+
+    /** 원작에서 캐릭터들 해제 */
+    @Transactional
+    fun unassignCharacters(originalWorkId: Long, characterIds: List<Long>) {
+        // 원작 존재 확인 (소프트 삭제 제외)
+        originalWorkRepository.findByIdAndIsDeletedFalse(originalWorkId)
+            .orElseThrow { SodaException("해당 원작을 찾을 수 없습니다") }
+        if (characterIds.isEmpty()) return
+        val characters = chatCharacterRepository.findByIdInAndIsActiveTrue(characterIds)
+        characters.forEach { it.originalWork = null }
+        chatCharacterRepository.saveAll(characters)
+    }
+
+    /** 단일 캐릭터를 지정 원작에 배정 */
+    @Transactional
+    fun assignOneCharacter(originalWorkId: Long, characterId: Long) {
+        val character = chatCharacterRepository.findById(characterId)
+            .orElseThrow { SodaException("해당 캐릭터를 찾을 수 없습니다") }
+
+        if (originalWorkId == 0L) {
+            character.originalWork = null
+        } else {
+            val ow = originalWorkRepository.findByIdAndIsDeletedFalse(originalWorkId)
+                .orElseThrow { SodaException("해당 원작을 찾을 수 없습니다") }
+            character.originalWork = ow
+        }
+
+        chatCharacterRepository.save(character)
+    }
+}
--- a/src/main/kotlin/kr/co/vividnext/sodalive/chat/character/ChatCharacter.kt
+++ b/src/main/kotlin/kr/co/vividnext/sodalive/chat/character/ChatCharacter.kt
@@ -1,5 +1,6 @@
 package kr.co.vividnext.sodalive.chat.character

+import kr.co.vividnext.sodalive.chat.original.OriginalWork
 import kr.co.vividnext.sodalive.common.BaseEntity
 import javax.persistence.CascadeType
 import javax.persistence.Column
@@ -7,6 +8,8 @@ import javax.persistence.Entity
 import javax.persistence.EnumType
 import javax.persistence.Enumerated
 import javax.persistence.FetchType
+import javax.persistence.JoinColumn
+import javax.persistence.ManyToOne
 import javax.persistence.OneToMany

@Entity
@@ -44,14 +47,19 @@ class ChatCharacter(
    @Column(columnDefinition = "TEXT")
    var appearance: String? = null,

-    // 원작 (optional)
+    // 원작명/원작링크 (사용하지 않음 - 하위 호환을 위해 필드만 유지)
    @Column(nullable = true)
    var originalTitle: String? = null,

-    // 원작 링크 (optional)
+    // 원작 링크 (사용하지 않음 - 하위 호환을 위해 필드만 유지)
    @Column(nullable = true)
    var originalLink: String? = null,

+    // 연관 원작 (한 캐릭터는 하나의 원작에만 속함)
+    @ManyToOne(fetch = FetchType.LAZY)
+    @JoinColumn(name = "original_work_id")
+    var originalWork: OriginalWork? = null,
+
    // 캐릭터 유형
    @Enumerated(EnumType.STRING)
    @Column(nullable = false)
--- a/src/main/kotlin/kr/co/vividnext/sodalive/chat/character/repository/ChatCharacterRepository.kt
+++ b/src/main/kotlin/kr/co/vividnext/sodalive/chat/character/repository/ChatCharacterRepository.kt
@@ -12,6 +12,7 @@ import org.springframework.stereotype.Repository
 interface ChatCharacterRepository : JpaRepository<ChatCharacter, Long> {
    fun findByName(name: String): ChatCharacter?
    fun findByIsActiveTrue(pageable: Pageable): Page<ChatCharacter>
+    fun findByOriginalWorkIdAndIsActiveTrue(originalWorkId: Long, pageable: Pageable): Page<ChatCharacter>

    /**
     * 2주 이내(파라미터 since 이상) 활성 캐릭터 페이징 조회
@@ -31,7 +32,7 @@ interface ChatCharacterRepository : JpaRepository<ChatCharacter, Long> {
    fun countByIsActiveTrueAndCreatedAtGreaterThanEqual(since: java.time.LocalDateTime): Long

    /**
-     * 이름, 설명, MBTI, 태그로 캐릭터 검색
+     * 이름, 설명, MBTI, 태그로 캐릭터 검색 - 페이징
     */
    @Query(
        """
--- a/src/main/kotlin/kr/co/vividnext/sodalive/chat/character/service/ChatCharacterService.kt
+++ b/src/main/kotlin/kr/co/vividnext/sodalive/chat/character/service/ChatCharacterService.kt
@@ -45,10 +45,10 @@ class ChatCharacterService(
    @Transactional(readOnly = true)
    @Cacheable(
        cacheNames = ["popularCharacters_24h"],
-        key = "T(kr.co.vividnext.sodalive.chat.character.service.RankingWindowCalculator).now('popular-chat-character').cacheKey"
+        key = "T(kr.co.vividnext.sodalive.chat.character.service.RankingWindowCalculator).now('popular-character').cacheKey"
    )
    fun getPopularCharacters(limit: Long = 20): List<Character> {
-        val window = RankingWindowCalculator.now("popular-chat-character")
+        val window = RankingWindowCalculator.now("popular-character")
        val topIds = popularCharacterQuery.findPopularCharacterIds(window.windowStart, window.nextBoundary, limit)
        val list = loadCharactersInOrder(topIds)
        return list.map {
--- a/src/main/kotlin/kr/co/vividnext/sodalive/chat/character/service/RankingWindowCalculator.kt
+++ b/src/main/kotlin/kr/co/vividnext/sodalive/chat/character/service/RankingWindowCalculator.kt
@@ -20,7 +20,7 @@ object RankingWindowCalculator {
    private const val BOUNDARY_HOUR = 20 // 20:00:00 UTC

    @JvmStatic
-    fun now(prefix: String = "popular-chat-character"): RankingWindow {
+    fun now(prefix: String = "popular-character"): RankingWindow {
        val now = ZonedDateTime.now(ZONE)
        val todayBoundary = now.toLocalDate().atTime(BOUNDARY_HOUR, 0, 0).atZone(ZONE)

--- a/src/main/kotlin/kr/co/vividnext/sodalive/chat/original/OriginalWork.kt
+++ b/src/main/kotlin/kr/co/vividnext/sodalive/chat/original/OriginalWork.kt
@@ -0,0 +1,65 @@
+package kr.co.vividnext.sodalive.chat.original
+
+import kr.co.vividnext.sodalive.common.BaseEntity
+import javax.persistence.CascadeType
+import javax.persistence.Column
+import javax.persistence.Entity
+import javax.persistence.OneToMany
+
+/**
+ * 원작(오리지널 작품) 엔티티
+ * - 캐릭터를 원작별로 묶기 위한 기준 엔티티
+ * - 각 필드는 운영에서 관리자가 입력/수정한다.
+ */
+@Entity
+class OriginalWork(
+    /** 원작 제목 */
+    @Column(nullable = false)
+    var title: String,
+
+    /** 콘텐츠 타입 (예: 웹소설, 웹툰 등) */
+    @Column(nullable = false)
+    var contentType: String,
+
+    /** 카테고리/장르 (예: 로맨스, 판타지 등) */
+    @Column(nullable = false)
+    var category: String,
+
+    /** 19금 여부 */
+    @Column(nullable = false)
+    var isAdult: Boolean = false,
+
+    /** 작품 소개 */
+    @Column(columnDefinition = "TEXT")
+    var description: String = "",
+
+    /** 원천 원작 */
+    @Column(nullable = true)
+    var originalWork: String? = null,
+
+    /** 원천 원작 링크(단일) */
+    @Column(nullable = true)
+    var originalLink: String? = null,
+
+    /** 작가 */
+    @Column(nullable = true)
+    var writer: String? = null,
+
+    /** 제작사 */
+    @Column(nullable = true)
+    var studio: String? = null
+) : BaseEntity() {
+    /** 원작 대표 이미지 S3 경로 */
+    var imagePath: String? = null
+
+    /** 소프트 삭제 여부 (true면 삭제된 것으로 간주) */
+    var isDeleted: Boolean = false
+
+    /** 원작 링크들 (1:N) */
+    @OneToMany(mappedBy = "originalWork", cascade = [CascadeType.ALL], orphanRemoval = true)
+    var originalLinks: MutableList<OriginalWorkLink> = mutableListOf()
+
+    /** 원작 태그 매핑들 (1:N) */
+    @OneToMany(mappedBy = "originalWork", cascade = [CascadeType.ALL], orphanRemoval = true)
+    var tagMappings: MutableList<OriginalWorkTagMapping> = mutableListOf()
+}
--- a/src/main/kotlin/kr/co/vividnext/sodalive/chat/original/OriginalWorkLink.kt
+++ b/src/main/kotlin/kr/co/vividnext/sodalive/chat/original/OriginalWorkLink.kt
@@ -0,0 +1,22 @@
+package kr.co.vividnext.sodalive.chat.original
+
+import kr.co.vividnext.sodalive.common.BaseEntity
+import javax.persistence.Column
+import javax.persistence.Entity
+import javax.persistence.FetchType
+import javax.persistence.JoinColumn
+import javax.persistence.ManyToOne
+
+/**
+ * 원작 원본 링크 엔티티
+ * - 하나의 원작(OriginalWork)에 여러 개의 링크가 연결될 수 있음 (1:N)
+ */
+@Entity
+class OriginalWorkLink(
+    @Column(nullable = false)
+    var url: String,
+
+    @ManyToOne(fetch = FetchType.LAZY)
+    @JoinColumn(name = "original_work_id")
+    var originalWork: OriginalWork? = null
+) : BaseEntity()
--- a/src/main/kotlin/kr/co/vividnext/sodalive/chat/original/OriginalWorkRepository.kt
+++ b/src/main/kotlin/kr/co/vividnext/sodalive/chat/original/OriginalWorkRepository.kt
@@ -0,0 +1,63 @@
+package kr.co.vividnext.sodalive.chat.original
+
+import org.springframework.data.domain.Page
+import org.springframework.data.domain.Pageable
+import org.springframework.data.jpa.repository.JpaRepository
+import org.springframework.data.jpa.repository.Query
+import org.springframework.data.repository.query.Param
+import org.springframework.stereotype.Repository
+import java.util.Optional
+
+@Repository
+interface OriginalWorkRepository : JpaRepository<OriginalWork, Long> {
+    fun findByTitleAndIsDeletedFalse(title: String): OriginalWork?
+    fun findByIdAndIsDeletedFalse(id: Long): Optional<OriginalWork>
+    fun findByIsDeletedFalse(pageable: Pageable): Page<OriginalWork>
+
+    /**
+     * 제목/콘텐츠타입/카테고리 기준 부분 검색 (소프트 삭제 제외) - 무페이징 전체 목록
+     */
+    @Query(
+        """
+        SELECT ow FROM OriginalWork ow
+        WHERE ow.isDeleted = false AND (
+            LOWER(ow.title) LIKE LOWER(CONCAT('%', :searchTerm, '%')) OR
+            LOWER(ow.contentType) LIKE LOWER(CONCAT('%', :searchTerm, '%')) OR
+            LOWER(ow.category) LIKE LOWER(CONCAT('%', :searchTerm, '%'))
+        )
+        ORDER BY ow.createdAt DESC
+        """
+    )
+    fun searchNoPaging(
+        @Param("searchTerm") searchTerm: String
+    ): List<OriginalWork>
+
+    /**
+     * 앱용 원작 목록 조회 (페이징)
+     * - 소프트 삭제 제외
+     * - includeAdult=false이면 19금 제외
+     * - 활성 캐릭터가 하나라도 연결된 원작만 조회
+     */
+    @Query(
+        value = """
+        SELECT ow FROM OriginalWork ow
+        WHERE ow.isDeleted = false
+          AND (:includeAdult = true OR ow.isAdult = false)
+          AND EXISTS (
+            SELECT 1 FROM ChatCharacter c
+            WHERE c.originalWork = ow AND c.isActive = true
+          )
+        ORDER BY ow.createdAt DESC
+        """,
+        countQuery = """
+        SELECT COUNT(ow) FROM OriginalWork ow
+        WHERE ow.isDeleted = false
+          AND (:includeAdult = true OR ow.isAdult = false)
+          AND EXISTS (
+            SELECT 1 FROM ChatCharacter c
+            WHERE c.originalWork = ow AND c.isActive = true
+          )
+        """
+    )
+    fun findAllForAppPage(@Param("includeAdult") includeAdult: Boolean, pageable: Pageable): Page<OriginalWork>
+}
--- a/src/main/kotlin/kr/co/vividnext/sodalive/chat/original/OriginalWorkTag.kt
+++ b/src/main/kotlin/kr/co/vividnext/sodalive/chat/original/OriginalWorkTag.kt
@@ -0,0 +1,21 @@
+package kr.co.vividnext.sodalive.chat.original
+
+import kr.co.vividnext.sodalive.common.BaseEntity
+import javax.persistence.Column
+import javax.persistence.Entity
+import javax.persistence.OneToMany
+import javax.persistence.Table
+import javax.persistence.UniqueConstraint
+
+/**
+ * 원작 태그 엔티티 (작품/시리즈 태그와 분리)
+ */
+@Entity
+@Table(uniqueConstraints = [UniqueConstraint(columnNames = ["tag"])])
+class OriginalWorkTag(
+    @Column(nullable = false)
+    val tag: String
+) : BaseEntity() {
+    @OneToMany(mappedBy = "tag")
+    var tagMappings: MutableList<OriginalWorkTagMapping> = mutableListOf()
+}
--- a/src/main/kotlin/kr/co/vividnext/sodalive/chat/original/OriginalWorkTagMapping.kt
+++ b/src/main/kotlin/kr/co/vividnext/sodalive/chat/original/OriginalWorkTagMapping.kt
@@ -0,0 +1,21 @@
+package kr.co.vividnext.sodalive.chat.original
+
+import kr.co.vividnext.sodalive.common.BaseEntity
+import javax.persistence.Entity
+import javax.persistence.FetchType
+import javax.persistence.JoinColumn
+import javax.persistence.ManyToOne
+
+/**
+ * OriginalWork 와 OriginalWorkTag 매핑 엔티티
+ */
+@Entity
+class OriginalWorkTagMapping(
+    @ManyToOne(fetch = FetchType.LAZY)
+    @JoinColumn(name = "original_work_id")
+    val originalWork: OriginalWork,
+
+    @ManyToOne(fetch = FetchType.LAZY)
+    @JoinColumn(name = "tag_id")
+    val tag: OriginalWorkTag
+) : BaseEntity()
--- a/src/main/kotlin/kr/co/vividnext/sodalive/chat/original/controller/OriginalWorkController.kt
+++ b/src/main/kotlin/kr/co/vividnext/sodalive/chat/original/controller/OriginalWorkController.kt
@@ -0,0 +1,115 @@
+package kr.co.vividnext.sodalive.chat.original.controller
+
+import kr.co.vividnext.sodalive.chat.character.dto.Character
+import kr.co.vividnext.sodalive.chat.original.dto.OriginalWorkCharactersPageResponse
+import kr.co.vividnext.sodalive.chat.original.dto.OriginalWorkDetailResponse
+import kr.co.vividnext.sodalive.chat.original.dto.OriginalWorkListItemResponse
+import kr.co.vividnext.sodalive.chat.original.dto.OriginalWorkListResponse
+import kr.co.vividnext.sodalive.chat.original.service.OriginalWorkQueryService
+import kr.co.vividnext.sodalive.common.ApiResponse
+import kr.co.vividnext.sodalive.common.SodaException
+import kr.co.vividnext.sodalive.member.Member
+import org.springframework.beans.factory.annotation.Value
+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.RequestMapping
+import org.springframework.web.bind.annotation.RequestParam
+import org.springframework.web.bind.annotation.RestController
+
+/**
+ * 앱용 원작(오리지널 작품) 공개 API
+ * 1) 목록: 로그인 불필요, 미인증 사용자는 19금 제외, 활성 캐릭터 연결된 원작만 노출
+ * 2) 상세: 로그인 + 본인인증 필수
+ */
+@RestController
+@RequestMapping("/api/chat/original")
+class OriginalWorkController(
+    private val queryService: OriginalWorkQueryService,
+    @Value("\${cloud.aws.cloud-front.host}")
+    private val imageHost: String
+) {
+
+    /**
+     * 원작 목록 (페이징)
+     * - 로그인 불필요
+     * - 본인인증하지 않은 경우 19금 제외
+     * - 활성 캐릭터가 하나라도 연결된 원작만 노출
+     * - 요청: page(기본 0), size(기본 20)
+     * - 반환: totalCount + [imageUrl, title, contentType]
+     */
+    @GetMapping("/list")
+    fun list(
+        @RequestParam(defaultValue = "0") page: Int,
+        @RequestParam(defaultValue = "20") size: Int,
+        @AuthenticationPrincipal(expression = "#this == 'anonymousUser' ? null : member") member: Member?
+    ) = run {
+        val includeAdult = member?.auth != null
+        val pageRes = queryService.listForAppPage(includeAdult, page, size)
+        val content = pageRes.content.map { OriginalWorkListItemResponse.from(it, imageHost) }
+        ApiResponse.ok(OriginalWorkListResponse(totalCount = pageRes.totalElements, content = content))
+    }
+
+    /**
+     * 원작 상세
+     * - 로그인 및 본인인증 필수
+     * - 반환: 이미지, 제목, 콘텐츠 타입, 카테고리, 19금 여부, 작품 소개, 원작 링크
+     * - 해당 원작의 활성 캐릭터 리스트 [imageUrl, name, description]
+     * - 캐릭터는 페이징 적용: 첫 페이지 20개
+     */
+    @GetMapping("/{id}")
+    fun detail(
+        @PathVariable id: Long,
+        @AuthenticationPrincipal(expression = "#this == 'anonymousUser' ? null : member") member: Member?
+    ) = run {
+        if (member == null) throw SodaException("로그인 정보를 확인해주세요.")
+        if (member.auth == null) throw SodaException("본인인증을 하셔야 합니다.")
+
+        val ow = queryService.getOriginalWork(id)
+        val pageRes = queryService.getActiveCharactersPage(id, page = 0, size = 20)
+        val characters = pageRes.content.map {
+            val path = it.imagePath ?: "profile/default-profile.png"
+            Character(
+                characterId = it.id!!,
+                name = it.name,
+                description = it.description,
+                imageUrl = "$imageHost/$path"
+            )
+        }
+        val response = OriginalWorkDetailResponse.from(ow, imageHost, characters)
+        ApiResponse.ok(response)
+    }
+
+    /**
+     * 지정 원작에 속한 활성 캐릭터 목록 조회 (페이징)
+     * - 로그인 및 본인인증 필수
+     * - 기본 페이지 사이즈 20
+     */
+    @GetMapping("/{id}/characters")
+    fun listCharacters(
+        @PathVariable id: Long,
+        @RequestParam(defaultValue = "0") page: Int,
+        @RequestParam(defaultValue = "20") size: Int,
+        @AuthenticationPrincipal(expression = "#this == 'anonymousUser' ? null : member") member: Member?
+    ) = run {
+        if (member == null) throw SodaException("로그인 정보를 확인해주세요.")
+        if (member.auth == null) throw SodaException("본인인증을 하셔야 합니다.")
+
+        val pageRes = queryService.getActiveCharactersPage(id, page, size)
+        val content = pageRes.content.map {
+            val path = it.imagePath ?: "profile/default-profile.png"
+            Character(
+                characterId = it.id!!,
+                name = it.name,
+                description = it.description,
+                imageUrl = "$imageHost/$path"
+            )
+        }
+        ApiResponse.ok(
+            OriginalWorkCharactersPageResponse(
+                totalCount = pageRes.totalElements,
+                content = content
+            )
+        )
+    }
+}
--- a/src/main/kotlin/kr/co/vividnext/sodalive/chat/original/dto/OriginalWorkAppDtos.kt
+++ b/src/main/kotlin/kr/co/vividnext/sodalive/chat/original/dto/OriginalWorkAppDtos.kt
@@ -0,0 +1,95 @@
+package kr.co.vividnext.sodalive.chat.original.dto
+
+import com.fasterxml.jackson.annotation.JsonProperty
+import kr.co.vividnext.sodalive.chat.character.dto.Character
+import kr.co.vividnext.sodalive.chat.original.OriginalWork
+
+/**
+ * 앱용 원작 목록 아이템 응답 DTO
+ */
+data class OriginalWorkListItemResponse(
+    @JsonProperty("id") val id: Long,
+    @JsonProperty("imageUrl") val imageUrl: String?,
+    @JsonProperty("title") val title: String,
+    @JsonProperty("contentType") val contentType: String
+) {
+    companion object {
+        fun from(entity: OriginalWork, imageHost: String = ""): OriginalWorkListItemResponse {
+            val fullImage = if (entity.imagePath != null && imageHost.isNotEmpty()) {
+                "$imageHost/${entity.imagePath}"
+            } else {
+                entity.imagePath
+            }
+            return OriginalWorkListItemResponse(
+                id = entity.id!!,
+                imageUrl = fullImage,
+                title = entity.title,
+                contentType = entity.contentType
+            )
+        }
+    }
+}
+
+/**
+ * 앱용 원작 목록 응답 DTO
+ */
+data class OriginalWorkListResponse(
+    @JsonProperty("totalCount") val totalCount: Long,
+    @JsonProperty("content") val content: List<OriginalWorkListItemResponse>
+)
+
+/**
+ * 앱용 원작 상세 응답 DTO
+ */
+data class OriginalWorkDetailResponse(
+    @JsonProperty("imageUrl") val imageUrl: String?,
+    @JsonProperty("title") val title: String,
+    @JsonProperty("contentType") val contentType: String,
+    @JsonProperty("category") val category: String,
+    @JsonProperty("isAdult") val isAdult: Boolean,
+    @JsonProperty("description") val description: String,
+    @JsonProperty("originalWork") val originalWork: String?,
+    @JsonProperty("originalLink") val originalLink: String?,
+    @JsonProperty("writer") val writer: String?,
+    @JsonProperty("studio") val studio: String?,
+    @JsonProperty("originalLinks") val originalLinks: List<String>,
+    @JsonProperty("tags") val tags: List<String>,
+    @JsonProperty("characters") val characters: List<Character>
+) {
+    companion object {
+        fun from(
+            entity: OriginalWork,
+            imageHost: String = "",
+            characters: List<Character>
+        ): OriginalWorkDetailResponse {
+            val fullImage = if (entity.imagePath != null && imageHost.isNotEmpty()) {
+                "$imageHost/${entity.imagePath}"
+            } else {
+                entity.imagePath
+            }
+            return OriginalWorkDetailResponse(
+                imageUrl = fullImage,
+                title = entity.title,
+                contentType = entity.contentType,
+                category = entity.category,
+                isAdult = entity.isAdult,
+                description = entity.description,
+                originalWork = entity.originalWork,
+                originalLink = entity.originalLink,
+                writer = entity.writer,
+                studio = entity.studio,
+                originalLinks = entity.originalLinks.map { it.url },
+                tags = entity.tagMappings.map { it.tag.tag },
+                characters = characters
+            )
+        }
+    }
+}
+
+/**
+ * 앱용: 원작별 활성 캐릭터 페이징 응답 DTO
+ */
+data class OriginalWorkCharactersPageResponse(
+    @JsonProperty("totalCount") val totalCount: Long,
+    @JsonProperty("content") val content: List<Character>
+)
--- a/src/main/kotlin/kr/co/vividnext/sodalive/chat/original/repository/OriginalWorkTagRepository.kt
+++ b/src/main/kotlin/kr/co/vividnext/sodalive/chat/original/repository/OriginalWorkTagRepository.kt
@@ -0,0 +1,10 @@
+package kr.co.vividnext.sodalive.chat.original.repository
+
+import kr.co.vividnext.sodalive.chat.original.OriginalWorkTag
+import org.springframework.data.jpa.repository.JpaRepository
+import org.springframework.stereotype.Repository
+
+@Repository
+interface OriginalWorkTagRepository : JpaRepository<OriginalWorkTag, Long> {
+    fun findByTag(tag: String): OriginalWorkTag?
+}
--- a/src/main/kotlin/kr/co/vividnext/sodalive/chat/original/service/OriginalWorkQueryService.kt
+++ b/src/main/kotlin/kr/co/vividnext/sodalive/chat/original/service/OriginalWorkQueryService.kt
@@ -0,0 +1,68 @@
+package kr.co.vividnext.sodalive.chat.original.service
+
+import kr.co.vividnext.sodalive.chat.character.ChatCharacter
+import kr.co.vividnext.sodalive.chat.character.repository.ChatCharacterRepository
+import kr.co.vividnext.sodalive.chat.original.OriginalWork
+import kr.co.vividnext.sodalive.chat.original.OriginalWorkRepository
+import kr.co.vividnext.sodalive.common.SodaException
+import org.springframework.data.domain.Page
+import org.springframework.data.domain.PageRequest
+import org.springframework.data.domain.Sort
+import org.springframework.stereotype.Service
+import org.springframework.transaction.annotation.Transactional
+
+/**
+ * 앱 사용자용 원작(오리지널 작품) 조회 서비스
+ * - 목록/상세 조회 전용
+ */
+@Service
+class OriginalWorkQueryService(
+    private val originalWorkRepository: OriginalWorkRepository,
+    private val chatCharacterRepository: ChatCharacterRepository
+) {
+    /**
+     * 앱용 원작 목록 조회 (페이징)
+     * @param includeAdult true면 19금 포함, false면 제외
+     * @param page 페이지 번호(0부터)
+     * @param size 페이지 크기(기본 20, 최대 50)
+     */
+    @Transactional(readOnly = true)
+    fun listForAppPage(includeAdult: Boolean, page: Int = 0, size: Int = 20): Page<OriginalWork> {
+        val safePage = if (page < 0) 0 else page
+        val safeSize = when {
+            size <= 0 -> 20
+            size > 50 -> 50
+            else -> size
+        }
+        val pageable = PageRequest.of(safePage, safeSize, Sort.by("createdAt").descending())
+        return originalWorkRepository.findAllForAppPage(includeAdult, pageable)
+    }
+
+    /**
+     * 원작 상세 조회 (소프트 삭제 제외)
+     */
+    @Transactional(readOnly = true)
+    fun getOriginalWork(id: Long): OriginalWork {
+        return originalWorkRepository.findByIdAndIsDeletedFalse(id)
+            .orElseThrow { SodaException("해당 원작을 찾을 수 없습니다") }
+    }
+
+    /**
+     * 지정 원작에 속한 활성 캐릭터 페이징 조회 (최신순)
+     */
+    @Transactional(readOnly = true)
+    fun getActiveCharactersPage(originalWorkId: Long, page: Int = 0, size: Int = 20): Page<ChatCharacter> {
+        // 원작 존재 및 소프트 삭제 여부 확인
+        originalWorkRepository.findByIdAndIsDeletedFalse(originalWorkId)
+            .orElseThrow { SodaException("해당 원작을 찾을 수 없습니다") }
+
+        val safePage = if (page < 0) 0 else page
+        val safeSize = when {
+            size <= 0 -> 20
+            size > 50 -> 50
+            else -> size
+        }
+        val pageable = PageRequest.of(safePage, safeSize, Sort.by("createdAt").descending())
+        return chatCharacterRepository.findByOriginalWorkIdAndIsActiveTrue(originalWorkId, pageable)
+    }
+}
--- a/src/main/kotlin/kr/co/vividnext/sodalive/configs/SecurityConfig.kt
+++ b/src/main/kotlin/kr/co/vividnext/sodalive/configs/SecurityConfig.kt
@@ -95,6 +95,7 @@ class SecurityConfig(
            .antMatchers(HttpMethod.GET, "/notice/latest").permitAll()
            .antMatchers(HttpMethod.GET, "/api/chat/character/main").permitAll()
            .antMatchers(HttpMethod.GET, "/api/chat/room/list").permitAll()
+            .antMatchers(HttpMethod.GET, "/api/chat/original/list").permitAll()
            .anyRequest().authenticated()
            .and()
            .build()
Author	SHA1	Message	Date
klaus	b69756ef81	Merge pull request 'test' (#343 ) from test into main Reviewed-on: #343	2025-09-18 19:25:50 +00:00
Klaus	dad517a953	feat(admin-character-list): 캐릭터 검색결과 - 캐릭터 목록과 동일한 내용으로 변경	2025-09-18 19:58:12 +09:00
Klaus	eb2d093b02	feat(admin-character-list): 캐릭터 검색에 페이징 추가	2025-09-18 19:29:34 +09:00
Klaus	67186bba55	feat(original): 원작 - 원천 원작, 원천 원작 링크, 글/그림 작가, 제작사, 태그 추가	2025-09-18 18:04:59 +09:00
klaus	1a3a9149a2	Merge pull request 'test' (#342 ) from test into main Reviewed-on: #342	2025-09-16 06:11:32 +00:00
Klaus	edeecad2ce	feat(original-app): 원작 리스트 - 페이징 추가	2025-09-15 16:00:09 +09:00
Klaus	387f5388d9	feat(original-app): 원작 상세, 캐릭터 리스트 - 원작 상세에 캐릭터 20개 조회 - 지정 원작에 속한 활성 캐릭터 목록 조회 API 추가	2025-09-15 15:32:20 +09:00
Klaus	adcaa0a5fd	fix(original): 캐릭터 수정 - 원작 ID가 0이 들어오면 캐릭터의 원작을 null로 처리한다.	2025-09-15 06:43:40 +09:00
Klaus	47b2c1cb93	fix(original): 캐릭터 수정 - 원작 ID가 0이 들어오면 캐릭터의 원작을 null로 처리한다.	2025-09-15 06:17:55 +09:00
klaus	ce120a6d5d	Merge pull request 'test' (#341 ) from test into main Reviewed-on: #341	2025-09-14 20:33:50 +00:00
Klaus	7f3589dcfb	fix(original): 인기 캐릭터 조회 - 캐시 키 변경	2025-09-15 05:20:46 +09:00
Klaus	b134c28c10	feat(original): 관리자 캐릭터 상세 조회 - 원작 데이터 추가	2025-09-15 05:18:01 +09:00
Klaus	41c8d0367d	feat(original): 원작별 캐릭터 조회 API 추가	2025-09-15 00:31:14 +09:00
Klaus	3b148d549e	feat(original-app): 앱용 원작 목록/상세 API 및 조회 로직 추가 - 공개 목록 API: 미인증 사용자는 19금 비노출, 활성 캐릭터가 1개 이상 연결된 원작만 반환, 총개수+리스트 제공 - 상세 API: 로그인/본인인증 필수, 원작 상세+소속 활성 캐릭터 리스트 반환	2025-09-14 23:27:58 +09:00
Klaus	b6c96af8a2	feat(original): 원작 도메인과 캐릭터를 연결하기 위해 각각 검색 API 추가	2025-09-14 23:00:33 +09:00
Klaus	4904625488	feat(original): 원작 도메인 추가, 관리자 CRUD/연결 API, 소프트 삭제, 서비스 계층 정비 - 원작 엔티티/레포지토리/관리자 API 구축(이미지 S3 업로드 포함) - 캐릭터-원작 연관관계 및 관리자에서 배정/해제 API 제공 - 소프트 삭제(`isDeleted`) 도입 및 조회/수정/배정 로직에서 삭제 항목 필터링 - 컨트롤러-레포지토리 직접 접근 제거, `AdminOriginalWorkService`로 DB 접근 캡슐화 - 캐릭터 등록/수정에서 `originalWorkId` 지원 및 외부 API 업데이트 조건 분리	2025-09-14 22:33:30 +09:00