docs(gift): 수취인 정보 전달 조건을 기록한다

build.gradle.kts

@@ -27,6 +27,7 @@ repositories {
 
 dependencies {
     implementation("org.redisson:redisson-spring-data-27:3.19.2")
+    implementation("org.springframework.boot:spring-boot-starter-actuator")
     implementation("org.springframework.boot:spring-boot-starter-aop")
     implementation("org.springframework.boot:spring-boot-starter-data-jpa")
     implementation("org.springframework.boot:spring-boot-starter-data-redis")

docs/20260914_배포검증readiness및deployment엔드포인트/plan-task.md

@@ -0,0 +1,144 @@
+# OCI Blue/Green 배포 검증 endpoint 구현 계획
+
+| 문서 항목 | 내용 |
+|---|---|
+| 상태 | 구현 완료 |
+| 작성일 | 2026-09-14 |
+| 요구사항 기준 | `docs/20260914_배포검증readiness및deployment엔드포인트/prd.md` |
+| 현재 Phase | Phase 1 배포 검증 endpoint |
+| 현재 활성 Goal | 없음 |
+
+## 목표
+
+배포 스크립트가 애플리케이션 포트에서 readiness를, management 포트에서 readiness와 배포 식별자를 확인할 수 있다.
+
+## 현재 상태
+
+| Phase | 상태 | 완료 Task | 활성/다음 Goal | 차단 또는 남은 조건 |
+|---:|---|---:|---|---|
+| 1 | 완료 | `4/4` | 없음 | 없음 |
+
+## 범위
+
+### 포함
+
+- `spring-boot-starter-actuator` 의존성 추가.
+- `application.yml`(main/test)의 포트·probe·exposure·deployment property 설정.
+- `DeploymentEndpoint` custom Actuator endpoint 구현.
+- `SecurityConfig`의 `/readyz` permitAll 최소 변경.
+- 위 동작을 검증하는 통합 test.
+
+### 제외
+
+- Kubernetes 의존성·설정.
+- 배포 스크립트(`scripts/`, `appspec.yml`) 변경.
+- 신규 추상화/라이브러리, 기존 API 변경.
+
+## 기술적 제약
+
+- 기술 스택: Kotlin 1.6.21, Spring Boot 2.7.14, Gradle Kotlin DSL, JUnit 5.
+- 배포 식별자는 property placeholder만 사용하고 별도 환경변수 파싱·fallback 코드를 만들지 않는다.
+- 응답 필드명은 snake_case 고정(`application_artifact_version`, `config_commit`).
+- 검증: 신규 test 우선 실행 후 `./gradlew test` 전체 회귀(공통 보안·설정 변경이므로 전체 회귀 필요).
+
+## Phase 1 배포 검증 endpoint
+
+**Phase 결과:** readiness와 deployment endpoint가 지정된 포트 경계에 맞게 동작한다.
+
+**선행조건:** 없음.
+
+**Phase 완료 조건:** `P1-T1`~`P1-T4` 완료, `./gradlew test`와 `./gradlew bootJar` 성공 기록.
+
+### 구현 항목
+
+#### Task 1.1 Actuator 의존성과 기본 설정
+
+**Goal 실행 `P1-T1`:** Actuator를 추가하고 포트·exposure·deployment property 계약을 설정에 반영한다.
+
+- **시작 조건:** PRD `DEPLOY-001`, `DEPLOY-002`, `DEPLOY-005`.
+- **완료 증거:** 설정 파일 diff와 애플리케이션 컨텍스트 기동 test 통과.
+- **범위 밖:** endpoint 구현, security 변경.
+
+**Files:**
+
+- Modify: `build.gradle.kts`
+- Modify: `src/main/resources/application.yml`
+- Modify: `src/test/resources/application.yml`
+- Test: `src/test/kotlin/kr/co/vividnext/sodalive/deployment/DeploymentEndpointIntegrationTest.kt`
+- Test: `src/test/kotlin/kr/co/vividnext/sodalive/deployment/DeploymentEndpointInjectedValueIntegrationTest.kt`
+
+- [x] **RED:** `DeploymentEndpointIntegrationTest`에서 management 포트 readiness/deployment 호출 test를 작성했다.
+- [x] **RED 확인:** Actuator 부재로 `Could not resolve placeholder 'local.management.port'` 실패를 확인했다.
+- [x] **GREEN:** `spring-boot-starter-actuator`와 포트·exposure·deployment 설정을 추가했다.
+- [x] **GREEN 확인:** `./gradlew test --tests 'kr.co.vividnext.sodalive.deployment.*'` 통과.
+- [x] **REFACTOR:** deprecated `LocalServerPort` import 정리, `./gradlew ktlintCheck` 성공.
+
+#### Task 1.2 readiness 접근 허용
+
+**Goal 실행 `P1-T2`:** `/readyz`와 management readiness가 인증 없이 200을 반환한다.
+
+- **시작 조건:** `P1-T1` 완료.
+- **완료 증거:** readiness test 통과.
+- **범위 밖:** 기타 endpoint의 security 정책 변경.
+
+**Files:**
+
+- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/configs/SecurityConfig.kt`
+- Test: `src/test/kotlin/kr/co/vividnext/sodalive/deployment/DeploymentEndpointIntegrationTest.kt`
+
+- [x] **RED:** `/readyz` 200 기대 test 작성(`DeploymentEndpointIntegrationTest`).
+- [x] **RED 확인:** Actuator/보안 미적용 상태 실패 확인.
+- [x] **GREEN:** `SecurityConfig`에 `/readyz` permitAll과 `EndpointRequest.toAnyEndpoint()` permitAll 추가.
+- [x] **GREEN 확인:** readiness test 2건 통과.
+- [x] **REFACTOR:** 추가 변경 없음.
+
+#### Task 1.3 deployment custom Actuator endpoint
+
+**Goal 실행 `P1-T3`:** `/actuator/deployment`가 snake_case 배포 식별자를 반환한다.
+
+- **시작 조건:** `P1-T1` 완료.
+- **완료 증거:** 기본값·주입값 test 통과.
+- **범위 밖:** 추가 필드.
+
+**Files:**
+
+- Create: `src/main/kotlin/kr/co/vividnext/sodalive/deployment/DeploymentEndpoint.kt`
+- Test: `src/test/kotlin/kr/co/vividnext/sodalive/deployment/DeploymentEndpointIntegrationTest.kt`
+
+- [x] **RED:** 기본값(`local`, 40자리 zero)과 주입값 검증 test 작성.
+- [x] **RED 확인:** endpoint 미구현 실패 확인.
+- [x] **GREEN:** `@Endpoint(id = "deployment")` + `@ReadOperation` 구현.
+- [x] **GREEN 확인:** 기본값·주입값 test 통과.
+- [x] **REFACTOR:** `./gradlew ktlintCheck` 성공.
+
+#### Task 1.4 포트 접근 경계 검증
+
+**Goal 실행 `P1-T4`:** 애플리케이션 포트에서 `/actuator/deployment`가 노출되지 않음을 검증한다.
+
+- **시작 조건:** `P1-T3` 완료.
+- **완료 증거:** 애플리케이션 포트 접근 test 통과.
+- **범위 밖:** 그 외 경로 노출 정책.
+
+**Files:**
+
+- Test: `src/test/kotlin/kr/co/vividnext/sodalive/deployment/DeploymentEndpointIntegrationTest.kt`
+
+- [x] **RED:** 애플리케이션 포트 접근이 200이 아님을 기대하는 test 작성.
+- [x] **RED 확인:** 초기 404 기대 단정이 `401 UNAUTHORIZED`로 실패함을 확인.
+- [x] **GREEN:** management 포트 분리로 애플리케이션 포트에서는 endpoint가 매핑되지 않고 401로 차단됨을 확인, 단정을 "200 아님 + 배포 식별자 미포함" 계약으로 정정.
+- [x] **GREEN 확인:** 해당 test 통과.
+- [x] **REFACTOR:** `./gradlew test` 전체 회귀 성공.
+
+### Phase Gate `P1-GATE`
+
+- [x] `./gradlew test` 성공.
+- [x] `./gradlew bootJar` 성공 및 실행 가능한 JAR 생성 확인.
+
+## 검증 기록
+
+- 2026-09-14 `./gradlew test --tests 'kr.co.vividnext.sodalive.deployment.*'` → RED 5 failed → GREEN 5 passed.
+- 2026-09-14 `./gradlew ktlintCheck` → BUILD SUCCESSFUL.
+- 2026-09-14 `./gradlew test` → BUILD SUCCESSFUL (전체 회귀).
+- 2026-09-14 `./gradlew bootJar` → `build/libs/sodalive-0.0.1-SNAPSHOT.jar`(141MB), `Main-Class: org.springframework.boot.loader.JarLauncher` 확인.
+- 참고: 기존 test 실행에는 `JWT_SECRET` 환경변수가 필요하며 이는 이번 변경 이전부터 동일한 전제다.
+- 참고: 애플리케이션 포트에서 `/actuator/deployment`는 404가 아니라 401로 차단된다. `EndpointRequest` matcher가 management 포트 분리 시 애플리케이션 포트 요청에 매칭되지 않기 때문이며, 노출되지 않는다는 요구는 충족한다.

docs/20260914_배포검증readiness및deployment엔드포인트/prd.md

@@ -0,0 +1,101 @@
+# OCI Blue/Green 배포 검증용 readiness 및 deployment endpoint PRD
+
+## 문서 정보
+
+| 항목 | 내용 |
+|---|---|
+| 문서 상태 | 구현 완료 |
+| 작성일 | 2026-09-14 |
+| 최종 수정일 | 2026-09-14 |
+| 대상 제품 | sodalive server 배포 검증 endpoint |
+| 작성자·결정권자 | 요청 사용자 |
+| 관련 구현 계획 | `docs/20260914_배포검증readiness및deployment엔드포인트/plan-task.md` |
+| 관련 review | 없음 |
+
+## 1. Overview
+
+OCI Blue/Green 배포에서 배포 스크립트가 새로 기동한 인스턴스의 기동 완료 여부와, 실제로 어떤 artifact/config가 올라갔는지를
+HTTP로 확인할 수 있어야 한다. 이를 위해 Spring Boot Actuator의 readiness probe와 배포 식별 정보를 반환하는 custom Actuator
+endpoint를 제공한다.
+
+## 2. Problem Statement
+
+- 현재 프로젝트에는 Actuator 의존성과 health endpoint가 없어 배포 스크립트가 기동 완료를 판정할 방법이 없다.
+- 어떤 artifact 버전과 config commit이 배포되었는지 런타임에서 확인할 수 없다.
+- 모든 요청이 Spring Security의 `anyRequest().authenticated()`로 보호되어 있어 인증 없는 probe 호출이 불가능하다.
+
+해결 판단 기준: 배포 스크립트가 인증 없이 `GET :8080/readyz`로 기동을 판정하고, 운영 전용 포트에서
+`GET :8082/actuator/deployment`로 배포 식별자를 확인할 수 있다.
+
+## 3. Goals
+
+- 애플리케이션 포트(8080)에서 인증 없이 readiness 확인 가능.
+- Management 포트(8082)에서 readiness와 배포 식별 정보 확인 가능.
+- 배포 식별자는 환경변수로 주입하고, 환경변수가 없어도 로컬/테스트 기동이 가능해야 한다.
+
+## 4. Non-Goals
+
+- Kubernetes 관련 의존성·설정 추가.
+- liveness 기반 자동 재기동 정책, 배포 스크립트 자체 변경.
+- health details/components 공개, 신규 추상화 계층 도입.
+
+## 5. 권한
+
+- 인증 주체: 없음(배포 스크립트/로드밸런서).
+- `/readyz`: 애플리케이션 포트에서 인증 없이 허용.
+- `/actuator/**`: management 포트(8082)에서만 노출. 애플리케이션 포트에서는 노출하지 않는다.
+- `/readyz` 응답에는 민감 정보나 배포 식별자를 포함하지 않는다.
+
+## 6. 기능 요구사항
+
+| ID | 상태 | 요구사항 | 수용 기준 | Goal 연결 |
+|---|---|---|---|---|
+| `DEPLOY-001` | 확정 | `spring-boot-starter-actuator` 의존성을 추가한다(중복 추가 금지). | `build.gradle.kts`에 1회만 존재 | `P1-T1` |
+| `DEPLOY-002` | 확정 | 애플리케이션 포트 8080, management 포트 8082로 분리한다. | `application.yml`에 `server.port: 8080`, `management.server.port: 8082` | `P1-T1` |
+| `DEPLOY-003` | 확정 | health probes와 additional path를 활성화해 `/readyz`를 제공한다. | `GET :8080/readyz` → 200 | `P1-T2` |
+| `DEPLOY-004` | 확정 | management 포트에서 readiness를 제공한다. | `GET :8082/actuator/health/readiness` → 200 | `P1-T2` |
+| `DEPLOY-005` | 확정 | web exposure는 `health`, `deployment`만 포함하고 health details/components는 공개하지 않는다. | `management.endpoints.web.exposure.include: health,deployment`, `show-details: never`, `show-components: never` | `P1-T1` |
+| `DEPLOY-006` | 확정 | `DEPLOY_ARTIFACT_VERSION`/`DEPLOY_CONFIG_COMMIT`을 property placeholder로 연결한다. | 환경변수 없으면 `local`, 40자리 zero commit | `P1-T3` |
+| `DEPLOY-007` | 확정 | `/actuator/deployment`를 custom Actuator endpoint로 구현한다. | REST controller가 아닌 `@Endpoint` 구현체 존재 | `P1-T3` |
+| `DEPLOY-008` | 확정 | 응답 필드는 정확히 `application_artifact_version`, `config_commit`이다. | snake_case JSON 검증 test 통과 | `P1-T3` |
+| `DEPLOY-009` | 확정 | 애플리케이션 포트에서 `/actuator/deployment`가 노출되지 않는다. | `GET :8080/actuator/deployment` → 200 아님 | `P1-T4` |
+| `DEPLOY-010` | 확정 | Security 정책 최소 변경으로 readiness가 401/403/redirect 되지 않는다. | `SecurityConfig`에 `/readyz` permitAll 추가 | `P1-T2` |
+
+## 7. API 계약
+
+### 7.1 `GET :8080/readyz`
+
+- 인증 불필요. 응답 body는 Actuator 기본 health 응답(`{"status":"UP"}`), 세부 정보 비공개.
+
+### 7.2 `GET :8082/actuator/health/readiness`
+
+- 응답: `{"status":"UP"}`.
+
+### 7.3 `GET :8082/actuator/deployment`
+
+```json
+{
+  "application_artifact_version": "local",
+  "config_commit": "0000000000000000000000000000000000000000"
+}
+```
+
+## 8. 성공 기준
+
+- [x] `GET :8080/readyz`가 200을 반환한다. (`DEPLOY-003`, `DEPLOY-010`)
+- [x] `GET :8082/actuator/health/readiness`가 200을 반환한다. (`DEPLOY-004`)
+- [x] `GET :8082/actuator/deployment`가 주입값을 snake_case JSON으로 반환한다. (`DEPLOY-006`~`DEPLOY-008`)
+- [x] `GET :8080/actuator/deployment`가 200을 반환하지 않는다(401로 차단). (`DEPLOY-009`)
+- [x] `./gradlew test`, `./gradlew bootJar` 성공.
+
+## 9. Open Questions
+
+없음.
+
+## 10. Decision Log
+
+| 날짜 | ID | 상태 | 결정 | 근거 | 영향 요구사항 |
+|---|---|---|---|---|---|
+| 2026-09-14 | `DEC-001` | 확정 | Kubernetes 의존성 없이 Actuator 기본 probe만 사용 | 사용자 요구사항 범위 제한 | `DEPLOY-003`, `DEPLOY-004` |
+| 2026-09-14 | `DEC-002` | 확정 | 배포 식별자는 별도 파싱 코드 없이 Spring property placeholder로만 연결 | 사용자 요구사항, 단순성 유지 | `DEPLOY-006` |
+| 2026-09-14 | `DEC-003` | 확정 | `/actuator/deployment`는 `@Endpoint` 기반 custom Actuator endpoint로 구현 | 사용자 요구사항(REST controller 금지) | `DEPLOY-007` |

docs/20260914_크리에이터_리스너_DM방_생성/plan-task.md

@@ -0,0 +1,388 @@
+# 크리에이터 시작 DM 방 생성 Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use `superpowers:subagent-driven-development` 또는 `superpowers:executing-plans`로 task 단위 구현을 진행한다. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** `POST /api/v2/user-creator-chat/rooms/create`가 기존 리스너 시작 DM 생성과 새 크리에이터 시작 DM 생성을 모두 지원한다.
+
+**Architecture:** 기존 endpoint와 응답 DTO를 유지하고 request DTO만 `recipientId` 중심으로 확장한다. Controller에서 `request.recipientMemberId()`로 단일 상대 회원 ID를 산출하고, 기존 `UserCreatorChatService.createOrGetRoom(member, recipientId)` 흐름과 `validateRecipient` 정책을 재사용한다. 메시지 저장/전달/푸시는 기존 WebSocket 및 메시지 발송 흐름에 맡긴다.
+
+**Tech Stack:** Kotlin, Spring Boot 2.7.14, Java 17, JUnit 5, Mockito, Gradle Wrapper
+
+---
+
+| 문서 항목 | 내용 |
+|---|---|
+| 상태 | 구현 중 |
+| 작성일 | 2026-09-14 |
+| 요구사항 기준 | `docs/20260914_크리에이터_리스너_DM방_생성/prd.md` |
+| API 기준 | PRD §8 |
+| 현재 Phase | Phase 1 |
+| 현재 활성 Goal | 없음 |
+
+## 목표
+
+기존 `creatorId` 요청을 깨지 않으면서 신규 `recipientId` 요청으로 발신자 역할과 무관하게 유저-크리에이터 DM 방을 생성/조회할 수 있게 한다.
+
+## 현재 상태
+
+| Phase | 상태 | 완료 Task | 활성/다음 Goal | 차단 또는 남은 조건 |
+|---:|---|---:|---|---|
+| 1 | 진행 중 | `3/3` | `P1-GATE` | 전체 `./gradlew build`가 `:test` 단계에서 timeout 됨 |
+
+## 범위
+
+### 포함
+
+- `POST /api/v2/user-creator-chat/rooms/create` request DTO 확장
+- `recipientId` 표준 필드 추가
+- 기존 `creatorId` alias 유지
+- `recipientId`/`creatorId` 누락·불일치 validation
+- 기존 방 재사용 및 새 방 생성 회귀 검증
+- `/create`가 메시지를 만들지 않는다는 회귀 검증
+
+### 제외
+
+- 첫 메시지 발송 request 추가
+- WebSocket 프로토콜 변경
+- FCM 푸시 정책 변경
+- DB 스키마 변경
+- 새 endpoint 추가
+- 기존 `creatorId` alias 제거
+
+## 기술적 제약
+
+- 공개 API 응답 `CreateUserCreatorChatRoomResponse(roomId)`는 변경하지 않는다.
+- 신규 클라이언트는 `recipientId`를 사용하지만, 기존 클라이언트의 `creatorId` 요청도 허용한다.
+- `recipientId`와 `creatorId`가 모두 있고 값이 다르면 `common.error.invalid_request`로 거부한다.
+- 권한/상태 검증은 기존 `UserCreatorChatService.validateRecipient` 정책을 재사용한다.
+- 새 공용 abstraction, 새 dependency, DB migration은 만들지 않는다.
+- 구현 Task는 RED → GREEN → REFACTOR 순서로 수행한다.
+
+## 파일 구조 계획
+
+- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/v2/usercreatorchat/dto/UserCreatorChatDtos.kt`
+  - `CreateUserCreatorChatRoomRequest`에 `recipientId` nullable 필드와 기존 `creatorId` nullable alias를 둔다.
+  - 단일 상대 ID 산출 함수를 DTO 내부에 둔다.
+- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/v2/usercreatorchat/controller/UserCreatorChatController.kt`
+  - `request.recipientMemberId()` 결과를 `service.createOrGetRoom(member, recipientId)`에 전달한다.
+- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/v2/usercreatorchat/service/UserCreatorChatService.kt`
+  - 함수 파라미터명만 의미에 맞게 `recipientId`로 바꾸는 것을 검토한다. 동작은 유지한다.
+- Modify: `src/test/kotlin/kr/co/vividnext/sodalive/v2/usercreatorchat/UserCreatorChatServiceTest.kt`
+  - 새 방 생성, 기존 방 재사용, 메시지 미생성, validation 회귀를 검증한다.
+- Modify: `src/test/kotlin/kr/co/vividnext/sodalive/v2/usercreatorchat/UserCreatorChatControllerMappingTest.kt`
+  - request alias 해석 단위 테스트 또는 controller mapping 테스트를 보강한다.
+
+## Phase 1: `/create` request 일반화
+
+**Phase 결과:** 기존 클라이언트와 신규 클라이언트 모두 같은 `/create` endpoint로 DM 방을 생성/조회할 수 있다.
+
+**선행조건:** PRD `DEC-001`~`DEC-003` 확정.
+
+**Phase 완료 조건:** `P1-T1`~`P1-T3`과 `P1-GATE` 완료, 검증 기록 누적.
+
+### 구현 항목
+
+#### Task 1.1 request DTO alias 계약 추가
+
+**Goal 실행 `P1-T1`:** `CreateUserCreatorChatRoomRequest`가 `recipientId`와 기존 `creatorId` alias에서 하나의 상대 회원 ID를 산출한다.
+
+- **시작 조건:** PRD `DMROOM-001~004`, `DEC-003` 확인.
+- **완료 증거:** DTO/Controller focused test 통과와 request 계약 문서 일치.
+- **범위 밖:** 방 생성 repository 동작 변경, 메시지 발송.
+
+**Files:**
+
+- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/v2/usercreatorchat/dto/UserCreatorChatDtos.kt`
+- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/v2/usercreatorchat/controller/UserCreatorChatController.kt`
+- Modify: `src/test/kotlin/kr/co/vividnext/sodalive/v2/usercreatorchat/UserCreatorChatControllerMappingTest.kt`
+
+**Interfaces:**
+
+- Consumes: request JSON `{ "recipientId": Long? }`, `{ "creatorId": Long? }`
+- Produces: `CreateUserCreatorChatRoomRequest.recipientMemberId(): Long`
+
+- [x] **RED:** `UserCreatorChatControllerMappingTest`에 `recipientId`만 보낸 요청이 service에 해당 ID를 전달하는 실패 테스트를 작성한다.
+
+```kotlin
+@Test
+fun shouldCreateRoomWithRecipientId() {
+    val service = Mockito.mock(UserCreatorChatService::class.java)
+    val controller = UserCreatorChatController(service)
+    val member = Member(email = "creator@test.com", password = "pw", nickname = "creator")
+    member.id = 10L
+    Mockito.`when`(service.createOrGetRoom(member, 20L))
+        .thenReturn(CreateUserCreatorChatRoomResponse(roomId = 30L))
+
+    val response = controller.createOrGetRoom(
+        member,
+        CreateUserCreatorChatRoomRequest(recipientId = 20L, creatorId = null)
+    )
+
+    Mockito.verify(service).createOrGetRoom(member, 20L)
+    assertEquals(30L, response.data!!.roomId)
+}
+```
+
+- [x] **RED:** 기존 `creatorId`만 보낸 요청도 service에 해당 ID를 전달하는 실패 테스트를 작성한다.
+
+```kotlin
+@Test
+fun shouldCreateRoomWithLegacyCreatorId() {
+    val request = CreateUserCreatorChatRoomRequest(recipientId = null, creatorId = 20L)
+
+    assertEquals(20L, request.recipientMemberId())
+}
+```
+
+- [x] **RED:** 두 필드가 모두 없거나 서로 다르면 `common.error.invalid_request`가 발생하는 실패 테스트를 작성한다.
+
+```kotlin
+@Test
+fun shouldRejectMissingOrConflictingRecipientIds() {
+    val missing = assertThrows(SodaException::class.java) {
+        CreateUserCreatorChatRoomRequest(recipientId = null, creatorId = null).recipientMemberId()
+    }
+    assertEquals("common.error.invalid_request", missing.messageKey)
+
+    val conflict = assertThrows(SodaException::class.java) {
+        CreateUserCreatorChatRoomRequest(recipientId = 20L, creatorId = 21L).recipientMemberId()
+    }
+    assertEquals("common.error.invalid_request", conflict.messageKey)
+}
+```
+
+- [x] **RED 확인:** `./gradlew test --tests kr.co.vividnext.sodalive.v2.usercreatorchat.UserCreatorChatControllerMappingTest`를 실행해 `recipientId` 생성자 파라미터 또는 `recipientMemberId()` 부재로 실패하는 것을 확인한다.
+- [x] **GREEN:** DTO를 최소 확장한다.
+
+```kotlin
+data class CreateUserCreatorChatRoomRequest(
+    val recipientId: Long? = null,
+    val creatorId: Long? = null
+) {
+    fun recipientMemberId(): Long {
+        if (recipientId != null && creatorId != null && recipientId != creatorId) {
+            throw SodaException(messageKey = "common.error.invalid_request")
+        }
+        return recipientId ?: creatorId ?: throw SodaException(messageKey = "common.error.invalid_request")
+    }
+}
+```
+
+- [x] **GREEN:** Controller에서 `request.recipientMemberId()`를 service에 전달한다.
+
+```kotlin
+ApiResponse.ok(service.createOrGetRoom(member, request.recipientMemberId()))
+```
+
+- [x] **GREEN 확인:** 같은 focused test를 다시 실행해 성공을 확인한다.
+- [x] **REFACTOR:** 테스트 helper 중 이번 Task가 만든 중복만 정리하고 `./gradlew ktlintCheck` 결과를 Progress에 기록한다.
+
+#### Task 1.2 service 방 생성 정책 회귀 보강
+
+**Goal 실행 `P1-T2`:** 발신자 역할과 무관하게 기존 수신자 검증, 기존 방 재사용, 메시지 미생성 정책을 유지한다.
+
+- **시작 조건:** `P1-T1` 완료.
+- **완료 증거:** `UserCreatorChatServiceTest` focused test 통과.
+- **범위 밖:** `validateRecipient` 정책 변경, WebSocket 발송 구현.
+
+**Files:**
+
+- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/v2/usercreatorchat/service/UserCreatorChatService.kt`
+- Modify: `src/test/kotlin/kr/co/vividnext/sodalive/v2/usercreatorchat/UserCreatorChatServiceTest.kt`
+
+**Interfaces:**
+
+- Consumes: `createOrGetRoom(member: Member, recipientId: Long)`
+- Produces: `CreateUserCreatorChatRoomResponse(roomId: Long)`
+
+- [x] **RED:** 크리에이터 역할 회원이 일반 회원에게 방을 생성할 수 있는 실패 테스트를 작성한다.
+
+```kotlin
+@Test
+fun shouldCreateRoomWhenCreatorStartsDmToUser() {
+    val creator = member(1L, "creator").apply { role = MemberRole.CREATOR }
+    val user = member(2L, "user")
+    Mockito.`when`(memberRepository.findById(2L)).thenReturn(Optional.of(user))
+    Mockito.`when`(roomRepository.findActiveRoomByParticipantMemberIds(1L, 2L)).thenReturn(null)
+    Mockito.`when`(roomRepository.save(Mockito.any(UserCreatorChatRoom::class.java))).thenReturn(room(10L))
+
+    val response = service.createOrGetRoom(creator, 2L)
+
+    assertEquals(10L, response.roomId)
+    Mockito.verify(participantRepository).save(Mockito.argThat { it.member == creator })
+    Mockito.verify(participantRepository).save(Mockito.argThat { it.member == user })
+    Mockito.verifyNoInteractions(messageRepository)
+}
+```
+
+- [x] **RED:** 기존 활성 방이 있으면 새 방과 메시지를 만들지 않는 회귀 테스트를 작성한다.
+
+```kotlin
+@Test
+fun shouldReturnExistingRoomWithoutCreatingMessage() {
+    val creator = member(1L, "creator").apply { role = MemberRole.CREATOR }
+    val user = member(2L, "user")
+    val existingRoom = room(10L)
+    Mockito.`when`(memberRepository.findById(2L)).thenReturn(Optional.of(user))
+    Mockito.`when`(roomRepository.findActiveRoomByParticipantMemberIds(1L, 2L)).thenReturn(existingRoom)
+
+    val response = service.createOrGetRoom(creator, 2L)
+
+    assertEquals(10L, response.roomId)
+    Mockito.verify(roomRepository, Mockito.never()).save(Mockito.any(UserCreatorChatRoom::class.java))
+    Mockito.verifyNoInteractions(messageRepository)
+}
+```
+
+- [x] **RED 확인:** `./gradlew test --tests kr.co.vividnext.sodalive.v2.usercreatorchat.UserCreatorChatServiceTest`를 실행해 누락된 동작 또는 helper compile 실패를 확인한다.
+- [x] **GREEN:** 필요하면 `createOrGetRoom(member, creatorId)` 파라미터명을 `recipientId`로 변경한다. 함수 내부 로직은 기존 `memberRepository.findById`, `validateRecipient`, `findActiveRoomByParticipantMemberIds`, participant 저장 흐름을 유지한다.
+
+```kotlin
+@Transactional
+fun createOrGetRoom(member: Member, recipientId: Long): CreateUserCreatorChatRoomResponse {
+    val recipient = memberRepository.findById(recipientId).orElseThrow {
+        SodaException(messageKey = "message.error.recipient_not_found")
+    }
+    validateRecipient(member, recipient)
+
+    val existingRoom = roomRepository.findActiveRoomByParticipantMemberIds(member.id!!, recipient.id!!)
+    if (existingRoom != null) {
+        return CreateUserCreatorChatRoomResponse(roomId = existingRoom.id!!)
+    }
+
+    val room = roomRepository.save(UserCreatorChatRoom())
+    participantRepository.save(UserCreatorChatParticipant(room, member))
+    participantRepository.save(UserCreatorChatParticipant(room, recipient))
+    return CreateUserCreatorChatRoomResponse(roomId = room.id!!)
+}
+```
+
+- [x] **GREEN 확인:** 같은 focused test를 다시 실행해 성공을 확인한다.
+- [x] **REFACTOR:** 파라미터명 변경으로 테스트/문서와 의미가 맞는지 확인하고 새 abstraction 없이 종료한다.
+
+#### Task 1.3 통합 회귀 검증 보강
+
+**Goal 실행 `P1-T3`:** 기존 리스너 시작 흐름과 신규 크리에이터 시작 흐름이 통합 환경에서 모두 동작한다.
+
+- **시작 조건:** `P1-T1`, `P1-T2` 완료.
+- **완료 증거:** 통합 테스트와 focused 회귀 명령 통과.
+- **범위 밖:** 전체 메시징 E2E, 푸시 발송 검증.
+
+**Files:**
+
+- Modify: `src/test/kotlin/kr/co/vividnext/sodalive/v2/usercreatorchat/UserCreatorChatServiceIntegrationTest.kt`
+
+- [x] **RED:** 리스너가 `creatorId` alias로 기존처럼 방을 만들 수 있는 통합 회귀 테스트를 작성한다.
+- [x] **RED:** 크리에이터가 일반 회원 ID로 방을 만들 수 있는 통합 테스트를 작성한다.
+- [x] **RED 확인:** `./gradlew test --tests kr.co.vividnext.sodalive.v2.usercreatorchat.UserCreatorChatServiceIntegrationTest`를 실행해 현재 계약 미지원 실패를 확인한다.
+- [x] **GREEN:** `P1-T1`, `P1-T2` 구현만으로 통합 테스트를 통과시킨다. 추가 production 코드를 만들지 않는다.
+- [x] **GREEN 확인:** 같은 통합 테스트를 다시 실행해 성공을 확인한다.
+- [x] **REFACTOR:** 통합 테스트 fixture 중 이번 Task가 만든 중복만 정리한다.
+
+### 완료 조건
+
+- [x] `P1-T1`, `P1-T2`, `P1-T3`의 체크박스와 완료 증거가 모두 충족됐다.
+- [x] PRD `DMROOM-001~007`이 구현 또는 명시적 제외로 추적된다.
+- [x] 기존 `creatorId` 요청과 신규 `recipientId` 요청의 차이가 문서와 테스트에 남아 있다.
+
+### 검증 방법
+
+#### Phase 1 Gate
+
+**Goal 실행 `P1-GATE`:** `/create` request 호환성, 방 생성 정책, 메시지 비생성 정책을 최종 판정한다.
+
+- **시작 조건:** Phase 1의 모든 Task goal 완료.
+- **완료 증거:** 아래 명령 통과와 Progress 기록.
+- **범위 밖:** 실패와 무관한 채팅방 목록, openRoom 응답, WebSocket 기능 수정.
+
+```bash
+./gradlew test --tests kr.co.vividnext.sodalive.v2.usercreatorchat.UserCreatorChatControllerMappingTest
+./gradlew test --tests kr.co.vividnext.sodalive.v2.usercreatorchat.UserCreatorChatServiceTest
+./gradlew test --tests kr.co.vividnext.sodalive.v2.usercreatorchat.UserCreatorChatServiceIntegrationTest
+./gradlew ktlintCheck
+```
+
+**Expected:** 모든 명령이 `BUILD SUCCESSFUL`이고, `/create` 호출만으로 메시지 저장/전달/푸시가 발생하지 않는 테스트가 통과한다.
+
+## 실행 순서와 의존성
+
+| 순서 | Goal | 선행조건 | 병행 가능 | 차단 시 다음 행동 |
+|---:|---|---|---|---|
+| 1 | `P1-T1` | PRD 확정 | 아니요 | request 계약 재확인 |
+| 2 | `P1-T2` | `P1-T1` | 아니요 | 기존 service 정책 대조 |
+| 3 | `P1-T3` | `P1-T1`, `P1-T2` | 아니요 | 통합 fixture 보정 |
+| 4 | `P1-GATE` | Phase 1 Task 전체 | 아니요 | 실패 소유 Task로 회귀 수정 |
+
+```text
+P1-T1 → P1-T2 → P1-T3 → P1-GATE
+```
+
+## 변경 금지 항목
+
+- `/create`에서 메시지를 저장하거나 발송하지 않는다.
+- 기존 `creatorId` request를 제거하지 않는다.
+- `CreateUserCreatorChatRoomResponse` 필드를 바꾸지 않는다.
+- DB schema, WebSocket message type, FCM event 계약을 변경하지 않는다.
+- test를 삭제·skip·완화하지 않는다.
+- 요청 범위 밖 리팩터링과 공용 abstraction을 추가하지 않는다.
+
+## Progress
+
+기존 기록을 삭제하거나 덮어쓰지 않고 실제 실행 결과를 차수별로 누적한다.
+
+### P1-T1 1차 실행 — 2026-09-14
+
+- 상태: 완료
+- 무엇을: `CreateUserCreatorChatRoomRequest`에 `recipientId` 표준 필드와 `creatorId` alias를 추가하고, controller가 `recipientMemberId()` 결과를 service에 전달하도록 구현했다.
+- 왜: `DMROOM-001~004`, `DEC-003` 기준으로 신규 클라이언트와 기존 클라이언트 request를 모두 지원하기 위해서다.
+- 어떻게:
+  - `./gradlew test --tests kr.co.vividnext.sodalive.v2.usercreatorchat.UserCreatorChatControllerMappingTest` — RED 확인, `recipientId` 생성자 파라미터와 `recipientMemberId()` 부재로 `compileTestKotlin` 실패.
+  - `./gradlew test --tests kr.co.vividnext.sodalive.v2.usercreatorchat.UserCreatorChatControllerMappingTest` — GREEN 확인, `BUILD SUCCESSFUL`.
+- 남은 항목: 없음.
+- 다음 행동: `P1-T2` 진행.
+
+### P1-T2 1차 실행 — 2026-09-14
+
+- 상태: 완료
+- 무엇을: 크리에이터 시작 DM 방 생성, 기존 방 재사용, `/create` 메시지 미생성 정책을 `UserCreatorChatServiceTest`로 고정했다. production service는 파라미터명만 `recipientId`로 정리했다.
+- 왜: `DMROOM-005~007`, `DEC-001`, `DEC-002` 기준으로 기존 수신자 검증과 메시지 발송 분리 정책을 유지하기 위해서다.
+- 어떻게:
+  - `./gradlew test --tests kr.co.vividnext.sodalive.v2.usercreatorchat.UserCreatorChatServiceTest` — `BUILD SUCCESSFUL`.
+- 남은 항목: 없음.
+- 다음 행동: `P1-T3` 진행.
+
+### P1-T3 1차 실행 — 2026-09-14
+
+- 상태: 완료
+- 무엇을: 리스너 시작 기존 흐름과 크리에이터 시작 신규 흐름을 `UserCreatorChatServiceIntegrationTest`에 추가했다.
+- 왜: 실제 JPA 통합 환경에서 양방향 방 생성과 메시지 미생성을 확인하기 위해서다.
+- 어떻게:
+  - `./gradlew test --tests kr.co.vividnext.sodalive.v2.usercreatorchat.UserCreatorChatServiceIntegrationTest` — `BUILD SUCCESSFUL`.
+- 남은 항목: 없음.
+- 다음 행동: `P1-GATE` 진행.
+
+### P1-GATE 1차 실행 — 2026-09-14
+
+- 상태: 차단 감사 중
+- 무엇을: Phase 1 focused test와 lint를 검증하고 전체 build를 시도했다.
+- 왜: `/create` request 호환성, 방 생성 정책, 메시지 비생성 정책과 공통 품질 기준을 판정하기 위해서다.
+- 어떻게:
+  - `./gradlew test --tests kr.co.vividnext.sodalive.v2.usercreatorchat.UserCreatorChatControllerMappingTest --tests kr.co.vividnext.sodalive.v2.usercreatorchat.UserCreatorChatServiceTest --tests kr.co.vividnext.sodalive.v2.usercreatorchat.UserCreatorChatServiceIntegrationTest` — `BUILD SUCCESSFUL`.
+  - `./gradlew ktlintCheck` — 최초 import 정렬 오류로 실패 후 수정, 재실행 `BUILD SUCCESSFUL`.
+  - `./gradlew build` — 120초 timeout, 재시도 600초 timeout. 두 번 모두 `:test` 단계에서 종료되지 않아 전체 build 성공 증거는 확보하지 못했다.
+- 남은 항목: 전체 build timeout 원인 분리 또는 별도 승인.
+- 다음 행동: 변경 범위 리뷰와 전체 suite hang 원인 보고.
+
+## Decision Log
+
+| 날짜 | ID | 상태 | 결정 | 근거 | 영향 Goal/문서 |
+|---|---|---|---|---|---|
+| 2026-09-14 | `DEC-001` | 확정 | `/create`는 방 생성/조회만 처리한다. | 사용자 선택 A | `P1-T2`, PRD `DEC-001` |
+| 2026-09-14 | `DEC-002` | 확정 | 수신자는 `MemberRole` 제한 없이 기존 수신자 검증 정책을 따른다. | 사용자 선택 B | `P1-T2`, PRD `DEC-002` |
+| 2026-09-14 | `DEC-003` | 확정 | `recipientId`를 표준 필드로 추가하고 `creatorId` alias를 유지한다. | 기존 클라이언트 호환 필요 | `P1-T1`, PRD `DEC-003` |
+
+## 발견된 문제
+
+| ID | 심각도 | 상태 | 발견 내용 | 영향 Goal | 처리 계획 |
+|---|---|---|---|---|---|
+| 없음 | - | - | - | - | - |

docs/20260914_크리에이터_리스너_DM방_생성/prd.md

@@ -0,0 +1,159 @@
+# PRD: 크리에이터 시작 DM 방 생성
+
+## 문서 정보
+
+| 항목 | 내용 |
+|---|---|
+| 문서 상태 | 구현 기준 확정 |
+| 작성일 | 2026-09-14 |
+| 최종 수정일 | 2026-09-14 |
+| 대상 제품 | 유저-크리에이터 DM |
+| 작성자·결정권자 | 사용자 인터뷰 기준 |
+| 관련 구현 계획 | `docs/20260914_크리에이터_리스너_DM방_생성/plan-task.md` |
+| 관련 review | 없음 |
+
+## 1. Overview
+
+현재 `POST /api/v2/user-creator-chat/rooms/create`는 일반 유저가 크리에이터에게 DM을 시작할 때 방을 생성하거나 기존 방을 반환한다. 이번 요구사항은 같은 DM 도메인에서 크리에이터도 상대 회원에게 먼저 DM 방을 만들 수 있게 하는 것이다.
+
+첫 메시지 저장, 실시간 전달, 푸시는 이번 API에서 처리하지 않는다. 방 생성 후 메시지는 기존 WebSocket 텍스트 발송 또는 기존 메시지 발송 흐름을 사용한다.
+
+## 2. Problem Statement
+
+- 현재 생성 요청 DTO는 `creatorId`만 받기 때문에 API 의미가 “일반 유저가 크리에이터에게 DM 시작”에 고정되어 있다.
+- 크리에이터가 먼저 상대 회원에게 연락하려면 같은 유저-크리에이터 DM 방을 만들 수 있는 서버 계약이 필요하다.
+- 기존 클라이언트는 이미 `creatorId`를 보내고 있으므로, 새 필드만 강제하면 기존 리스너 시작 DM 생성 흐름이 깨진다.
+
+문제 해결 여부는 신규 클라이언트가 `recipientId`로 방을 만들 수 있고, 기존 클라이언트가 `creatorId`로 같은 API를 계속 사용할 수 있는지로 판단한다.
+
+## 3. Goals
+
+- `POST /api/v2/user-creator-chat/rooms/create`가 발신자 역할과 무관하게 상대 회원 ID로 DM 방을 생성하거나 기존 방을 반환한다.
+- 신규 표준 request 필드는 `recipientId`로 한다.
+- 기존 클라이언트 호환을 위해 `creatorId` request 필드는 alias로 유지한다.
+- 기존 리스너 → 크리에이터 방 생성 흐름은 계속 동작한다.
+- 크리에이터 → 상대 회원 방 생성 흐름도 같은 참여자/중복 방 정책을 따른다.
+
+## 4. Non-Goals
+
+- `/create`에서 첫 텍스트 메시지를 저장하거나 발송하지 않는다.
+- `/create`에서 WebSocket 메시지를 대신 보내지 않는다.
+- FCM 푸시 발송 정책은 변경하지 않는다.
+- DB 스키마를 변경하지 않는다.
+- 새 endpoint를 만들지 않는다.
+- 기존 `roomId` 응답 구조를 변경하지 않는다.
+- `creatorId` alias 제거 시점이나 클라이언트 마이그레이션 일정은 이번 범위에서 정하지 않는다.
+
+## 5. Target Users and Permissions
+
+| 사용자 | 목표 | 주요 작업 | 사용 환경 |
+|---|---|---|---|
+| 리스너/일반 유저 | 크리에이터에게 먼저 DM 시작 | 상대 회원 지정 후 방 생성 | 모바일 클라이언트 |
+| 크리에이터 | 상대 회원에게 먼저 DM 시작 | 상대 회원 지정 후 방 생성 | 모바일 클라이언트 |
+
+권한과 거부 조건:
+
+- 인증 주체: 로그인 `Member`
+- 허용 역할: 별도 `MemberRole` 제한 없음
+- 수신자 조건: 활성 회원, AI 캐릭터 아님, 자기 자신 아님, 차단 정책 통과
+- 미인증: 기존처럼 `common.error.bad_credentials`
+- 수신자 없음 또는 AI 캐릭터: 기존 정책에 맞춰 `message.error.recipient_not_found`
+- 비활성 수신자: 기존처럼 `message.error.recipient_inactive`
+- 자기 자신: 기존처럼 `common.error.invalid_request`
+- 상대가 발신자를 차단한 경우: 기존처럼 `message.error.blocked_by_recipient`
+
+## 6. 핵심 사용자 흐름
+
+1. 인증 회원이 DM을 시작할 상대 회원을 선택한다.
+2. 클라이언트는 `POST /api/v2/user-creator-chat/rooms/create`에 `recipientId`를 보낸다.
+3. 서버는 기존 alias인 `creatorId`만 온 요청도 허용한다.
+4. 서버는 발신자와 수신자 사이의 활성 DM 방이 있으면 기존 `roomId`를 반환한다.
+5. 활성 DM 방이 없으면 방과 두 참여자를 생성하고 새 `roomId`를 반환한다.
+6. 클라이언트는 반환된 `roomId`로 기존 방 입장 및 메시지 발송 흐름을 진행한다.
+
+## 7. 기능 요구사항
+
+| ID | 상태 | 요구사항 | 수용 기준 | 계약/Goal 연결 |
+|---|---|---|---|---|
+| `DMROOM-001` | 확정 | `/create`는 `recipientId`를 표준 상대 회원 ID로 받아 방을 생성/조회한다. | `recipientId`만 보낸 요청이 기존 `roomId` 응답을 받는다. | `P1-T1` |
+| `DMROOM-002` | 확정 | 기존 클라이언트 호환을 위해 `creatorId`만 보낸 요청도 계속 허용한다. | 기존 `creatorId` request가 깨지지 않고 동일한 서비스 흐름을 탄다. | `P1-T1` |
+| `DMROOM-003` | 확정 | `recipientId`와 `creatorId`가 모두 없으면 잘못된 요청으로 거부한다. | `common.error.invalid_request`로 실패한다. | `P1-T1` |
+| `DMROOM-004` | 확정 | 두 필드가 모두 있고 값이 다르면 모호한 요청으로 거부한다. | `common.error.invalid_request`로 실패하고 방을 만들지 않는다. | `P1-T1` |
+| `DMROOM-005` | 확정 | 수신자 권한/상태 검증은 기존 `validateRecipient` 정책을 재사용한다. | 비활성, AI 캐릭터, 자기 자신, 차단 관계의 기존 오류 key가 유지된다. | `P1-T2` |
+| `DMROOM-006` | 확정 | 기존 활성 방이 있으면 새 방을 만들지 않고 기존 `roomId`를 반환한다. | 같은 두 회원으로 두 번 호출해도 활성 방은 1개다. | `P1-T2` |
+| `DMROOM-007` | 확정 | `/create`는 첫 메시지 저장/전달/푸시를 수행하지 않는다. | 방 생성 후 `UserCreatorChatMessage`가 생성되지 않는다. | `P1-T2` |
+
+## 8. API 계약
+
+### 8.1 Endpoint
+
+- Method: `POST`
+- Path: `/api/v2/user-creator-chat/rooms/create`
+- Auth: 로그인 회원 필수
+- Success envelope: 기존 `ApiResponse.ok(...)`
+
+### 8.2 Request
+
+```json
+{
+  "recipientId": 200,
+  "creatorId": 200
+}
+```
+
+- `recipientId`: 신규 표준 필드. 발신자 반대편 회원 ID다.
+- `creatorId`: 기존 클라이언트 호환용 alias. 신규 클라이언트는 `recipientId`를 사용한다.
+- 둘 중 하나만 보내는 요청을 허용한다.
+- 둘 다 보내는 경우 값이 같으면 허용한다.
+- 둘 다 보내는 경우 값이 다르면 `common.error.invalid_request`로 거부한다.
+- 둘 다 없으면 `common.error.invalid_request`로 거부한다.
+
+### 8.3 Response
+
+```json
+{
+  "roomId": 123
+}
+```
+
+- 응답 DTO `CreateUserCreatorChatRoomResponse`의 필드는 변경하지 않는다.
+
+## 9. 보안과 데이터 취급
+
+- 수신자 ID는 요청 본문 외 로그에 별도 기록하지 않는다.
+- 차단 정책은 기존 `BlockMemberRepository.isBlocked(blockedMemberId = sender.id, memberId = recipient.id)` 기준을 유지한다.
+- AI 캐릭터용 `Member`와의 DM 방은 계속 생성하지 않는다.
+- 공개 API 스키마에서 기존 필드 제거는 금지한다.
+
+## 10. 성공 기준
+
+- [x] 신규 `recipientId` 요청으로 크리에이터가 상대 회원과 DM 방을 만들 수 있다.
+- [x] 기존 `creatorId` 요청으로 리스너가 크리에이터와 DM 방을 만들 수 있다.
+- [x] 같은 두 회원의 중복 요청은 같은 활성 `roomId`를 반환한다.
+- [x] `/create` 호출만으로 메시지, WebSocket 전달, FCM 푸시가 발생하지 않는다.
+- [x] 오류 key는 기존 정책과 호환된다.
+
+## 11. Open Questions
+
+없음. 인터뷰로 아래 결정을 확정했다.
+
+## 12. 요구사항 추적표
+
+| 요구사항 범위 | 계획 Phase | Goal | 자동 검증 | 수동 검증 |
+|---|---:|---|---|---|
+| `DMROOM-001~004` | 1 | `P1-T1` | `UserCreatorChatControllerMappingTest`, `UserCreatorChatServiceTest` | request alias 계약 대조 |
+| `DMROOM-005~007` | 1 | `P1-T2` | `UserCreatorChatServiceTest`, `UserCreatorChatServiceIntegrationTest` | 기존 메시지 발송 흐름 분리 확인 |
+
+## 13. Decision Log
+
+| 날짜 | ID | 상태 | 결정 | 근거 | 영향 요구사항·계약·Goal |
+|---|---|---|---|---|---|
+| 2026-09-14 | `DEC-001` | 확정 | `/create`는 방 생성/조회만 처리하고 첫 메시지는 발송하지 않는다. | 사용자 선택 A | `DMROOM-007`, `P1-T2` |
+| 2026-09-14 | `DEC-002` | 확정 | 수신자는 `MemberRole`로 제한하지 않고 활성/AI 아님/자기 자신 아님/차단 정책으로 제한한다. | 사용자 선택 B, 기존 `validateRecipient` 정책 | `DMROOM-005`, `P1-T2` |
+| 2026-09-14 | `DEC-003` | 확정 | 신규 표준 필드는 `recipientId`로 하고 기존 `creatorId`는 alias로 유지한다. | 기능 의미는 A가 맞지만 기존 클라이언트 동작 보존 필요 | `DMROOM-001~004`, `P1-T1` |
+
+## 14. 변경 관리
+
+- 코드 구현 전 `plan-task.md`의 체크박스와 Goal 단위를 따른다.
+- 구현 중 API 계약이 바뀌면 이 PRD의 Decision Log를 먼저 갱신한다.
+- 기존 `creatorId` alias를 제거하려면 별도 PRD와 클라이언트 마이그레이션 계획을 작성한다.

docs/20260917_라이브_크리에이터_입장제한/plan-task.md

@@ -0,0 +1,357 @@
+# 라이브 크리에이터 입장 제한 구현 계획
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use `subagent-driven-development` or `executing-plans` to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+| 문서 항목 | 내용 |
+|---|---|
+| 상태 | Phase 1~3 구현 및 검증 완료 |
+| 작성일 | `2026-09-17` |
+| 요구사항 기준 | `docs/20260917_라이브_크리에이터_입장제한/prd.md` |
+| API 기준 | 기존 API 응답 스키마 변경 없음 |
+| 현재 Phase | 완료 |
+| 현재 활성 Goal | 없음 |
+| 다음 Goal | 없음 |
+
+## 목표
+
+다른 크리에이터가 `isAvailableJoinCreator = false` 라이브 방을 볼 수도, 직접 입장할 수도 없게 하고, 입장 가능 성별(`genderRestriction`)도 조회와 입장 경계에서 일관되게 적용한다.
+
+## 현재 상태
+
+| Phase | 상태 | 완료 Task | 활성/다음 Goal | 차단 또는 남은 조건 |
+|---:|---|---:|---|---|
+| 1 | 완료 | `2/2` | 없음 | 없음 |
+| 2 | 완료 | `1/1` | 없음 | 없음 |
+| 3 | 완료 | `2/2` | 없음 | 없음 |
+
+## 범위
+
+### 포함
+
+- `v2` 홈 추천/온에어 라이브 조회의 `isAvailableJoinCreator` 및 `genderRestriction` 필터 누락 보정.
+- `v2` 크리에이터 채널 라이브 탭의 조회자 크리에이터 판정 보정.
+- `/live/room/enter`에서 다른 크리에이터의 제한 방 직접 입장 차단과 기존 성별 입장 차단 회귀 검증.
+- focused test와 직접 영향 회귀 검증.
+- 후속 리뷰 `REV-001`: `/live/room/info/{id}`의 토큰 발급 전 크리에이터·성별 제한 적용.
+- 후속 리뷰 `REV-002`: 채널 소유자 본인의 제한 방 조회를 repository 회귀 테스트로 고정.
+
+### 제외
+
+- 공개 API DTO 필드 추가/삭제.
+- DB schema 변경.
+- 기존 성인/성별/차단/강퇴/비공개/결제 정책 재설계.
+- 관리자용 라이브 조회 정책 변경.
+
+## 기술적 제약
+
+- 기술 스택: Kotlin, Spring Boot 2.7.14, QueryDSL, Gradle Wrapper.
+- 기존 QueryDSL 조건 패턴을 재사용하고 새 abstraction은 만들지 않는다.
+- 크리에이터 제한 조건은 `isViewerCreator && memberId != null`일 때만 적용하며, 방 생성자는 `liveRoom.member.id.eq(memberId)`로 예외 처리한다.
+- 성별 제한 조건은 기존 조회 경로와 같은 정책을 따른다. `Gender.MALE`은 `ALL`, `MALE_ONLY`, `Gender.FEMALE`은 `ALL`, `FEMALE_ONLY`, `Gender.NONE` 또는 비로그인/null 유효 성별은 필터 없음이다.
+- 방 생성자 본인은 성별 제한 조건에서도 `liveRoom.member.id.eq(memberId)`로 예외 처리한다.
+- 모든 production 변경 Task는 `RED → GREEN → REFACTOR` 순서로 진행한다.
+- 공개 API schema 변경은 금지한다.
+
+## Phase 1: 리스트 노출 제한 보정
+
+**Phase 결과:** 다른 크리에이터가 문제 의심 리스트 경로에서 제한 방을 받지 않고, 성별 제한에 맞지 않는 사용자가 v2 홈 추천/온에어 라이브에서 제한 방을 받지 않는다.
+
+**선행조건:** PRD 확정.
+
+**Phase 완료 조건:** `P1-T1`, `P1-T2`, `P1-GATE` 완료 및 검증 기록 누적.
+
+### 구현 항목
+
+#### Task 1.1 v2 홈 추천/온에어 라이브 필터 적용
+
+**Goal 실행 `P1-T1`:** `findLiveRecommendations()` 계열 호출에서 조회자 크리에이터 여부와 유효 성별을 전달하고 QueryDSL 필터를 적용한다.
+
+- **시작 조건:** `LCR-001` 확정.
+- **완료 증거:** 다른 크리에이터가 제한 방을 받지 않고, 성별 제한에 맞지 않는 사용자가 제한 방을 받지 않으며, 방 생성자 본인은 예외인 focused test 통과.
+- **범위 밖:** `/live/room/enter` 입장 차단.
+
+**Files:**
+
+- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/v2/recommendation/port/out/HomeRecommendationQueryPort.kt`
+- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/v2/recommendation/application/HomeRecommendationQueryService.kt`
+- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/v2/recommendation/adapter/out/persistence/DefaultHomeRecommendationQueryRepository.kt`
+- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/v2/api/home/application/HomeRecommendationFacade.kt`
+- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/v2/api/home/live/application/HomeOnAirLiveFacade.kt`
+- Test: repository/service 기존 테스트 위치를 우선 확인하고, 없으면 `src/test/kotlin/kr/co/vividnext/sodalive/v2/recommendation/adapter/out/persistence/DefaultHomeRecommendationQueryRepositoryTest.kt`
+
+**Interfaces:**
+
+- `findLiveRecommendations(offset, limit, memberId, includeAdultLives, isViewerCreator, effectiveViewerGender)` 형태로 파라미터를 추가한다.
+- `isViewerCreator` 기본값은 `false`로 둬 snapshot refresh 등 기존 호출을 보존한다.
+- `effectiveViewerGender` 기본값은 `null`로 둬 비로그인/성별 미설정과 snapshot refresh 등 기존 호출을 보존한다.
+- `HomeRecommendationFacade`와 `HomeOnAirLiveFacade`는 `member.auth?.gender` 우선, 없으면 `member.gender`로 기존 경로와 같은 유효 성별을 계산해 전달한다.
+
+- [x] **RED:** 크리에이터 조회자에게 `isAvailableJoinCreator = false` 라이브가 제외되는 테스트, 성별 제한에 맞지 않는 조회자에게 `genderRestriction` 제한 라이브가 제외되는 테스트, 방 생성자 본인은 포함되는 테스트를 작성한다.
+- [x] **RED 확인:** `./gradlew test --tests '*DefaultHomeRecommendationQueryRepositoryTest'`를 실행해 필터 미구현으로 크리에이터 제한 방 또는 성별 제한 방이 포함되는 assertion 실패를 확인한다.
+- [x] **GREEN:** `HomeRecommendationQueryPort`, `HomeRecommendationQueryService`, `DefaultHomeRecommendationQueryRepository`, `HomeRecommendationFacade`, `HomeOnAirLiveFacade`에 `isViewerCreator`, `effectiveViewerGender` 전달과 조건을 최소 추가한다.
+- [x] **GREEN 확인:** `./gradlew test --tests '*DefaultHomeRecommendationQueryRepositoryTest'`를 다시 실행해 성공을 확인한다.
+- [x] **REFACTOR:** 이번 Task가 만든 중복만 정리하고 `./gradlew ktlintCheck` 및 focused test 결과를 Progress에 기록한다.
+
+#### Task 1.2 v2 크리에이터 채널 라이브 탭 판정 보정
+
+**Goal 실행 `P1-T2`:** 크리에이터 채널 라이브 탭에서 “조회자가 크리에이터인지” 기준으로 제한 방 노출을 막는다.
+
+- **시작 조건:** `LCR-002` 확정.
+- **완료 증거:** 다른 크리에이터는 제한 방을 받지 않고 방 생성자 본인은 받을 수 있는 focused test 통과.
+- **범위 밖:** 크리에이터 채널 홈은 이미 `viewer.role == MemberRole.CREATOR`를 사용하므로 변경하지 않는다.
+
+**Files:**
+
+- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/v2/creator/channel/live/application/CreatorChannelLiveQueryService.kt`
+- Test: 기존 테스트 위치를 우선 확인하고, 없으면 `src/test/kotlin/kr/co/vividnext/sodalive/v2/creator/channel/live/application/CreatorChannelLiveQueryServiceTest.kt`
+
+**Interfaces:**
+
+- `queryPort.findCurrentLive(..., isViewerCreator = viewer.role == MemberRole.CREATOR, ...)`로 전달한다.
+- repository의 기존 `creatorJoinLiveCondition(viewerId, isViewerCreator)`와 본인 예외는 유지한다.
+
+- [x] **RED:** 다른 크리에이터 viewer가 `isAvailableJoinCreator = false` 현재 라이브를 받지 않는 service test를 작성한다.
+- [x] **RED 확인:** `./gradlew test --tests '*CreatorChannelLiveQueryServiceTest'`를 실행해 기존 `viewerId == creatorId` 판정 때문에 제한 방이 반환되는 assertion 실패를 확인한다.
+- [x] **GREEN:** `CreatorChannelLiveQueryService`의 `isViewerCreator` 계산을 `viewer.role == MemberRole.CREATOR`로 변경한다.
+- [x] **GREEN 확인:** 같은 focused test를 다시 실행해 성공을 확인한다.
+- [x] **REFACTOR:** 중복 정리 없이 끝낼 수 있으면 그대로 두고 focused test 및 `./gradlew ktlintCheck` 결과를 Progress에 기록한다.
+
+### 검증 방법
+
+#### Phase 1 Gate
+
+**Goal 실행 `P1-GATE`:** 리스트 노출 제한과 성별 제한 경로가 PRD 요구사항과 일치하는지 판정한다.
+
+- **시작 조건:** `P1-T1`, `P1-T2` 완료.
+- **완료 증거:** 아래 명령 통과와 수동 대조 기록.
+- **범위 밖:** 입장 차단 구현.
+
+```bash
+./gradlew test --tests '*DefaultHomeRecommendationQueryRepositoryTest' --tests '*CreatorChannelLiveQueryServiceTest'
+./gradlew ktlintCheck
+```
+
+**Expected:** focused test와 ktlint가 0 exit code로 종료한다.
+
+수동 대조:
+
+- [x] `HomeFollowingQueryService`와 `CreatorChannelHomeQueryService`의 기존 정상 조건은 변경하지 않았음을 확인한다.
+- [x] `HomeRecommendationFacade.getHomeRecommendations`, `HomeRecommendationFacade.getLives`, `HomeOnAirLiveFacade.getOnAirLives`가 모두 조회자 크리에이터 여부와 유효 성별을 전달함을 확인한다.
+
+## Phase 2: 직접 입장 차단
+
+**Phase 결과:** 다른 크리에이터가 제한 방 ID를 알고 있어도 `/live/room/enter`로 입장할 수 없고, 성별 제한에 맞지 않는 사용자의 직접 입장도 기존 정책대로 차단된다.
+
+**선행조건:** `P1-GATE` 완료.
+
+**Phase 완료 조건:** `P2-T1`, `P2-GATE` 완료 및 검증 기록 누적.
+
+### 구현 항목
+
+#### Task 2.1 `/live/room/enter` 크리에이터 제한 차단 및 성별 제한 회귀 검증
+
+**Goal 실행 `P2-T1`:** `LiveRoomService.enterLive()`에서 다른 크리에이터의 제한 방 입장을 결제/roomInfo 변경 전 차단하고, 기존 성별 제한 입장 차단을 회귀 테스트로 고정한다.
+
+- **시작 조건:** `LCR-003` 확정, `P1-GATE` 완료.
+- **완료 증거:** 다른 크리에이터는 예외, 성별 제한에 맞지 않는 사용자는 `live.room.gender_restricted` 예외, 방 생성자 본인과 일반 유저는 기존 정책 유지 test 통과.
+- **범위 밖:** error envelope schema 변경.
+
+**Files:**
+
+- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/live/room/LiveRoomService.kt`
+- Test: 기존 테스트 위치를 우선 확인하고, 없으면 `src/test/kotlin/kr/co/vividnext/sodalive/live/room/LiveRoomServiceTest.kt`
+- Optional Modify: 메시지 key 추가가 필요하다고 확인될 때만 `src/main/resources/messages*.properties` 계열 파일
+
+**Implementation rule:**
+
+`enterLive()`에서 room 조회 후, 결제나 `LiveRoomInfo` 변경 전에 아래 의미의 조건을 추가한다.
+
+```kotlin
+if (
+    member.role == MemberRole.CREATOR &&
+    room.member!!.id!! != member.id!! &&
+    !room.isAvailableJoinCreator
+) {
+    throw SodaException(messageKey = "live.room.not_found")
+}
+```
+
+기존 message key 재사용이 부적절하다고 확인되면 PRD와 plan-task를 먼저 갱신한 뒤 새 message key를 추가한다.
+
+성별 제한은 현재 구현된 아래 의미의 조건을 유지한다. 이 작업에서는 해당 조건을 약화하지 말고 회귀 테스트로 고정한다.
+
+```kotlin
+if (room.member!!.id!! != member.id!! && !member.canEnter(room.genderRestriction)) {
+    throw SodaException(messageKey = "live.room.gender_restricted")
+}
+```
+
+- [x] **RED:** 다른 크리에이터가 `isAvailableJoinCreator = false` 방에 입장하면 예외가 발생하고 `roomInfoRepository.save`와 `canPaymentService.spendCan`이 호출되지 않는 테스트를 작성한다. 성별 제한에 맞지 않는 사용자가 입장하면 `live.room.gender_restricted` 예외가 발생하는 회귀 테스트도 작성한다.
+- [x] **RED 확인:** `./gradlew test --tests '*LiveRoomServiceTest'`를 실행해 기존 구현이 입장을 허용하거나 후속 저장을 호출하는 assertion 실패를 확인한다.
+- [x] **GREEN:** `LiveRoomService.enterLive()`에 최소 조건을 추가한다.
+- [x] **GREEN 확인:** 같은 focused test를 다시 실행해 성공을 확인한다.
+- [x] **REFACTOR:** 방 생성자 본인, 일반 유저, `Gender.NONE` 사용자 회귀 테스트를 함께 실행하고 `./gradlew ktlintCheck` 결과를 Progress에 기록한다.
+
+### 검증 방법
+
+#### Phase 2 Gate
+
+**Goal 실행 `P2-GATE`:** 입장 차단, 리스트 노출 차단, 성별 제한 전체 흐름을 최종 판정한다.
+
+- **시작 조건:** `P2-T1` 완료.
+- **완료 증거:** 아래 명령 통과와 계획 문서 Progress 기록.
+- **범위 밖:** 실패 test 삭제·완화, 무관한 리팩터링.
+
+```bash
+./gradlew test --tests '*DefaultHomeRecommendationQueryRepositoryTest' --tests '*CreatorChannelLiveQueryServiceTest' --tests '*LiveRoomServiceTest'
+./gradlew ktlintCheck
+./gradlew test
+```
+
+**Expected:** focused test, ktlint, 전체 test가 0 exit code로 종료한다. 크리에이터 제한과 성별 제한이 모두 조회/입장 경계에서 검증된다. 전체 test가 환경 문제로 실패하면 실패 원인과 focused/영향 범위 대체 검증을 Progress에 기록한다.
+
+## Phase 3: 후속 리뷰 항목 구현
+
+**근거:** `reviews/현재변경사항-review.md`의 `REV-001`, `REV-002` 및 두 항목을 후속 구현사항으로 추가하라는 사용자 요청.
+
+**Phase 결과:** 제한 사용자는 방 정보 API로 토큰을 발급받지 못하고, 채널 소유자 본인의 제한 방 조회는 실제 repository 테스트로 보장된다.
+
+**선행조건:** Phase 1~2 완료 및 후속 리뷰 확인. 기존 완료 체크박스와 검증 기록은 유지한다.
+
+**Phase 완료 조건:** `P3-T1`, `P3-T2`, `P3-GATE` 완료와 실행 증거 기록.
+
+### Task 3.1 토큰 발급 경계의 입장 제한 보강
+
+- [x] **Task 3.1 완료**
+
+**Goal 실행 `P3-T1`:** `REV-001`에 따라 `getRoomInfo()`에서 토큰 생성 전에 크리에이터·성별 제한을 적용하고 허용 사용자 회귀를 검증한다.
+
+- **시작 조건:** `REV-001`의 제한 검사 누락 확인. 실제 RTC 우회 접속은 아직 재현되지 않았으므로 서버의 토큰 생성 호출 여부부터 검증한다.
+- **완료 증거:** 제한 사용자에 대한 실패 테스트 → 최소 수정 후 예외 key 및 RTC/RTM 생성기 무호출 검증 → 소유자·허용 사용자 회귀 통과.
+- **범위 밖:** 새로운 입장 완료 여부 검사, 성인/비공개/결제 정책 재설계, 기존 발급 토큰 회수, Agora SDK 변경, API/DB 스키마 변경.
+
+**Files:**
+
+- Modify: `docs/20260917_라이브_크리에이터_입장제한/prd.md` — LCR-003 및 성공 기준에 방 정보 API의 토큰 발급 경계를 명시.
+- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/live/room/LiveRoomService.kt` — `getRoomInfo()`.
+- Test: `src/test/kotlin/kr/co/vividnext/sodalive/live/room/LiveRoomServiceTest.kt`.
+- Read: `src/main/kotlin/kr/co/vividnext/sodalive/live/room/LiveRoomController.kt`, `src/main/kotlin/kr/co/vividnext/sodalive/member/Member.kt`.
+
+**구현 기준:** 기존 방/roomInfo 존재 및 상호 차단 검사를 유지하고 첫 토큰 생성 호출 전에 `/enter`와 동일한 조건을 적용한다. 다른 크리에이터의 제한 방 접근은 `live.room.not_found`, 다른 사용자의 성별 불일치는 `live.room.gender_restricted`로 거절한다. 두 제한이 겹치면 크리에이터 제한을 먼저 판정한다. 생성자는 두 제한의 예외이며 성별은 `Member.canEnter()`를 재사용해 인증 성별 우선 및 `Gender.NONE` 허용 정책을 유지한다. RTC, RTM, v2v 토큰 모두 제한 검사를 통과한 뒤에만 생성한다.
+
+- [x] **문서 정합성:** production 수정 전에 기존 PRD의 LCR-003, 관련 흐름·성공 기준에 토큰 발급 제한을 반영하고 후속 검증 항목은 미완료로 둔다.
+- [x] **RED:** roomInfo와 room이 존재하고 차단 관계가 없는 fixture에서 다른 크리에이터의 제한 방 접근 및 성별 불일치 접근을 테스트한다. 토큰 생성기는 테스트용 문자열을 반환하도록 준비하고 정상 응답 구성에 필요한 의존성도 설정해, 무관한 null 오류가 아닌 예상 예외 미발생으로 실패하는지 확인한다.
+- [x] **GREEN:** 위 조건을 최소 추가하고 예외 key, `rtcTokenBuilder`와 `rtmTokenBuilder`의 무호출을 검증한다. `/enter` 거절 후 `/info/{id}`에 해당하는 서비스 호출도 토큰을 생성하지 않는지 확인한다.
+- [x] **회귀:** 소유자는 크리에이터·성별 제한이 모두 걸려도 허용되고, 일반 사용자와 허용 방의 다른 크리에이터는 성별이 맞으면 응답을 받는다. 인증 성별 우선, `Gender.NONE` 허용, 기존 상호 차단 거절을 확인한다.
+- [x] **REFACTOR/기록:** 불필요한 추상화 없이 기존 스타일을 유지하고 아래 명령의 결과와 무엇을/왜/어떻게 검증했는지를 이 Task 아래에 누적한다.
+
+```bash
+./gradlew test --tests '*LiveRoomServiceTest' --tests '*LiveRoomServiceAdultVisibilityPolicyTest'
+```
+
+**Expected:** RED 단계는 제한 검사 누락으로 실패하고, GREEN 이후는 exit 0. 차단 경로에서는 토큰이 생성되지 않는다.
+
+**검증 기록 (2026-09-17):** `LiveRoomServiceTest`에 정상 응답 fixture와 제한·허용 회귀 10건을 추가했다. RED에서 다른 크리에이터, 성별 불일치, 중첩 제한, `/enter` 거절 후 정보 조회 테스트가 모두 예상 `SodaException` 미발생으로 실패했다. `getRoomInfo()`의 기존 상호 차단 검사 뒤와 모든 RTC/RTM/v2v 토큰 생성 앞에 `/enter`와 동일한 크리에이터·성별 조건을 추가한 뒤 `./gradlew test --rerun-tasks --tests '*LiveRoomServiceTest' --tests '*LiveRoomServiceAdultVisibilityPolicyTest'`가 20건 모두 통과하며 `BUILD SUCCESSFUL`로 종료했다. 거절 경로의 token builder 무호출과 소유자·성별 일치 사용자·허용 방 크리에이터·인증 성별 우선·`Gender.NONE`·기존 상호 차단 회귀를 확인했다. 실제 HTTP/RTC 연결은 검증하지 않았다. P3-T1 리뷰 결과 Blocker는 0건이다.
+
+### Task 3.2 채널 소유자 제한 방 조회 회귀 테스트
+
+- [x] **Task 3.2 완료**
+
+**Goal 실행 `P3-T2`:** `REV-002`에 따라 채널 소유자 본인이 `isAvailableJoinCreator = false`인 현재 방을 조회할 수 있음을 H2 repository 테스트로 고정한다.
+
+- **시작 조건:** `REV-002` 확인. 기본 실행 순서는 `P3-T1` 이후이며 파일 변경은 독립적이다.
+- **완료 증거:** 실제 repository의 `findCurrentLive()` 결과가 생성한 제한 방 ID와 일치하고 기존 타인 필터 테스트도 통과한다.
+- **범위 밖:** production 조회 조건 수정, 채널 API/DTO 변경, 조회 정책 재설계.
+
+**Files:**
+
+- Test: `src/test/kotlin/kr/co/vividnext/sodalive/v2/creator/channel/live/adapter/out/persistence/DefaultCreatorChannelLiveQueryRepositoryTest.kt`.
+- Read: `src/main/kotlin/kr/co/vividnext/sodalive/v2/creator/channel/live/adapter/out/persistence/DefaultCreatorChannelLiveQueryRepository.kt`.
+
+**TDD 예외 사유:** 소유자 예외는 이미 구현돼 있고 이번 Task는 누락된 테스트만 추가한다. RED를 만들기 위해 정상 production 코드를 변경하지 않는다. 대체 검증은 실제 H2 조회 결과 assertion과 기존 타인 제외 테스트의 동시 통과다.
+
+- [x] **테스트 추가:** 기존 fixture로 활성·비성인·유효 channelName의 현재 방을 생성하고 `isAvailableJoinCreator = false`로 설정한다. `flushAndClear()` 후 `viewerId == creatorId`, `isViewerCreator = true`, 성별 제한과 일치하는 유효 성별로 조회해 방 ID를 단정한다.
+- [x] **GREEN:** 아래 focused test로 소유자 조회와 기존 타인 제외 동작이 함께 통과하는지 확인한다.
+- [x] **REFACTOR/기록:** 기존 fixture를 재사용하고 이 Task 아래에 명령과 검증 결과를 누적한다. 예상 밖 실패는 원인을 판정한 뒤 production 수정이 필요하면 먼저 Task 범위를 갱신한다.
+
+```bash
+./gradlew test --tests '*DefaultCreatorChannelLiveQueryRepositoryTest' --tests '*CreatorChannelLiveQueryServiceTest'
+```
+
+**Expected:** exit 0. 소유자에게 제한 방이 반환되고 다른 크리에이터에게는 기존대로 제외된다.
+
+**검증 기록 (2026-09-17):** production 조건은 변경하지 않고 `DefaultCreatorChannelLiveQueryRepositoryTest.shouldReturnRestrictedCurrentLiveForChannelOwner`를 추가했다. 활성·비성인·유효 channelName·`isAvailableJoinCreator = false`·`MALE_ONLY` 방을 실제 H2에 저장하고 `viewerId == creatorId`, `isViewerCreator = true`, `Gender.MALE`로 조회해 생성한 방 ID를 단정했다. `./gradlew test --rerun-tasks --tests '*DefaultCreatorChannelLiveQueryRepositoryTest' --tests '*CreatorChannelLiveQueryServiceTest'`가 기존 다른 크리에이터 제외 테스트와 함께 `BUILD SUCCESSFUL`로 종료했다. `git diff --check`도 통과했다.
+
+### Phase 3 Gate
+
+**Goal 실행 `P3-GATE`:** 후속 두 항목과 기존 목록·입장 정책의 회귀 검증을 완료한다.
+
+- **시작 조건:** `P3-T1`, `P3-T2` 완료.
+- **완료 증거:** 아래 명령 exit 0, 토큰 생성 전 제한 검사 수동 대조, 소유자 조회 assertion 확인, PRD·리뷰·계획의 상태 및 검증 기록 갱신.
+- **범위 밖:** 실제 RTC 접속을 검증하지 않고 검증했다고 기록하는 행위, 무관한 리팩터링.
+
+```bash
+./gradlew test --tests '*LiveRoomServiceTest' --tests '*LiveRoomServiceAdultVisibilityPolicyTest' --tests '*DefaultCreatorChannelLiveQueryRepositoryTest' --tests '*CreatorChannelLiveQueryServiceTest' --tests '*DefaultHomeRecommendationQueryRepositoryTest'
+./gradlew ktlintCheck
+./gradlew tasks --all
+```
+
+- [x] 위 명령을 실행하고 각 Task의 완료 증거를 대조한다.
+- [x] 실제 HTTP/RTC 연결 검증 여부와 환경 한계를 별도로 기록한다. 서비스 테스트 통과를 실제 RTC 접속 검증으로 간주하지 않는다.
+- [x] 전체 회귀는 공통 인증·예외·설정까지 변경하거나 focused test로 영향 범위를 판단할 수 없는 경우 또는 사용자 요청 시 실행한다. 생략 시 이유와 위 대체 회귀 명령을 Progress에 남긴다.
+- [x] `reviews/현재변경사항-review.md`에 수정 후 검증을 누적하고, PRD의 후속 성공 기준 및 Phase 3 상태를 실제 결과에 맞춰 갱신한다.
+
+## 실행 순서와 의존성
+
+| 순서 | Goal | 선행조건 | 병행 가능 | 차단 시 다음 행동 |
+|---:|---|---|---|---|
+| 1 | `P1-T1` | PRD 확정 | 아니요 | 호출부/port signature 대조 후 문서 갱신 |
+| 2 | `P1-T2` | PRD 확정 | 예, `P1-T1`과 파일 충돌 없음 | service test 작성 방식 확정 |
+| 3 | `P1-GATE` | `P1-T1`, `P1-T2` | 아니요 | 실패 소유 Task로 회귀 수정 |
+| 4 | `P2-T1` | `P1-GATE` | 아니요 | 오류 message key 결정 후 문서 갱신 |
+| 5 | `P2-GATE` | `P2-T1` | 아니요 | 실패 소유 Task로 회귀 수정 |
+| 6 | `P3-T1` | `P2-GATE`, `REV-001` | 기본 순차 | 토큰 생성 전 거절 재현과 PRD 정합성 확인 |
+| 7 | `P3-T2` | `REV-002` | `P3-T1`과 파일 독립 | 기존 fixture·현재 방 조건 확인 |
+| 8 | `P3-GATE` | `P3-T1`, `P3-T2` | 아니요 | 실패 소유 Task로 회귀 수정 |
+
+```text
+P1-T1 ─┐
+       ├→ P1-GATE → P2-T1 → P2-GATE
+P1-T2 ─┘
+
+P2-GATE → P3-T1 ─┐
+          P3-T2 ─┴→ P3-GATE
+```
+
+## 변경 금지 항목
+
+- 공개 API 응답 DTO를 변경하지 않는다.
+- `isAvailableJoinCreator`의 DB schema나 기본값을 변경하지 않는다.
+- 기존 성인/성별/차단/강퇴/비공개/결제 조건을 완화하지 않는다.
+- 테스트를 삭제·skip·완화하지 않는다.
+- `as any`, 타입 억제, 불필요한 새 abstraction을 만들지 않는다.
+
+## Progress
+
+- 2026-09-17: PRD와 계획 문서 작성. 구현은 아직 시작하지 않음.
+- 2026-09-17: v2 홈 추천/온에어 라이브의 `genderRestriction` 조회 필터와 `/live/room/enter` 성별 제한 회귀 검증을 PRD/계획에 반영. 구현은 아직 시작하지 않음.
+- 2026-09-17: `P1-T1` RED 확인. 신규 인자 추가 전 `compileTestKotlin`에서 `isViewerCreator`/`effectiveViewerGender` 미정의로 실패했고, 시그니처 연결 후 repository focused test 79건 중 크리에이터 제한 1건과 성별 제한 2건이 assertion 실패했다. facade 전달 전 `HomeRecommendationControllerTest.shouldLogHomeRecommendationPageFailure`도 신규 인자 불일치로 실패했다.
+- 2026-09-17: `P1-T1` GREEN 확인. `./gradlew test --rerun-tasks --tests '*DefaultHomeRecommendationQueryRepositoryTest' --tests '*HomeRecommendationQueryServiceTest' --tests '*HomeRecommendationFacadeTest' --tests '*HomeOnAirLiveFacadeTest'`가 `BUILD SUCCESSFUL`로 종료했다. 컴파일 경고는 기존 deprecated API 및 기존 테스트 경고이며 신규 실패는 없다.
+- 2026-09-17: `P1-T1` REFACTOR 확인. 추가 추상화 없이 기존 QueryDSL 패턴을 재사용했고 `./gradlew ktlintCheck`가 `BUILD SUCCESSFUL`로 종료했다.
+- 2026-09-17: `P1-T2` RED 확인. 다른 ID의 `MemberRole.CREATOR` viewer 테스트에서 `currentLiveIsViewerCreator`가 기대값 `true`, 실제값 `false`로 실패했다.
+- 2026-09-17: `P1-T2` GREEN 확인. `CreatorChannelLiveQueryService`가 `viewer.role == MemberRole.CREATOR`를 전달하도록 최소 수정한 뒤 `./gradlew test --rerun-tasks --tests '*CreatorChannelLiveQueryServiceTest'`가 `BUILD SUCCESSFUL`로 종료했다.
+- 2026-09-17: `P1-T2` REFACTOR 확인. 별도 추상화 없이 기존 역할 enum을 사용했고 `./gradlew ktlintCheck`가 `BUILD SUCCESSFUL`로 종료했다.
+- 2026-09-17: `P1-GATE` 자동 검증. `./gradlew test --rerun-tasks --tests '*DefaultHomeRecommendationQueryRepositoryTest' --tests '*HomeRecommendationQueryServiceTest' --tests '*HomeRecommendationFacadeTest' --tests '*HomeOnAirLiveFacadeTest' --tests '*CreatorChannelLiveQueryServiceTest'`와 `./gradlew ktlintCheck`가 모두 `BUILD SUCCESSFUL`로 종료했다. 출력된 deprecated API 및 unchecked cast 경고는 변경 범위 밖의 기존 경고다.
+- 2026-09-17: `P1-GATE` 수동 대조. `HomeFollowingQueryService`와 `CreatorChannelHomeQueryService`는 변경하지 않았고, 홈 추천·라이브·온에어 facade 세 경로가 조회자 역할과 유효 성별을 전달함을 확인했다.
+- 2026-09-17: `P1-GATE` 리뷰 승인. Phase 1 전체 변경 범위의 PRD/계획 위반과 기존 필터 약화가 없음을 확인했으며 Blocker는 0건이다.
+- 2026-09-17: `P2-T1` RED 확인. 다른 크리에이터의 제한 방 입장 테스트가 `SodaException`을 기대했지만 예외가 발생하지 않아 실패했다.
+- 2026-09-17: `P2-T1` GREEN 확인. `LiveRoomService.enterLive()`의 결제 및 room-info 접근 전에 역할·방 생성자·`isAvailableJoinCreator` 조건을 추가한 뒤 `./gradlew test --rerun-tasks --tests '*LiveRoomServiceTest'`가 5건 모두 통과하며 `BUILD SUCCESSFUL`로 종료했다.
+- 2026-09-17: `P2-T1` REFACTOR 확인. 방 생성자, 일반 사용자, `Gender.NONE`, 성별 불일치 회귀 테스트와 차단 경로의 무부수효과 검증을 유지했고 `./gradlew ktlintCheck`가 `BUILD SUCCESSFUL`로 종료했다.
+- 2026-09-17: `P2-GATE` 자동 검증. `./gradlew test --rerun-tasks --tests '*DefaultHomeRecommendationQueryRepositoryTest' --tests '*CreatorChannelLiveQueryServiceTest' --tests '*LiveRoomServiceTest'`, `./gradlew ktlintCheck`, `./gradlew test --rerun-tasks`가 모두 `BUILD SUCCESSFUL`로 종료했다.
+- 2026-09-17: `P2-GATE` 최종 리뷰 승인. 구현·테스트·문서의 PRD/계획 일치와 API/스키마 유지 여부를 재검토했으며 Blocker는 0건이다.
+- 2026-09-17: 현재 변경사항 후속 리뷰. focused 140건 및 직접 영향 회귀 42건, 총 182건 통과. `./gradlew ktlintCheck tasks --all` 성공(ktlint UP-TO-DATE). 소스 수정 없이 목록·입장 경계 중심의 검토이므로 전체 회귀는 재실행하지 않았다. 명시된 구현 범위는 적합하나, 기존 `/live/room/info/{id}` 토큰 발급 경계의 제한 누락과 채널 소유자 조회 테스트 보완점을 `reviews/현재변경사항-review.md`에 기록했다. 실제 HTTP/RTC 연결은 미검증이며, 제품 전체의 입장 차단 완결성 승인은 보류한다. 기존 완료 기록은 유지한다.
+- 2026-09-17: 사용자 요청에 따라 `REV-001`을 토큰 발급 제한 보강 `P3-T1`, `REV-002`를 채널 소유자 조회 테스트 `P3-T2`로 구체화하고 `P3-GATE`를 추가했다. 파일·조건·예외 key·회귀 시나리오·명령·완료 증거를 명시했으며 기존 Phase 1~2 완료 기록은 유지했다. `./gradlew tasks --all`은 exit 0, `BUILD SUCCESSFUL`; `git diff --check`도 통과했다. 이번 변경은 계획 문서만 갱신하므로 코드 테스트는 실행하지 않았다. 후속 구현은 미착수이며 다음 Goal은 `P3-T1`이다.
+- 2026-09-17: `P3-T1` 시작 전 문서 정합성 완료. PRD의 관련 review, 문제·목표·사용자 흐름, `LCR-003`, API 계약, 보안 기준과 미완료 성공 기준에 `/live/room/info/{id}` 토큰 발급 경계 및 `REV-002` 회귀 검증을 반영했다.
+- 2026-09-17: `P3-GATE` 자동 검증. `./gradlew test --rerun-tasks --tests '*LiveRoomServiceTest' --tests '*LiveRoomServiceAdultVisibilityPolicyTest' --tests '*DefaultCreatorChannelLiveQueryRepositoryTest' --tests '*CreatorChannelLiveQueryServiceTest' --tests '*DefaultHomeRecommendationQueryRepositoryTest'`가 119건, 실패·오류·skip 0으로 `BUILD SUCCESSFUL` 종료했다. `./gradlew ktlintCheck`, `./gradlew tasks --all`, `git diff --check`도 모두 성공했다.
+- 2026-09-17: 토큰 발급 경계는 보안 관련 변경이므로 조건부 전체 회귀를 실행했다. `./gradlew test --rerun-tasks`가 `BUILD SUCCESSFUL`로 종료했다. 실제 HTTP 인증/직렬화 및 Agora RTC/RTM 연결은 환경상 실행하지 않았고, 실제 서비스 메서드 호출과 token builder 무호출 assertion 및 H2 repository 조회를 대체 실행 증거로 사용했다.
+- 2026-09-17: `P3-GATE` 최종 reviewer gate 승인. Phase 3 구현·테스트·PRD·계획·후속 리뷰 해소 기록을 전체 diff 기준으로 검토했으며 Blocker는 0건이다.

docs/20260917_라이브_크리에이터_입장제한/prd.md

@@ -0,0 +1,115 @@
+# 라이브 크리에이터 입장 제한 PRD
+
+## 문서 정보
+
+| 항목 | 내용 |
+|---|---|
+| 문서 상태 | Phase 1~3 구현 및 검증 완료 |
+| 작성일 | `2026-09-17` |
+| 최종 수정일 | `2026-09-17` |
+| 대상 제품 | 라이브 방 목록 노출 및 입장 제한 |
+| 작성자·결정권자 | Sisyphus / 사용자 |
+| 관련 API Contract | 기존 API 응답 스키마 변경 없음 |
+| 관련 구현 계획 | `docs/20260917_라이브_크리에이터_입장제한/plan-task.md` |
+| 관련 review | `reviews/현재변경사항-review.md` (`REV-001`, `REV-002`) |
+
+## 1. Overview
+
+라이브 방 생성자가 `isAvailableJoinCreator = false`로 설정한 방은 다른 크리에이터 계정에게 노출되거나 입장 가능하면 안 된다. 또한 `genderRestriction`으로 입장 가능 성별이 제한된 방은 조회 단계에서도 입장 가능한 사용자에게만 노출돼야 한다. 기존 `/live/room` 계열 조회는 대부분 이 정책을 적용하지만, v2 홈 추천/온에어 라이브와 일부 크리에이터 채널 라이브 경로에서 정책 누락 가능성이 확인됐다. 후속 리뷰에서 `/live/room/info/{id}`가 같은 제한을 확인하지 않고 RTC/RTM 토큰을 발급하는 경로도 확인됐다.
+
+## 2. Problem Statement
+
+- `v2` 홈 추천/온에어 라이브 조회는 `findLiveRecommendations()`에서 조회자의 크리에이터 여부와 유효 성별을 받지 않아 `isAvailableJoinCreator = false`인 방도 크리에이터에게 노출될 수 있고, 성별 제한 방도 입장 불가능한 사용자에게 노출될 수 있다.
+- `v2` 크리에이터 채널 라이브 탭은 조회자가 크리에이터인지가 아니라 조회자가 해당 채널 주인인지로만 `isViewerCreator`를 계산해, 다른 크리에이터에게 제한 방이 노출될 수 있다.
+- `/live/room/enter`는 성인, 비공개, 차단, 강퇴, 성별, 정원, 결제 조건은 확인하지만 크리에이터 입장 제한을 최종 차단하지 않는다.
+- `/live/room/info/{id}`는 방 정보와 상호 차단만 확인한 뒤 RTC/RTM 토큰을 생성하므로 `/enter`에서 거절된 사용자도 토큰 발급을 요청할 수 있다.
+
+문제를 해결했다는 판단은 다른 크리에이터가 `isAvailableJoinCreator = false` 방을 리스트에서 보지 못하고, 성별 제한에 맞지 않는 사용자가 제한 방을 리스트에서 보지 못하며, 직접 `enter` 요청을 보내도 차단되는 것으로 한다.
+
+## 3. Goals
+
+- 다른 크리에이터 계정은 `isAvailableJoinCreator = false` 라이브 방을 문제 의심 경로에서 볼 수 없다.
+- 다른 크리에이터 계정은 `isAvailableJoinCreator = false` 라이브 방에 직접 입장할 수 없다.
+- 입장 가능 성별이 제한된 라이브 방은 성별이 맞는 사용자 또는 방 생성자 본인에게만 조회된다.
+- 입장 가능 성별이 제한된 라이브 방은 성별이 맞는 사용자 또는 방 생성자 본인만 입장할 수 있다.
+- 방을 만든 크리에이터 본인은 예외로 계속 조회 및 입장 가능하다.
+- 제한 사용자는 `/live/room/info/{id}`에서 RTC/RTM/v2v 토큰을 발급받을 수 없다.
+- 기존 응답 DTO와 공개 API 스키마는 변경하지 않는다.
+
+## 4. Non-Goals
+
+- `isAvailableJoinCreator` 필드명, 의미, DB 스키마 변경은 하지 않는다.
+- 일반 유저, 관리자, 봇, 에이전트의 기존 노출/입장 정책은 변경하지 않는다.
+- 기존 성인/성별/차단/강퇴/비공개/결제 정책은 재설계하지 않는다.
+- `Gender.NONE` 사용자의 기존 정책은 변경하지 않는다. 기존 `Member.canEnter()`와 리스트 조건처럼 성별 미설정 사용자는 성별 제한을 통과한다.
+- 새 API endpoint나 새 응답 필드는 만들지 않는다.
+
+## 5. Target Users and Permissions
+
+| 사용자 | 목표 | 정책 |
+|---|---|---|
+| 방 생성 크리에이터 | 본인이 만든 방 조회 및 입장 | `isAvailableJoinCreator = false`여도 허용 |
+| 다른 크리에이터 | 크리에이터 입장 제한 방 접근 방지 | `isAvailableJoinCreator = false`면 목록 미노출 및 입장 차단 |
+| 일반 유저 | 기존 라이브 조회 및 입장 | `genderRestriction`에 맞으면 허용, `Gender.NONE`은 기존처럼 허용 |
+
+## 6. 핵심 사용자 흐름
+
+1. 일반 유저 또는 방 생성자가 `isAvailableJoinCreator = false` 방을 조회하면 기존 정책에 따라 표시된다.
+2. 성별 제한에 맞지 않는 사용자가 `genderRestriction` 제한 방을 v2 홈 추천/온에어 라이브에서 조회하면 표시되지 않는다.
+3. 다른 크리에이터가 같은 방을 v2 홈 추천/온에어 라이브 또는 크리에이터 채널 라이브 경로에서 조회하면 표시되지 않는다.
+4. 성별 제한에 맞지 않는 사용자가 방 ID를 알고 `/live/room/enter`를 호출하면 입장이 거부된다.
+5. 다른 크리에이터가 방 ID를 알고 `/live/room/enter`를 호출하면 입장이 거부된다.
+6. 방 생성 크리에이터가 본인 방에 입장하면 기존처럼 허용된다.
+7. `/enter`에서 거절되는 다른 크리에이터 또는 성별 불일치 사용자가 `/live/room/info/{id}`를 호출하면 토큰 생성 전에 같은 정책으로 거절된다.
+8. 방 생성자, 성별이 맞는 일반 사용자, 크리에이터 입장이 허용된 방의 다른 크리에이터는 기존처럼 방 정보와 토큰을 받는다.
+
+## 7. 기능 요구사항
+
+| ID | 상태 | 요구사항 | 수용 기준 | 계약/Goal 연결 |
+|---|---|---|---|---|
+| `LCR-001` | 확정 | v2 홈 추천/온에어 라이브 조회에서 다른 크리에이터에게 `isAvailableJoinCreator = false` 방을 숨기고, 성별 제한에 맞지 않는 사용자에게 `genderRestriction` 제한 방을 숨긴다. | `HomeRecommendationQueryService.findLiveRecommendations()` 호출 경로가 조회자 크리에이터 여부와 유효 성별을 전달한다. repository는 `liveRoom.isAvailableJoinCreator.isTrue.or(liveRoom.member.id.eq(memberId))`와 `Gender.MALE -> ALL/MALE_ONLY`, `Gender.FEMALE -> ALL/FEMALE_ONLY`, `Gender.NONE/null -> 필터 없음` 조건을 적용한다. | `P1-T1` |
+| `LCR-002` | 확정 | v2 크리에이터 채널 라이브 탭에서 다른 크리에이터에게 제한 방을 숨긴다. | `CreatorChannelLiveQueryService`가 `viewer.role == MemberRole.CREATOR` 기준으로 조회자 크리에이터 여부를 전달한다. 방 생성자 본인은 예외다. | `P1-T2` |
+| `LCR-003` | 확정 | `/live/room/enter`와 `/live/room/info/{id}`에서 다른 크리에이터의 제한 방 입장·토큰 발급과 성별 제한에 맞지 않는 접근을 차단한다. | 다른 크리에이터 제한은 `live.room.not_found`, 성별 제한은 `live.room.gender_restricted`로 결제·입장 상태 변경 또는 RTC/RTM/v2v 토큰 생성 전에 거절한다. 생성자는 예외이며 성별 판정은 `Member.canEnter()`를 재사용한다. | `P2-T1`, `P3-T1` |
+| `LCR-004` | 확정 | 기존 정상 경로는 유지한다. | 일반 유저와 방 생성자 본인의 조회/입장 동작은 유지되고 기존 테스트 또는 신규 회귀 테스트로 확인된다. | `P2-GATE` |
+
+## 8. API 계약
+
+- 변경되는 공개 request/response 필드는 없다.
+- `/live/room/enter`는 기존 오류 envelope를 사용한다.
+- `/live/room/info/{id}`도 기존 오류 envelope와 message key를 재사용하며 응답 필드는 변경하지 않는다.
+- 신규 message key 추가 여부는 구현 단계에서 기존 `live.room.gender_restricted`, `common.error.invalid_request`, `live.room.not_found` 패턴을 확인해 결정한다. 새 key가 필요하면 메시지 리소스와 테스트를 함께 갱신한다.
+
+## 9. 보안과 데이터 취급
+
+- 숨김 정책은 클라이언트 표시만으로 끝내지 않고 서버 입장 경계에서 한 번 더 차단한다.
+- 제한 방 존재 여부를 다른 크리에이터에게 과도하게 노출하지 않는 오류 메시지를 우선한다.
+- 민감정보, 결제 정보, password, token은 로그나 테스트 fixture에 기록하지 않는다.
+- 제한 검사는 RTC, RTM, v2v 토큰 생성 호출보다 먼저 수행한다.
+
+## 10. 성공 기준
+
+- [x] 다른 크리에이터는 `isAvailableJoinCreator = false` 방을 v2 홈 추천/온에어 라이브에서 받지 않는다. (`LCR-001`)
+- [x] 성별 제한에 맞지 않는 사용자는 `genderRestriction` 제한 방을 v2 홈 추천/온에어 라이브에서 받지 않는다. (`LCR-001`)
+- [x] 다른 크리에이터는 `isAvailableJoinCreator = false` 방을 v2 크리에이터 채널 라이브 탭에서 받지 않는다. (`LCR-002`)
+- [x] 다른 크리에이터는 `isAvailableJoinCreator = false` 방에 직접 입장할 수 없다. (`LCR-003`)
+- [x] 성별 제한에 맞지 않는 사용자는 제한 방에 직접 입장할 수 없다. (`LCR-003`)
+- [x] 방 생성 크리에이터 본인은 본인 방을 조회하고 입장할 수 있다. (`LCR-001`~`LCR-003`)
+- [x] 공개 API 스키마 변경 없이 focused test와 영향 범위 회귀가 통과한다.
+- [x] 다른 크리에이터와 성별 불일치 사용자는 `/live/room/info/{id}`에서 토큰 생성 전에 거절되고 토큰 생성기가 호출되지 않는다. (`LCR-003`)
+- [x] 방 생성자, 성별이 맞는 일반 사용자, 크리에이터 입장이 허용된 방의 다른 크리에이터, `Gender.NONE` 사용자는 기존처럼 방 정보와 토큰을 받는다. (`LCR-003`, `LCR-004`)
+- [x] 채널 소유자 본인은 `isAvailableJoinCreator = false`인 현재 방을 repository 조회에서 받는다. (`LCR-002`, `LCR-004`)
+
+## 11. Decision Log
+
+| 일시 | 결정 | 근거 |
+|---|---|---|
+| 2026-09-17 | `isAvailableJoinCreator = false`는 다른 크리에이터만 제한하고 방 생성자 본인은 예외로 둔다. | 기존 QueryDSL 조건들이 `liveRoom.member.id.eq(viewerId)` 예외를 두는 패턴과 사용자 선택 A |
+| 2026-09-17 | 이 작업은 문서가 필요한 구현 작업으로 분류한다. | 저장소 `AGENTS.md`와 `docs/agent-guides/작업절차.md`가 모든 구현 작업 전 PRD와 plan-task를 요구 |
+| 2026-09-17 | v2 홈 추천/온에어 라이브에도 기존 조회 경로와 같은 `genderRestriction` 필터를 적용한다. | `/live/room`, 팔로잉, 크리에이터 채널 조회 경로가 이미 성별 조건을 조회 단계에서 적용하고 있으며 사용자가 문서 반영을 요청 |
+| 2026-09-17 | `/live/room/enter`의 성별 제한은 기존 `Member.canEnter()` 정책을 유지한다. | 현재 `LiveRoomService.enterLive()`가 이미 `room.member.id != member.id && !member.canEnter(room.genderRestriction)`을 차단하고, `Gender.NONE`은 `canEnter()`에서 허용됨 |
+| 2026-09-17 | `/live/room/info/{id}`에서도 `/enter`와 같은 크리에이터·성별 제한을 토큰 생성 전에 적용한다. | `REV-001`에서 `/enter` 거절 후에도 RTC/RTM/v2v 토큰 생성 경로가 열려 있음을 코드로 확인 |
+| 2026-09-17 | 채널 소유자의 제한 방 조회는 production 변경 없이 H2 repository 회귀 테스트로 고정한다. | `REV-002`와 기존 `creatorJoinLiveCondition()`의 소유자 예외 |
+
+## 12. 열린 질문
+
+- 없음. 구현 중 기존 메시지 key 재사용이 부적절하다고 확인되면 plan-task 범위를 먼저 갱신한다.

docs/20260917_라이브_크리에이터_입장제한/reviews/현재변경사항-review.md

@@ -0,0 +1,114 @@
+# 라이브 크리에이터 입장 제한 현재 변경사항 리뷰
+
+## 1. 리뷰 정보
+
+- 일자: 2026-09-17
+- 기준: `62c834d28f0d142e81f2d303273eb1220cab0611` 위의 현재 staged/working tree 변경사항. commit 자체에 대한 승인이 아니다.
+- 소스 diff SHA-256 (`git diff HEAD -- src`): `7b951c79f1575832ac65870a479005909da22e640772c5609a3cbdd983209b98`
+- 기준 문서: `../prd.md`, `../plan-task.md`
+- 범위: LCR-001~004, 변경 production 7개 파일과 관련 테스트, 기존 조회/입장 정책.
+- 상태: 판정 완료. production 및 테스트 코드는 수정하지 않았다.
+
+## 2. 검토 기준 및 근거
+
+- 홈 추천·라이브·온에어의 역할/인증 성별 전달, QueryDSL 필터와 생성자 예외를 대조한다.
+- 크리에이터 채널 라이브의 역할 판정과 기존 repository 조건을 대조한다.
+- 직접 입장 거부가 결제 및 roomInfo 접근보다 먼저 발생하는지 확인한다.
+- 공개 DTO, 일반 사용자, Gender.NONE, 기존 성인/차단/결제 정책의 회귀 여부를 확인한다.
+- `docs/sample/sample-review.md` 기준으로 확정 결함과 검증 한계를 구분한다.
+
+## 3. 검토별 증거 기록
+
+| 검토 | 기준 HEAD | 판정 | 근거 |
+|---|---|---|---|
+| 코드 품질 | `62c834d28f0d142e81f2d303273eb1220cab0611` + 현재 변경 | PASS | `/root/quality`: SQL WHERE 적용 후 페이지네이션, 호출 3곳 인자 전달, 기본값 및 생성자 예외, 부수효과 전 차단 확인. 이전 XML은 이번 실행 증거로 사용하지 않음. |
+| 요구사항 | `62c834d28f0d142e81f2d303273eb1220cab0611` + 현재 변경 | PASS | `/root/requirements`: LCR-001~004 구현 일치. 채널 소유자 조회의 직접 회귀 테스트는 보완 여지 있음. |
+| 주변 문맥 | `62c834d28f0d142e81f2d303273eb1220cab0611` + 현재 변경 | PASS | `/root/context`: 기존 팔로잉·채널 홈 조건 및 Member.canEnter와 일치. 기존 상세 조회의 제한 미검사는 이번 diff 밖임. |
+| 보안 | `62c834d28f0d142e81f2d303273eb1220cab0611` + 현재 변경 | FAIL | `/root/security`: getRoomInfo의 기존 RTC 토큰 발급 경로가 입장 제한을 검사하지 않음. 코드 추적 근거이며 실제 RTC 연결은 미검증. |
+| 자동 QA | `62c834d28f0d142e81f2d303273eb1220cab0611` + 현재 변경 | PASS | `/root/qa`: focused 140건 + 인접 회귀 42건 통과. 실제 HTTP/RTC QA는 INCONCLUSIVE. |
+| 런타임 감사 | `62c834d28f0d142e81f2d303273eb1220cab0611` + 현재 변경 | INCONCLUSIVE | H2 쿼리 결과, 서비스 거부 예외 및 무부수효과 assertion은 실행 확인. 실제 RTC 토큰을 사용한 연결 우회는 실행하지 않음. |
+
+## 4. 실행 검증
+
+환경: macOS, Java 17, Gradle Wrapper, repository 테스트 H2. 전체 회귀 대신 변경 파일 focused test 및 직접 영향받는 기능 회귀를 실행한다. 공개 DTO·공통 인증·설정 변경은 없으며 이 리뷰에서 소스를 수정하지 않아 전체 테스트를 재실행하지 않았다. 기존 계획의 전체 회귀 성공 기록은 이번 실행 결과로 간주하지 않는다.
+
+```bash
+./gradlew test --rerun-tasks --tests '*DefaultHomeRecommendationQueryRepositoryTest' --tests '*CreatorChannelLiveQueryServiceTest' --tests '*LiveRoomServiceTest' --tests '*HomeRecommendationQueryServiceTest' --tests '*HomeRecommendationFacadeTest' --tests '*HomeOnAirLiveFacadeTest'
+```
+
+- `/root/qa` 실행: BUILD SUCCESSFUL, 140건, 실패/오류/skip 0, 3분 19초.
+- `./gradlew ktlintCheck tasks --all`: BUILD SUCCESSFUL. ktlint 작업은 UP-TO-DATE이며 강제 재실행은 하지 않았다.
+- `git diff --check`: exit 0.
+- `./gradlew test --tests '*HomeRecommendationControllerTest' --tests '*DefaultCreatorChannelLiveQueryRepositoryTest' --tests '*HomeOnAirLiveControllerTest' --tests '*LiveRoomServiceAdultVisibilityPolicyTest'`: exit 0, 42건, 실패/오류/skip 0, 41초.
+- 합계: 182건 통과. 추천 repository 81, 추천 service 35, 추천 facade 6, 온에어 facade 4, 채널 service 9, 입장 service 5, 추천 controller 27, 온에어 controller 2, 채널 repository 8, 기존 성인 정책 5.
+- 실제 HTTP/RTC 연결은 미검증. localhost:8080에 실행 중 서버가 없고 운영 데이터·외부 서비스에 연결하지 않았다. 서비스 Mockito 테스트 및 H2 repository 테스트는 입장 거부/조회 필터의 실행 증거이며 실제 RTC 우회 재현 증거는 아니다.
+
+## 5. 발견 사항 및 종료 판정
+
+### REV-001 — 기존 방 정보 API의 토큰 발급 경계에 제한 검사 없음
+
+- 심각도: High. 상태: 제한 검사 누락은 코드로 확정, 실제 RTC 접속 우회는 미검증.
+- 관련 목표: PRD §3의 다른 크리에이터·성별 불일치 사용자의 입장 차단.
+- 이번 diff가 도입한 결함은 아니며, 계획에 명시된 목록 및 `/enter` 수정 범위 밖의 기존 경로다.
+- `LiveRoomController.kt:129`의 `GET /live/room/info/{id}`는 로그인 확인 후 `getRoomInfo()`를 호출한다.
+- `LiveRoomService.kt:972`는 roomInfo·room 존재와 상호 차단만 검사한다. 크리에이터 제한, 성별 제한, 호출자의 입장 완료 여부는 확인하지 않는다.
+- 같은 파일 `:991`부터 RTC 토큰 생성기를 호출하고 `:1065`부터 채널명과 토큰을 응답에 넣는다. `RtcTokenBuilder.kt:83`은 JoinChannel 권한을 추가한다.
+- 확인 시나리오: roomInfo가 존재하는 제한 방에서, 호스트와 차단 관계가 없는 다른 크리에이터가 방 ID로 `/info/{id}`를 요청한다. `/enter`에서 거절됐더라도 이 경로의 토큰 발급 전 제한 검사가 없다.
+- 권장 조치: 토큰 발급 경계에도 생성자 예외를 포함한 크리에이터·성별 제한을 적용하고, 제한 사용자는 토큰 생성기가 호출되지 않는 회귀 테스트로 고정한다. 전체 입장 정책 재설계는 별도 범위다.
+
+### REV-002 — 채널 소유자 조회의 직접 회귀 테스트 보완
+
+- 심각도: Low, 비차단 검증 보완점.
+- `CreatorChannelLiveQueryServiceTest.kt:67`은 다른 크리에이터의 `isViewerCreator` 전달을 검증한다.
+- `DefaultCreatorChannelLiveQueryRepositoryTest.kt:206`은 다른 크리에이터 조회 필터를 검증하지만, 소유자 본인의 제한 방 반환을 직접 검증하지 않는다.
+- 소유자 허용 조건 자체는 `DefaultCreatorChannelLiveQueryRepository.kt:353`에 존재하므로 구현 누락으로 판정하지 않는다.
+- 권장 조치: viewerId == creatorId이고 isAvailableJoinCreator == false인 현재 방이 반환되는 repository 회귀 테스트 1건으로 P1-T2 완료 증거를 보강한다.
+
+## 6. 후속 처리
+
+코드 수정은 수행하지 않았다. 명시된 구현 범위의 기능 결함은 발견하지 못했으나, 제품 전체의 입장 차단 완료 판정에는 REV-001 확인·보강이 필요하다. 구현을 진행할 경우 기존 계획에 토큰 발급 경계 보강 Task를 추가한 뒤 실패 재현 → 최소 수정 → 회귀 검증 순서로 진행한다. 기존 완료 체크박스와 검증 기록은 유지한다.
+
+**종합 판정:** 명시된 목록·`/enter` 구현 범위는 적합하다. 보안 검토 FAIL 및 실제 API/RTC 검증 한계 때문에 제품 전체의 입장 차단에 대한 무조건 승인은 보류한다. 이번 diff에서 새로 도입된 확정 결함은 발견하지 못했다.
+
+**다음 행동:** REV-001의 토큰 발급 경계를 후속 검증·수정 범위로 반영한다.
+
+## 7. Phase 3 후속 구현 검증
+
+- 일자: 2026-09-17
+- 대상: `REV-001`, `REV-002` 후속 구현과 Phase 3 Gate.
+- [x] `REV-001` 해소: `LiveRoomService.getRoomInfo()`가 기존 room/roomInfo 존재 및 상호 차단 검사 뒤, RTC/RTM/v2v 토큰 생성 전에 다른 크리에이터와 성별 불일치 사용자를 각각 `live.room.not_found`, `live.room.gender_restricted`로 거절한다.
+- [x] `REV-001` 회귀: 제한 경로의 token builder 무호출, `/enter` 거절 후 정보 조회 거절, 소유자·성별 일치 사용자·허용 방 크리에이터·인증 성별 우선·`Gender.NONE` 허용, 기존 상호 차단 거절을 서비스 테스트로 확인했다.
+- [x] `REV-002` 해소: 실제 H2 repository 테스트가 채널 소유자에게 `isAvailableJoinCreator = false`인 본인 현재 방 ID를 반환하고, 기존 다른 크리에이터 제외 테스트도 통과했다.
+- [x] Phase 3 focused 회귀: 5개 테스트 클래스 119건이 실패·오류·skip 0으로 통과했다.
+- [x] 품질 및 명령 검증: `./gradlew ktlintCheck`, `./gradlew tasks --all`, `git diff --check`가 성공했다.
+- [x] 전체 회귀: 보안 경계 변경을 반영해 `./gradlew test --rerun-tasks`를 실행했고 `BUILD SUCCESSFUL`로 종료했다.
+- [x] 검증 한계 기록: 실제 HTTP 인증/직렬화 및 Agora RTC/RTM 연결은 실행하지 않았으며 서비스 메서드 호출, token builder 무호출 assertion, 실제 H2 조회를 대체 실행 증거로 사용했다.
+- [x] 최종 reviewer gate: Phase 3 구현·테스트·문서 정합성을 전체 diff 기준으로 재검토했고 Blocker 0건으로 승인됐다.
+
+**후속 판정:** `REV-001`, `REV-002`는 구현 및 회귀 검증으로 해소됐다. 기존 리뷰의 보안 FAIL은 토큰 발급 전 서버 제한 검사 누락 기준에서 해소됐으며, 실제 RTC 연결 검증을 수행했다는 주장은 하지 않는다.
+
+## 8. Phase 1~3 문서·코드 정적 재대조 — 2026-09-17
+
+- 사용자 요청: 전체 자동 테스트는 이미 수행됐으므로 재실행하지 않고 문서와 실제 코드의 스펙 일치 여부를 확인한다.
+- 기준 HEAD: `62c834d28f0d142e81f2d303273eb1220cab0611` 및 현재 staged/working tree 변경.
+- 소스 diff SHA-256 (`git diff HEAD -- src`): `4d90f90b2a262d1ee081c8e9fc78085ce6d04199d9c50a3d5a7506ceaeed0fbe`.
+- 범위: LCR-001~004, P1~P3, REV-001/002, 호출 경로와 테스트 assertion. 이번 검토에서 테스트·애플리케이션은 실행하지 않는다. 기존 실행 성공 기록과 이번 정적 검토 판정은 구분한다.
+
+| 검토 | 정적 판정 | 근거 |
+|---|---|---|
+| 요구사항 | PASS | `/root/spec_v3`: 전체 호출 3곳 역할·성별 전달, 목록 필터 및 생성자 예외, 입장/토큰 발급 전 거절, 채널 소유자 repository assertion까지 LCR-001~004 구현 확인. |
+| 보안 경계 | PASS | `/root/security_v3`: LiveRoomService.kt:986~995 검사 뒤 :1001/:1009/:1016 토큰 생성. 기존 존재·양방향 차단 검사 및 /enter의 결제 전 차단 유지. |
+| 코드 품질 | PASS | `/root/quality_v3`: 모든 호출부 인자 전달, WHERE 필터 후 페이지네이션, 내부 기본값 및 공개 API/DB 스키마 유지. |
+| 테스트 소스 | PASS | `/root/tests_v3`: LiveRoomServiceTest.kt:180~326 제한/허용/우선순위/무호출 assertion, :368 세 토큰 응답 및 호출 횟수, 채널 repository 테스트 :244~266 실제 소유자 방 ID assertion 확인. 실행 QA 판정은 아님. |
+| 문서·주변 정책 | PASS | `/root/context_v3`: Member.canEnter 및 기존 채널 조건과 일치. 이전 FAIL/미착수는 보존된 이력이며 후속 완료 기록으로 해소됨. |
+
+위 판정은 명시된 HEAD와 소스 diff 조합에 한정한다.
+
+**요구사항 대조:**
+
+- LCR-001: 홈 추천·라이브·온에어의 역할/유효 성별 전달과 조회 필터 일치. 생성자 예외와 NONE/null 정책 유지.
+- LCR-002: 채널 조회자의 실제 CREATOR 역할 판정 및 생성자 예외 일치. REV-002의 소유자 H2 테스트 추가 확인.
+- LCR-003: /enter는 결제·상태 변경 전, /info는 모든 토큰 생성 전에 동일 제한 검사. 예외 key·우선순위·생성자 예외·Member.canEnter 재사용 일치. REV-001 해소 확인.
+- LCR-004: 허용 사용자·생성자·인증 성별 우선·Gender.NONE 회귀 assertion 존재. 공개 DTO/DB 스키마 및 기존 제한 조건 유지.
+
+**최종 정적 판정: PASS.** 문서에 명시된 Phase 1~3 구현 및 후속 두 항목의 누락·스펙 위반은 발견하지 못했다. 새 수정 Task로 전환할 확정 항목은 없다. 코드·테스트는 변경하지 않았으며 이 절만 누적했다. 사용자 요청에 따라 테스트와 Gradle 작업을 재실행하지 않고 문서·소스·diff를 대조했다. 전체 자동 테스트 성공은 사용자 확인 및 기존 문서 기록으로 구분하며, 이번에 HTTP/RTC 실행 또는 과거 RED→GREEN을 재검증했다고 주장하지 않는다.

docs/20260917_성인콘텐츠노출정책_Deprecated함수_제거/plan-task.md

@@ -0,0 +1,299 @@
+# 성인 콘텐츠 노출 정책 Deprecated 함수 제거 구현 계획
+
+| 문서 항목 | 내용 |
+|---|---|
+| 상태 | Phase 1~3 완료, P3-R1 구현 완료·실행 검증 대기 |
+| 작성일 | `2026-09-17` |
+| 요구사항 기준 | `docs/20260917_성인콘텐츠노출정책_Deprecated함수_제거/prd.md` |
+| API 기준 | 기존 API 응답 스키마 변경 없음 |
+| 현재 Phase | Phase 3 후속 실행 검증 대기 |
+| 현재 활성 Goal | `P3-R1` 실행 검증 |
+| 다음 Goal | 없음 |
+
+## 목표
+
+`MemberContentPreferencePolicy.isAdultVisibleByPolicy(...)` / `resolveCountryCodeByPolicy(...)` Deprecated 경로를 `MemberContentPreferenceService` 정식 경로로 이전하고, Deprecated 함수와 전용 테스트를 제거한다. 사용자가 확정한 JP 강제 매핑의 `2L` 제거를 제외하고 성인 콘텐츠 노출 판정 결과는 유지한다.
+
+## 현재 상태
+
+| Phase | 상태 | 완료 Task | 활성/다음 Goal | 차단 또는 남은 조건 |
+|---:|---|---:|---|---|
+| 1 | 완료 | `1/1` | 없음 | 없음 |
+| 2 | 완료 | `4/4` | 없음 | 없음 |
+| 3 | 완료 | `1/1` | 없음 | 없음 |
+| 3 후속 | 진행 중 | `0/1` | 활성: `P3-R1` 실행 검증 | 회귀 테스트 구현·소스 검토 완료, 자동 실행 대기 |
+
+## 범위
+
+### 포함
+
+- `MemberContentPreferenceService`에 `isAdultVisibleForQuery(member, isAdultContentVisible)` 추가.
+- production 12개 파일 27곳의 `isAdultVisibleByPolicy(...)` 호출 치환 및 `MemberContentPreferenceService` 생성자 주입.
+- `MemberContentPreferencePolicy.kt`, `MemberContentPreferencePolicyTest.kt` 제거와 고유 검증 이전.
+- 영향 범위 focused test 및 ktlint 검증.
+
+### 제외
+
+- `isAdult` 판정 알고리즘 변경 및 JP 강제 매핑의 `2L` 제거 외 국가 강제 매핑 회원 ID 변경.
+- 각 서비스 public 메서드 시그니처 변경, 공개 API 스키마 변경.
+- `CanController`의 통화 강제 로직.
+
+## 기술적 제약
+
+- 기술 스택: Kotlin, Spring Boot 2.7.14, Gradle Wrapper, ktlint.
+- 신규 abstraction을 만들지 않는다. 기존 `MemberContentPreferenceService`의 `resolveCountryCode` + `calculateIsAdultForQuery`를 재사용한다.
+- `CountryContext`는 `@RequestScope`이므로 마이그레이션 대상은 웹 요청 경로에서만 호출되는 서비스로 한정한다(`RISK-001`).
+- 모든 production 변경 Task는 `RED → GREEN → REFACTOR` 순서로 진행한다.
+- 테스트 실행은 변경 범위 focused test를 우선하고, 전체 회귀는 실행하지 않으며 생략 근거를 검증 기록에 남긴다.
+
+## Phase 1: 정식 경로 단일 진입점 확보
+
+**Phase 결과:** `MemberContentPreferenceService.isAdultVisibleForQuery(...)`가 Deprecated 함수와 동일한 판정을 제공한다.
+
+**선행조건:** PRD 확정.
+
+**Phase 완료 조건:** `P1-T1` 완료 및 검증 기록 누적.
+
+### 구현 항목
+
+#### Task 1.1 `isAdultVisibleForQuery` 추가
+
+**Goal 실행 `P1-T1`:** `MemberContentPreferenceService`에 접속 국가 계산과 성인 노출 판정을 묶은 단일 메서드를 추가한다.
+
+- **시작 조건:** `DEPREM-001` 확정.
+- **완료 증거:** KR + 미인증 → `false`, KR + 인증 → 전달값, 비KR → 전달값, 강제 매핑 회원은 헤더보다 강제 국가 우선인 focused test 통과.
+- **범위 밖:** 호출부 치환.
+
+**Files:**
+
+- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/member/contentpreference/MemberContentPreferenceService.kt`
+- Test: `src/test/kotlin/kr/co/vividnext/sodalive/member/contentpreference/MemberContentPreferenceServiceTest.kt`
+
+**Interfaces:**
+
+- `fun isAdultVisibleForQuery(member: Member, isAdultContentVisible: Boolean): Boolean`
+- 구현은 `calculateIsAdultForQuery(member, resolveCountryCode(member), isAdultContentVisible)`로 한다. DB 조회를 추가하지 않는다.
+
+- [x] **RED:** `MemberContentPreferenceServiceTest`에 `isAdultVisibleForQuery` 판정 테스트 4건(KR 미인증/KR 인증/비KR/강제 매핑)을 작성한다.
+- [x] **RED 확인:** `MemberContentPreferenceServiceTest` 실행 결과 `Unresolved reference: isAdultVisibleForQuery` 컴파일 실패를 확인했다.
+- [x] **GREEN:** `MemberContentPreferenceService`에 `isAdultVisibleForQuery`를 추가했다.
+- [x] **GREEN 확인:** `MemberContentPreferenceServiceTest` 25/25 통과.
+- [x] **REFACTOR:** `resolveCountryCode` + `calculateIsAdultForQuery` 재사용만으로 구현해 중복 계산이 없음을 확인했고 ktlint 통과.
+
+## Phase 2: production 호출부 마이그레이션
+
+**Phase 결과:** production 코드에서 `isAdultVisibleByPolicy(...)` 호출이 0건이 된다.
+
+**선행조건:** Phase 1 완료.
+
+**Phase 완료 조건:** `P2-T1`~`P2-T4`와 `P2-GATE` 완료 및 검증 기록 누적.
+
+### 구현 항목
+
+#### Task 2.1 메인 탭 서비스 7개 치환
+
+**Goal 실행 `P2-T1`:** 콘텐츠 메인 탭 서비스 7개가 `MemberContentPreferenceService`로 성인 노출 여부를 계산한다.
+
+- **시작 조건:** `P1-T1` 완료.
+- **완료 증거:** 7개 파일에서 `isAdultVisibleByPolicy` import/호출 0건, 컴파일 및 영향 범위 테스트 통과.
+- **범위 밖:** `AudioContentService`, `ContentSeriesService`.
+
+**Files:**
+
+- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/content/main/tab/asmr/AudioContentMainTabAsmrService.kt`
+- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/content/main/tab/replay/AudioContentMainTabLiveReplayService.kt`
+- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/content/main/tab/series/AudioContentMainTabSeriesService.kt`
+- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/content/main/tab/alarm/AudioContentMainTabAlarmService.kt`
+- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/content/main/tab/content/AudioContentMainTabContentService.kt`
+- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/content/main/tab/free/AudioContentMainTabFreeService.kt`
+- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/content/main/tab/home/AudioContentMainTabHomeService.kt`
+
+**Interfaces:**
+
+- 각 서비스 생성자에 `private val memberContentPreferenceService: MemberContentPreferenceService`를 추가한다.
+- `isAdultVisibleByPolicy(member, isAdultContentVisible)` → `memberContentPreferenceService.isAdultVisibleForQuery(member, isAdultContentVisible)`.
+- `AudioContentMainTabHomeService`의 nullable member 처리(`member?.let { ... } ?: false`)는 유지한다.
+
+- [x] **RED:** 7개 서비스가 각각 대응 `*Controller`에서만 주입됨을 확인해 `RISK-001` 위반 경로가 없음을 검증했다.
+- [x] **GREEN:** 7개 파일의 호출부와 생성자를 치환했다.
+- [x] **GREEN 확인:** 테스트 컴파일과 `src/test/kotlin/kr/co/vividnext/sodalive/content` 42/42 통과로 확인했다.
+- [x] **REFACTOR:** `isAdultVisibleByPolicy` import를 `MemberContentPreferenceService` import로 교체했고 ktlint 통과.
+
+#### Task 2.2 메인/큐레이션/테마 서비스 치환
+
+**Goal 실행 `P2-T2`:** `AudioContentMainService`, `AudioContentCurationService`, `AudioContentThemeService`를 정식 경로로 치환한다.
+
+- **시작 조건:** `P2-T1` 완료.
+- **완료 증거:** 3개 파일에서 `isAdultVisibleByPolicy` 0건, 컴파일 및 영향 범위 테스트 통과.
+- **범위 밖:** 다른 Task 대상 파일.
+
+**Files:**
+
+- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/content/main/AudioContentMainService.kt`
+- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/content/main/curation/AudioContentCurationService.kt`
+- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/content/theme/AudioContentThemeService.kt`
+
+**Interfaces:**
+
+- `P2-T1`과 동일한 치환 규칙을 적용한다.
+
+- [x] **RED:** 3개 서비스의 치환 대상이 모두 `member`를 받는 웹 조회 메서드임을 확인했다.
+- [x] **GREEN:** 3개 파일을 치환했다.
+- [x] **GREEN 확인:** 테스트 컴파일 성공 및 `content` 패키지 회귀 통과.
+- [x] **REFACTOR:** import 정리 후 ktlint 통과.
+
+#### Task 2.3 `AudioContentService` 치환
+
+**Goal 실행 `P2-T3`:** `AudioContentService`의 3곳을 정식 경로로 치환한다.
+
+- **시작 조건:** `P2-T2` 완료.
+- **완료 증거:** `AudioContentServiceTest`가 갱신된 생성자로 통과한다.
+- **범위 밖:** `ContentSeriesService`.
+
+**Files:**
+
+- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/content/AudioContentService.kt`
+- Modify: `src/test/kotlin/kr/co/vividnext/sodalive/content/AudioContentServiceTest.kt`
+
+**Interfaces:**
+
+- `P2-T1`과 동일한 치환 규칙을 적용하고, 테스트에서는 `MemberContentPreferenceService`를 mock으로 주입한다.
+
+- [x] **RED:** `AudioContentServiceTest.kt:118`에서 `No value passed for parameter 'memberContentPreferenceService'` 컴파일 실패를 확인했다.
+- [x] **GREEN:** `getDetail`, `getLatestCreatorAudioContent`, `getAudioContentList` 3곳을 치환하고 테스트에 mock을 주입했다.
+- [x] **GREEN 확인:** `AudioContentServiceTest` 16/16 통과.
+- [x] **REFACTOR:** import 정리 후 ktlint 통과.
+
+#### Task 2.4 `ContentSeriesService` 치환
+
+**Goal 실행 `P2-T4`:** `ContentSeriesService`의 5곳을 정식 경로로 치환한다.
+
+- **시작 조건:** `P2-T3` 완료.
+- **완료 증거:** 시리즈 관련 영향 범위 테스트 통과, `isAdultVisibleByPolicy` 0건.
+- **범위 밖:** Deprecated 함수 제거.
+
+**Files:**
+
+- Modify: `src/main/kotlin/kr/co/vividnext/sodalive/content/series/ContentSeriesService.kt`
+- Test: 필요 시 `src/test/kotlin/kr/co/vividnext/sodalive/content/series/main/SeriesMainControllerTest.kt` 등 영향 테스트 갱신
+
+**Interfaces:**
+
+- `P2-T1`과 동일한 치환 규칙을 적용한다.
+
+- [x] **RED:** 테스트 컴파일을 실행해 `ContentSeriesService`를 직접 생성하는 테스트가 없어 추가 수정이 필요 없음을 확인했다.
+- [x] **GREEN:** 5곳(`getSeriesList`, `getSeriesListByGenre`, `getSeriesDetail`, `getSeriesContentList`, `getRecommendSeriesList`)을 치환했다.
+- [x] **GREEN 확인:** 테스트 컴파일 성공 및 Spring 컨텍스트 로딩 테스트 통과.
+- [x] **REFACTOR:** import 정리 후 ktlint 통과.
+
+### Phase 2 Gate
+
+**Goal 실행 `P2-GATE`:** production에서 Deprecated 호출이 0건임을 확인한다.
+
+- [x] `isAdultVisibleByPolicy|resolveCountryCodeByPolicy` 검색 결과가 `src/main/kotlin`에서 0건이다.
+- [x] Phase 2 대상 파일의 영향 범위 테스트가 통과한다(`content` 42/42).
+
+## Phase 3: Deprecated 함수 제거와 테스트 정리
+
+**Phase 결과:** Deprecated 함수와 전용 테스트가 제거되고 고유 검증이 정식 경로 테스트에 남는다.
+
+**선행조건:** Phase 2 완료.
+
+**Phase 완료 조건:** `P3-T1`, `P3-GATE` 완료 및 검증 기록 누적.
+
+### 구현 항목
+
+#### Task 3.1 Deprecated 정의 제거와 검증 이전
+
+**Goal 실행 `P3-T1`:** `MemberContentPreferencePolicy.kt`와 `MemberContentPreferencePolicyTest.kt`를 제거하고 고유 검증을 이전한다.
+
+- **시작 조건:** `P2-GATE` 완료.
+- **완료 증거:** 두 파일이 삭제되고 `member/contentpreference` 테스트가 모두 통과한다.
+- **범위 밖:** `MemberContentPreferenceCountryResolver.kt` 변경.
+
+**Files:**
+
+- Delete: `src/main/kotlin/kr/co/vividnext/sodalive/member/contentpreference/MemberContentPreferencePolicy.kt`
+- Delete: `src/test/kotlin/kr/co/vividnext/sodalive/member/contentpreference/MemberContentPreferencePolicyTest.kt`
+- Modify: `src/test/kotlin/kr/co/vividnext/sodalive/member/contentpreference/MemberContentPreferenceServiceTest.kt`
+
+**Interfaces:**
+
+- 이전 대상 검증: 헤더 공백/소문자 정규화(`" us "` → `US`), 국가 컨텍스트 없음 → `KR` fallback, 비KR에서 저장 `countryCode` 무시.
+- 이미 정식 경로 테스트에 존재하는 검증은 중복 추가하지 않는다.
+
+- [x] **RED:** 로그인 회원의 헤더 공백/소문자 정규화와 KR fallback 검증을 `MemberContentPreferenceServiceTest`에 추가했다. 나머지 항목(비로그인 정규화, 저장 `countryCode` 미사용)은 기존 테스트가 이미 커버함을 확인해 중복 추가하지 않았다.
+- [x] **GREEN:** `MemberContentPreferencePolicy.kt`와 `MemberContentPreferencePolicyTest.kt`를 삭제했다.
+- [x] **GREEN 확인:** `member/contentpreference` 36/36 통과.
+- [x] **REFACTOR:** ktlint 통과 및 잔여 참조 0건 확인.
+
+### Phase 3 Gate
+
+**Goal 실행 `P3-GATE`:** 전체 정리 상태를 확인한다.
+
+- [x] `isAdultVisibleByPolicy|resolveCountryCodeByPolicy` 참조가 `src/main/kotlin`, `src/test/kotlin`에서 0건이다.
+- [x] `member/contentpreference` 테스트와 Phase 2 영향 범위 테스트가 통과한다.
+- [x] `./gradlew ktlintMainSourceSetCheck ktlintTestSourceSetCheck`가 통과한다.
+- [x] PRD 성공 기준 체크박스를 갱신했다.
+
+## Phase 3 후속: 리뷰 검증 보강
+
+### Task 3.R1 저장 국가 무시 검증 이전
+
+**Goal 실행 `P3-R1`:** 저장 국가가 KR인 미인증 회원이 US에서 조회할 때 저장 국가를 무시하는 기존 정책을 정식 서비스 테스트로 검증한다.
+
+- **시작 조건:** DEPREM-004 및 `reviews/문서대비구현-review.md`의 REV-002 확정. REV-001은 사용자 확인으로 결함 판정 철회; `2L` 제거 유지.
+- **완료 증거:** 아래 테스트 추가 및 조건·assertion 소스 검토, 후속 실행이 허용된 경우 focused test 결과 기록. 실행하지 않았으면 실행 검증 대기로 남기고 완료 처리하지 않는다.
+- **범위 밖:** production 정책·resolver·매핑 변경, API 변경, 테스트 helper 리팩터링, 전체 회귀 실행.
+- **TDD 예외:** 현재 production은 올바르게 저장 국가를 무시하므로 신규 테스트는 처음부터 통과하는 것이 정상이다. 실패를 만들려고 정상 구현을 변경하지 않는다. 삭제된 테스트와 새 테스트의 입력·assertion 대조로 누락 검증 이전을 확인한다.
+- **실행 제약:** 이번 문서 갱신에서는 테스트를 실행하지 않는다. 기존 자동 테스트 미실행 지시가 유지되는 동안 후속 작업도 소스 검토까지만 진행하고 실행 상태를 별도로 남긴다.
+
+**Files:**
+
+- Modify: `src/test/kotlin/kr/co/vividnext/sodalive/member/contentpreference/MemberContentPreferenceServiceTest.kt`
+- Update: `docs/20260917_성인콘텐츠노출정책_Deprecated함수_제거/plan-task.md`
+- Update: `docs/20260917_성인콘텐츠노출정책_Deprecated함수_제거/reviews/문서대비구현-review.md`
+
+**추가할 테스트:** 기존 `createMember`, `countryContext`, `service`, JUnit import를 재사용한다.
+
+```kotlin
+@Test
+@DisplayName("비KR 요청에서는 회원의 저장 국가와 무관하게 전달한 성인 노출값을 사용한다")
+fun shouldIgnoreStoredCountryCodeWhenRequestCountryIsNotKr() {
+    val member = createMember(id = 2401L, withAuth = false).apply {
+        countryCode = "KR"
+    }
+    countryContext.setCountryCode("US")
+
+    assertEquals("US", service.resolveCountryCode(member))
+    assertTrue(service.isAdultVisibleForQuery(member, isAdultContentVisible = true))
+    assertFalse(service.isAdultVisibleForQuery(member, isAdultContentVisible = false))
+}
+```
+
+- [x] **누락 확인:** 삭제된 정책 테스트와 비교해 저장 KR·요청 US·미인증 조건이 기존 정식 테스트에 없음을 확인했다(TDD 예외 적용).
+- [x] **최소 구현:** 위 테스트 1건만 추가했다. 강제 매핑이 없는 ID 2401을 사용하고 production은 변경하지 않았다.
+- [x] **소스 검토:** 국가 결과 US 및 노출 전달값 true/false 보존 assertion을 확인했다. 저장 국가 KR을 우선하면 국가 assertion과 `true` 전달값 assertion이 실패한다.
+- [ ] **실행 검증:** 자동 테스트 실행이 허용되는 후속 단계에서 아래 focused test와 ktlint를 실행하고 결과를 기록한다. 미실행이면 완료 표시하지 않는다.
+- [x] **기록 갱신:** P3-T1의 기존 완료 기록을 유지하고, REV-002 보강 결과와 실행 대기 상태를 본 Task와 리뷰에 누적했다.
+
+**후속 실행용 명령(이번에는 미실행):** 저장소와 호환되는 JDK 환경에서 실행한다.
+
+```bash
+./gradlew test --tests 'kr.co.vividnext.sodalive.member.contentpreference.MemberContentPreferenceServiceTest'
+./gradlew ktlintTestSourceSetCheck
+```
+
+기대 결과: 신규 테스트를 포함한 서비스 테스트 및 테스트 소스 ktlint 성공. 테스트 한 파일의 검증 보강이므로 전체 회귀는 생략한다.
+
+## 검증 기록
+
+- 2026-09-17 Phase 3 후속 P3-R1: 삭제된 정책 테스트와 현재 서비스 테스트를 대조해 저장 KR·요청 US·미인증 조건의 누락을 확인하고 `MemberContentPreferenceServiceTest.shouldIgnoreStoredCountryCodeWhenRequestCountryIsNotKr` 1건을 추가했다. 국가 결과 US와 전달값 true/false 보존 assertion을 소스로 검토했다. production은 변경하지 않았으며 기존 자동 테스트 미실행 지시에 따라 focused test와 ktlint는 실행하지 않아 Task 완료 처리는 보류했다.
+- 2026-09-17 리뷰 후속 문서 갱신: 사용자가 JP 매핑의 `2L` 제거를 의도한 변경으로 확정했다. REV-002 검증 누락은 `P3-R1`로 추가하고 REV-003 호출 수는 27곳으로 정정했다. 문서와 테스트 소스의 식별자·조건을 대조했으며 사용자 지시에 따라 자동 테스트 및 Gradle 명령은 실행하지 않았다.
+
+- 2026-09-17 Phase 1: `MemberContentPreferenceServiceTest` 실행 → RED에서 `Unresolved reference: isAdultVisibleForQuery` 확인, GREEN 후 25/25 통과. 검증 이유: 신규 판정 메서드가 Deprecated 함수와 동일한 결과를 내는지 확인.
+- 2026-09-17 Phase 2: `AudioContentServiceTest.kt:118` 컴파일 실패로 생성자 변경 영향을 확인한 뒤 mock 주입. `src/test/kotlin/kr/co/vividnext/sodalive/content` 42/42 통과, `AudioContentServiceTest` 16/16 통과.
+- 2026-09-17 Phase 3: `src/test/kotlin/kr/co/vividnext/sodalive/member/contentpreference` 36/36 통과(Deprecated 테스트 5건 삭제, 신규 3건 추가 반영).
+- 2026-09-17 빈 주입 회귀: `SpringBootIntegrationSampleTest` 1/1 통과로 12개 서비스에 추가된 `MemberContentPreferenceService` 주입이 애플리케이션 컨텍스트에서 정상 해석됨을 확인(순환 의존 없음).
+- 2026-09-17 스타일: `JAVA_HOME=<Android Studio JBR 21> ./gradlew ktlintMainSourceSetCheck ktlintTestSourceSetCheck` BUILD SUCCESSFUL. JetBrains JBR 25는 Gradle 8.1.1과 비호환이어서 Java 21 JBR을 사용했다.
+- 2026-09-17 전체 회귀 생략: `./gradlew test` 전체 회귀는 실행하지 않았다. 근거는 변경이 `isAdult` 계산 위임 경로 치환으로 한정되고 공개 스키마/DB/보안 설정 변경이 없으며, 대신 변경 범위 focused test(`content` 42, `member/contentpreference` 36, `AudioContentServiceTest` 16)와 컨텍스트 로딩 테스트, ktlint 전체 소스셋 검사를 실행했다.

docs/20260917_성인콘텐츠노출정책_Deprecated함수_제거/prd.md

@@ -0,0 +1,132 @@
+# 성인 콘텐츠 노출 정책 Deprecated 함수 제거 PRD
+
+## 문서 정보
+
+| 항목 | 내용 |
+|---|---|
+| 문서 상태 | Phase 1~3 완료, 리뷰 후 고유 검증 보강 대기 |
+| 작성일 | `2026-09-17` |
+| 최종 수정일 | `2026-09-17` |
+| 대상 제품 | 성인 콘텐츠 노출 여부 / 접속 국가 코드 계산 정책 |
+| 작성자·결정권자 | Junie / 사용자 |
+| 관련 API Contract | 기존 API 응답 스키마 변경 없음 |
+| 관련 구현 계획 | `docs/20260917_성인콘텐츠노출정책_Deprecated함수_제거/plan-task.md` |
+| 관련 review | `reviews/문서대비구현-review.md` |
+
+## 1. Overview
+
+성인 콘텐츠 노출 여부(`isAdult`)와 접속 국가 코드 계산 정책은 현재 두 경로에 중복 구현되어 있다. 하나는 `@Deprecated`로 표시된 top-level 함수 `MemberContentPreferencePolicy.isAdultVisibleByPolicy(...)` / `resolveCountryCodeByPolicy(...)`이고, 다른 하나는 정식 경로인 `MemberContentPreferenceService`다. Deprecated 경로가 production 12개 파일에서 여전히 27곳 호출되고 있어 정책 변경 시 두 곳을 모두 고쳐야 하는 위험이 남아 있다. 이 작업은 Deprecated 경로 호출부를 `MemberContentPreferenceService`로 이전하고 Deprecated 함수와 그 전용 테스트를 제거한다.
+
+## 2. Problem Statement
+
+- `MemberContentPreferencePolicy.kt`의 두 함수는 `docs/20260623_메인_콘텐츠_추천_탭_API/plan-task.md`에서 `@Deprecated` 처리만 되고 호출부 이전은 완료되지 않았다.
+- 접속 국가 판정 기준이 두 경로에서 다르게 조달된다. Deprecated 경로는 `RequestContextHolder`에서 `CloudFront-Viewer-Country` 헤더를 직접 읽고, 정식 경로는 `CountryContext`(요청 스코프)에서 읽는다. 값 출처(같은 헤더, `CountryInterceptor`가 주입)는 같지만 경로가 둘이다.
+- Deprecated 함수의 유일한 테스트인 `MemberContentPreferencePolicyTest`의 5개 검증은 `MemberContentPreferenceServiceTest` / `MemberContentPreferenceIntegrationTest`에 이미 동등하게 존재해, 회원 ID 강제 매핑 정책을 변경할 때마다 같은 상수를 3~4개 파일에서 함께 고쳐야 한다.
+- 결과적으로 정책 변경(예: 국가 강제 매핑 회원 ID 추가/삭제)이 중복 지점 누락으로 회귀를 만들 수 있다.
+
+문제를 해결했다는 판단은 `isAdultVisibleByPolicy` / `resolveCountryCodeByPolicy` 참조가 `src/main/kotlin`과 `src/test/kotlin`에서 0건이 되고, 기존 legacy 콘텐츠 조회 API의 `isAdult` 계산 결과가 그대로 유지되는 것으로 한다.
+
+## 3. Goals
+
+- 성인 콘텐츠 노출 여부 계산의 단일 진입점을 `MemberContentPreferenceService`로 만든다.
+- `MemberContentPreferencePolicy.kt`의 Deprecated 함수 2개와 파일, 전용 테스트를 제거한다.
+- 기존 legacy 콘텐츠 조회 API의 `isAdult` / 국가 코드 계산 동작을 유지하되, 사용자가 확정한 JP 강제 매핑의 `2L` 제거는 예외로 반영한다.
+- 공개 API request/response 스키마를 변경하지 않는다.
+
+## 4. Non-Goals
+
+- `isAdult` 판정 정책 자체(KR + 본인인증 여부, 해외 전달값 사용)를 변경하지 않는다.
+- JP 강제 매핑의 `2L` 제거 외에는 회원 ID 국가 강제 매핑(`FORCED_KR_MEMBER_IDS`, `FORCED_JP_MEMBER_IDS`) 값을 변경하지 않는다.
+- `isAdultContentVisible`을 서비스 파라미터에서 제거하거나 저장값 조회로 대체하는 리팩터링은 하지 않는다. 호출부 시그니처는 유지한다.
+- `CanController`의 통화(currency) 강제 지정 로직은 국가 강제 매핑과 무관하므로 건드리지 않는다.
+- `MemberContentPreferenceCountryResolver.kt`의 강제 매핑 알고리즘은 유지하고, JP 대상에서 `2L`만 제외한다.
+
+## 5. 영향 범위
+
+### 5.1 Deprecated 함수 정의
+
+| 파일 | 대상 |
+|---|---|
+| `src/main/kotlin/kr/co/vividnext/sodalive/member/contentpreference/MemberContentPreferencePolicy.kt` | `resolveCountryCodeByPolicy(member)`, `isAdultVisibleByPolicy(member, isAdultContentVisible)` |
+
+### 5.2 production 호출부
+
+| 파일 | 호출 수 |
+|---|---:|
+| `content/series/ContentSeriesService.kt` | 5 |
+| `content/AudioContentService.kt` | 3 |
+| `content/main/AudioContentMainService.kt` | 2 |
+| `content/main/curation/AudioContentCurationService.kt` | 2 |
+| `content/theme/AudioContentThemeService.kt` | 2 |
+| `content/main/tab/free/AudioContentMainTabFreeService.kt` | 4 |
+| `content/main/tab/alarm/AudioContentMainTabAlarmService.kt` | 2 |
+| `content/main/tab/content/AudioContentMainTabContentService.kt` | 2 |
+| `content/main/tab/home/AudioContentMainTabHomeService.kt` | 2 |
+| `content/main/tab/asmr/AudioContentMainTabAsmrService.kt` | 1 |
+| `content/main/tab/replay/AudioContentMainTabLiveReplayService.kt` | 1 |
+| `content/main/tab/series/AudioContentMainTabSeriesService.kt` | 1 |
+
+12개 파일, 총 27곳이다. 어떤 파일도 현재 `MemberContentPreferenceService`를 주입받지 않는다.
+
+### 5.3 테스트 호출부
+
+| 파일 | 처리 |
+|---|---|
+| `src/test/kotlin/.../member/contentpreference/MemberContentPreferencePolicyTest.kt` | 삭제. 동등 검증이 `MemberContentPreferenceServiceTest`, `MemberContentPreferenceIntegrationTest`에 이미 존재하며, 부족한 항목은 `MemberContentPreferenceServiceTest`로 이전한다. |
+
+## 6. 기능 요구사항
+
+| ID | 상태 | 요구사항 | 수용 기준 | 계약/Goal 연결 |
+|---|---|---|---|---|
+| `DEPREM-001` | 확정 | `MemberContentPreferenceService`에 `isAdultVisibleForQuery(member, isAdultContentVisible)`를 추가해 `resolveCountryCode(member)` + `calculateIsAdultForQuery(...)` 조합을 단일 메서드로 제공한다. | KR + `auth == null`이면 `false`, KR + `auth != null`이면 전달값, 비KR이면 전달값. 회원 ID 강제 매핑이 접속 국가 헤더보다 우선한다. | `P1-T1` |
+| `DEPREM-002` | 확정 | production 12개 파일의 `isAdultVisibleByPolicy(...)` 27곳을 `memberContentPreferenceService.isAdultVisibleForQuery(...)`로 치환하고 `MemberContentPreferenceService`를 생성자 주입한다. | 각 파일에서 `isAdultVisibleByPolicy` import와 호출이 사라지고, `isAdult` 계산 결과가 기존과 동일하다. | `P2-T1`~`P2-T4` |
+| `DEPREM-003` | 확정 | `MemberContentPreferencePolicy.kt`와 `MemberContentPreferencePolicyTest.kt`를 제거한다. | `isAdultVisibleByPolicy|resolveCountryCodeByPolicy` 검색 결과가 `src/main/kotlin`, `src/test/kotlin`에서 0건이다. | `P3-T1` |
+| `DEPREM-004` | 확정 | Deprecated 테스트에서 제거되는 검증 항목 중 정식 경로 테스트에 없는 것은 `MemberContentPreferenceServiceTest`로 이전한다. | 헤더 공백/소문자 정규화(`" us "` → `US`), 국가 컨텍스트 없음 → `KR` fallback, 비KR에서 저장 `countryCode` 무시 검증이 정식 경로 테스트에 존재한다. | `P3-T1` |
+| `DEPREM-005` | 확정 | 기존 legacy 콘텐츠 조회 동작을 회귀 없이 유지한다. | `AudioContentServiceTest` 등 영향 범위 테스트와 `member/contentpreference` 테스트가 모두 통과하고 ktlint가 통과한다. | `P3-GATE` |
+
+## 7. API 계약
+
+- 변경되는 공개 request/response 필드는 없다.
+- 신규 message key, 신규 endpoint는 없다.
+- 각 서비스의 public 메서드 시그니처(`isAdultContentVisible` 파라미터 포함)는 유지한다. 변경되는 것은 생성자 의존성뿐이다.
+
+## 8. 보안과 데이터 취급
+
+- 접속 국가 판정은 계속 `CloudFront-Viewer-Country` 헤더를 `CountryInterceptor`가 `CountryContext`에 주입한 값만 사용한다.
+- 성인 콘텐츠 노출은 KR에서 본인인증(`member.auth != null`)이 있는 경우에만 허용하는 기존 정책을 유지한다.
+- 회원 ID, 이메일 등 개인정보는 로그에 추가하지 않는다.
+
+## 9. 리스크
+
+| ID | 리스크 | 대응 |
+|---|---|---|
+| `RISK-001` | `CountryContext`는 `@RequestScope`이므로 비웹 스레드에서 호출되면 예외가 발생할 수 있다. Deprecated 함수는 `RequestContextHolder`가 없을 때 `KR`로 fallback했다. | 대상 12개 서비스가 controller 요청 경로에서만 호출되는지 Phase 2에서 파일별로 확인한다. 스케줄러/비동기 호출 경로가 발견되면 해당 Task를 진행하지 않고 계획을 먼저 갱신한다. |
+| `RISK-002` | 생성자 파라미터 추가로 기존 서비스 테스트가 컴파일 실패할 수 있다. | 해소됨. `AudioContentServiceTest` 1곳만 영향받아 mock 주입으로 해결했다. |
+| `RISK-003` | 순환 의존 발생 가능성. | `MemberContentPreferenceService`는 `MemberContentPreferenceRepository`, `MemberRepository`, `CountryContext`, `CacheManager`만 의존하므로 콘텐츠 서비스와 순환이 발생하지 않음을 확인했다. |
+
+## 10. 성공 기준
+
+- [x] `MemberContentPreferenceService.isAdultVisibleForQuery(...)`가 기존 `isAdultVisibleByPolicy(...)`와 동일한 판정을 한다. (`DEPREM-001`)
+- [x] production 12개 파일 27곳이 모두 정식 경로를 호출한다. (`DEPREM-002`)
+- [x] `MemberContentPreferencePolicy.kt`, `MemberContentPreferencePolicyTest.kt`가 제거되고 참조가 0건이다. (`DEPREM-003`)
+- [x] Deprecated 테스트의 고유 검증이 `MemberContentPreferenceServiceTest`에 남아 있다. (`DEPREM-004`)
+- [x] 영향 범위 focused test와 ktlint가 통과한다. (`DEPREM-005`)
+
+## 11. Decision Log
+
+기존 성공 기준 체크박스는 당시 완료 기록으로 유지한다. 후속 리뷰에서 DEPREM-004의 저장 국가 충돌 검증 누락을 확인했으며, `plan-task.md`의 `P3-R1` 완료 전까지 해당 검증 보강은 미완료다.
+
+| 일시 | 결정 | 근거 |
+|---|---|---|
+| 2026-09-17 | Deprecated 함수 제거를 위해 production 호출부를 모두 마이그레이션하는 방식(선택지 3)을 택한다. | 사용자 선택. 테스트만 정식 경로로 바꾸면 production에서 쓰이는 Deprecated 경로가 커버리지 0이 되므로 부적절 |
+| 2026-09-17 | 호출부 1:1 치환을 위해 `MemberContentPreferenceService`에 `isAdultVisibleForQuery(member, isAdultContentVisible)` wrapper를 추가한다. | 호출부마다 `resolveCountryCode(...)` + `calculateIsAdultForQuery(...)` 2단계를 반복하면 중복이 27곳으로 늘어남 |
+| 2026-09-17 | `MemberContentPreferencePolicyTest`는 삭제하고 고유 검증만 `MemberContentPreferenceServiceTest`로 이전한다. | 5개 검증 중 대부분이 정식 경로 테스트와 중복이며, 함수 제거 후에는 테스트 대상이 사라짐 |
+| 2026-09-17 | Phase를 서비스 묶음 단위로 나눠 진행한다. | 27곳 동시 변경 시 실패 원인 추적이 어려움. 저장소 규칙("작은 단위로 안전하게 수정") 준수 |
+| 2026-09-17 | `RISK-001`은 해소로 판정한다. | 치환한 27곳이 모두 controller 진입 조회 경로임을 파일별로 확인했고, 스케줄러(`Recommendation/Ranking/ChargeEvent`)는 이 경로를 호출하지 않음 |
+
+- 2026-09-17 사용자 확정: JP 강제 매핑에서 `2L`을 제거한 것은 의도된 정책 변경이다. REV-001은 결함 판정을 철회하며 `2L`을 복원하지 않는다. 나머지 매핑은 유지한다.
+- 2026-09-17 후속 계획: REV-002의 저장 국가 무시 검증을 `P3-R1`로 추가한다. 이번 작업은 문서 갱신이며 테스트 구현·실행은 하지 않는다.
+
+## 12. 열린 질문
+
+- 없음. Phase 2에서 비웹 호출 경로(`RISK-001`)가 발견되면 계획을 먼저 갱신하고 사용자에게 확인한다.

docs/20260917_성인콘텐츠노출정책_Deprecated함수_제거/reviews/문서대비구현-review.md

@@ -0,0 +1,65 @@
+# 문서 대비 구현 리뷰
+
+## 리뷰 정보와 범위
+
+- 일자: 2026-09-17
+- 기준: HEAD `8c87286acd69174f6024d30a267458e838e35cf5` 및 리뷰 시작 시 존재한 미커밋 변경
+- 요구사항: `../prd.md`, `../plan-task.md`의 Phase 1~3
+- 방법: 문서, production 코드, 테스트 소스, 현재 diff와 호출 경로 정적 대조
+- 사용자 지시에 따라 자동 테스트·빌드·ktlint·애플리케이션 실행은 하지 않았다. 기존 실행 성공 기록을 재검증한 것으로 취급하지 않는다.
+- 구현 및 기존 PRD/계획은 수정하지 않았다. 아래 판정은 현재 작업 트리에 대한 것이며 변경 작성자나 의도를 추정하지 않는다.
+
+## 발견 사항
+
+### REV-001 — 강제 JP 매핑 값이 변경됨
+
+- 심각도: High / 상태: 확정
+- 요구사항: PRD §3 기존 동작 유지, §4 강제 매핑 값 변경 금지; 계획 P3-T1의 resolver 변경 제외
+- 근거: `src/main/kotlin/kr/co/vividnext/sodalive/member/contentpreference/MemberContentPreferenceCountryResolver.kt:6`에서 `FORCED_JP_MEMBER_IDS`의 `2L`이 제거됐다.
+- 코드 추적: 회원 ID 2, 인증 없음, 요청 국가 KR 또는 헤더 없음, `isAdultContentVisible=true`이면 기존 JP 판정/성인 노출 true에서 KR 판정/false로 바뀐다.
+- 관련 테스트도 `MemberContentPreferenceServiceTest.kt:64`, `MemberContentPreferenceIntegrationTest.kt:187`에서 ID 2를 29721로 교체해 기존 매핑 회귀를 검출하지 못한다.
+- 권장 조치: 문서대로라면 기존 매핑과 해당 테스트 대상을 복원한다. 별도로 의도한 정책 변경이라면 해당 결정과 범위를 문서에 명시해야 한다.
+
+### REV-002 — 저장 국가 무시 검증이 이전되지 않음
+
+- 심각도: Medium / 상태: 확정
+- 요구사항: DEPREM-004, P3-T1
+- 근거: 삭제된 PolicyTest는 저장 `member.countryCode="KR"`, 요청 국가 US 조건을 검증했다. 현재 `MemberContentPreferenceServiceTest.kt:469`의 해외 노출 테스트와 `:536`의 회원 생성 함수는 저장 국가를 설정하지 않는다. IntegrationTest에도 이 충돌 조건이 없다.
+- 영향: 현재 resolver는 저장 국가를 참조하지 않아 구현 자체는 맞지만, 문서에서 이전하도록 요구한 고유 회귀 검증이 빠졌다. `plan-task.md:224`의 기존 테스트가 이미 커버한다는 기록은 부정확하다.
+- 권장 조치: 일반 미인증 회원의 저장 국가를 KR로 설정하고 요청 국가는 US로 두어, 정식 진입점의 국가 US/성인 노출 true를 확인하는 검증을 추가한다.
+
+### REV-003 — 호출부 합계 오기
+
+- 심각도: Low / 상태: 확정
+- 근거: PRD §5.2 표의 합계와 실제 치환은 모두 12개 파일 27곳이다. PRD와 계획에는 반복해서 24곳으로 기록돼 있다.
+- 영향: 호출 치환 누락은 없으며 문서 수치가 틀렸다.
+- 권장 조치: 두 문서의 합계를 27곳으로 정정한다.
+
+## 충족 항목과 한계
+
+| 항목 | 정적 검토 결과 |
+|---|---|
+| DEPREM-001 단일 진입점 | 기존 resolveCountryCode + calculateIsAdultForQuery 재사용, 추가 DB 조회 없음 |
+| DEPREM-002 호출부 이전 | 12개 파일 27곳 이전, 인자 및 홈의 member=null → false 유지 |
+| DEPREM-003 정의/참조 제거 | 두 파일 삭제, src/main/kotlin 및 src/test/kotlin의 두 Deprecated 함수 이름 검색 0건 |
+| DEPREM-004 고유 검증 이전 | 정규화/null 국가값 fallback은 존재, 저장 국가 충돌 검증 누락 |
+| DEPREM-005 실행 검증 | 사용자 요청에 따라 재실행 제외 |
+| API 계약 | 기존 공개 메서드 인자와 request/response 스키마 변경 없음 |
+| 요청 경로/의존성 | 변경된 조회 메서드의 비웹 호출 및 새 순환 의존 발견 없음 |
+
+국가값 null 검증은 요청 스코프 자체가 없는 상황과 다르다. 새 경로는 요청 스코프와 회원 ID를 요구하므로 모든 입력에서 구 함수와 동등하다고 일반화할 수 없다. 다만 검토한 변경 호출 경로에서 해당 비웹/ID 없는 입력은 확인하지 못해 별도 운영 결함으로 확정하지 않았다.
+
+## 리뷰 종료 판정과 후속 작업
+
+요구사항, 테스트 소스, 코드 품질, 보안, 주변 호출 맥락의 검토 결과를 종합했다. 확정 불일치 3건으로 문서와 완전히 일치하는 구현이라고 판정할 수 없다.
+
+이번 요청은 검토이므로 수정 goal은 실행하지 않았다. 후속 구현 시 기존 완료 기록을 유지하면서 REV-001 매핑 일치, REV-002 고유 검증 이전, REV-003 문서 수치 정정을 별도 회귀 Task로 계획에 추가한다. 자동 검증은 이번 검토에서 수행하지 않았다.
+
+## 후속 판정 정정 — 2026-09-17
+
+위 내용은 최초 검토 당시 기록이며, 사용자 확인 이후 현재 판정은 다음과 같다.
+
+- **REV-001: 결함 판정 철회.** 사용자가 `2L` 제거를 의도한 변경으로 확정했다. PRD·계획에 해당 예외를 반영했으며 매핑과 테스트 대상을 복원하지 않는다.
+- **REV-002: 구현 완료 / 실행 검증 대기.** `MemberContentPreferenceServiceTest.shouldIgnoreStoredCountryCodeWhenRequestCountryIsNotKr`를 추가해 저장 KR·요청 US·미인증 회원 조건에서 국가 결과 US와 전달값 true/false 보존을 검증한다. production은 변경하지 않았고, 기존 자동 테스트 미실행 지시에 따라 focused test와 ktlint는 실행하지 않았다.
+- **REV-003: 문서 정정 완료.** PRD·계획의 24곳 표기를 실제 합계 27곳으로 정정했다.
+- **현재 결론:** `P3-R1` 테스트 구현과 소스 검토는 완료했으며, 남은 항목은 focused test와 ktlint 실행 검증이다.

docs/20260918_캔조회_회원2_강제통화제거/plan-task.md

@@ -0,0 +1,62 @@
+# 캔 조회 회원 2 강제 통화 제거 구현 계획
+
+- 상태: 구현 완료
+- 작성일: 2026-09-18
+- 요구사항: [prd.md](prd.md)
+- 현재 Phase: 1 완료
+- 활성 Goal: 없음
+- 실행 순서: CAN-P1-T1 → CAN-P1-GATE
+
+### Phase 1: 회원 2의 기본 통화 적용과 회귀 확인
+
+- [x] **Task 1.1: 회원 2의 강제 통화 제거** (`CAN-P1-T1`)
+  - Objective: 회원 2가 다른 일반 회원처럼 요청 국가에 따른 통화의 캔 상품을 조회한다.
+  - 시작 조건: PRD 확정, 기존 컨트롤러·서비스 및 테스트 확인 완료.
+  - 완료 증거: RED/GREEN 결과, 실제 컨트롤러·서비스·저장소 통합 테스트와 캔 패키지 회귀 통과.
+  - 범위 밖: 다른 회원 예외 제거, 국가 결정·API 스키마·서비스 리팩터링.
+  - 수정: `src/main/kotlin/kr/co/vividnext/sodalive/can/CanController.kt`
+  - 생성: `src/test/kotlin/kr/co/vividnext/sodalive/can/CanControllerIntegrationTest.kt`
+  - 확인: `src/main/kotlin/kr/co/vividnext/sodalive/can/CanService.kt`, `src/test/kotlin/kr/co/vividnext/sodalive/can/CanServiceTest.kt`
+  - [x] **RED:** 회원 2의 KRW/USD, 유지할 예외·일반 회원·비로그인·국가 누락 통합 테스트를 작성한다.
+  - [x] **RED 확인:** `./gradlew test --tests 'kr.co.vividnext.sodalive.can.CanControllerIntegrationTest'`로 회원 2의 JPY 반환 assertion 실패를 확인한다.
+  - [x] **GREEN:** 컨트롤러 조건에서 `member.id == 2L ||`만 제거한다.
+  - [x] **GREEN 확인:** 동일 focused test가 통과하는지 확인한다.
+  - [x] **REFACTOR:** 불필요한 정리 없이 `./gradlew test --tests 'kr.co.vividnext.sodalive.can.*'` 및 변경 파일 lint로 회귀를 확인한다.
+
+#### Task 검증 기록
+- 2026-09-18: 기존 `getCans` 및 `/can` 직접 테스트가 없음을 확인했다. 새 테스트는 `@SpringBootTest`와 H2, 요청 범위의 실제 CountryContext를 사용하고 트랜잭션 롤백으로 상품 데이터를 격리한다.
+- 2026-09-18 RED: 테스트 작성 중 `Member.password` 필수 인자 누락을 수정한 뒤 production/test 컴파일이 통과했다. 이후 공통 JWT 기본 키의 길이 부족으로 발생한 컨텍스트 로딩 실패는 테스트 실행에만 임시 키를 제공하여 해결했다. 이 두 실패는 동작 RED에 포함하지 않았다.
+- 2026-09-18 RED 확인: 아래 환경 설정 후 `./gradlew test --tests 'kr.co.vividnext.sodalive.can.CanControllerIntegrationTest' --console=plain` 실행. 13개 중 회원 2의 4개만 assertion 실패(exit 1): KR은 KRW, US/JP/국가 누락은 USD 기대였으나 실제 JPY. 나머지 9개 통과.
+- 2026-09-18 GREEN 확인: 조건 제거 후 같은 focused 명령으로 13개 전부 통과(exit 0), production/test 컴파일 성공.
+- 2026-09-18 회귀 확인: `./gradlew test --tests 'kr.co.vividnext.sodalive.can.*' --console=plain` 성공(exit 0). 신규 13개와 기존 14개, 총 5개 클래스 27개 테스트 통과(실패·오류·skip 0). 기존 테스트를 완화하거나 수정할 필요가 없었다.
+
+- [x] **Phase Gate: 변경 범위와 검증 기록 확인** (`CAN-P1-GATE`)
+  - Objective: 요구사항과 최소 변경, 검증 증거가 일치함을 확인한다.
+  - 시작 조건: CAN-P1-T1 완료.
+  - 완료 증거: 캔 패키지 테스트 통과, 문서 명령·diff 확인 및 PRD 체크박스 완료.
+  - 범위 밖: 전체 서비스 실행과 관련 없는 기능 수정.
+  - 확인 파일: 이 문서, `docs/20260918_캔조회_회원2_강제통화제거/prd.md`, 위 Task의 코드·테스트.
+  - TDD 예외 사유: 구현 없는 최종 검증 단계.
+  - 대체 검증 방법: `./gradlew tasks --all`, `git diff --check`, 변경 파일 대조.
+
+## 검증 범위
+- 단일 루트 프로젝트이며 변경은 컨트롤러의 조건 하나에 한정된다. 전체 회귀 실행 조건(공통 코드·여러 도메인 변경·영향 불명확 실패·사용자 명시 요청)이 발생하지 않으면 전체 테스트는 생략하고 캔 패키지 전체를 실행한다.
+- 테스트 실행으로 production/test 컴파일을 함께 확인한다. 새 API나 실행 환경 변경이 없어 별도 애플리케이션 구동은 하지 않는다.
+
+## Progress
+- 2026-09-18: 요구사항 및 TDD 계획 작성, CAN-P1-T1 준비.
+- 2026-09-18: CAN-P1-T1 RED 확인 완료, 회원 2 조건 제거 진행.
+- 2026-09-18: CAN-P1-T1 완료. 조건 한 항만 제거했고 신규 13개 및 기존 14개 테스트가 통과했다.
+- 2026-09-18: CAN-P1-GATE 완료. API 스키마·다른 회원 예외가 유지되는 diff와 PRD 수용 기준, 검증 기록을 대조했다. 남은 작업 없음.
+
+## 공통 검증 기록
+- 셸에 기본 Java가 없어 기존 Gradle 캐시의 Java 17을 사용했다. 설정 파일은 변경하지 않았다.
+- 테스트 JWT 기본값은 디코딩 후 키 길이가 부족하므로 실행 프로세스에만 임시 키를 전달했다. 키 값은 저장·출력하지 않는다. 아래 환경 설정 뒤 문서의 검증 명령을 실행한다.
+
+```bash
+export JAVA_HOME=~/.gradle/jdks/eclipse_adoptium-17-x86_64-os_x.2/jdk-17.0.19+10/Contents/Home
+export JWT_SECRET="$(openssl rand -base64 64 | tr -d '\n')"
+```
+
+- 2026-09-18: `./gradlew tasks --all --console=plain`, `git diff --check` 성공(exit 0). 변경 Kotlin 파일의 IDE 정적 검사에서 오류 없음. 신규 테스트는 경고도 없으며 기존 컨트롤러의 수정하지 않은 인증 SpEL 식에는 변수 해석 경고 8개가 있다.
+- 2026-09-18: 전체 테스트·전체 ktlint 및 별도 서버 실행은 생략했다. 변경은 컨트롤러 조건 한 곳이고 다른 도메인·공통 코드·하위 모듈 변경이 없어 focused 통합 테스트, 캔 패키지 전체 회귀, 변경 파일 정적 검사로 검증했다.

docs/20260918_캔조회_회원2_강제통화제거/prd.md

@@ -0,0 +1,27 @@
+# 캔 조회 회원 2 강제 통화 제거
+
+## 문서 정보
+- 상태: 구현 완료
+- 작성일: 2026-09-18
+- 관련 계획: [plan-task.md](plan-task.md)
+
+## 문제와 목표
+`GET /can`의 `getCans`는 회원 2·4·44144에게 JPY를 강제 적용한다.
+사용자 요청에 따라 회원 2만 제외하여 기존 국가별 통화 선택을 따르게 한다.
+
+## 확정 요구사항과 수용 기준
+| ID | 요구사항 | 수용 기준 | Goal |
+|---|---|---|---|
+| CAN-CURRENCY-001 | 회원 2의 JPY 강제 조건 제거 | KR 요청은 KRW, 그 외 국가는 USD 상품 반환 | CAN-P1-T1 |
+| CAN-CURRENCY-002 | 나머지 동작 유지 | 회원 4·44144는 JPY, 일반 회원·비로그인은 기존 국가별 통화 적용 | CAN-P1-T1 |
+| CAN-CURRENCY-003 | 관련 테스트 검증 | 변경 전 실패 재현, 변경 후 캔 패키지 테스트 통과 | CAN-P1-GATE |
+
+## 범위 밖
+- 다른 진입점의 회원 ID 조건, 국가 판정 및 성인콘텐츠 정책 변경.
+- 서비스의 KR → KRW / 그 외 → USD 정책 변경.
+- 공개 API 요청·응답 스키마, 인증 및 상품 판매 상태 필터 변경.
+
+## 성공 기준
+- [x] 회원 2에 대한 회귀 테스트가 변경 전 실패하고 변경 후 통과한다.
+- [x] 회원 4·44144, 일반 회원, 비로그인 및 국가 누락의 기존 동작이 유지된다.
+- [x] 관련 기존 테스트가 통과하고 검증 결과를 계획 문서에 기록한다.

docs/20260929_크리에이터_선물하기/admin-page-prompts.md

@@ -0,0 +1,549 @@
+# 선물 관리자 페이지 구현 프롬프트
+
+이 문서는 관리자 페이지의 선물 관련 4개 화면을 프론트엔드 구현 에이전트에게 전달하기 위한 프롬프트 모음이다.
+
+공통 전제:
+
+- 관리자 메뉴에는 parent 메뉴 `선물함 관리` 아래에 다음 4개 하위 메뉴가 있다.
+  - `선물함 리스트` → `/gift/list`
+  - `받을 주소` → `/gift/mailbox`
+  - `선물 카테고리` → `/gift/category`
+  - `선물 사이즈` → `/gift/size`
+- 모든 API 응답은 기존 공통 envelope를 사용한다. 화면에서는 `response.data`를 실제 payload로 사용한다.
+- 인증/권한 처리는 기존 관리자 페이지의 API 클라이언트, 토큰 저장 방식, 에러 처리 방식을 따른다.
+- 새 디자인 시스템을 만들지 말고 기존 관리자 페이지의 테이블, 필터, 버튼, 모달, 폼, 토스트, 확인창 패턴을 재사용한다.
+- 화면 문구는 한국어로 작성한다.
+- API 실패 시 기존 관리자 페이지의 공통 에러 표시 방식을 따른다.
+
+---
+
+## 1. 선물함 리스트 페이지 프롬프트
+
+```text
+관리자 선물함 리스트 페이지를 구현해줘.
+
+목표:
+- 관리자 메뉴 `선물함 관리 > 선물함 리스트`에서 전체 선물 신청 목록을 조회한다.
+- 상태, 신청번호, 닉네임으로 필터링할 수 있다.
+- 목록 row에서 선물 상세를 확인하고, 현재 상태에서 가능한 운영 액션을 실행할 수 있다.
+- 기존 관리자 페이지의 테이블/필터/페이지네이션/모달/확인창 스타일을 그대로 따른다.
+
+라우트:
+- `/gift/list`
+
+필수 화면 구성:
+- 상단 제목: `선물함 리스트`
+- 필터 영역:
+  - 상태 select: 전체, 접수 완료, 발송 확인, 사서함 도착, 검수 완료, 전달 완료, 전달 불가, 신청 취소
+  - 신청번호 검색 input: `applicationNo` 부분 검색
+  - 닉네임 검색 input: 발송인 또는 수취인 닉네임 부분 검색
+  - 검색 버튼, 초기화 버튼
+- 목록 테이블 컬럼:
+  - 신청번호 `applicationNo`
+  - 발송인 닉네임 `senderNickname`
+  - 수취인 닉네임 `recipientNickname`
+  - 사이즈 `sizeName` / `sizeCode`
+  - 카테고리 `categoryName`
+  - 분류번호 `classificationNumber`
+  - 택배사 `courierCompanyName`
+  - 운송장번호 `trackingNumber`
+  - 상태 `statusName`
+  - 액션 버튼
+- 페이지네이션:
+  - 서버의 `page`, `size`, `totalCount`, `hasNext` 기준으로 기존 관리자 페이지 패턴에 맞춘다.
+
+목록 조회 API:
+- Method: `GET`
+- URL: `/api/v2/admin/gifts`
+- Query:
+  - `status?: GiftStatus`
+  - `applicationNo?: string`
+  - `nickname?: string`
+  - `page?: number` 기본 `0`
+  - `size?: number` 기본 `20`
+- 필터 조합:
+  - 선택 필터는 AND 조건이다.
+  - `nickname`은 발송인/수취인 닉네임 중 하나에 포함되면 매칭된다.
+
+목록 조회 response `data`:
+```ts
+type AdminGiftListResponse = {
+  totalCount: number;
+  items: AdminGiftListItemResponse[];
+  page: number;
+  size: number;
+  hasNext: boolean;
+};
+
+type AdminGiftListItemResponse = {
+  applicationNo: string;
+  senderNickname: string;
+  recipientNickname: string;
+  sizeCode: string;
+  sizeName: string;
+  categoryName: string;
+  classificationNumber: string;
+  courierCompanyName: string | null;
+  trackingNumber: string | null;
+  status: GiftStatus;
+  statusName: string;
+  availableActions: AdminGiftAction[];
+};
+```
+
+상태 enum:
+```ts
+type GiftStatus =
+  | "RECEIVED"
+  | "TRACKING_REGISTERED"
+  | "ARRIVED_AT_MAILBOX"
+  | "INSPECTION_COMPLETED"
+  | "DELIVERED"
+  | "UNDELIVERABLE"
+  | "CANCELED";
+```
+
+상태 표시명:
+- `RECEIVED`: `접수 완료`
+- `TRACKING_REGISTERED`: `발송 확인`
+- `ARRIVED_AT_MAILBOX`: `사서함 도착`
+- `INSPECTION_COMPLETED`: `검수 완료`
+- `DELIVERED`: `전달 완료`
+- `UNDELIVERABLE`: `전달 불가`
+- `CANCELED`: `신청 취소`
+
+상세 조회 API:
+- Method: `GET`
+- URL: `/api/v2/admin/gifts/{applicationNo}`
+- 용도:
+  - 목록 row 클릭 또는 `상세` 버튼 클릭 시 상세 모달/상세 패널을 연다.
+
+상세 response `data`:
+```ts
+type AdminGiftDetailResponse = {
+  applicationNo: string;
+  senderInfo: AdminGiftMemberInfoResponse;
+  recipientInfo: AdminGiftMemberInfoResponse;
+  productInfo: AdminGiftProductInfoResponse;
+  inboundDeliveryInfo: AdminGiftInboundDeliveryInfoResponse;
+  status: GiftStatus;
+  statusName: string;
+  availableActions: AdminGiftAction[];
+};
+
+type AdminGiftMemberInfoResponse = {
+  nickname: string;
+  name: string;
+  phoneNumber: string;
+  address: string;
+};
+
+type AdminGiftProductInfoResponse = {
+  sizeCode: string;
+  sizeName: string;
+  categoryName: string;
+  classificationNumber: string;
+};
+
+type AdminGiftInboundDeliveryInfoResponse = {
+  courierCompanyName: string | null;
+  trackingNumber: string | null;
+};
+```
+
+상세 표시 요구사항:
+- 발송인 정보: 닉네임, 이름, 전화번호, 주소
+- 수취인 정보: 닉네임, 이름, 전화번호, 주소
+- 상품 정보: 사이즈, 카테고리, 분류번호
+- 입고 배송 정보: 택배사, 운송장번호
+- 현재 상태와 가능한 액션
+- 수취인이 배송지를 아직 입력하지 않은 경우 `recipientInfo.nickname`은 표시하고 `name`, `phoneNumber`, `address`는 빈 문자열로 온다. 화면에서는 `미입력`으로 표시해도 된다.
+
+운영 액션 enum:
+```ts
+type AdminGiftAction =
+  | "ARRIVE_MAILBOX"
+  | "COMPLETE_INSPECTION"
+  | "COMPLETE_DELIVERY"
+  | "MARK_UNDELIVERABLE";
+```
+
+상태별 `availableActions`:
+- `RECEIVED`: 없음
+- `TRACKING_REGISTERED`: `ARRIVE_MAILBOX`, `MARK_UNDELIVERABLE`
+- `ARRIVED_AT_MAILBOX`: `COMPLETE_INSPECTION`, `MARK_UNDELIVERABLE`
+- `INSPECTION_COMPLETED`: `COMPLETE_DELIVERY`, `MARK_UNDELIVERABLE`
+- `DELIVERED`: 없음
+- `UNDELIVERABLE`: 없음
+- `CANCELED`: 없음
+
+액션 버튼 문구:
+- `ARRIVE_MAILBOX`: `사서함 도착 처리`
+- `COMPLETE_INSPECTION`: `검수 완료 처리`
+- `COMPLETE_DELIVERY`: `전달 완료 처리`
+- `MARK_UNDELIVERABLE`: `전달 불가 처리`
+
+액션 API:
+- 사서함 도착 처리
+  - Method: `POST`
+  - URL: `/api/v2/admin/gifts/{applicationNo}/arrive-mailbox`
+  - Body: 없음
+- 검수 완료 처리
+  - Method: `POST`
+  - URL: `/api/v2/admin/gifts/{applicationNo}/complete-inspection`
+  - Body: 없음
+- 전달 완료 처리
+  - Method: `POST`
+  - URL: `/api/v2/admin/gifts/{applicationNo}/complete-delivery`
+  - Body: 없음
+- 전달 불가 처리
+  - Method: `POST`
+  - URL: `/api/v2/admin/gifts/{applicationNo}/mark-undeliverable`
+  - Body:
+```ts
+type AdminGiftMarkUndeliverableRequest = {
+  reason: string;
+};
+```
+
+액션 response `data`:
+```ts
+type AdminGiftOperationStatusResponse = {
+  applicationNo: string;
+  status: GiftStatus;
+  statusName: string;
+  occurredAt: string; // UTC ISO string, e.g. 2026-09-30T12:00:00Z
+};
+```
+
+액션 UX:
+- 모든 상태 변경 액션은 확인창을 띄운다.
+- `MARK_UNDELIVERABLE`은 사유 입력 모달을 띄운다.
+- 전달 불가 사유는 공백만 입력할 수 없고 255자 이내로 제한한다.
+- 액션 성공 후:
+  - 상세 모달이 열려 있으면 상세를 다시 조회한다.
+  - 목록도 현재 필터/페이지 기준으로 다시 조회한다.
+  - 성공 토스트를 표시한다.
+- 액션 실패 시 기존 관리자 페이지 에러 토스트/알림 패턴을 따른다.
+
+빈 값 표시:
+- `courierCompanyName`, `trackingNumber`가 null이면 `-`로 표시한다.
+- 수취인 개인정보가 빈 문자열이면 `미입력`으로 표시한다.
+
+테스트/검증:
+- API 클라이언트 함수 단위 테스트 또는 페이지 테스트에서 query parameter가 올바르게 전달되는지 확인한다.
+- `availableActions`에 따라 버튼 노출이 달라지는지 확인한다.
+- 전달 불가 사유 빈 값 validation을 확인한다.
+```
+
+---
+
+## 2. 받을 주소 설정 페이지 프롬프트
+
+```text
+관리자 선물 받을 주소 설정 페이지를 구현해줘.
+
+목표:
+- 관리자 메뉴 `선물함 관리 > 받을 주소`에서 팬이 선물을 보낼 전역 단일 주소를 조회하고 저장한다.
+- 이 주소는 팬의 보낸 선물 상세 API에서 정상 진행 상태 중 전달 완료 전(`RECEIVED`, `TRACKING_REGISTERED`, `ARRIVED_AT_MAILBOX`, `INSPECTION_COMPLETED`)일 때 `mailbox`로 노출된다.
+- 기존 관리자 페이지의 폼, 저장 버튼, 토스트, 에러 표시 패턴을 그대로 따른다.
+
+라우트:
+- `/gift/mailbox`
+
+필수 화면 구성:
+- 상단 제목: `받을 주소`
+- 설명 문구: `팬이 선물을 발송할 때 확인하는 받을 주소입니다.`
+- 입력 폼:
+  - 받을 사람 이름 `name`
+  - 연락처 `phoneNumber`
+  - 우편번호 `zipCode`
+  - 주소 `address`
+  - 상세주소 `addressDetail`
+- 저장 버튼: `저장`
+
+초기 조회 API:
+- Method: `GET`
+- URL: `/api/v2/admin/gift-mailbox`
+- response `data`:
+```ts
+type AdminGiftMailboxResponse = {
+  name: string;
+  address: string;
+  phoneNumber: string;
+} | null;
+```
+- `data`가 null이면 빈 폼을 표시한다.
+
+저장 API:
+- Method: `PUT`
+- URL: `/api/v2/admin/gift-mailbox`
+- Request:
+```ts
+type AdminGiftMailboxRequest = {
+  name: string;
+  phoneNumber: string;
+  zipCode: string;
+  address: string;
+  addressDetail: string | null;
+};
+```
+- Response `data`:
+```ts
+type AdminGiftMailboxResponse = {
+  name: string;
+  address: string;
+  phoneNumber: string;
+};
+```
+
+Validation:
+- `name`, `phoneNumber`, `zipCode`, `address`는 필수다.
+- 공백만 입력할 수 없다.
+- 저장 실패 시 기존 관리자 페이지의 공통 에러 표시 방식을 따른다.
+
+저장 성공 UX:
+- 성공 토스트를 표시한다.
+- 저장 API response 기준으로 화면 값을 갱신한다.
+- `address`는 서버가 조립한 `(우편번호) 주소, 상세주소` 형식으로 표시해도 되고, 입력 필드는 사용자가 입력한 값을 유지해도 된다.
+
+테스트/검증:
+- 초기 조회 시 null이면 빈 폼을 표시하는지 확인한다.
+- 저장 시 PUT body가 정확히 전달되는지 확인한다.
+- 필수값 공백 validation을 확인한다.
+```
+
+---
+
+## 3. 선물 카테고리 CRUD 페이지 프롬프트
+
+```text
+관리자 선물 카테고리 CRUD 페이지를 구현해줘.
+
+목표:
+- 관리자 메뉴 `선물함 관리 > 선물 카테고리`에서 선물 카테고리를 조회, 등록, 수정, 비활성화한다.
+- 기존 관리자 페이지의 CRUD 테이블, 등록/수정 모달, 삭제 확인창, 토스트 패턴을 그대로 따른다.
+
+라우트:
+- `/gift/category`
+
+필수 화면 구성:
+- 상단 제목: `선물 카테고리`
+- 상단 우측 `카테고리 등록` 버튼
+- 목록 테이블 컬럼:
+  - 카테고리 ID `categoryId`
+  - 분류번호 `classificationNumber`
+  - 카테고리 코드 `categoryCode`
+  - 카테고리명 `name`
+  - 접수 코드 `receiptCode`
+  - 대표 품목 `representativeItem`
+  - 파손면책 동의 필요 여부 `requiresDamageWaiver`
+  - 활성 여부 `isActive`
+  - 관리 버튼: 수정, 비활성화
+- 등록/수정 폼 필드:
+  - `classificationNumber`
+  - `categoryCode`
+  - `name`
+  - `receiptCode`
+  - `representativeItem`
+  - `requiresDamageWaiver`
+  - `isActive`
+
+목록 조회 API:
+- Method: `GET`
+- URL: `/api/v2/admin/gift-categories`
+- Request: 없음
+- Response `data`:
+```ts
+type AdminGiftCategoryResponse = {
+  categoryId: number;
+  classificationNumber: string;
+  categoryCode: string;
+  name: string;
+  receiptCode: string;
+  representativeItem: string;
+  requiresDamageWaiver: boolean;
+  isActive: boolean;
+};
+```
+
+등록 API:
+- Method: `POST`
+- URL: `/api/v2/admin/gift-categories`
+- Body:
+```ts
+type AdminGiftCategoryRequest = {
+  classificationNumber: string;
+  categoryCode: string;
+  name: string;
+  receiptCode: string;
+  representativeItem: string;
+  requiresDamageWaiver: boolean;
+  isActive: boolean;
+};
+```
+- Response `data`: `AdminGiftCategoryResponse`
+
+수정 API:
+- Method: `PUT`
+- URL: `/api/v2/admin/gift-categories/{categoryId}`
+- Body: `AdminGiftCategoryRequest`
+- Response `data`: `AdminGiftCategoryResponse`
+
+비활성화 API:
+- Method: `DELETE`
+- URL: `/api/v2/admin/gift-categories/{categoryId}`
+- Body: 없음
+- Response `data`: `AdminGiftCategoryResponse`
+- 서버는 실제 삭제가 아니라 `isActive=false` 논리 삭제로 처리한다.
+
+폼 validation:
+- `classificationNumber`: 필수, 숫자 3자리. 예: `100`
+- `categoryCode`: 필수, 50자 이하. 예: `DOLL`
+- `name`: 필수, 50자 이하. 예: `인형`
+- `receiptCode`: 필수, 영문 대문자 1~9자. 예: `A`
+- `representativeItem`: 필수, 100자 이하. 예: `피규어`
+- `requiresDamageWaiver`: boolean
+- `isActive`: boolean
+
+UX 요구사항:
+- 등록 성공 후 목록을 다시 조회하고 모달을 닫는다.
+- 수정 성공 후 목록을 다시 조회하고 모달을 닫는다.
+- 비활성화 버튼은 확인창을 띄운 뒤 호출한다.
+- 이미 비활성화된 row는 비활성화 버튼을 disabled 처리한다.
+- boolean 값은 기존 관리자 페이지 표현에 맞춰 `예/아니오`, `활성/비활성` 또는 badge로 표시한다.
+- `categoryCode`는 수정 폼에 표시하되 서버 쪽 엔티티는 코드 변경을 실제로 반영하지 않을 수 있으므로, 가능하면 수정 시 읽기 전용으로 두고 나머지 운영 필드만 수정하도록 UX를 구성한다.
+
+테스트/검증:
+- 목록 조회가 `GET /api/v2/admin/gift-categories`를 호출하는지 확인한다.
+- 등록/수정 body가 `AdminGiftCategoryRequest` 형태와 일치하는지 확인한다.
+- validation 실패 시 API를 호출하지 않고 폼 에러를 표시한다.
+- 비활성화 성공 후 해당 row의 `isActive=false`가 반영되는지 확인한다.
+```
+
+---
+
+## 4. 선물 사이즈 가격 CRUD 페이지 프롬프트
+
+```text
+관리자 선물 사이즈 가격 CRUD 페이지를 구현해줘.
+
+목표:
+- 관리자 메뉴 `선물함 관리 > 선물 사이즈`에서 선물 사이즈별 기본가/판매가/활성 여부를 조회하고 수정한다.
+- 현재 API는 사이즈 가격의 목록 조회와 수정만 제공한다. 신규 생성과 물리 삭제 기능은 만들지 않는다.
+- 기존 관리자 페이지의 테이블, 수정 모달, 저장 확인/토스트 패턴을 그대로 따른다.
+
+라우트:
+- `/gift/size`
+
+필수 화면 구성:
+- 상단 제목: `선물 사이즈`
+- 목록 테이블 컬럼:
+  - 사이즈 코드 `sizeCode`
+  - 사이즈명 `name`
+  - 기본가 `basePriceCan`
+  - 판매가 `salePriceCan`
+  - 활성 여부 `isActive`
+  - 관리 버튼: 수정
+- 수정 폼 필드:
+  - `sizeCode`: 읽기 전용
+  - `name`: 읽기 전용
+  - `basePriceCan`: number input
+  - `salePriceCan`: number input
+  - `isActive`: checkbox/switch
+
+목록 조회 API:
+- Method: `GET`
+- URL: `/api/v2/admin/gift-size-prices`
+- Request: 없음
+- Response `data`:
+```ts
+type AdminGiftSizePriceResponse = {
+  sizeCode: GiftSize;
+  name: string;
+  basePriceCan: number;
+  salePriceCan: number;
+  isActive: boolean;
+};
+```
+
+수정 API:
+- Method: `PUT`
+- URL: `/api/v2/admin/gift-size-prices/{sizeCode}`
+- Body:
+```ts
+type AdminGiftSizePriceRequest = {
+  basePriceCan: number;
+  salePriceCan: number;
+  isActive: boolean;
+};
+```
+- Response `data`: `AdminGiftSizePriceResponse`
+
+사이즈 enum:
+```ts
+type GiftSize = "SMALL" | "MEDIUM" | "LARGE";
+```
+
+서버 validation:
+- `salePriceCan`은 0보다 커야 한다.
+- `salePriceCan`은 `basePriceCan`보다 클 수 없다.
+
+프론트 validation:
+- `basePriceCan`: 필수, 1 이상 정수
+- `salePriceCan`: 필수, 1 이상 정수
+- `salePriceCan <= basePriceCan`
+- validation 실패 시 API 호출을 막고 필드 에러를 표시한다.
+
+UX 요구사항:
+- 가격은 숫자 입력이지만 테이블 표시에서는 기존 관리자 페이지의 숫자 포맷을 따른다.
+- 수정 버튼 클릭 시 현재 row 값을 폼 초기값으로 넣는다.
+- 저장 전 확인창은 기존 관리자 페이지 패턴이 있으면 따른다.
+- 저장 성공 후 목록을 다시 조회하고 모달을 닫는다.
+- 신규 생성/삭제 버튼은 만들지 않는다.
+
+테스트/검증:
+- 목록 조회가 `GET /api/v2/admin/gift-size-prices`를 호출하는지 확인한다.
+- 수정 저장 시 `PUT /api/v2/admin/gift-size-prices/{sizeCode}`와 request body가 정확한지 확인한다.
+- `salePriceCan > basePriceCan`일 때 API를 호출하지 않고 validation 메시지를 표시하는지 확인한다.
+- 저장 성공 후 목록 refresh가 일어나는지 확인한다.
+```
+
+---
+
+## 구현 시 참고할 공통 타입
+
+```ts
+type ApiResponse<T> = {
+  success: boolean;
+  data: T;
+  message?: string;
+};
+
+type GiftStatus =
+  | "RECEIVED"
+  | "TRACKING_REGISTERED"
+  | "ARRIVED_AT_MAILBOX"
+  | "INSPECTION_COMPLETED"
+  | "DELIVERED"
+  | "UNDELIVERABLE"
+  | "CANCELED";
+
+type AdminGiftAction =
+  | "ARRIVE_MAILBOX"
+  | "COMPLETE_INSPECTION"
+  | "COMPLETE_DELIVERY"
+  | "MARK_UNDELIVERABLE";
+
+type GiftSize = "SMALL" | "MEDIUM" | "LARGE";
+```
+
+## 구현 순서 추천
+
+1. API client 함수와 TypeScript 타입을 먼저 추가한다.
+2. `/gift/list` 선물함 리스트와 상세/상태변경 모달을 구현한다.
+3. `/gift/mailbox` 받을 주소 설정 화면을 구현한다.
+4. `/gift/category` 카테고리 CRUD를 구현한다.
+5. `/gift/size` 사이즈 가격 수정 화면을 구현한다.
+6. 기존 관리자 메뉴의 `선물함 관리` 하위 route와 연결되는지 확인한다.
+7. 각 페이지별 loading/empty/error/success 상태를 확인한다.

docs/20260929_크리에이터_선물하기/client-api-summary.md

@@ -0,0 +1,368 @@
+# 선물하기 클라이언트 API 요약
+
+## 문서 목적
+
+- 이 문서는 클라이언트 구현 프롬프트 작성용 빠른 참조다.
+- 상세 request/response 계약은 `prd.md`의 `8. API 계약`을 기준으로 한다.
+- 여기서는 사용자 역할별 URI, 역할, 핵심 request/response 필드만 요약한다.
+
+## 문서 분리 결정
+
+PRD에는 상세 API 계약, request/response 예시, 요구사항을 유지한다. 클라이언트 프롬프트용 역할별 인벤토리는 별도 문서로 둔다.
+
+- 이유: PRD에 같은 URI 정보를 역할별로 다시 넣으면 상세 계약과 요약표를 동시에 갱신해야 한다.
+- 기준: PRD는 제품 요구사항과 API 계약의 원본, 이 문서는 클라이언트 구현을 위한 탐색용 색인이다.
+
+## 공통/조회 API
+
+| 사용자 | Method | URI | 역할 | Request | Response |
+|---|---:|---|---|---|---|
+| 비회원/회원 | GET | `/api/v2/gifts/form-options` | 선물 신청 폼에 필요한 활성 카테고리와 사이즈별 가격 옵션을 조회한다. | 없음 | `sizes[]`, `categories[]` |
+| 팬/크리에이터 | GET | `/api/v2/gifts?type=ALL&page=0&size=20` | 내 선물함 목록을 조회하고 `type=ALL|SENT|RECEIVED`로 전체/보낸/받은 선물을 필터링한다. | query: `type`, `page`, `size` | `items[]`, `page`, `size`, `hasNext` |
+| 팬/크리에이터 | GET | `/api/v2/gifts/{applicationNo}` | 선물 상세를 조회하며 로그인 회원이 팬인지 크리에이터인지에 따라 노출 정보와 CTA flag가 달라진다. | path: `applicationNo` | `applicationNo`, `direction`, `status`, `statusName`, `giftInfo`, `senderInfo`, `recipientAddress`, `mailbox`, `trackingRequired`, `recipientAddressRequired`, `delivery`, `statusTimeline`, `review` |
+
+## 팬 API
+
+| 사용자 | Method | URI | 역할 | Request | Response |
+|---|---:|---|---|---|---|
+| 팬 | POST | `/api/v2/gifts` | 크리에이터에게 선물을 신청하고 최종 결제 금액만큼 캔을 차감한다. | body: `recipientMemberId`, `senderName`, `senderPhoneNumber`, `senderZipCode`, `senderAddress`, `senderAddressDetail`, `sizeCode`, `categoryId`, `senderTermsAgreed`, `senderPrivacyAgreed`, `damageWaiverAgreed` | `applicationNo`, `status`, `statusName`, `priceCan`, `trackingDeadlineAt` |
+| 팬 | POST | `/api/v2/gifts/{applicationNo}/cancel` | 운송장 등록 전 선물 신청을 취소하고 전액 환불한다. | path: `applicationNo` | `applicationNo`, `status`, `statusName`, `priceCan`, `canceledAt` |
+| 팬 | POST | `/api/v2/gifts/{applicationNo}/tracking` | 발송 후 택배사와 운송장 번호를 등록한다. | path: `applicationNo`, body: `courierCompanyName`, `trackingNumber` | `applicationNo`, `status`, `statusName`, `courierCompanyName`, `trackingNumber`, `trackingRegisteredAt`, `recipientAddressDeadlineAt` |
+| 팬 | POST | `/api/v2/gifts/{applicationNo}/review` | 전달 완료된 선물에 리뷰를 작성한다. | path: `applicationNo`, body: `rating`, `keywords`, `comment` | `reviewId`, `applicationNo`, `rating`, `keywords`, `comment`, `createdAt` |
+
+## 크리에이터 API
+
+| 사용자 | Method | URI | 역할 | Request | Response |
+|---|---:|---|---|---|---|
+| 크리에이터 | POST | `/api/v2/gifts/{applicationNo}/recipient-address` | 운송장 등록 이후 배송지와 수령 약관 동의를 등록한다. | path: `applicationNo`, body: `recipientName`, `recipientPhoneNumber`, `recipientZipCode`, `recipientAddress`, `recipientAddressDetail`, `recipientTermsAgreed`, `recipientPrivacyAgreed` | `applicationNo`, `status`, `statusName`, `recipientAddressRegisteredAt` |
+| 크리에이터 | POST | `/api/v2/gifts/{applicationNo}/delivery-complete` | 검수 완료된 선물을 직접 수령 완료 처리한다. | path: `applicationNo` | `applicationNo`, `status`, `statusName`, `deliveredAt` |
+
+## 관리자 API
+
+| 사용자 | Method | URI | 역할 | Request | Response |
+|---|---:|---|---|---|---|
+| 관리자 | GET | `/api/v2/admin/gift-categories` | 선물 카테고리 목록을 조회한다. | 없음 | `AdminGiftCategoryResponse[]` |
+| 관리자 | GET | `/api/v2/admin/gifts` | 전체 선물함 목록을 조회하고 상태/신청번호/닉네임으로 검색한다. | query: `status`, `applicationNo`, `nickname`, `page`, `size` | `totalCount`, `items[]`, `page`, `size`, `hasNext` |
+| 관리자 | GET | `/api/v2/admin/gifts/{applicationNo}` | 선물 상세와 발송인/수취인 개인정보, 상품/배송/상태 정보를 조회한다. | path: `applicationNo` | `applicationNo`, `senderInfo`, `recipientInfo`, `productInfo`, `inboundDeliveryInfo`, `status`, `statusName`, `availableActions` |
+| 관리자 | POST | `/api/v2/admin/gift-categories` | 선물 카테고리를 등록한다. | body: `classificationNumber`, `categoryCode`, `name`, `receiptCode`, `representativeItem`, `requiresDamageWaiver`, `isActive` | `categoryId`, `classificationNumber`, `categoryCode`, `name`, `receiptCode`, `representativeItem`, `requiresDamageWaiver`, `isActive` |
+| 관리자 | PUT | `/api/v2/admin/gift-categories/{categoryId}` | 선물 카테고리를 수정한다. | path: `categoryId`, body: `classificationNumber`, `categoryCode`, `name`, `receiptCode`, `representativeItem`, `requiresDamageWaiver`, `isActive` | `categoryId`, `classificationNumber`, `categoryCode`, `name`, `receiptCode`, `representativeItem`, `requiresDamageWaiver`, `isActive` |
+| 관리자 | DELETE | `/api/v2/admin/gift-categories/{categoryId}` | 선물 카테고리를 비활성화한다. | path: `categoryId` | `categoryId`, `classificationNumber`, `categoryCode`, `name`, `receiptCode`, `representativeItem`, `requiresDamageWaiver`, `isActive=false` |
+| 관리자 | GET | `/api/v2/admin/gift-size-prices` | 사이즈별 기본가와 판매가를 조회한다. | 없음 | `AdminGiftSizePriceResponse[]` |
+| 관리자 | PUT | `/api/v2/admin/gift-size-prices/{sizeCode}` | 사이즈별 기본가와 판매가를 수정한다. | path: `sizeCode`, body: `basePriceCan`, `salePriceCan`, `isActive` | `sizeCode`, `name`, `basePriceCan`, `salePriceCan`, `isActive` |
+| 관리자 | POST | `/api/v2/admin/gifts/{applicationNo}/arrive-mailbox` | 발송 확인 선물을 사서함 도착 처리한다. | path: `applicationNo` | `applicationNo`, `status`, `statusName`, `occurredAt` |
+| 관리자 | POST | `/api/v2/admin/gifts/{applicationNo}/complete-inspection` | 사서함 도착 선물을 검수 완료 처리한다. | path: `applicationNo` | `applicationNo`, `status`, `statusName`, `occurredAt` |
+| 관리자 | POST | `/api/v2/admin/gifts/{applicationNo}/mark-undeliverable` | 진행 중 선물을 전달 불가 처리하고 사유를 저장한다. | path: `applicationNo`, body: `reason` | `applicationNo`, `status`, `statusName`, `occurredAt` |
+| 관리자 | POST | `/api/v2/admin/gifts/{applicationNo}/complete-delivery` | 검수 완료 선물을 운영자가 전달 완료 처리한다. | path: `applicationNo` | `applicationNo`, `status`, `statusName`, `occurredAt` |
+
+관리자 응답 DTO 요약:
+
+- `AdminGiftCategoryResponse`: `categoryId`, `classificationNumber`, `categoryCode`, `name`, `receiptCode`, `representativeItem`, `requiresDamageWaiver`, `isActive`
+- `AdminGiftListResponse`: `totalCount`, `items`, `page`, `size`, `hasNext`
+- `AdminGiftListItemResponse`: `applicationNo`, `senderNickname`, `recipientNickname`, `sizeCode`, `sizeName`, `categoryName`, `classificationNumber`, `courierCompanyName`, `trackingNumber`, `status`, `statusName`, `availableActions`
+- `AdminGiftDetailResponse`: `applicationNo`, `senderInfo`, `recipientInfo`, `productInfo`, `inboundDeliveryInfo`, `status`, `statusName`, `availableActions`
+- `AdminGiftSizePriceResponse`: `sizeCode`, `name`, `basePriceCan`, `salePriceCan`, `isActive`
+- `AdminGiftOperationStatusResponse`: `applicationNo`, `status`, `statusName`, `occurredAt`
+
+## Kotlin DTO 형태
+
+아래는 JSON으로 변환되기 직전의 API request/response `data class` 형태다. `companion object` 변환 함수는 클라이언트 입력/출력 형태와 직접 관련이 없어 생략했다. 응답 시각 필드는 UTC ISO 문자열이다. 예: `2026-09-30T12:00:00Z`.
+
+### 사용자 Request DTO
+
+```kotlin
+data class GiftApplicationRequest(
+    val recipientMemberId: Long,
+    val senderName: String,
+    val senderPhoneNumber: String,
+    val senderZipCode: String,
+    val senderAddress: String,
+    val senderAddressDetail: String?,
+    val sizeCode: GiftSize,
+    val categoryId: Long,
+    val senderTermsAgreed: Boolean,
+    val senderPrivacyAgreed: Boolean,
+    val damageWaiverAgreed: Boolean
+)
+
+data class GiftTrackingRegistrationRequest(
+    val courierCompanyName: String,
+    val trackingNumber: String
+)
+
+data class GiftRecipientAddressRegistrationRequest(
+    val recipientName: String,
+    val recipientPhoneNumber: String,
+    val recipientZipCode: String,
+    val recipientAddress: String,
+    val recipientAddressDetail: String?,
+    val recipientTermsAgreed: Boolean,
+    val recipientPrivacyAgreed: Boolean
+)
+
+data class GiftReviewRequest(
+    val rating: Int,
+    val keywords: List<String>,
+    val comment: String?
+)
+```
+
+### 사용자 Response DTO
+
+```kotlin
+data class GiftFormOptionsResponse(
+    val sizes: List<GiftSizeOptionResponse>,
+    val categories: List<GiftCategoryOptionResponse>
+)
+
+data class GiftSizeOptionResponse(
+    val sizeCode: String,
+    val name: String,
+    val basePriceCan: Int,
+    val salePriceCan: Int
+)
+
+data class GiftCategoryOptionResponse(
+    val categoryId: Long,
+    val name: String,
+    val requiresDamageWaiver: Boolean
+)
+
+// name은 사용자 폼 옵션에서만 "분류명/대표품목" 형태로 조합된다.
+
+data class GiftListResponse(
+    val totalCount: Long,
+    val items: List<GiftListItemResponse>,
+    val page: Int,
+    val size: Int,
+    val hasNext: Boolean
+)
+
+data class GiftListItemResponse(
+    val applicationNo: String,
+    val direction: String,
+    val status: String,
+    val statusName: String,
+    val priceCan: Int,
+    val categoryName: String,
+    val sizeName: String,
+    val createdAt: String?
+)
+
+data class GiftDetailResponse(
+    val applicationNo: String,
+    val direction: String,
+    val status: String,
+    val statusName: String,
+    val giftInfo: GiftDetailInfoResponse,
+    val senderInfo: GiftAddressResponse?,
+    val recipientAddress: GiftAddressResponse?,
+    val mailbox: GiftMailboxResponse?,
+    val trackingRequired: Boolean,
+    val recipientAddressRequired: Boolean,
+    val recipientAddressDeadlineAt: String?,
+    val delivery: GiftDeliveryInfoResponse,
+    val statusTimeline: List<GiftStatusTimelineResponse>
+)
+
+data class GiftDetailInfoResponse(
+    val recipientCreatorNickname: String?,
+    val senderNickname: String?,
+    val sizeName: String,
+    val categoryName: String,
+    val applicationNo: String?,
+    val paidCan: Int?,
+    val tracking: String?,
+    val shippingRequestedAt: String?
+)
+
+data class GiftAddressResponse(
+    val name: String,
+    val phoneNumber: String,
+    val address: String
+)
+
+data class GiftMailboxResponse(
+    val name: String,
+    val address: String,
+    val phoneNumber: String
+)
+
+// mailbox는 direction=SENT이고 status가 RECEIVED, TRACKING_REGISTERED,
+// ARRIVED_AT_MAILBOX, INSPECTION_COMPLETED일 때만 값이 있다.
+// DELIVERED, UNDELIVERABLE, CANCELED 또는 direction=RECEIVED이면 null이다.
+
+data class GiftDeliveryInfoResponse(
+    val canceledAt: String?,
+    val undeliverableAt: String?,
+    val undeliverableReason: String?
+)
+
+data class GiftStatusTimelineResponse(
+    val status: String,
+    val statusName: String,
+    val occurredAt: String?
+)
+
+data class GiftApplicationResponse(
+    val applicationNo: String,
+    val status: String,
+    val statusName: String,
+    val priceCan: Int,
+    val trackingDeadlineAt: String
+)
+
+data class GiftCancellationResponse(
+    val applicationNo: String,
+    val status: String,
+    val statusName: String,
+    val priceCan: Int,
+    val canceledAt: String
+)
+
+data class GiftTrackingRegistrationResponse(
+    val applicationNo: String,
+    val status: String,
+    val statusName: String,
+    val courierCompanyName: String,
+    val trackingNumber: String,
+    val trackingRegisteredAt: String,
+    val recipientAddressDeadlineAt: String
+)
+
+data class GiftRecipientAddressRegistrationResponse(
+    val applicationNo: String,
+    val status: String,
+    val statusName: String,
+    val recipientAddressRegisteredAt: String
+)
+
+data class GiftDeliveryConfirmationResponse(
+    val applicationNo: String,
+    val status: String,
+    val statusName: String,
+    val deliveredAt: String
+)
+
+data class GiftReviewResponse(
+    val reviewId: Long,
+    val applicationNo: String,
+    val rating: Int,
+    val keywords: List<String>,
+    val comment: String?,
+    val createdAt: String?
+)
+```
+
+### 관리자 Request DTO
+
+```kotlin
+data class AdminGiftCategoryRequest(
+    val classificationNumber: String,
+    val categoryCode: String,
+    val name: String,
+    val receiptCode: String,
+    val representativeItem: String,
+    val requiresDamageWaiver: Boolean,
+    val isActive: Boolean
+)
+
+data class AdminGiftSizePriceRequest(
+    val basePriceCan: Int,
+    val salePriceCan: Int,
+    val isActive: Boolean
+)
+
+data class AdminGiftMarkUndeliverableRequest(
+    val reason: String
+)
+```
+
+### 관리자 Response DTO
+
+```kotlin
+data class AdminGiftCategoryResponse(
+    val categoryId: Long,
+    val classificationNumber: String,
+    val categoryCode: String,
+    val name: String,
+    val receiptCode: String,
+    val representativeItem: String,
+    val requiresDamageWaiver: Boolean,
+    val isActive: Boolean
+)
+
+data class AdminGiftListResponse(
+    val totalCount: Long,
+    val items: List<AdminGiftListItemResponse>,
+    val page: Int,
+    val size: Int,
+    val hasNext: Boolean
+)
+
+data class AdminGiftListItemResponse(
+    val applicationNo: String,
+    val senderNickname: String,
+    val recipientNickname: String,
+    val sizeCode: String,
+    val sizeName: String,
+    val categoryName: String,
+    val classificationNumber: String,
+    val courierCompanyName: String?,
+    val trackingNumber: String?,
+    val status: String,
+    val statusName: String,
+    val availableActions: List<String>
+)
+
+data class AdminGiftDetailResponse(
+    val applicationNo: String,
+    val senderInfo: AdminGiftMemberInfoResponse,
+    val recipientInfo: AdminGiftMemberInfoResponse,
+    val productInfo: AdminGiftProductInfoResponse,
+    val inboundDeliveryInfo: AdminGiftInboundDeliveryInfoResponse,
+    val status: String,
+    val statusName: String,
+    val availableActions: List<String>
+)
+
+data class AdminGiftMemberInfoResponse(
+    val nickname: String,
+    val name: String,
+    val phoneNumber: String,
+    val address: String
+)
+
+data class AdminGiftProductInfoResponse(
+    val sizeCode: String,
+    val sizeName: String,
+    val categoryName: String,
+    val classificationNumber: String
+)
+
+data class AdminGiftInboundDeliveryInfoResponse(
+    val courierCompanyName: String?,
+    val trackingNumber: String?
+)
+
+data class AdminGiftSizePriceResponse(
+    val sizeCode: String,
+    val name: String,
+    val basePriceCan: Int,
+    val salePriceCan: Int,
+    val isActive: Boolean
+)
+
+data class AdminGiftOperationStatusResponse(
+    val applicationNo: String,
+    val status: GiftStatus,
+    val statusName: String,
+    val occurredAt: String
+)
+```
+
+## 클라이언트 구현 참고
+
+- 선물 푸시 딥링크는 `deepLinkValue=GIFT_DETAIL`, `deepLinkId=applicationNo`를 사용한다.
+- 딥링크 진입 후에는 `GET /api/v2/gifts/{applicationNo}`로 상세를 조회해 `direction`, `trackingRequired`, `recipientAddressRequired`를 기준으로 화면과 CTA를 결정한다.
+- 운송장 미등록 자동취소는 서버 스케줄러가 처리하며, 팬 클라이언트는 상세 조회의 `status=CANCELED`와 푸시를 기준으로 표시한다.
+- 모든 응답은 기존 `ApiResponse.ok(...)` envelope 안의 `data`로 내려간다.

docs/20260929_크리에이터_선물하기/gift-detail-tracking-page-prompt.md

@@ -0,0 +1,433 @@
+# 보낸 선물 상세 및 운송장 등록 페이지 생성 프롬프트
+
+이 문서는 Android/iOS 앱의 `선물함` 리스트에서 보낸 선물 상세 페이지와 운송장 등록 페이지를 생성할 때 사용하는 프롬프트다.
+
+참고 Figma:
+
+- 선물 보내기 신청 상세 운송장 등록 전 UI: `2481:19011`
+- 선물 보내기 신청 상세 운송장 등록 후 UI: `2481:19152`
+- 선물 보내기 신청 상세 전달 완료 UI: `2481:19320`
+- 전달 불가 UI: `2481:19456`
+- 취소 버튼 다이얼로그 UI: `2481:19500`
+- 취소 완료 페이지 UI: `2481:19521`
+- 운송장 등록 UI: `2481:19066`
+- 운송장 정보를 채우고 난 후 UI: `2481:19109`
+
+전제:
+
+- 선물함 리스트 item 탭 시 `applicationNo`를 전달받아 상세 페이지로 이동한다.
+- 새 디자인 시스템을 만들지 말고 Android/iOS 각각의 기존 디자인 시스템, 컴포넌트, API client, 상태 관리, toast/dialog, navigation 패턴을 재사용한다.
+- 모든 API 응답은 공통 envelope를 사용하며 실제 payload는 `response.data`다.
+- Figma의 진행 상태는 4단계처럼 보이지만 실제 구현은 서버의 `statusTimeline` 5개 상태를 모두 사용한다.
+- 운송장 등록의 택배사 선택지는 서버 API가 없으므로 앱 로컬 상수로 관리한다.
+- 취소 확인 팝업은 앱의 `v2 dialog` 컴포넌트를 기본으로 사용한다.
+
+---
+
+## 모바일 앱 구현 프롬프트
+
+```text
+Android/iOS 앱의 선물 상세 페이지와 운송장 등록 페이지를 Figma 기준으로 생성하고 API 연동을 구현해줘.
+
+범위:
+- 선물함 리스트에서 `applicationNo`를 받아 선물 상세 페이지로 이동한다.
+- 상세 페이지는 `GET /api/v2/gifts/{applicationNo}` 응답으로 렌더링한다.
+- `trackingRequired=true`인 보낸 선물 상세에서는 운송장 등록 CTA를 표시하고 운송장 등록 페이지로 이동한다.
+- 운송장 등록 페이지는 같은 상세 API를 조회해 신청 요약과 보낼 주소를 표시한 뒤 `POST /api/v2/gifts/{applicationNo}/tracking`으로 운송장 정보를 등록한다.
+
+중요 전제:
+- Figma의 visual structure와 문구를 우선 따르되, 상태 개수와 데이터 노출은 API 계약을 우선한다.
+- 상세 진행 단계는 Figma처럼 4단계로 고정하지 말고 API `statusTimeline`의 5개 정상 진행 상태를 모두 렌더링한다.
+- 택배사 목록은 API로 조회하지 않는다. 앱 로컬 상수로 관리하고 선택한 한글 표시명을 `courierCompanyName`으로 전송한다.
+- 운송장 등록 완료 후 수정 기능은 만들지 않는다.
+
+상세 페이지 진입:
+- 선물함 리스트 item에서 받은 `applicationNo`로 진입한다.
+- 화면 진입 시 `GET /api/v2/gifts/{applicationNo}`를 호출한다.
+- 조회 결과 `status=CANCELED`이면 일반 신청 상세 화면을 렌더링하지 말고 취소 완료 페이지 UI를 보여준다.
+- 로딩 중에는 기존 앱 상세 화면 로딩/스켈레톤 패턴을 사용한다.
+- 실패 시 기존 앱 toast/dialog와 재시도 패턴을 사용한다.
+
+상세 페이지 공통 레이아웃:
+1. 상단 고정 내비게이션
+   - 타이틀: `신청 상세`
+   - 뒤로가기 버튼은 기존 앱 패턴을 사용한다.
+2. 스크롤 콘텐츠
+   - 배송 상태 hero
+   - 진행 상태 progress
+   - 상태별 action button 영역
+   - 선물 정보
+   - 필요한 경우 보내는 사람, 받는 사서함, 사유 섹션
+3. 하단 safe area
+   - 기존 앱 패턴을 따른다.
+
+상태별 hero 문구:
+| status | chip | title | body |
+|---|---|---|---|
+| `RECEIVED` | 없음 또는 `접수 완료` | `선물 신청 완료!` | `선물이 정상적으로 접수되었어요!` |
+| `TRACKING_REGISTERED` | `발송 확인` | `사서함으로 이동 중이에요` | 없음 |
+| `ARRIVED_AT_MAILBOX` | `사서함 도착` | `선물이 사서함에 도착했어요` | 없음 |
+| `INSPECTION_COMPLETED` | `검수 완료` | `선물 검수를 완료했어요` | 없음 |
+| `DELIVERED` | `전달 완료` | `크리에이터에게 선물을 전달했어요` | 없음 |
+| `UNDELIVERABLE` | `전달 불가` | `전달할 수 없는 품목입니다` | `보내주신 선물은 SODALIVE 선물 정책에 따라 크리에이터에게 전달할 수 없는 품목으로 확인되었습니다.` |
+| `CANCELED` | `신청 취소` | `선물 신청이 취소되었어요` | `사용한 캔은 환불 처리됩니다.` |
+
+진행 상태 progress:
+- `statusTimeline` 배열을 그대로 사용한다.
+- 항상 아래 5개 단계를 이 순서로 표시한다.
+  1. `RECEIVED`: `신청 접수`
+  2. `TRACKING_REGISTERED`: `발송 확인`
+  3. `ARRIVED_AT_MAILBOX`: `사서함 도착`
+  4. `INSPECTION_COMPLETED`: `검수 완료`
+  5. `DELIVERED`: `전달 완료`
+- `occurredAt`이 있으면 해당 단계는 완료 색상으로 표시하고 `MM.DD`를 표시한다.
+- `occurredAt`이 null이면 비활성 색상으로 표시하고 날짜는 표시하지 않는다.
+- `UNDELIVERABLE`, `CANCELED`는 정상 진행 단계가 아니므로 progress step으로 추가하지 않는다.
+- 종료 상태에서도 `statusTimeline`에 있는 정상 진행 이력은 그대로 표시한다.
+
+상세 페이지 섹션 표시 규칙:
+- `선물 정보`는 항상 표시한다.
+- `direction=SENT`이면 크리에이터명은 `giftInfo.recipientCreatorNickname`을 사용한다.
+- `direction=RECEIVED`이면 보낸 팬명은 `giftInfo.senderNickname`을 사용한다.
+- `senderInfo`가 있으면 `보내는 사람` 섹션을 표시한다.
+- `mailbox`가 있으면 `받는 사서함` 또는 `보내실 주소` 섹션을 표시한다.
+- `recipientAddress`가 있으면 `받는 사람` 또는 `배송지` 섹션을 표시한다.
+- `delivery.undeliverableReason`이 있으면 `사유` 섹션을 표시한다.
+
+선물 정보 표시 필드:
+- 크리에이터 또는 보낸 팬 닉네임
+- 선물 사이즈: `giftInfo.sizeName`
+- 카테고리: `giftInfo.categoryName`
+- 신청번호: `applicationNo` 또는 `giftInfo.applicationNo`
+- 캔: `giftInfo.paidCan`이 null이 아닐 때만 표시
+- 운송장 번호: `giftInfo.tracking`이 null이 아닐 때 표시
+- 검수일: `statusTimeline`에서 `INSPECTION_COMPLETED.occurredAt`이 있으면 표시
+- 전달 완료일: `statusTimeline`에서 `DELIVERED.occurredAt`이 있으면 표시
+- 취소일: `delivery.canceledAt`이 있으면 표시
+
+받는 사서함/보내실 주소 표시:
+- `mailbox.name`을 사서함/받는 분으로 표시한다.
+- `mailbox.address`를 주소로 표시한다.
+- `mailbox.phoneNumber`를 연락처로 표시한다.
+- `mailbox`는 관리자가 등록한 전역 단일 주소다. 상대방 주소가 아니다.
+- `mailbox`는 `direction=SENT`이고 `status`가 `RECEIVED`, `TRACKING_REGISTERED`, `ARRIVED_AT_MAILBOX`, `INSPECTION_COMPLETED`일 때 내려온다.
+- `DELIVERED`, `UNDELIVERABLE`, `CANCELED` 또는 `direction=RECEIVED`에서는 `mailbox=null`이다.
+- `mailbox=null`이면 해당 섹션을 표시하지 않는다.
+
+보내는 사람 표시:
+- `senderInfo.name`
+- `senderInfo.phoneNumber`
+- `senderInfo.address`
+- 이 정보는 보낸 팬 본인이 신청 시 입력한 정보다.
+
+전달 불가 표시:
+- `status=UNDELIVERABLE`이면 Figma `2481:19456` 패턴을 따른다.
+- 사유 섹션의 제목은 `delivery.undeliverableReason`을 사용한다.
+- `delivery.undeliverableReason`이 null이면 사유 섹션 제목은 `전달 불가`로 표시한다.
+- 안내 문구는 `해당 선물은 정책에 따라 폐기되며 반송되지 않습니다.`를 사용한다.
+
+상세 페이지 action:
+- `trackingRequired=true`이면 하단 주요 CTA `운송장 작성하기`를 표시하고 운송장 등록 페이지로 이동한다.
+- `direction=SENT && status=RECEIVED`이면 보조 action `신청 취소`를 표시할 수 있다.
+- 신청 취소 버튼을 누르면 즉시 API를 호출하지 말고 `v2 dialog` 확인 팝업을 먼저 표시한다.
+- `status=DELIVERED && direction=SENT`이면 `리뷰 남기기` 버튼을 표시하고 기존 리뷰 작성 화면/플로우로 이동한다.
+- `문의하기`, `선물 정책 확인` 버튼은 기존 앱에 해당 이동 경로가 있으면 연결하고, 없으면 기존 정책에 맞춰 숨기거나 비활성 처리한다.
+
+신청 취소 확인 다이얼로그:
+- Figma `2481:19500`을 참고한다.
+- 앱의 기본 `v2 dialog` 컴포넌트를 사용한다. 새 dialog 컴포넌트를 만들지 않는다.
+- 제목: `신청 취소`
+- 본문:
+  - `{크리에이터}에게 보내는 선물을 취소할까요?`
+  - `선물 보내기 규정에 따라 선물 취소 및 사용한 캔이 모두 환불됩니다.`
+- 왼쪽 action: `나가기`
+  - dialog만 닫고 상세/운송장 등록 화면 상태를 유지한다.
+- 오른쪽 destructive action: `취소하기`
+  - `POST /api/v2/gifts/{applicationNo}/cancel`을 호출한다.
+  - 호출 중에는 중복 탭을 막고 loading 상태를 표시한다.
+  - 실패 시 dialog를 닫지 말고 기존 앱 에러 toast/dialog 패턴으로 안내한다.
+  - 성공 시 취소 완료 페이지로 replace navigation 한다.
+
+취소 완료 페이지:
+- Figma `2481:19521`을 참고한다.
+- 취소 API 성공 직후뿐 아니라 상세 페이지 접근 시 `GET /api/v2/gifts/{applicationNo}` 응답이 `status=CANCELED`인 경우에도 이 화면을 보여준다.
+- 상단 타이틀: `취소 완료`
+- hero chip: `취소 완료`
+- hero title: `선물 신청이 취소되었어요`
+- hero body: `{크리에이터}에게 보내는 선물 신청({applicationNo})이 취소되었습니다. 취소한 신청은 되돌릴 수 없으며, 다시 보내려면 새로 신청해 주세요.`
+- 섹션 제목: `취소 상세`
+- 취소 상세 카드 표시 필드:
+  - 크리에이터: `giftInfo.recipientCreatorNickname`
+  - 선물 사이즈: `giftInfo.sizeName`
+  - 카테고리: `giftInfo.categoryName`
+  - 신청번호: `applicationNo`
+  - 신청일: `statusTimeline`의 `RECEIVED.occurredAt`
+  - 취소일: 취소 API response의 `canceledAt` 또는 상세 API 조회 시 `delivery.canceledAt`
+  - 환불 캔: 취소 API response의 `priceCan` 또는 상세 API의 `giftInfo.paidCan`
+- 하단 또는 카드 아래에 `문의하기` 버튼을 표시한다.
+- 뒤로가기 동작은 취소 전 상세/운송장 등록 화면으로 돌아가지 않게 한다. 기존 앱 navigation 정책에 맞춰 선물함 리스트 또는 이전 안전 화면으로 이동한다.
+
+운송장 등록 페이지 진입:
+- 상세 페이지에서 `trackingRequired=true`일 때만 진입시킨다.
+- 진입 시 `GET /api/v2/gifts/{applicationNo}`를 다시 조회한다.
+- 조회 결과에서 `trackingRequired=false`이면 이미 등록 불가 상태이므로 기존 오류 처리 후 상세 페이지로 돌아간다.
+
+운송장 등록 페이지 레이아웃:
+1. 상단 고정 내비게이션
+   - 타이틀: `운송장 등록`
+2. 신청 건 요약 카드
+   - `applicationNo`
+   - 크리에이터 닉네임: `giftInfo.recipientCreatorNickname`
+   - `giftInfo.sizeName · giftInfo.categoryName · 신청일`
+   - 신청일은 `statusTimeline`의 `RECEIVED.occurredAt`을 `YYYY.MM.DD`로 표시한다.
+3. 보내실 주소
+   - `mailbox`를 사용한다.
+   - `mailbox=null`이면 운송장 등록을 막고 `받을 주소가 등록되어 있지 않습니다.` 오류를 표시한다.
+4. 운송장 정보
+   - 택배사 select
+   - 운송장 번호 input
+5. 등록 안내
+   - Figma의 안내 문구를 유지한다.
+6. 하단 action bar
+   - 왼쪽: `신청 취소`
+   - 오른쪽: `등록 완료`
+
+택배사 로컬 상수:
+- 서버에서 택배사 옵션을 조회하지 않는다.
+- 앱에 아래 로컬 옵션을 둔다. 이미 앱 공통 택배사 상수가 있으면 그것을 우선 사용한다.
+```ts
+const giftCourierCompanyNames = [
+  "CJ대한통운",
+  "우체국택배",
+  "GS25 편의점택배",
+  "CU 편의점택배",
+  "한진택배",
+  "롯데택배",
+  "로젠택배",
+  "경동택배",
+  "대신택배",
+  "일양로지스",
+  "천일택배",
+  "합동택배",
+  "건영택배",
+  "농협택배"
+];
+```
+- 선택 UI는 기존 앱의 bottom sheet, picker, dialog 중 이미 쓰는 방식을 사용한다.
+- API에는 선택된 한글 표시명을 그대로 `courierCompanyName`으로 보낸다.
+
+운송장 등록 CTA 활성 조건:
+- 택배사를 선택했다.
+- 운송장 번호를 입력했다.
+- 운송장 번호는 공백만 입력할 수 없다.
+- submit 중에는 중복 탭을 막고 loading 상태를 표시한다.
+- 비활성 상태는 Figma `2481:19066`, 활성 상태는 Figma `2481:19109`를 따른다.
+
+운송장 등록 성공 처리:
+- `POST /api/v2/gifts/{applicationNo}/tracking` 성공 후 성공 toast를 표시한다.
+- 상세 페이지로 돌아가거나 replace navigation으로 상세 페이지를 다시 연다.
+- 상세 페이지는 `GET /api/v2/gifts/{applicationNo}`를 다시 호출해 `TRACKING_REGISTERED` 상태를 표시한다.
+
+API 명세:
+
+선물 상세 조회:
+- Method: `GET`
+- URL: `/api/v2/gifts/{applicationNo}`
+- 인증: 로그인 필요
+- Response envelope 예시:
+```json
+{
+  "success": true,
+  "data": {
+    "applicationNo": "A-1002609300001",
+    "direction": "SENT",
+    "status": "RECEIVED",
+    "statusName": "접수 완료",
+    "giftInfo": {
+      "recipientCreatorNickname": "달빛수집가",
+      "senderNickname": null,
+      "sizeName": "소형",
+      "categoryName": "잡화",
+      "applicationNo": "A-1002609300001",
+      "paidCan": 100,
+      "tracking": null,
+      "shippingRequestedAt": null
+    },
+    "senderInfo": {
+      "name": "김소다",
+      "phoneNumber": "01012345678",
+      "address": "(04030) 서울특별시 마포구 양화로 000, 3층"
+    },
+    "recipientAddress": null,
+    "mailbox": {
+      "name": "소다라이브 사서함",
+      "address": "(06174) 서울특별시 강남구 테헤란로108길 8, 유민빌딩 4층",
+      "phoneNumber": "02-2055-1477"
+    },
+    "trackingRequired": true,
+    "recipientAddressRequired": false,
+    "recipientAddressDeadlineAt": null,
+    "delivery": {
+      "canceledAt": null,
+      "undeliverableAt": null,
+      "undeliverableReason": null
+    },
+    "statusTimeline": [
+      {
+        "status": "RECEIVED",
+        "statusName": "접수 완료",
+        "occurredAt": "2026-09-18T03:00:00Z"
+      },
+      {
+        "status": "TRACKING_REGISTERED",
+        "statusName": "발송 확인",
+        "occurredAt": null
+      },
+      {
+        "status": "ARRIVED_AT_MAILBOX",
+        "statusName": "사서함 도착",
+        "occurredAt": null
+      },
+      {
+        "status": "INSPECTION_COMPLETED",
+        "statusName": "검수완료",
+        "occurredAt": null
+      },
+      {
+        "status": "DELIVERED",
+        "statusName": "전달완료",
+        "occurredAt": null
+      }
+    ]
+  },
+  "message": ""
+}
+```
+
+Response `data` 필드:
+
+| 필드 | 타입 | 설명 |
+|---|---|---|
+| `applicationNo` | string | 선물 신청번호 |
+| `direction` | string | `SENT` 또는 `RECEIVED` |
+| `status` | string | 선물 상태 코드 |
+| `statusName` | string | 서버 상태 표시명 |
+| `giftInfo` | object | 선물 기본 정보 |
+| `giftInfo.recipientCreatorNickname` | string 또는 null | 보낸 선물 관점에서 받는 크리에이터 닉네임 |
+| `giftInfo.senderNickname` | string 또는 null | 받은 선물 관점에서 보낸 팬 닉네임 |
+| `giftInfo.sizeName` | string | 선물 사이즈명 |
+| `giftInfo.categoryName` | string | 카테고리명 |
+| `giftInfo.applicationNo` | string 또는 null | 보낸 선물 관점 신청번호 |
+| `giftInfo.paidCan` | number 또는 null | 보낸 선물 관점 사용 캔 |
+| `giftInfo.tracking` | string 또는 null | 운송장 표시 문자열. 예: `한진택배_123456789012` |
+| `giftInfo.shippingRequestedAt` | string 또는 null | 받은 선물 관점 배송신청일. UTC ISO 문자열 |
+| `senderInfo` | object 또는 null | 보낸 팬 본인이 신청 시 입력한 보내는 사람 정보 |
+| `senderInfo.name` | string | 이름 |
+| `senderInfo.phoneNumber` | string | 휴대폰 번호 |
+| `senderInfo.address` | string | `(우편번호) 주소, 상세주소` 형식 주소 |
+| `recipientAddress` | object 또는 null | 받는 크리에이터 본인이 입력한 배송지 |
+| `mailbox` | object 또는 null | 관리자가 등록한 전역 선물 받을 주소. 보낸 선물의 `DELIVERED` 전 정상 진행 상태에서만 값이 있다 |
+| `mailbox.name` | string | 사서함/받는 분 이름 |
+| `mailbox.address` | string | `(우편번호) 주소, 상세주소` 형식 주소 |
+| `mailbox.phoneNumber` | string | 연락처 |
+| `trackingRequired` | boolean | 보낸 팬이 운송장 등록을 해야 하는 상태인지 여부 |
+| `recipientAddressRequired` | boolean | 받는 크리에이터가 배송지를 입력해야 하는 상태인지 여부 |
+| `recipientAddressDeadlineAt` | string 또는 null | 배송지 입력 마감일. UTC ISO 문자열 |
+| `delivery.canceledAt` | string 또는 null | 취소일. UTC ISO 문자열 |
+| `delivery.undeliverableAt` | string 또는 null | 전달 불가 처리일. UTC ISO 문자열 |
+| `delivery.undeliverableReason` | string 또는 null | 전달 불가 사유 |
+| `statusTimeline` | array | 정상 진행 5단계 타임라인 |
+| `statusTimeline[].status` | string | 단계 상태 코드 |
+| `statusTimeline[].statusName` | string | 단계 표시명 |
+| `statusTimeline[].occurredAt` | string 또는 null | 해당 단계 도달 시각. UTC ISO 문자열 |
+
+운송장 등록:
+- Method: `POST`
+- URL: `/api/v2/gifts/{applicationNo}/tracking`
+- 인증: 로그인 필요
+- Request:
+```json
+{
+  "courierCompanyName": "한진택배",
+  "trackingNumber": "123456789012"
+}
+```
+- Response envelope 예시:
+```json
+{
+  "success": true,
+  "data": {
+    "applicationNo": "A-1002609300001",
+    "status": "TRACKING_REGISTERED",
+    "statusName": "발송 확인",
+    "courierCompanyName": "한진택배",
+    "trackingNumber": "123456789012",
+    "trackingRegisteredAt": "2026-09-19T03:00:00Z",
+    "recipientAddressDeadlineAt": "2026-09-26T03:00:00Z"
+  },
+  "message": ""
+}
+```
+
+운송장 등록 response `data` 필드:
+
+| 필드 | 타입 | 설명 |
+|---|---|---|
+| `applicationNo` | string | 선물 신청번호 |
+| `status` | string | 등록 후 상태. `TRACKING_REGISTERED` |
+| `statusName` | string | 서버 상태 표시명 |
+| `courierCompanyName` | string | 선택한 택배사 한글명 |
+| `trackingNumber` | string | 운송장 번호 |
+| `trackingRegisteredAt` | string | 운송장 등록일. UTC ISO 문자열 |
+| `recipientAddressDeadlineAt` | string | 크리에이터 배송지 입력 마감일. UTC ISO 문자열 |
+
+선물 보내기 취소:
+- Method: `POST`
+- URL: `/api/v2/gifts/{applicationNo}/cancel`
+- Request: 없음
+- 용도: `direction=SENT && status=RECEIVED`에서만 `신청 취소` action에 사용한다.
+- Response envelope 예시:
+```json
+{
+  "success": true,
+  "data": {
+    "applicationNo": "A-1002609300001",
+    "status": "CANCELED",
+    "statusName": "신청 취소",
+    "priceCan": 100,
+    "canceledAt": "2026-09-18T04:00:00Z"
+  },
+  "message": ""
+}
+```
+
+선물 보내기 취소 response `data` 필드:
+
+| 필드 | 타입 | 설명 |
+|---|---|---|
+| `applicationNo` | string | 선물 신청번호 |
+| `status` | string | 취소 후 상태. `CANCELED` |
+| `statusName` | string | 서버 상태 표시명 |
+| `priceCan` | number | 환불되는 캔 수량 |
+| `canceledAt` | string | 취소일. UTC ISO 문자열 |
+
+테스트/검증:
+- 리스트 item 탭 시 `applicationNo`로 상세 페이지가 열리는지 확인한다.
+- 상세 진입 시 `GET /api/v2/gifts/{applicationNo}`가 호출되는지 확인한다.
+- 상세 조회 결과 `status=CANCELED`이면 일반 상세가 아니라 취소 완료 페이지가 표시되는지 확인한다.
+- `statusTimeline` 5개 단계가 모두 표시되는지 확인한다.
+- Figma처럼 4단계로 하드코딩하지 않았는지 확인한다.
+- `trackingRequired=true`이면 `운송장 작성하기`가 표시되는지 확인한다.
+- 신청 취소 버튼 탭 시 `v2 dialog` 확인 팝업이 뜨고 즉시 API를 호출하지 않는지 확인한다.
+- 취소 확인 dialog에서 `나가기`를 누르면 dialog만 닫히는지 확인한다.
+- 취소 확인 dialog에서 `취소하기`를 누르면 `POST /api/v2/gifts/{applicationNo}/cancel`을 호출하는지 확인한다.
+- 취소 성공 후 취소 완료 페이지가 표시되고 취소 전 상세/등록 화면으로 돌아가지 않는지 확인한다.
+- `mailbox`가 있을 때만 사서함 주소 섹션이 표시되는지 확인한다.
+- `direction=SENT`의 `RECEIVED`, `TRACKING_REGISTERED`, `ARRIVED_AT_MAILBOX`, `INSPECTION_COMPLETED` 상태에서 `mailbox`가 표시되는지 확인한다.
+- `DELIVERED`, `UNDELIVERABLE`, `CANCELED`, `direction=RECEIVED`에서는 `mailbox`가 표시되지 않는지 확인한다.
+- `UNDELIVERABLE`이면 전달 불가 hero와 사유 섹션이 표시되는지 확인한다.
+- 운송장 등록 페이지에서 택배사/운송장 번호 누락 시 API를 호출하지 않는지 확인한다.
+- 운송장 등록 시 선택한 택배사 한글명과 운송장 번호가 request body로 전송되는지 확인한다.
+- 운송장 등록 성공 후 상세 페이지가 재조회되어 `TRACKING_REGISTERED` 상태로 보이는지 확인한다.
+- 모든 날짜는 UTC ISO 문자열을 앱 표시 형식으로 변환해 표시하는지 확인한다.
+```

docs/20260929_크리에이터_선물하기/gift-list-page-prompt.md

@@ -0,0 +1,274 @@
+# 선물함 리스트 페이지 생성 프롬프트
+
+이 문서는 Android/iOS 앱의 `선물함` 리스트 페이지를 생성할 때 사용하는 프롬프트다.
+
+참고 Figma:
+
+- 팬 모드, 신청한 내역이 있을 때: `2481:19382`
+- 팬 모드, 신청한 내역이 없을 때: `2520:35587`
+- 크리에이터 모드, 받은 선물 내역이 없을 때: `2531:36283`
+- 크리에이터 모드, 받은 선물 내역이 있을 때: `2531:36194`
+- 크리에이터 모드, 받은 선물 상태별 카드 표시: `2531:36237`
+
+전제:
+
+- Android/iOS 각각의 기존 디자인 시스템, 컴포넌트, API client, 상태 관리, toast/dialog, navigation 패턴을 재사용한다.
+- Figma의 visual structure를 기준으로 구현하되, 아래 사용자 요구사항을 Figma보다 우선한다.
+- 상단 뒤로가기 내비게이션 영역은 고정한다.
+- 상단 뒤로가기 내비게이션 영역을 제외한 전체 콘텐츠 영역은 스크롤되어야 한다.
+- `신청 내역`, `선물 내역` 섹션 타이틀은 표시하지 않는다.
+- 리스트는 신청일/취소일 최신순으로 보여야 한다.
+- request/response 설명은 모바일 공통 JSON 기준이다.
+
+---
+
+## 모바일 앱 구현 프롬프트
+
+```text
+Android/iOS 앱의 선물함 리스트 페이지를 Figma 기준으로 생성하고 API 연동을 구현해줘.
+
+Figma는 두 관점의 상태를 보여준다.
+- 보낸 선물 관점: 사용자가 본인이 신청한 선물 내역을 확인하는 상태다. Figma `2481:19382`, `2520:35587`를 기준으로 한다.
+- 받은 선물 관점: 사용자가 본인이 받을 선물 내역을 확인하는 상태다. Figma `2531:36283`, `2531:36194`, `2531:36237`를 기준으로 한다.
+- 실제 선물함 API는 두 관점을 나누어 호출하지 않고 `type=ALL`로 한 번 호출한다.
+- 응답 item의 `direction` 값이 `SENT`이면 보낸 선물 카드로, `RECEIVED`이면 받은 선물 카드로 렌더링한다.
+- 각 카드에는 상대방 프로필 이미지와 닉네임을 표시한다.
+  - `direction=SENT`: 상대방은 선물을 받는 크리에이터다.
+  - `direction=RECEIVED`: 상대방은 선물을 보낸 팬이다.
+
+중요 요구사항:
+- 상단 뒤로가기 내비게이션은 고정한다.
+- 상단 내비게이션 아래의 전체 콘텐츠만 스크롤되게 한다.
+- Figma에 보이는 `신청 내역`, `선물 내역` 섹션 타이틀은 실제 구현에서 표시하지 않는다.
+- 선물함 리스트는 신청일/취소일 최신순으로 정렬한다.
+- 현재 API 응답만으로 취소일 기준 정렬/표시는 완전하지 않으므로, API가 취소일을 내려주지 않으면 서버 응답 순서를 우선 사용하고 취소 건 날짜 라벨은 `createdAt` 기준으로 표시한다. 취소일 표시가 필수이면 API 보강이 필요하다.
+
+API 호출:
+- 선물함 리스트는 항상 `GET /api/v2/gifts?type=ALL&page=0&size=20`로 조회한다.
+- `SENT`, `RECEIVED`로 따로 호출하지 않는다.
+- `items[].direction`으로 보낸 선물/받은 선물 UI를 결정한다.
+- 페이지 진입 시 첫 페이지를 조회한다.
+- `hasNext=true`이면 스크롤 하단에서 다음 page를 추가 조회한다.
+- pull-to-refresh가 기존 앱에 있으면 page를 0으로 초기화하고 다시 조회한다.
+
+공통 레이아웃:
+1. 상단 고정 내비게이션
+   - 타이틀: `선물함`
+   - 뒤로가기 버튼은 기존 앱 패턴을 사용한다.
+   - 이 영역은 스크롤되지 않는다.
+
+2. 스크롤 콘텐츠
+   - nav 아래부터 시작한다.
+   - 안내 배너, 빈 상태, 리스트, 하단 여백 또는 하단 문의 버튼까지 스크롤 영역에 포함한다.
+   - iOS safe area와 Android navigation bar 여백은 기존 앱 패턴을 따른다.
+
+보낸 선물 UI:
+- `direction=SENT`인 item에 적용한다.
+- 사용자가 신청한 선물 내역을 보여준다.
+- 보낸 선물만 있는 상태는 Figma `2481:19382`를 따른다.
+- 상단 안내 배너를 표시한다.
+  - 제목: `사서함을 통해 안전하게 전달됩니다`
+  - 본문: `크리에이터 및 팬의 주소는 공개되지 않습니다. 선물은 소다라이브 사서함에 도착한 뒤 크리에이터에게 전달됩니다.`
+- `신청 내역` 섹션 타이틀은 표시하지 않는다.
+- 카드 구성:
+  - 상단 왼쪽: `statusName`
+  - 상단 오른쪽: 날짜 라벨
+    - 기본: `{createdAt} 신청`
+    - 상태가 `CANCELED`이고 취소일 필드가 있으면 `{canceledAt} 취소`
+    - 현재 리스트 API에는 `canceledAt`이 없으므로 기존 API만 사용할 때는 `{createdAt} 취소` 또는 `{createdAt} 신청` 중 제품 정책에 맞춰 하나로 통일한다.
+  - 프로필 row 내부: `counterpartProfileImageUrl`, `counterpartNickname`을 사용해 받는 크리에이터 프로필을 표시한다.
+  - 프로필 row 아래 보조 문구: `sizeName · categoryName`
+  - 프로필 이미지가 없으면 기존 앱의 기본 프로필 이미지를 표시한다.
+  - 우측 chevron
+  - 탭 시 선물 상세 페이지로 이동하며 `applicationNo`를 전달한다.
+- 리스트가 비어 있고 보낸 선물 관점으로 진입한 화면이면 Figma `2520:35587`를 따른다.
+  - 상단 안내 배너만 표시한다.
+  - 별도 empty title/body를 추가하지 않는다.
+
+받은 선물 UI:
+- `direction=RECEIVED`인 item에 적용한다.
+- 사용자가 받을 선물 내역을 보여준다.
+- 리스트가 비어 있고 받은 선물 관점으로 진입한 화면이면 Figma `2531:36283`를 따른다.
+  - 가운데 empty title: `전달 예정인 선물이 없어요`
+  - empty body: `베타 기간에는 팬이 선물을 보내는 기능만 제공돼요. 더 다양해진 선물 기능으로 곧 다시 만나요!`
+  - 버튼: `의견 남기기`
+  - 의견 남기기 동작은 기존 앱의 문의/피드백 이동 패턴을 사용한다.
+- 받은 선물이 있는 상태는 Figma `2531:36194`, `2531:36237`를 따른다.
+- 상단 안내 배너를 표시한다.
+  - 제목: `배송지 입력 기간 안내`
+  - 본문: `알림을 받은 날부터 7일 이내에 배송지를 입력해 주세요. 기한 내 입력하지 않으면 선물이 반송됩니다.`
+- `선물 내역` 섹션 타이틀은 표시하지 않는다.
+- 배송지 입력이 필요한 선물이 있으면 파란 안내 배너를 리스트 상단에 표시한다.
+  - 제목: `팬이 보낸 선물이 있어요!`
+  - 본문: `선물이 늦지 않게 전달될 수 있도록 배송지를 입력해 주세요.`
+  - 보조 문구: `*n일 이내로 입력하지 않으면 선물이 사라져요.`
+  - 현재 리스트 API에는 배송지 입력 마감일이 없으므로 정확한 n일 계산이 필요하면 API 보강이 필요하다.
+  - 배너 탭 시 배송지 입력이 필요한 첫 번째 선물 상세로 이동한다.
+- 카드 구성:
+  - 상단 왼쪽 프로필 row 내부: `counterpartProfileImageUrl`, `counterpartNickname`을 사용해 보낸 팬 프로필을 표시한다.
+  - 상단 오른쪽: `{createdAt} 신청`
+  - 본문 메인: 상태 표시 문구
+  - 본문 서브: 상태 보조 문구가 필요한 경우만 표시
+  - 우측 chevron
+  - 탭 시 선물 상세 페이지로 이동하며 `applicationNo`를 전달한다.
+- 리스트 하단에는 Figma처럼 `문의하기` 하단 버튼을 둘 수 있다. 기존 앱 정책상 고정 버튼이면 하단 safe area를 포함하고, 스크롤 콘텐츠 내부 버튼이면 콘텐츠 하단에 둔다.
+
+상태 표시 매핑:
+
+보낸 선물 카드:
+| API status | 표시 문구 |
+|---|---|
+| `RECEIVED` | `운송장 등록 필요` |
+| `TRACKING_REGISTERED` | `발송 확인` |
+| `ARRIVED_AT_MAILBOX` | `사서함 도착` |
+| `INSPECTION_COMPLETED` | `선물 검수 완료` |
+| `DELIVERED` | `전달 완료` |
+| `UNDELIVERABLE` | `전달 불가` |
+| `CANCELED` | `신청 취소` |
+
+받은 선물 카드:
+| API status | 메인 문구 | 서브 문구 |
+|---|---|---|
+| `TRACKING_REGISTERED` | `배송지 입력 필요` | `전달 예정` |
+| `ARRIVED_AT_MAILBOX` | `선물 검수` | `선물 확인 중` |
+| `INSPECTION_COMPLETED` | `선물 검수 완료` | `배송 중` |
+| `DELIVERED` | `전달 완료` | 없음 |
+| `UNDELIVERABLE` | `전달 불가` | 없음 |
+
+API 명세:
+
+선물함 리스트 조회 API:
+- Method: `GET`
+- URL: `/api/v2/gifts`
+- 인증: 로그인 필요
+- Query:
+  - `type`: `ALL`, `SENT`, `RECEIVED`
+  - `page`: 0부터 시작
+  - `size`: 페이지 크기. 기본 20
+- 이 페이지에서는 `type=ALL`만 사용한다.
+- Response envelope 예시:
+```json
+{
+  "success": true,
+  "data": {
+    "totalCount": 1,
+    "items": [],
+    "page": 0,
+    "size": 20,
+    "hasNext": false
+  },
+  "message": ""
+}
+```
+
+Response `data` 예시:
+```json
+{
+  "totalCount": 2,
+  "items": [
+    {
+      "applicationNo": "A-1002609300001",
+      "direction": "SENT",
+      "status": "RECEIVED",
+      "statusName": "접수 완료",
+      "priceCan": 80,
+      "categoryName": "아크릴/스탠드",
+      "sizeName": "소형",
+      "counterpartMemberId": 200,
+      "counterpartNickname": "달빛수집가",
+      "counterpartProfileImageUrl": "https://example.com/profile.png",
+      "createdAt": "2026-09-18T03:00:00Z"
+    }
+  ],
+  "page": 0,
+  "size": 20,
+  "hasNext": false
+}
+```
+
+Response `data` 필드:
+
+| 필드 | 타입 | 설명 |
+|---|---|---|
+| `totalCount` | number | 전체 개수 |
+| `items` | array | 선물함 리스트 |
+| `items[].applicationNo` | string | 선물 신청번호. 상세 이동 ID |
+| `items[].direction` | string | `SENT` 또는 `RECEIVED` |
+| `items[].status` | string | 선물 상태 코드 |
+| `items[].statusName` | string | 서버 상태 표시명 |
+| `items[].priceCan` | number | 사용된 캔 |
+| `items[].categoryName` | string | 카테고리명 |
+| `items[].sizeName` | string | 사이즈명 |
+| `items[].counterpartMemberId` | number | 상대방 회원 ID. `SENT`에서는 받는 크리에이터, `RECEIVED`에서는 보낸 팬 |
+| `items[].counterpartNickname` | string | 상대방 닉네임 |
+| `items[].counterpartProfileImageUrl` | string 또는 null | 상대방 프로필 이미지 URL. 없으면 기본 프로필 이미지 표시 |
+| `items[].createdAt` | string 또는 null | 신청일. UTC ISO 문자열 |
+| `page` | number | 현재 페이지 |
+| `size` | number | 페이지 크기 |
+| `hasNext` | boolean | 다음 페이지 존재 여부 |
+
+정렬:
+- 현재 서버 API는 `createdAt desc, id desc`로 정렬한다.
+- 요구사항은 신청일/취소일 최신순이다.
+- 취소일 최신순까지 정확히 맞추려면 리스트 API가 `canceledAt` 또는 `displayedAt` 같은 정렬 기준 시각을 내려주고 그 기준으로 정렬해야 한다.
+- API 보강 전에는 서버 응답 순서를 그대로 사용하고, 클라이언트에서 임의 재정렬하지 않는다.
+
+상대방 프로필 표시 규칙:
+- `counterpartNickname`은 카드의 프로필 row 이름으로 표시한다.
+- `counterpartProfileImageUrl`이 있으면 해당 이미지를 원형 프로필 이미지로 표시한다.
+- `counterpartProfileImageUrl`이 `null`이거나 빈 값이면 기존 앱의 기본 프로필 이미지를 표시한다.
+- `direction=SENT`에서는 받는 크리에이터 정보로 해석한다.
+- `direction=RECEIVED`에서는 보낸 팬 정보로 해석한다.
+
+현재 API만으로 부족한 Figma 표시값:
+- 취소일 `canceledAt`
+- 배송지 입력 마감일 또는 남은 일수
+
+추가 API 보강이 가능하면 리스트 item에 아래 필드를 추가해달라고 요청한다.
+```json
+{
+  "canceledAt": "2026-09-18T03:00:00Z",
+  "recipientAddressDeadlineAt": "2026-09-25T03:00:00Z",
+  "sortAt": "2026-09-18T03:00:00Z"
+}
+```
+- `canceledAt`: 취소 상태의 취소일 표시용
+- `recipientAddressDeadlineAt`: 크리에이터 배송지 입력 안내 배너의 남은 일수 계산용
+- `sortAt`: 신청/취소 최신순 정렬 기준. 취소 건은 취소일, 그 외에는 신청일
+
+로딩/에러/빈 상태:
+- 최초 로딩 중에는 기존 앱 리스트 스켈레톤 또는 loading 패턴을 사용한다.
+- 실패 시 기존 앱 toast/dialog와 재시도 버튼을 사용한다.
+- 빈 상태는 진입 관점에 따라 다르게 표시한다.
+- 보낸 선물 관점으로 진입한 화면이면 안내 배너만 남긴다.
+- 받은 선물 관점으로 진입한 화면이면 중앙 empty UI와 `의견 남기기` 버튼을 표시한다.
+
+테스트/검증:
+- 선물함 진입 시 `type=ALL`로 API를 한 번 호출하는지 확인한다.
+- `direction=SENT` item은 보낸 선물 카드 UI로 표시되는지 확인한다.
+- `direction=RECEIVED` item은 받은 선물 카드 UI로 표시되는지 확인한다.
+- 각 item의 `counterpartNickname`, `counterpartProfileImageUrl`이 프로필 row에 표시되는지 확인한다.
+- `counterpartProfileImageUrl=null`이면 기본 프로필 이미지가 표시되는지 확인한다.
+- 상단 내비게이션은 고정되고 아래 콘텐츠만 스크롤되는지 확인한다.
+- `신청 내역`, `선물 내역` 텍스트가 실제 화면에 노출되지 않는지 확인한다.
+- 리스트 item 탭 시 `applicationNo`로 상세 화면 이동이 되는지 확인한다.
+- 빈 상태가 진입 관점에 맞는 Figma 기준으로 표시되는지 확인한다.
+- `hasNext=true`일 때 다음 page를 추가 조회하는지 확인한다.
+- API 실패 시 입력/스크롤 상태를 깨지 않고 오류와 재시도를 제공하는지 확인한다.
+```
+
+---
+
+## API 요약
+
+| 목적 | Method | URL | Query | Response data |
+|---|---|---|---|---|
+| 선물함 리스트 조회 | GET | `/api/v2/gifts` | `type=ALL`, `page`, `size` | 선물 리스트, 페이지 정보 |
+
+## Figma 반영 메모
+
+- 보낸 선물 리스트 있음: 안내 배너 + 카드 리스트. 단, 실제 구현에서는 `신청 내역` 타이틀을 제거한다.
+- 보낸 선물 관점 empty: 안내 배너만 표시한다.
+- 받은 선물 관점 empty: 중앙 empty UI와 `의견 남기기` 버튼을 표시한다.
+- 받은 선물 리스트 있음: 안내 배너 + 배송지 입력 CTA 배너 + 카드 리스트. 단, 실제 구현에서는 `선물 내역` 타이틀을 제거한다.
+- 받은 선물 상태별 카드는 `배송지 입력 완료/전달 예정`, `전달 완료`, `전달 불가`, `선물 검수/선물 확인 중`, `선물 검수 완료/배송 중` 패턴을 사용한다.

docs/20260929_크리에이터_선물하기/gift-mailbox-admin-page-prompt.md

@@ -0,0 +1,114 @@
+# 선물 받을 주소 관리자 페이지 구현 프롬프트
+
+이 문서는 관리자 페이지에서 전역 선물 받을 주소를 등록/수정하는 화면을 구현할 때 사용하는 프롬프트다.
+
+## 전제
+
+- 여기서 말하는 `선물 받을 주소`는 선물 상대방 주소가 아니다.
+- 관리자가 등록하는 전역 단일 주소다.
+- 팬이 보낸 선물 상세를 정상 진행 상태 중 전달 완료 전(`RECEIVED`, `TRACKING_REGISTERED`, `ARRIVED_AT_MAILBOX`, `INSPECTION_COMPLETED`)에 조회할 때, 이 주소가 `mailbox`로 노출된다.
+- 새 디자인 시스템을 만들지 말고 기존 관리자 페이지의 폼, 버튼, 토스트, 에러 표시 패턴을 재사용한다.
+
+## 구현 프롬프트
+
+```text
+관리자 선물 받을 주소 설정 페이지를 구현해줘.
+
+목표:
+- 관리자 메뉴 `선물함 관리 > 받을 주소`에서 팬이 선물을 보낼 전역 단일 주소를 조회하고 저장한다.
+- 이 주소는 상대방 주소가 아니라 관리자가 등록하는 운영 주소다.
+- 팬의 선물 상세 API에서는 `direction=SENT`이고 `status`가 `RECEIVED`, `TRACKING_REGISTERED`, `ARRIVED_AT_MAILBOX`, `INSPECTION_COMPLETED`일 때 이 주소가 `mailbox`로 노출된다.
+- 기존 관리자 페이지의 폼, 저장 버튼, 토스트, 에러 표시 패턴을 그대로 따른다.
+
+라우트:
+- `/gift/mailbox`
+
+메뉴:
+- parent: `선물함 관리`
+- label: `받을 주소`
+- path: `/gift/mailbox`
+
+필수 화면 구성:
+- 상단 제목: `받을 주소`
+- 설명 문구: `팬이 선물을 발송할 때 확인하는 받을 주소입니다.`
+- 입력 폼:
+  - 받을 사람 이름 `name`
+  - 연락처 `phoneNumber`
+  - 우편번호 `zipCode`
+  - 주소 `address`
+  - 상세주소 `addressDetail`
+- 저장 버튼: `저장`
+
+초기 조회 API:
+- Method: `GET`
+- URL: `/api/v2/admin/gift-mailbox`
+- 모든 API 응답은 기존 공통 envelope를 사용한다.
+- 화면에서는 `response.data`를 실제 payload로 사용한다.
+- response `data`:
+```ts
+type AdminGiftMailboxResponse = {
+  name: string;
+  address: string;
+  phoneNumber: string;
+} | null;
+```
+- `data`가 null이면 아직 등록된 받을 주소가 없는 상태다.
+- null이면 빈 폼을 표시한다.
+
+저장 API:
+- Method: `PUT`
+- URL: `/api/v2/admin/gift-mailbox`
+- Request:
+```ts
+type AdminGiftMailboxRequest = {
+  name: string;
+  phoneNumber: string;
+  zipCode: string;
+  address: string;
+  addressDetail: string | null;
+};
+```
+- Response `data`:
+```ts
+type AdminGiftMailboxResponse = {
+  name: string;
+  address: string;
+  phoneNumber: string;
+};
+```
+
+동작 규칙:
+- 받을 주소는 전역 단일 설정이다.
+- 등록과 수정은 같은 `PUT /api/v2/admin/gift-mailbox` API를 사용한다.
+- 최초 저장이면 생성처럼 동작한다.
+- 이미 저장된 값이 있으면 기존 주소를 수정한다.
+- 별도 ID, 목록, 삭제 기능은 만들지 않는다.
+
+폼 validation:
+- `name`, `phoneNumber`, `zipCode`, `address`는 필수다.
+- 필수값은 공백만 입력할 수 없다.
+- `addressDetail`은 선택이다.
+- validation 실패 시 API를 호출하지 않고 기존 관리자 페이지의 필드 에러 표시 방식을 따른다.
+
+저장 성공 UX:
+- 성공 토스트를 표시한다.
+- 저장 API response 기준으로 화면 값을 갱신한다.
+- response의 `address`는 서버가 조립한 `(우편번호) 주소, 상세주소` 형식이다.
+- 입력 필드는 사용자가 입력한 `zipCode`, `address`, `addressDetail` 값을 유지해도 된다.
+
+빈 상태 UX:
+- 조회 결과 `data=null`이면 빈 폼을 보여준다.
+- 필요하면 안내 문구 `등록된 받을 주소가 없습니다. 주소를 입력하고 저장해주세요.`를 표시한다.
+
+에러 처리:
+- API 실패 시 기존 관리자 페이지의 공통 에러 토스트/알림 패턴을 따른다.
+- 인증/권한 처리는 기존 관리자 API client와 토큰 처리 방식을 따른다.
+
+테스트/검증:
+- `/gift/mailbox` route가 선물함 관리 메뉴에서 접근되는지 확인한다.
+- 초기 조회 시 `GET /api/v2/admin/gift-mailbox`를 호출하는지 확인한다.
+- 조회 결과가 null이면 빈 폼을 표시하는지 확인한다.
+- 저장 시 `PUT /api/v2/admin/gift-mailbox`와 request body가 정확한지 확인한다.
+- 필수값 공백 validation 시 API를 호출하지 않는지 확인한다.
+- 저장 성공 후 성공 토스트와 화면 갱신이 일어나는지 확인한다.
+```

docs/20260929_크리에이터_선물하기/gift-received-detail-page-prompt.md

@@ -0,0 +1,421 @@
+# 받은 선물 상세 및 배송지 입력 페이지 생성 프롬프트
+
+이 문서는 Android/iOS 앱의 `선물함` 리스트에서 받은 선물 상세 페이지와 배송지 입력 UI를 생성할 때 사용하는 프롬프트다.
+
+참고 Figma:
+
+- 배송지 입력 전 상세 UI: `2531:36290`
+- 배송지 입력 완료 후 상세 UI: `2531:36399`
+- 선물 전달 완료시 상세 UI: `2531:36330`
+- 선물 전달 불가시 상세 UI: `2531:36422`
+
+전제:
+
+- 선물함 리스트 item 탭 시 `applicationNo`를 전달받아 상세 페이지로 이동한다.
+- 새 디자인 시스템을 만들지 말고 Android/iOS 각각의 기존 디자인 시스템, 컴포넌트, API client, 상태 관리, toast/dialog, navigation 패턴을 재사용한다.
+- 모든 API 응답은 공통 envelope를 사용하며 실제 payload는 `response.data`다.
+- 이 프롬프트는 받는 크리에이터 관점(`direction=RECEIVED`)만 다룬다.
+- API 예시는 TypeScript 타입이 아니라 JSON으로 작성한다.
+
+---
+
+## 모바일 앱 구현 프롬프트
+
+```text
+Android/iOS 앱의 받은 선물 상세 페이지와 배송지 입력 UI를 Figma 기준으로 생성하고 API 연동을 구현해줘.
+
+범위:
+- 선물함 리스트에서 `applicationNo`를 받아 받은 선물 상세 페이지로 이동한다.
+- 상세 페이지는 `GET /api/v2/gifts/{applicationNo}` 응답으로 렌더링한다.
+- `direction=RECEIVED && recipientAddressRequired=true`이면 배송지 입력 UI를 표시한다.
+- 배송지 입력은 `POST /api/v2/gifts/{applicationNo}/recipient-address`로 연결한다.
+- 배송지 입력 완료 후에는 상세를 다시 조회해 배송지 입력 완료 상태 UI를 표시한다.
+
+중요 전제:
+- Figma의 visual structure와 문구를 우선 따르되, 데이터 노출과 CTA 조건은 API 계약을 우선한다.
+- `direction=RECEIVED` 화면에서 `senderInfo`, `mailbox`, `giftInfo.applicationNo`, `giftInfo.paidCan`, `giftInfo.tracking`은 표시하지 않는다.
+- `recipientAddress`가 null이면 받는 주소 섹션 자체를 표시하지 않는다. 전달 완료 후 배송지 정보가 삭제될 예정이므로 빈 섹션, skeleton, `-` 값도 표시하지 않는다.
+- 전달 불가 화면의 `문의하기`는 기존 앱의 카카오 채널 문의 연결과 동일하게 연결한다.
+- 전달 불가 화면의 `선물 정책 확인`은 버튼/action만 만들어두고 실제 외부 페이지 연결은 하지 않는다. 임의 URL을 연결하지 않는다.
+
+상세 페이지 진입:
+- 화면 진입 시 `GET /api/v2/gifts/{applicationNo}`를 호출한다.
+- 조회 결과 `direction`이 `RECEIVED`가 아니면 이 화면을 렌더링하지 말고 기존 앱의 잘못된 접근/상세 재라우팅 정책을 따른다.
+- 로딩 중에는 기존 앱 상세 화면 로딩/스켈레톤 패턴을 사용한다.
+- 실패 시 기존 앱 toast/dialog와 재시도 패턴을 사용한다.
+
+배송지 입력 전 UI:
+- 적용 조건: `direction=RECEIVED && recipientAddressRequired=true`.
+- Figma `2531:36290`을 따른다.
+- 상단 타이틀: `선물 받기`.
+- 개인정보 이용 안내 배너를 표시한다.
+  - 제목: `개인정보 이용 안내`
+  - 본문: `크리에이터 및 팬의 주소는 공개되지 않습니다. 입력한 배송지는 선물 전달 및 필요한 사고 처리에서 사용되며, 전달 완료 후 파기됩니다.`
+- `전달 예정 선물` 섹션을 표시한다.
+  - 발송인: `giftInfo.senderNickname`
+  - 사이즈: `giftInfo.sizeName`
+  - 카테고리: `giftInfo.categoryName`
+- `배송지 입력` 섹션을 표시한다.
+  - 이름 input: `recipientName`
+  - 휴대폰 번호 input: `recipientPhoneNumber`
+  - 우편번호 input: `recipientZipCode`
+  - 우편번호 검색 버튼: 기존 페이지와 동일하게 Kakao 우편번호 서비스를 사용한다.
+  - 주소 input: `recipientAddress`
+  - 상세 주소 input: `recipientAddressDetail`
+- `이용 약관 동의` 섹션을 표시한다.
+  - `소다라이브 크리에이터 상품 전달 이용약관 및 전달 가능 제한 품목을 확인하고 동의합니다.(필수)`
+  - `상품 전달을 위해 수령인 성명·연락처·주소 등 필요한 개인정보를 일시적으로 수집·이용하는 것에 동의합니다.(필수)`
+  - 두 항목 모두 체크해야 제출 가능하다.
+  - 약관 상세 링크는 앱에 기존 약관/webview 경로가 있으면 연결하고, 없으면 새 페이지를 만들지 않는다.
+- 하단 주요 CTA: `선물 받기`.
+- CTA 활성 조건:
+  - 이름, 휴대폰 번호, 우편번호, 주소가 공백이 아니다.
+  - 상세 주소는 선택 입력이다.
+  - 약관 2개가 모두 체크됐다.
+  - submit 중에는 중복 탭을 막고 loading 상태를 표시한다.
+
+배송지 입력 API 연결:
+- CTA 탭 시 `POST /api/v2/gifts/{applicationNo}/recipient-address`를 호출한다.
+- request body에는 화면 입력값과 약관 동의 boolean을 그대로 전송한다.
+- 성공 시 성공 toast를 표시하고 상세 페이지를 다시 조회하거나 replace navigation으로 상세를 다시 연다.
+- 실패 시 기존 앱 form error/toast/dialog 패턴을 따른다. 실패 상태에서 입력값은 유지한다.
+
+주소 검색 구현:
+- 기존 앱/페이지에 Kakao 우편번호 서비스 래퍼가 있으면 반드시 재사용한다.
+- 신규 연결이 필요하면 Kakao 우편번호 서비스 공식 가이드 `https://postcode.map.kakao.com/guide`를 따른다.
+- SDK script는 공식 가이드의 `//t1.kakaocdn.net/mapjsapi/bundle/postcode/prod/postcode.v2.js`를 사용한다. 임의 수정본이나 별도 주소 검색 API를 만들지 않는다.
+- Android/iOS WebView 또는 모바일웹 환경에서는 `window.open` 팝업이 막힐 수 있으므로, 기존 페이지와 같은 방식이 없다면 Kakao 가이드의 `embed()` 기반 레이어/페이지 삽입 방식을 우선 검토한다.
+- 검색 결과 선택 시:
+  - `data.zonecode`를 `recipientZipCode`에 넣는다.
+  - `data.userSelectedType === "R"`이면 `data.roadAddress`를, 그 외에는 `data.jibunAddress`를 `recipientAddress`에 넣는다.
+  - 주소 선택 후 `recipientAddressDetail` 입력으로 포커스를 이동한다.
+- 상세 주소는 Kakao 결과에서 채우지 않고 사용자가 직접 입력하게 한다.
+- 주소 검색 실패/취소 시 입력 중이던 이름, 휴대폰 번호, 약관 체크 상태를 초기화하지 않는다.
+
+배송지 입력 완료 후 상세 UI:
+- 적용 조건: `direction=RECEIVED && recipientAddressRequired=false && status`가 `TRACKING_REGISTERED`, `ARRIVED_AT_MAILBOX`, `INSPECTION_COMPLETED` 중 하나이며 `recipientAddress`가 있다.
+- Figma `2531:36399`를 따른다.
+- 상단 타이틀: `선물 상세`.
+- hero title: `배송지 입력 완료!`
+- hero body: `빠른 시일 내로 선물을 전달 드릴게요.`
+- `문의하기` 버튼을 표시하고 기존 카카오 채널 문의로 연결한다.
+- `선물 정보` 섹션을 표시한다.
+  - 발송인: `giftInfo.senderNickname`
+  - 사이즈: `giftInfo.sizeName`
+  - 카테고리: `giftInfo.categoryName`
+  - 배송 신청일: `giftInfo.shippingRequestedAt`
+- `받는 주소` 섹션은 `recipientAddress`가 있을 때만 표시한다.
+  - 이름: `recipientAddress.name`
+  - 휴대폰 번호: `recipientAddress.phoneNumber`
+  - 주소: `recipientAddress.address`
+
+선물 전달 완료 상세 UI:
+- 적용 조건: `direction=RECEIVED && status=DELIVERED`.
+- Figma `2531:36330`을 따른다.
+- 상단 타이틀: `선물 상세`.
+- hero title: `선물 전달 완료!`
+- hero body: `팬이 보낸 선물이 도착했어요. 선물이 도착하지 않은 경우, 문의해 주세요.`
+- `문의하기` 버튼을 표시하고 기존 카카오 채널 문의로 연결한다.
+- `선물 정보` 섹션을 표시한다.
+  - 발송인: `giftInfo.senderNickname`
+  - 사이즈: `giftInfo.sizeName`
+  - 카테고리: `giftInfo.categoryName`
+  - 배송 신청일: `giftInfo.shippingRequestedAt`
+  - 배송 완료일: `statusTimeline`에서 `DELIVERED.occurredAt`
+- `받는 주소` 섹션은 `recipientAddress`가 있을 때만 표시한다.
+  - 섹션 보조 문구: `배송 완료 3일 후 해당 정보는 사라져요`
+  - 이름: `recipientAddress.name`
+  - 휴대폰 번호: `recipientAddress.phoneNumber`
+  - 주소: `recipientAddress.address`
+- `recipientAddress=null`이면 `받는 주소` 섹션 전체를 숨긴다.
+
+선물 전달 불가 상세 UI:
+- 적용 조건: `direction=RECEIVED && status=UNDELIVERABLE`.
+- Figma `2531:36422`를 따른다.
+- 상단 타이틀: `선물 상세`.
+- chip: `전달 불가`
+- hero title: `전달할 수 없는 품목입니다`
+- hero body: `해당 선물은 SODALIVE 선물 정책에 따라 크리에이터에게 전달할 수 없는 품목으로 확인되었습니다.`
+- action button:
+  - `문의하기`: 기존 카카오 채널 문의로 연결한다.
+  - `선물 정책 확인`: action handler만 연결하고 실제 외부 페이지/URL은 연결하지 않는다. 기존 앱 정책상 no-op이 금지되어 있으면 `준비 중입니다.` toast만 표시한다.
+- `사유` 섹션을 표시한다.
+  - 사유 제목: `delivery.undeliverableReason`이 있으면 그 값을 사용한다.
+  - `delivery.undeliverableReason`이 null이면 `전달 불가`로 표시한다.
+  - 안내 문구: `해당 선물은 정책에 따라 폐기되며 반송되지 않습니다.`
+- 전달 불가 상태에서는 배송지 입력 UI를 표시하지 않는다.
+- `recipientAddress`가 응답에 있더라도 전달 불가 Figma에는 받는 주소 섹션이 없으므로 표시하지 않는다.
+
+날짜 표시:
+- API의 모든 날짜는 UTC ISO 문자열이다.
+- 앱 공통 날짜 formatter가 있으면 재사용한다.
+- Figma처럼 상세 필드 날짜는 `YYYY.MM.DD`로 표시한다.
+- 값이 null이면 해당 row를 숨긴다.
+
+API 명세:
+
+선물 상세 조회:
+- Method: `GET`
+- URL: `/api/v2/gifts/{applicationNo}`
+- 인증: 로그인 필요
+- Response envelope 예시 - 배송지 입력 전:
+```json
+{
+  "success": true,
+  "data": {
+    "applicationNo": "A-1002609300001",
+    "direction": "RECEIVED",
+    "status": "TRACKING_REGISTERED",
+    "statusName": "발송 확인",
+    "giftInfo": {
+      "recipientCreatorNickname": null,
+      "senderNickname": "팬닉네임이들어가는부분",
+      "sizeName": "소형",
+      "categoryName": "신규 전자굿즈",
+      "applicationNo": null,
+      "paidCan": null,
+      "tracking": null,
+      "shippingRequestedAt": "2026-10-12T03:00:00Z"
+    },
+    "senderInfo": null,
+    "recipientAddress": null,
+    "mailbox": null,
+    "trackingRequired": false,
+    "recipientAddressRequired": true,
+    "recipientAddressDeadlineAt": "2026-10-19T03:00:00Z",
+    "delivery": {
+      "canceledAt": null,
+      "undeliverableAt": null,
+      "undeliverableReason": null
+    },
+    "statusTimeline": [
+      {
+        "status": "RECEIVED",
+        "statusName": "접수 완료",
+        "occurredAt": "2026-10-11T03:00:00Z"
+      },
+      {
+        "status": "TRACKING_REGISTERED",
+        "statusName": "발송 확인",
+        "occurredAt": "2026-10-12T03:00:00Z"
+      },
+      {
+        "status": "ARRIVED_AT_MAILBOX",
+        "statusName": "사서함 도착",
+        "occurredAt": null
+      },
+      {
+        "status": "INSPECTION_COMPLETED",
+        "statusName": "검수완료",
+        "occurredAt": null
+      },
+      {
+        "status": "DELIVERED",
+        "statusName": "전달완료",
+        "occurredAt": null
+      }
+    ]
+  },
+  "message": ""
+}
+```
+
+Response envelope 예시 - 배송지 입력 완료/전달 완료:
+```json
+{
+  "success": true,
+  "data": {
+    "applicationNo": "A-1002609300001",
+    "direction": "RECEIVED",
+    "status": "DELIVERED",
+    "statusName": "전달완료",
+    "giftInfo": {
+      "recipientCreatorNickname": null,
+      "senderNickname": "팬닉네임이들어가는부분",
+      "sizeName": "소형",
+      "categoryName": "신규 전자굿즈",
+      "applicationNo": null,
+      "paidCan": null,
+      "tracking": null,
+      "shippingRequestedAt": "2026-10-12T03:00:00Z"
+    },
+    "senderInfo": null,
+    "recipientAddress": {
+      "name": "크리에이터이름",
+      "phoneNumber": "01012345678",
+      "address": "(04030) 서울특별시 마포구 양화로 000, 3층"
+    },
+    "mailbox": null,
+    "trackingRequired": false,
+    "recipientAddressRequired": false,
+    "recipientAddressDeadlineAt": "2026-10-19T03:00:00Z",
+    "delivery": {
+      "canceledAt": null,
+      "undeliverableAt": null,
+      "undeliverableReason": null
+    },
+    "statusTimeline": [
+      {
+        "status": "RECEIVED",
+        "statusName": "접수 완료",
+        "occurredAt": "2026-10-11T03:00:00Z"
+      },
+      {
+        "status": "TRACKING_REGISTERED",
+        "statusName": "발송 확인",
+        "occurredAt": "2026-10-12T03:00:00Z"
+      },
+      {
+        "status": "ARRIVED_AT_MAILBOX",
+        "statusName": "사서함 도착",
+        "occurredAt": "2026-10-14T03:00:00Z"
+      },
+      {
+        "status": "INSPECTION_COMPLETED",
+        "statusName": "검수완료",
+        "occurredAt": "2026-10-16T03:00:00Z"
+      },
+      {
+        "status": "DELIVERED",
+        "statusName": "전달완료",
+        "occurredAt": "2026-10-22T03:00:00Z"
+      }
+    ]
+  },
+  "message": ""
+}
+```
+
+Response envelope 예시 - 전달 불가:
+```json
+{
+  "success": true,
+  "data": {
+    "applicationNo": "A-1002609300001",
+    "direction": "RECEIVED",
+    "status": "UNDELIVERABLE",
+    "statusName": "전달불가",
+    "giftInfo": {
+      "recipientCreatorNickname": null,
+      "senderNickname": "팬닉네임이들어가는부분",
+      "sizeName": "소형",
+      "categoryName": "신규 전자굿즈",
+      "applicationNo": null,
+      "paidCan": null,
+      "tracking": null,
+      "shippingRequestedAt": "2026-10-12T03:00:00Z"
+    },
+    "senderInfo": null,
+    "recipientAddress": null,
+    "mailbox": null,
+    "trackingRequired": false,
+    "recipientAddressRequired": false,
+    "recipientAddressDeadlineAt": "2026-10-19T03:00:00Z",
+    "delivery": {
+      "canceledAt": null,
+      "undeliverableAt": "2026-10-16T03:00:00Z",
+      "undeliverableReason": "음식물 또는 보관이 어려운 품목"
+    },
+    "statusTimeline": [
+      {
+        "status": "RECEIVED",
+        "statusName": "접수 완료",
+        "occurredAt": "2026-10-11T03:00:00Z"
+      },
+      {
+        "status": "TRACKING_REGISTERED",
+        "statusName": "발송 확인",
+        "occurredAt": "2026-10-12T03:00:00Z"
+      },
+      {
+        "status": "ARRIVED_AT_MAILBOX",
+        "statusName": "사서함 도착",
+        "occurredAt": "2026-10-14T03:00:00Z"
+      },
+      {
+        "status": "INSPECTION_COMPLETED",
+        "statusName": "검수완료",
+        "occurredAt": null
+      },
+      {
+        "status": "DELIVERED",
+        "statusName": "전달완료",
+        "occurredAt": null
+      }
+    ]
+  },
+  "message": ""
+}
+```
+
+선물 상세 response `data` 필드:
+
+| 필드 | 설명 |
+|---|---|
+| `applicationNo` | 선물 신청번호. 화면 진입 key로 사용한다. |
+| `direction` | 이 프롬프트에서는 `RECEIVED`만 렌더링한다. |
+| `status` | `TRACKING_REGISTERED`, `ARRIVED_AT_MAILBOX`, `INSPECTION_COMPLETED`, `DELIVERED`, `UNDELIVERABLE` 등을 상태별 UI 분기에 사용한다. |
+| `giftInfo.senderNickname` | 받은 선물 관점의 발송인 팬 닉네임. |
+| `giftInfo.sizeName` | 선물 사이즈명. |
+| `giftInfo.categoryName` | 카테고리명. |
+| `giftInfo.shippingRequestedAt` | 배송 신청일. UTC ISO 문자열. |
+| `recipientAddress` | 크리에이터 본인이 입력한 배송지. null이면 받는 주소 섹션을 숨긴다. |
+| `recipientAddressRequired` | 배송지 입력 UI 표시 여부. |
+| `recipientAddressDeadlineAt` | 배송지 입력 마감일. 필요하면 안내 문구에 사용한다. |
+| `delivery.undeliverableReason` | 전달 불가 사유. |
+| `statusTimeline` | 배송 완료일 등 상태별 날짜를 찾는 데 사용한다. |
+
+배송지 입력:
+- Method: `POST`
+- URL: `/api/v2/gifts/{applicationNo}/recipient-address`
+- 인증: 로그인 필요
+- Request:
+```json
+{
+  "recipientName": "크리에이터이름",
+  "recipientPhoneNumber": "01012345678",
+  "recipientZipCode": "04030",
+  "recipientAddress": "서울특별시 마포구 양화로 000",
+  "recipientAddressDetail": "3층",
+  "recipientTermsAgreed": true,
+  "recipientPrivacyAgreed": true
+}
+```
+- Response envelope 예시:
+```json
+{
+  "success": true,
+  "data": {
+    "applicationNo": "A-1002609300001",
+    "status": "TRACKING_REGISTERED",
+    "statusName": "발송 확인",
+    "recipientAddressRegisteredAt": "2026-10-13T03:00:00Z"
+  },
+  "message": ""
+}
+```
+
+배송지 입력 response `data` 필드:
+
+| 필드 | 설명 |
+|---|---|
+| `applicationNo` | 선물 신청번호 |
+| `status` | 등록 후 상태. 일반적으로 기존 진행 상태 유지 |
+| `statusName` | 서버 상태 표시명 |
+| `recipientAddressRegisteredAt` | 배송지 입력 완료 시각. UTC ISO 문자열 |
+
+테스트/검증:
+- 리스트 item 탭 시 `applicationNo`로 받은 선물 상세 페이지가 열리는지 확인한다.
+- 상세 진입 시 `GET /api/v2/gifts/{applicationNo}`가 호출되는지 확인한다.
+- `direction=RECEIVED && recipientAddressRequired=true`이면 배송지 입력 UI가 표시되는지 확인한다.
+- 배송지 입력 필수값 또는 약관 동의가 누락되면 `POST /recipient-address`를 호출하지 않는지 확인한다.
+- 배송지 입력 submit 시 request body가 API 명세와 일치하는지 확인한다.
+- 배송지 입력 성공 후 상세가 재조회되고 배송지 입력 완료 UI가 표시되는지 확인한다.
+- 배송지 입력 완료/전달 완료 상태에서 `recipientAddress`가 있으면 받는 주소 섹션이 표시되는지 확인한다.
+- `recipientAddress=null`이면 받는 주소 섹션 자체가 표시되지 않는지 확인한다.
+- `status=DELIVERED`이면 전달 완료 UI와 배송 완료일이 표시되는지 확인한다.
+- `status=UNDELIVERABLE`이면 전달 불가 UI, 사유, 폐기/반송 불가 안내가 표시되는지 확인한다.
+- 전달 불가 화면의 `문의하기`는 기존 카카오 채널 문의로 연결되는지 확인한다.
+- 전달 불가 화면의 `선물 정책 확인`은 버튼 action만 있고 실제 외부 URL을 열지 않는지 확인한다.
+- 모든 날짜는 UTC ISO 문자열을 앱 표시 형식으로 변환해 표시하는지 확인한다.
+```

docs/20260929_크리에이터_선물하기/gift-schema.sql

@@ -0,0 +1,128 @@
+CREATE TABLE gift_category (
+    id BIGINT NOT NULL AUTO_INCREMENT COMMENT '내부 기본키',
+    classification_number VARCHAR(3) NOT NULL COMMENT '신청번호에 사용하는 3자리 분류번호',
+    category_code VARCHAR(50) NOT NULL COMMENT '내부 범용코드',
+    name VARCHAR(50) NOT NULL COMMENT '분류명',
+    receipt_code VARCHAR(9) NOT NULL COMMENT '신청번호에 사용하는 접수코드',
+    representative_item VARCHAR(100) NOT NULL COMMENT '대표품목',
+    requires_damage_waiver TINYINT(1) NOT NULL COMMENT '파손면책 동의 필요 여부',
+    is_active TINYINT(1) NOT NULL COMMENT '활성 여부',
+    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '생성 시각',
+    updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '수정 시각',
+    PRIMARY KEY (id),
+    UNIQUE KEY uk_gift_category_classification_number (classification_number),
+    UNIQUE KEY uk_gift_category_code (category_code),
+    UNIQUE KEY uk_gift_category_receipt_code (receipt_code)
+) COMMENT='선물 카테고리';
+
+CREATE TABLE gift_mailbox (
+    id BIGINT NOT NULL COMMENT '전역 단일 설정 ID. 항상 1',
+    name VARCHAR(50) NOT NULL COMMENT '받을 사람 이름',
+    phone_number VARCHAR(30) NOT NULL COMMENT '받을 연락처',
+    zip_code VARCHAR(20) NOT NULL COMMENT '받을 우편번호',
+    address VARCHAR(255) NOT NULL COMMENT '받을 주소',
+    address_detail VARCHAR(255) NULL COMMENT '받을 상세주소',
+    PRIMARY KEY (id)
+) COMMENT='선물 받을 주소 전역 설정';
+
+CREATE TABLE gift (
+    id BIGINT NOT NULL AUTO_INCREMENT COMMENT '내부 기본키',
+    application_no VARCHAR(40) NOT NULL COMMENT '신청번호',
+    sender_member_id BIGINT NOT NULL COMMENT '보내는 팬 회원번호',
+    recipient_member_id BIGINT NOT NULL COMMENT '받는 크리에이터 회원번호',
+    status VARCHAR(30) NOT NULL COMMENT '선물 상태',
+    size_code VARCHAR(20) NOT NULL COMMENT '선물 사이즈 코드',
+    category_id BIGINT NOT NULL COMMENT '신청 시 카테고리 ID',
+    category_name_snapshot VARCHAR(50) NOT NULL COMMENT '신청 시 카테고리명 스냅샷',
+    sale_price_can INT NOT NULL COMMENT '신청 시 결제 금액 스냅샷',
+    can_usage_id BIGINT NOT NULL COMMENT '캔 사용내역 ID',
+    sender_terms_agreed TINYINT(1) NOT NULL COMMENT '팬 이용약관 동의 여부',
+    sender_privacy_agreed TINYINT(1) NOT NULL COMMENT '팬 개인정보 동의 여부',
+    sender_terms_agreed_at TIMESTAMP NOT NULL COMMENT '팬 이용약관 동의 시각',
+    sender_privacy_agreed_at TIMESTAMP NOT NULL COMMENT '팬 개인정보 동의 시각',
+    recipient_terms_agreed TINYINT(1) NOT NULL COMMENT '크리에이터 이용약관 동의 여부',
+    recipient_privacy_agreed TINYINT(1) NOT NULL COMMENT '크리에이터 개인정보 동의 여부',
+    recipient_terms_agreed_at TIMESTAMP NULL COMMENT '크리에이터 이용약관 동의 시각',
+    recipient_privacy_agreed_at TIMESTAMP NULL COMMENT '크리에이터 개인정보 동의 시각',
+    damage_waiver_agreed TINYINT(1) NOT NULL COMMENT '파손면책 동의 여부',
+    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '생성 시각',
+    updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '수정 시각',
+    PRIMARY KEY (id),
+    UNIQUE KEY uk_gift_application_no (application_no),
+    CONSTRAINT fk_gift_sender_member FOREIGN KEY (sender_member_id) REFERENCES member (id),
+    CONSTRAINT fk_gift_recipient_member FOREIGN KEY (recipient_member_id) REFERENCES member (id),
+    CONSTRAINT fk_gift_category FOREIGN KEY (category_id) REFERENCES gift_category (id),
+    CONSTRAINT fk_gift_can_usage FOREIGN KEY (can_usage_id) REFERENCES use_can (id)
+) COMMENT='선물 신청';
+
+CREATE TABLE gift_delivery (
+    id BIGINT NOT NULL AUTO_INCREMENT COMMENT '내부 기본키',
+    gift_id BIGINT NOT NULL COMMENT '선물 ID',
+    sender_name VARCHAR(50) NOT NULL COMMENT '발신자 이름',
+    sender_phone_number VARCHAR(30) NOT NULL COMMENT '발신자 휴대폰 번호',
+    sender_zip_code VARCHAR(20) NOT NULL COMMENT '발신자 우편번호',
+    sender_address VARCHAR(255) NOT NULL COMMENT '발신자 주소',
+    sender_address_detail VARCHAR(255) NULL COMMENT '발신자 상세주소',
+    recipient_name VARCHAR(50) NULL COMMENT '수신자 이름',
+    recipient_phone_number VARCHAR(30) NULL COMMENT '수신자 휴대폰 번호',
+    recipient_zip_code VARCHAR(20) NULL COMMENT '수신자 우편번호',
+    recipient_address VARCHAR(255) NULL COMMENT '수신자 주소',
+    recipient_address_detail VARCHAR(255) NULL COMMENT '수신자 상세주소',
+    courier_company_name VARCHAR(50) NULL COMMENT '택배사 한글 표시명',
+    tracking_number VARCHAR(100) NULL COMMENT '운송장 번호',
+    tracking_deadline_at TIMESTAMP NOT NULL COMMENT '운송장 등록 기한',
+    recipient_address_deadline_at TIMESTAMP NULL COMMENT '수신자 배송지 입력 기한',
+    tracking_deadline_reminder_sent_at TIMESTAMP NULL COMMENT '운송장 등록 기한 안내 발송 시각',
+    recipient_address_deadline_reminder_sent_at TIMESTAMP NULL COMMENT '수신자 배송지 입력 기한 안내 발송 시각',
+    tracking_registered_at TIMESTAMP NULL COMMENT '운송장 등록 시각',
+    arrived_at_mailbox_at TIMESTAMP NULL COMMENT '사서함 도착 시각',
+    inspection_completed_at TIMESTAMP NULL COMMENT '검수완료 시각',
+    delivered_at TIMESTAMP NULL COMMENT '전달완료 시각',
+    canceled_at TIMESTAMP NULL COMMENT '취소 시각',
+    undeliverable_at TIMESTAMP NULL COMMENT '전달불가 시각',
+    undeliverable_reason VARCHAR(255) NULL COMMENT '전달불가 사유',
+    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '생성 시각',
+    updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '수정 시각',
+    PRIMARY KEY (id),
+    UNIQUE KEY uk_gift_delivery_gift_id (gift_id),
+    CONSTRAINT fk_gift_delivery_gift FOREIGN KEY (gift_id) REFERENCES gift (id)
+) COMMENT='선물 배송 정보';
+
+CREATE TABLE gift_size_price (
+    id BIGINT NOT NULL AUTO_INCREMENT COMMENT '내부 기본키',
+    size_code VARCHAR(20) NOT NULL COMMENT '선물 사이즈 코드',
+    base_price_can INT NOT NULL COMMENT '기본 금액',
+    sale_price_can INT NOT NULL COMMENT '결제 금액',
+    is_active TINYINT(1) NOT NULL COMMENT '활성 여부',
+    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '생성 시각',
+    updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '수정 시각',
+    PRIMARY KEY (id),
+    UNIQUE KEY uk_gift_size_price_size_code (size_code)
+) COMMENT='선물 사이즈별 가격';
+
+CREATE TABLE gift_review (
+    id BIGINT NOT NULL AUTO_INCREMENT COMMENT '내부 기본키',
+    gift_id BIGINT NOT NULL COMMENT '선물 ID',
+    sender_member_id BIGINT NOT NULL COMMENT '리뷰 작성 팬 회원번호',
+    rating INT NOT NULL COMMENT '별점',
+    keywords TEXT NULL COMMENT '리뷰 키워드 목록',
+    comment VARCHAR(255) NULL COMMENT '추가의견',
+    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '생성 시각',
+    updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '수정 시각',
+    PRIMARY KEY (id),
+    UNIQUE KEY uk_gift_review_gift_id (gift_id),
+    CONSTRAINT fk_gift_review_gift FOREIGN KEY (gift_id) REFERENCES gift (id),
+    CONSTRAINT fk_gift_review_sender_member FOREIGN KEY (sender_member_id) REFERENCES member (id)
+) COMMENT='선물 리뷰';
+
+CREATE TABLE gift_application_no_sequence (
+    id BIGINT NOT NULL AUTO_INCREMENT COMMENT '내부 기본키',
+    category_id BIGINT NOT NULL COMMENT '채번 기준 카테고리 ID',
+    sequence_date VARCHAR(6) NOT NULL COMMENT '채번 기준일 yyMMdd',
+    last_sequence INT NOT NULL COMMENT '마지막 일련번호',
+    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '생성 시각',
+    updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '수정 시각',
+    PRIMARY KEY (id),
+    UNIQUE KEY uk_gift_application_no_sequence_category_date (category_id, sequence_date),
+    CONSTRAINT fk_gift_application_no_sequence_category FOREIGN KEY (category_id) REFERENCES gift_category (id)
+) COMMENT='선물 신청번호 날짜별 채번';

docs/20260929_크리에이터_선물하기/gift-send-page-prompt.md

@@ -0,0 +1,263 @@
+# 선물 보내기 페이지 생성 프롬프트
+
+이 문서는 Android/iOS 앱의 `선물 보내기` 페이지를 생성하거나 기존 생성 UI에 API 연동을 붙일 때 사용하는 프롬프트다.
+
+참고 Figma:
+
+- 빈 입력 상태: `2481:18904`
+- 입력 완료 및 CTA 활성화 상태: `2481:18957`
+
+전제:
+
+- 크리에이터 닉네임과 `memberId`를 받아 `선물 보내기` 화면으로 이동하는 흐름은 이미 생성되어 있다.
+- 새 진입 흐름을 만들지 않는다.
+- Figma에 있는 UI 구조와 문구를 유지한다.
+- Android/iOS 각각의 기존 디자인 시스템, 컴포넌트, API client, 상태 관리, toast/dialog, navigation 패턴을 재사용한다.
+- 모든 API 응답은 공통 envelope를 사용하며 실제 payload는 `data`에 있다.
+- request/response 설명은 모바일 공통 JSON 기준이다.
+
+---
+
+## 모바일 앱 구현 프롬프트
+
+```text
+Android/iOS 앱의 선물 보내기 페이지를 Figma 기준으로 생성하고 API 연동을 구현해줘.
+
+중요 전제:
+- 크리에이터 닉네임과 memberId를 받아 이 화면으로 이동하는 기능은 이미 구현되어 있다.
+- 이 작업에서는 이동 경로를 새로 만들지 말고, 전달받은 값만 화면과 API request에 연결한다.
+- 전달받은 크리에이터 닉네임은 `받는 크리에이터` 영역에 표시한다.
+- 전달받은 memberId는 선물 신청 API의 `recipientMemberId`로 보낸다.
+
+Figma 참고 상태:
+- 빈 입력 상태: node `2481:18904`
+- 입력 완료 및 최하단 CTA 활성화 상태: node `2481:18957`
+
+화면 구조:
+
+1. 상단
+   - 타이틀: `선물 보내기`
+   - 뒤로가기 버튼은 기존 앱 패턴을 사용한다.
+
+2. 안내 배너
+   - 제목: `선물 보내기 베타 서비스 안내`
+   - 본문: `베타 기간 동안은 일부 기능만 제공됩니다. 크리에이터에게 마음을 잘 전할 수 있도록 더 넓어진 선물 보내기로 곧 다시 만나요!`
+
+3. 받는 크리에이터
+   - 이전 화면에서 전달받은 크리에이터 닉네임을 표시한다.
+   - Figma의 프로필 row 형태를 유지한다.
+   - memberId는 화면 표시용이 아니라 API request용으로만 사용한다.
+
+4. 선물 사이즈
+   - 화면 진입 시 `GET /api/v2/gifts/form-options`를 호출해 `sizes`를 가져온다.
+   - 조회된 `sizes`를 사이즈 카드 목록에 바인딩한다.
+   - 카드에는 `name`, 사이즈 설명, 캔 가격을 표시한다.
+   - 서버 응답에는 사이즈 설명 필드가 없으므로 설명 문구는 앱에서 코드별로 매핑한다.
+     - `SMALL`: `세 변의 합 100cm 이하 · 5kg 이하`
+     - `MEDIUM`, `LARGE`: 정책 문구가 앱에 이미 있으면 기존 문구를 사용하고, 없으면 이름과 가격만 표시한다.
+   - 가격은 `salePriceCan`을 표시하고 submit 금액도 `salePriceCan`을 사용한다.
+   - `basePriceCan`과 `salePriceCan`이 다르면 기존 앱 할인/정가 표시 패턴이 있을 때만 정가를 함께 보여준다.
+   - 기본 선택은 서버가 내려준 첫 번째 사이즈로 둔다.
+
+5. 카테고리
+   - 화면 진입 시 같은 `GET /api/v2/gifts/form-options` 응답의 `categories`를 사용한다.
+   - Figma의 select field를 유지한다.
+   - 빈 상태 문구: `카테고리 선택`
+   - 선택 후에는 선택한 카테고리 `name`을 표시한다.
+   - 카테고리 선택 UI는 기존 Android/iOS 앱 패턴에 맞는 bottom sheet, picker, dialog 중 이미 쓰는 방식을 사용한다.
+   - `requiresDamageWaiver=true`인 카테고리를 선택한 경우에만 카테고리 아래에 파손 면책 동의 row를 표시한다.
+   - 파손 면책 동의 문구: `파손 및 분실 면책 사항에 동의합니다. (필수)`
+   - `requiresDamageWaiver=false` 카테고리를 선택하면 파손 면책 동의 row를 숨기고 `damageWaiverAgreed=false`로 초기화한다.
+
+6. 보내는 사람
+   - 이름 input → `senderName`
+   - 휴대폰 번호 input → `senderPhoneNumber`
+   - 우편번호 input → `senderZipCode`
+   - 주소 input → `senderAddress`
+   - 상세 주소 input → `senderAddressDetail`
+   - `우편번호 검색` 버튼은 기존 주소 검색 기능과 연결한다.
+   - 주소 검색 결과로 우편번호와 기본 주소를 채운다.
+   - 기본 주소는 사용자가 직접 수정하지 못하게 하는 기존 패턴이 있으면 그 패턴을 따른다.
+
+7. 이용 약관 동의
+   - Figma의 발송 규정 요약 박스와 체크박스 2개를 유지한다.
+   - `소다라이브 크리에이터 상품 전달 이용약관에 동의합니다. (필수)` → `senderTermsAgreed`
+   - `상품 전달을 위한 개인정보 수집·이용에 동의합니다. (필수)` → `senderPrivacyAgreed`
+
+8. 하단 CTA
+   - 빈 상태 또는 필수값 누락 상태는 Figma 빈 상태처럼 비활성 버튼을 표시한다.
+   - 활성 조건을 모두 만족하면 Figma 활성 상태처럼 soda 색상 CTA로 바꾼다.
+   - 활성 CTA 문구는 선택된 사이즈의 `salePriceCan`을 사용해 `{salePriceCan}캔으로 선물 보내기`로 표시한다.
+   - submit 중에는 중복 탭을 막고 loading 상태를 표시한다.
+
+화면 진입 시 처리:
+- 이미 전달받은 `creatorNickname`과 `memberId`를 읽는다.
+- 둘 중 하나라도 없으면 기존 앱의 오류 처리 또는 뒤로가기 패턴을 따른다.
+- 즉시 `GET /api/v2/gifts/form-options`를 호출한다.
+- 로딩 중에는 기존 화면 스켈레톤/로딩 패턴을 사용한다.
+- 조회 실패 시 toast/dialog와 재시도 동작을 기존 패턴으로 제공한다.
+- `sizes` 또는 `categories`가 비어 있으면 선물 신청을 막고 CTA를 비활성화한다.
+
+CTA 활성 조건:
+- `memberId`가 있다.
+- 사이즈가 선택되어 있다.
+- 카테고리가 선택되어 있다.
+- 이름이 입력되어 있다.
+- 휴대폰 번호가 입력되어 있다.
+- 우편번호가 입력되어 있다.
+- 주소가 입력되어 있다.
+- 이용약관 동의가 true다.
+- 개인정보 수집·이용 동의가 true다.
+- 선택한 카테고리의 `requiresDamageWaiver=true`이면 파손 면책 동의가 true다.
+
+검증 실패 처리:
+- CTA는 기본적으로 위 조건을 만족할 때만 활성화한다.
+- 그래도 submit 시점에 한 번 더 validation 한다.
+- 누락된 필드는 기존 앱의 input error, toast, dialog 중 현재 화면 패턴에 맞춰 안내한다.
+- validation 실패 시 `POST /api/v2/gifts`를 호출하지 않는다.
+
+폼 옵션 조회 API:
+- Method: `GET`
+- URL: `/api/v2/gifts/form-options`
+- Request: 없음
+- Response envelope 예시:
+```json
+{
+  "success": true,
+  "data": {
+    "sizes": [],
+    "categories": []
+  },
+  "message": ""
+}
+```
+- Response `data` 예시:
+```json
+{
+  "sizes": [
+    {
+      "sizeCode": "SMALL",
+      "name": "소형",
+      "basePriceCan": 100,
+      "salePriceCan": 80
+    }
+  ],
+  "categories": [
+    {
+      "categoryId": 1,
+      "name": "아크릴",
+      "requiresDamageWaiver": true
+    }
+  ]
+}
+```
+
+폼 옵션 필드:
+
+| 필드 | 타입 | 설명 |
+|---|---|---|
+| `sizes` | array | 선택 가능한 선물 사이즈 목록 |
+| `sizes[].sizeCode` | string | 사이즈 코드. `SMALL`, `MEDIUM`, `LARGE` |
+| `sizes[].name` | string | 사이즈 표시명 |
+| `sizes[].basePriceCan` | number | 기본 가격, 단위는 캔 |
+| `sizes[].salePriceCan` | number | 실제 결제 가격, 단위는 캔 |
+| `categories` | array | 선택 가능한 활성 카테고리 목록 |
+| `categories[].categoryId` | number | 카테고리 ID |
+| `categories[].name` | string | 카테고리 표시명 |
+| `categories[].requiresDamageWaiver` | boolean | 파손 면책 동의 필요 여부 |
+
+선물 신청 접수 API:
+- Method: `POST`
+- URL: `/api/v2/gifts`
+- 인증: 로그인 회원 필요. 기존 앱 인증 토큰/세션 처리 방식을 사용한다.
+- Request body 예시:
+```json
+{
+  "recipientMemberId": 100,
+  "senderName": "김소다",
+  "senderPhoneNumber": "01000000000",
+  "senderZipCode": "12345",
+  "senderAddress": "서울시 강남구 ...",
+  "senderAddressDetail": "123동 456호",
+  "sizeCode": "SMALL",
+  "categoryId": 1,
+  "senderTermsAgreed": true,
+  "senderPrivacyAgreed": true,
+  "damageWaiverAgreed": true
+}
+```
+
+Request body 필드:
+
+| 필드 | 타입 | 필수 | 설명 |
+|---|---|---|---|
+| `recipientMemberId` | number | Y | 화면 진입 시 전달받은 memberId |
+| `senderName` | string | Y | 보내는 사람 이름 |
+| `senderPhoneNumber` | string | Y | 보내는 사람 휴대폰 번호 |
+| `senderZipCode` | string | Y | 보내는 사람 우편번호 |
+| `senderAddress` | string | Y | 보내는 사람 기본 주소 |
+| `senderAddressDetail` | string 또는 null | N | 보내는 사람 상세 주소 |
+| `sizeCode` | string | Y | 선택한 사이즈 코드 |
+| `categoryId` | number | Y | 선택한 카테고리 ID |
+| `senderTermsAgreed` | boolean | Y | 이용약관 동의 여부. 반드시 `true` |
+| `senderPrivacyAgreed` | boolean | Y | 개인정보 수집·이용 동의 여부. 반드시 `true` |
+| `damageWaiverAgreed` | boolean | Y | 파손 면책 동의 여부. 필요한 카테고리에서는 `true`, 필요 없는 카테고리에서는 `false` |
+
+- Response `data` 예시:
+```json
+{
+  "applicationNo": "A-1002609300001",
+  "status": "RECEIVED",
+  "statusName": "접수 완료",
+  "priceCan": 80,
+  "trackingDeadlineAt": "2026-10-02T03:00:00Z"
+}
+```
+
+Response `data` 필드:
+
+| 필드 | 타입 | 설명 |
+|---|---|---|
+| `applicationNo` | string | 선물 신청번호 |
+| `status` | string | 신청 상태 코드 |
+| `statusName` | string | 신청 상태 표시명 |
+| `priceCan` | number | 실제 차감된 캔 금액 |
+| `trackingDeadlineAt` | string | 운송장 등록 기한. UTC ISO 문자열 |
+
+성공 처리:
+- 신청 성공 시 기존 앱의 완료 dialog 또는 완료 화면 패턴을 사용한다.
+- 최소 표시값은 `applicationNo`, `statusName`, `priceCan`, `trackingDeadlineAt`이다.
+- 성공 이후 이동 CTA가 필요하면 기존 선물함 또는 선물 상세 이동 패턴을 사용한다.
+
+실패 처리:
+- 서버 오류 메시지가 있으면 기존 앱 에러 노출 방식으로 표시한다.
+- 잔액 부족, 유효하지 않은 카테고리, 파손 면책 미동의, 약관 미동의 등의 오류는 서버 메시지를 우선 사용한다.
+- 실패 시 입력값은 유지한다.
+
+테스트/검증:
+- 화면 진입 시 `GET /api/v2/gifts/form-options`가 호출되는지 확인한다.
+- 전달받은 크리에이터 닉네임이 받는 크리에이터 영역에 표시되는지 확인한다.
+- 전달받은 memberId가 `POST /api/v2/gifts`의 `recipientMemberId`로 들어가는지 확인한다.
+- 빈 상태에서는 CTA가 비활성화되는지 확인한다.
+- 필수 입력과 필수 동의를 모두 완료하면 CTA가 활성화되고 `{salePriceCan}캔으로 선물 보내기`가 표시되는지 확인한다.
+- `requiresDamageWaiver=true` 카테고리 선택 시 파손 면책 동의 row가 표시되고 동의 전에는 CTA가 비활성인지 확인한다.
+- `requiresDamageWaiver=false` 카테고리 선택 시 파손 면책 동의 row가 숨겨지고 request의 `damageWaiverAgreed`가 false인지 확인한다.
+- submit 성공 시 요청 body와 성공 처리 값을 확인한다.
+- submit 실패 시 입력값이 유지되고 기존 앱 방식으로 오류가 표시되는지 확인한다.
+```
+
+---
+
+## API 요약
+
+| 목적 | Method | URL | Request | Response data |
+|---|---|---|---|---|
+| 폼 옵션 조회 | GET | `/api/v2/gifts/form-options` | 없음 | 사이즈 목록, 카테고리 목록 |
+| 선물 신청 접수 | POST | `/api/v2/gifts` | 선물 신청 JSON body | 신청번호, 상태, 차감 금액, 운송장 등록 기한 |
+
+## Figma 반영 메모
+
+- 빈 상태 Figma는 카테고리 미선택, 보내는 사람 정보 미입력, 약관 미동의, 하단 CTA 비활성 상태다.
+- 활성 상태 Figma는 크리에이터 닉네임 표시, 카테고리 선택, 파손 면책 동의 노출, 보내는 사람 정보 입력, 약관 동의, 하단 CTA 활성 상태다.
+- Figma의 하단 버튼 텍스트는 캔 금액이 포함된 형태이므로 API의 `salePriceCan`으로 동적으로 표시한다.
+- Figma의 select, checkbox, radio, bottom action bar, safe area는 각 플랫폼의 기존 컴포넌트로 대응한다.

src/main/kotlin/kr/co/vividnext/sodalive/can/CanController.kt

@@ -17,7 +17,7 @@ class CanController(private val service: CanService) {
     fun getCans(
         @AuthenticationPrincipal(expression = "#this == 'anonymousUser' ? null : member") member: Member?
     ): ApiResponse<List<CanResponse>> {
-        val forcedCurrency = if (member != null && (member.id == 2L || member.id == 4L || member.id == 44144L)) {
+        val forcedCurrency = if (member != null && (member.id == 4L || member.id == 44144L)) {
             "JPY"
         } else {
             null

src/main/kotlin/kr/co/vividnext/sodalive/can/CanService.kt

@@ -120,6 +120,7 @@ class CanService(
 
                     CanUsage.CHAT_QUOTA_PURCHASE -> "캐릭터 톡 이용권 구매"
                     CanUsage.CHAT_ROOM_RESET -> "캐릭터 톡 초기화"
+                    CanUsage.GIFT -> "선물하기"
                 }
 
                 val createdAt = it.createdAt

src/main/kotlin/kr/co/vividnext/sodalive/can/payment/CanPaymentService.kt

@@ -54,7 +54,7 @@ class CanPaymentService(
         communityPost: CreatorCommunity? = null,
         auditionApplicant: AuditionApplicant? = null,
         container: String
-    ) {
+    ): UseCan {
         val member = memberRepository.findByIdOrNull(id = memberId)
             ?: throw SodaException(messageKey = "can.payment.invalid_request_retry")
         val useRewardCan = spendRewardCan(member, needCan, container)
@@ -131,6 +131,8 @@ class CanPaymentService(
             useCan.member = member
             useCan.chatRoomId = chatRoomId
             useCan.characterId = characterId
+        } else if (canUsage == CanUsage.GIFT) {
+            useCan.member = member
         } else {
             throw SodaException(messageKey = "common.error.invalid_request")
         }
@@ -160,6 +162,18 @@ class CanPaymentService(
             useCan,
             paymentGateway = PaymentGateway.APPLE_IAP
         )
+
+        return useCan
+    }
+
+    @Transactional
+    fun spendGiftCan(memberId: Long, needCan: Int, container: String): Long {
+        return spendCan(
+            memberId = memberId,
+            needCan = needCan,
+            canUsage = CanUsage.GIFT,
+            container = container
+        ).id!!
     }
 
     private fun setUseCanCalculate(
@@ -324,6 +338,24 @@ class CanPaymentService(
             roomId = roomId,
             canUsage = CanUsage.LIVE
         ) ?: throw SodaException(messageKey = "can.payment.invalid_reservation")
+        refundUseCan(member, useCan)
+    }
+
+    @Transactional
+    fun refundGiftCan(memberId: Long, useCanId: Long) {
+        val member = memberRepository.findByIdOrNull(memberId)
+            ?: throw SodaException(messageKey = "common.error.invalid_request")
+        val useCan = useCanRepository.findByIdOrNull(useCanId)
+            ?: throw SodaException(messageKey = "common.error.invalid_request")
+
+        if (useCan.member?.id != member.id || useCan.canUsage != CanUsage.GIFT || useCan.isRefund) {
+            throw SodaException(messageKey = "common.error.invalid_request")
+        }
+
+        refundUseCan(member, useCan)
+    }
+
+    private fun refundUseCan(member: Member, useCan: UseCan) {
         useCan.isRefund = true
 
         val useCanCalculates = useCanCalculateRepository.findByUseCanIdAndStatus(useCan.id!!)

src/main/kotlin/kr/co/vividnext/sodalive/can/use/CanUsage.kt

@@ -14,5 +14,6 @@ enum class CanUsage {
     CHAT_MESSAGE_PURCHASE, // 메시지를 통한 구매(이미지 등 다양한 리소스에 공통 적용)
     CHARACTER_IMAGE_PURCHASE, // 캐릭터 이미지 단독 구매
     CHAT_QUOTA_PURCHASE, // 채팅 횟수(쿼터) 충전
-    CHAT_ROOM_RESET // 채팅방 초기화 결제(별도 구분)
+    CHAT_ROOM_RESET, // 채팅방 초기화 결제(별도 구분)
+    GIFT
 }

src/main/kotlin/kr/co/vividnext/sodalive/configs/SecurityConfig.kt

@@ -10,6 +10,7 @@ import kr.co.vividnext.sodalive.jwt.TokenProvider
 import kr.co.vividnext.sodalive.v2.api.admin.aicharacter.error.AiCharacterAdminErrorResponseWriter
 import kr.co.vividnext.sodalive.v2.api.admin.aicharacter.error.AiCharacterAdminExceptionHandler
 import kr.co.vividnext.sodalive.v2.api.admin.aicharacter.security.AiCharacterAdminSecurityErrorHandler
+import org.springframework.boot.actuate.autoconfigure.security.servlet.EndpointRequest
 import org.springframework.context.annotation.Bean
 import org.springframework.context.annotation.Configuration
 import org.springframework.core.Ordered
@@ -156,6 +157,8 @@ class SecurityConfig(
                 JwtFilter::class.java
             )
             .authorizeRequests()
+            .antMatchers("/readyz").permitAll()
+            .requestMatchers(EndpointRequest.toAnyEndpoint()).permitAll()
             .antMatchers("/member/check/email").permitAll()
             .antMatchers("/member/check/nickname").permitAll()
             .antMatchers("/member/signup").permitAll()

src/main/kotlin/kr/co/vividnext/sodalive/content/AudioContentService.kt

@@ -38,7 +38,7 @@ import kr.co.vividnext.sodalive.i18n.translation.ResourceTranslationJobScheduler
 import kr.co.vividnext.sodalive.member.Member
 import kr.co.vividnext.sodalive.member.MemberRepository
 import kr.co.vividnext.sodalive.member.block.BlockMemberRepository
-import kr.co.vividnext.sodalive.member.contentpreference.isAdultVisibleByPolicy
+import kr.co.vividnext.sodalive.member.contentpreference.MemberContentPreferenceService
 import kr.co.vividnext.sodalive.utils.generateFileName
 import kr.co.vividnext.sodalive.v2.home.following.application.HomeFollowingNewsPublishService
 import kr.co.vividnext.sodalive.v2.recommendation.application.CreatorContentViewHistoryService
@@ -90,6 +90,7 @@ class AudioContentService(
 
     private val contentThemeTranslationRepository: ContentThemeTranslationRepository,
     private val homeFollowingNewsPublishService: HomeFollowingNewsPublishService,
+    private val memberContentPreferenceService: MemberContentPreferenceService,
 
     @Value("\${cloud.aws.s3.content-bucket}")
     private val audioContentBucket: String,
@@ -616,7 +617,7 @@ class AudioContentService(
         isAdultContentVisible: Boolean,
         timezone: String
     ): GetAudioContentDetailResponse {
-        val isAdult = isAdultVisibleByPolicy(member, isAdultContentVisible)
+        val isAdult = memberContentPreferenceService.isAdultVisibleForQuery(member, isAdultContentVisible)
 
         // 오디오 콘텐츠 조회 (content_id, 제목, 내용, 테마, 태그, 19여부, 이미지, 콘텐츠 PATH)
         val audioContent = repository.findByIdOrNull(id)
@@ -977,7 +978,7 @@ class AudioContentService(
         member: Member,
         isAdultContentVisible: Boolean
     ): GetAudioContentListItem? {
-        val isAdult = isAdultVisibleByPolicy(member, isAdultContentVisible)
+        val isAdult = memberContentPreferenceService.isAdultVisibleForQuery(member, isAdultContentVisible)
 
         if (isBlockedBetweenMembers(memberId = member.id!!, creatorId = creatorId)) {
             return null
@@ -1051,7 +1052,7 @@ class AudioContentService(
         offset: Long,
         limit: Long
     ): GetAudioContentListResponse {
-        val isAdult = isAdultVisibleByPolicy(member, isAdultContentVisible)
+        val isAdult = memberContentPreferenceService.isAdultVisibleForQuery(member, isAdultContentVisible)
         val isCreator = member.id == creatorId
 
         if (!isCreator && isBlockedBetweenMembers(memberId = member.id!!, creatorId = creatorId)) {

src/main/kotlin/kr/co/vividnext/sodalive/content/main/AudioContentMainService.kt

@@ -13,7 +13,7 @@ import kr.co.vividnext.sodalive.event.EventItem
 import kr.co.vividnext.sodalive.i18n.LangContext
 import kr.co.vividnext.sodalive.member.Member
 import kr.co.vividnext.sodalive.member.block.BlockMemberRepository
-import kr.co.vividnext.sodalive.member.contentpreference.isAdultVisibleByPolicy
+import kr.co.vividnext.sodalive.member.contentpreference.MemberContentPreferenceService
 import org.springframework.beans.factory.annotation.Value
 import org.springframework.cache.annotation.Cacheable
 import org.springframework.data.domain.Pageable
@@ -33,6 +33,8 @@ class AudioContentMainService(
 
     private val langContext: LangContext,
 
+    private val memberContentPreferenceService: MemberContentPreferenceService,
+
     @Value("\${cloud.aws.cloud-front.host}")
     private val imageHost: String
 ) {
@@ -69,7 +71,7 @@ class AudioContentMainService(
             } else {
                 emptyList()
             },
-            isAdult = isAdultVisibleByPolicy(member, isAdultContentVisible),
+            isAdult = memberContentPreferenceService.isAdultVisibleForQuery(member, isAdultContentVisible),
             contentType = contentType,
             offset = pageable.offset,
             limit = pageable.pageSize.toLong()
@@ -88,7 +90,7 @@ class AudioContentMainService(
          * - AS-IS theme은 한글만 처리하도록 되어 있음
          * - TO-BE 번역된 theme이 들어와도 동일한 동작을 하도록 처리
          */
-        val isAdult = isAdultVisibleByPolicy(member, isAdultContentVisible)
+        val isAdult = memberContentPreferenceService.isAdultVisibleForQuery(member, isAdultContentVisible)
         val themeListRaw = if (theme.isBlank()) {
             audioContentThemeRepository.getActiveThemeOfContent(
                 isAdult = isAdult,

src/main/kotlin/kr/co/vividnext/sodalive/content/main/curation/AudioContentCurationService.kt

@@ -6,7 +6,7 @@ import kr.co.vividnext.sodalive.content.SortType
 import kr.co.vividnext.sodalive.content.main.tab.GetContentCurationResponse
 import kr.co.vividnext.sodalive.member.Member
 import kr.co.vividnext.sodalive.member.block.BlockMemberRepository
-import kr.co.vividnext.sodalive.member.contentpreference.isAdultVisibleByPolicy
+import kr.co.vividnext.sodalive.member.contentpreference.MemberContentPreferenceService
 import org.springframework.beans.factory.annotation.Value
 import org.springframework.data.domain.Pageable
 import org.springframework.stereotype.Service
@@ -17,6 +17,7 @@ class AudioContentCurationService(
     private val repository: AudioContentCurationQueryRepository,
     private val contentRepository: AudioContentRepository,
     private val blockMemberRepository: BlockMemberRepository,
+    private val memberContentPreferenceService: MemberContentPreferenceService,
 
     @Value("\${cloud.aws.cloud-front.host}")
     private val cloudFrontHost: String
@@ -31,14 +32,14 @@ class AudioContentCurationService(
     ): GetCurationContentResponse {
         val totalCount = repository.findTotalCountByCurationId(
             curationId = curationId,
-            isAdult = isAdultVisibleByPolicy(member, isAdultContentVisible),
+            isAdult = memberContentPreferenceService.isAdultVisibleForQuery(member, isAdultContentVisible),
             contentType = contentType
         )
 
         val audioContentList = repository.findByCurationId(
             curationId = curationId,
             cloudfrontHost = cloudFrontHost,
-            isAdult = isAdultVisibleByPolicy(member, isAdultContentVisible),
+            isAdult = memberContentPreferenceService.isAdultVisibleForQuery(member, isAdultContentVisible),
             contentType = contentType,
             sortType = sortType,
             offset = pageable.offset,

src/main/kotlin/kr/co/vividnext/sodalive/content/main/tab/alarm/AudioContentMainTabAlarmService.kt

@@ -8,7 +8,7 @@ import kr.co.vividnext.sodalive.content.main.curation.AudioContentCurationQueryR
 import kr.co.vividnext.sodalive.content.main.tab.GetContentCurationResponse
 import kr.co.vividnext.sodalive.event.EventService
 import kr.co.vividnext.sodalive.member.Member
-import kr.co.vividnext.sodalive.member.contentpreference.isAdultVisibleByPolicy
+import kr.co.vividnext.sodalive.member.contentpreference.MemberContentPreferenceService
 import kr.co.vividnext.sodalive.rank.RankingService
 import org.springframework.stereotype.Service
 import java.time.DayOfWeek
@@ -21,14 +21,15 @@ class AudioContentMainTabAlarmService(
     private val contentRepository: AudioContentRepository,
     private val rankingService: RankingService,
     private val eventService: EventService,
-    private val curationRepository: AudioContentCurationQueryRepository
+    private val curationRepository: AudioContentCurationQueryRepository,
+    private val memberContentPreferenceService: MemberContentPreferenceService
 ) {
     fun fetchData(
         isAdultContentVisible: Boolean,
         contentType: ContentType,
         member: Member
     ): GetContentMainTabAlarmResponse {
-        val isAdult = isAdultVisibleByPolicy(member, isAdultContentVisible)
+        val isAdult = memberContentPreferenceService.isAdultVisibleForQuery(member, isAdultContentVisible)
         val memberId = member.id!!
 
         val contentBannerList = bannerService.getBannerList(
@@ -106,7 +107,7 @@ class AudioContentMainTabAlarmService(
         }
 
         val memberId = member.id!!
-        val isAdult = isAdultVisibleByPolicy(member, isAdultContentVisible)
+        val isAdult = memberContentPreferenceService.isAdultVisibleForQuery(member, isAdultContentVisible)
 
         val totalCount = contentRepository.totalAlarmCountByTheme(
             memberId = memberId,

src/main/kotlin/kr/co/vividnext/sodalive/content/main/tab/asmr/AudioContentMainTabAsmrService.kt

@@ -9,7 +9,7 @@ import kr.co.vividnext.sodalive.content.main.tab.AudioContentMainTabRepository
 import kr.co.vividnext.sodalive.content.main.tab.GetContentCurationResponse
 import kr.co.vividnext.sodalive.event.EventService
 import kr.co.vividnext.sodalive.member.Member
-import kr.co.vividnext.sodalive.member.contentpreference.isAdultVisibleByPolicy
+import kr.co.vividnext.sodalive.member.contentpreference.MemberContentPreferenceService
 import kr.co.vividnext.sodalive.rank.RankingService
 import org.springframework.stereotype.Service
 
@@ -20,14 +20,15 @@ class AudioContentMainTabAsmrService(
     private val contentRepository: AudioContentRepository,
     private val rankingService: RankingService,
     private val eventService: EventService,
-    private val curationRepository: AudioContentCurationQueryRepository
+    private val curationRepository: AudioContentCurationQueryRepository,
+    private val memberContentPreferenceService: MemberContentPreferenceService
 ) {
     fun fetchData(
         isAdultContentVisible: Boolean,
         contentType: ContentType,
         member: Member
     ): GetContentMainTabAsmrResponse {
-        val isAdult = isAdultVisibleByPolicy(member, isAdultContentVisible)
+        val isAdult = memberContentPreferenceService.isAdultVisibleForQuery(member, isAdultContentVisible)
         val memberId = member.id!!
         val theme = "ASMR"
         val tabId = 5L

src/main/kotlin/kr/co/vividnext/sodalive/content/main/tab/content/AudioContentMainTabContentService.kt

@@ -10,7 +10,7 @@ import kr.co.vividnext.sodalive.content.main.tab.GetContentCurationResponse
 import kr.co.vividnext.sodalive.content.theme.AudioContentThemeQueryRepository
 import kr.co.vividnext.sodalive.event.EventService
 import kr.co.vividnext.sodalive.member.Member
-import kr.co.vividnext.sodalive.member.contentpreference.isAdultVisibleByPolicy
+import kr.co.vividnext.sodalive.member.contentpreference.MemberContentPreferenceService
 import kr.co.vividnext.sodalive.rank.RankingService
 import org.springframework.stereotype.Service
 import java.time.LocalDateTime
@@ -23,7 +23,8 @@ class AudioContentMainTabContentService(
     private val rankingService: RankingService,
     private val eventService: EventService,
     private val tagCurationService: ContentMainTabTagCurationService,
-    private val curationRepository: AudioContentCurationQueryRepository
+    private val curationRepository: AudioContentCurationQueryRepository,
+    private val memberContentPreferenceService: MemberContentPreferenceService
 ) {
     fun fetchData(
         isAdultContentVisible: Boolean,
@@ -31,7 +32,7 @@ class AudioContentMainTabContentService(
         member: Member
     ): GetContentMainTabContentResponse {
         val memberId = member.id!!
-        val isAdult = isAdultVisibleByPolicy(member, isAdultContentVisible)
+        val isAdult = memberContentPreferenceService.isAdultVisibleForQuery(member, isAdultContentVisible)
         val tabId = 3L
 
         // 단편 배너
@@ -191,7 +192,7 @@ class AudioContentMainTabContentService(
         contentType: ContentType,
         member: Member
     ): List<GetAudioContentMainItem> {
-        val isAdult = isAdultVisibleByPolicy(member, isAdultContentVisible)
+        val isAdult = memberContentPreferenceService.isAdultVisibleForQuery(member, isAdultContentVisible)
 
         val themeList = if (theme.isBlank()) {
             audioContentThemeRepository.getActiveThemeOfContent(isAdult = isAdult, contentType = contentType)

src/main/kotlin/kr/co/vividnext/sodalive/content/main/tab/free/AudioContentMainTabFreeService.kt

@@ -11,7 +11,7 @@ import kr.co.vividnext.sodalive.content.main.tab.GetContentCurationResponse
 import kr.co.vividnext.sodalive.content.main.tab.RecommendSeriesRepository
 import kr.co.vividnext.sodalive.content.theme.AudioContentThemeQueryRepository
 import kr.co.vividnext.sodalive.member.Member
-import kr.co.vividnext.sodalive.member.contentpreference.isAdultVisibleByPolicy
+import kr.co.vividnext.sodalive.member.contentpreference.MemberContentPreferenceService
 import kr.co.vividnext.sodalive.rank.RankingService
 import org.springframework.stereotype.Service
 
@@ -24,14 +24,15 @@ class AudioContentMainTabFreeService(
     private val contentRepository: AudioContentRepository,
     private val rankingService: RankingService,
     private val audioContentRepository: AudioContentRepository,
-    private val audioContentThemeRepository: AudioContentThemeQueryRepository
+    private val audioContentThemeRepository: AudioContentThemeQueryRepository,
+    private val memberContentPreferenceService: MemberContentPreferenceService
 ) {
     fun fetchData(
         isAdultContentVisible: Boolean,
         contentType: ContentType,
         member: Member
     ): GetContentMainTabFreeResponse {
-        val isAdult = isAdultVisibleByPolicy(member, isAdultContentVisible)
+        val isAdult = memberContentPreferenceService.isAdultVisibleForQuery(member, isAdultContentVisible)
         val memberId = member.id!!
         val tabId = 7L
 
@@ -135,7 +136,7 @@ class AudioContentMainTabFreeService(
         offset: Long,
         limit: Long
     ): List<GetAudioContentMainItem> {
-        val isAdult = isAdultVisibleByPolicy(member, isAdultContentVisible)
+        val isAdult = memberContentPreferenceService.isAdultVisibleForQuery(member, isAdultContentVisible)
         val memberId = member.id!!
 
         val introduceCreatorCuration = curationRepository.findByContentMainTabIdAndTitle(
@@ -172,7 +173,7 @@ class AudioContentMainTabFreeService(
                 listOf(theme)
             } else {
                 audioContentThemeRepository.getActiveThemeOfContent(
-                    isAdult = isAdultVisibleByPolicy(member, isAdultContentVisible),
+                    isAdult = memberContentPreferenceService.isAdultVisibleForQuery(member, isAdultContentVisible),
                     isFree = true,
                     contentType = contentType
                 ).filter {
@@ -186,7 +187,7 @@ class AudioContentMainTabFreeService(
                         it != "자기소개"
                 }
             },
-            isAdult = isAdultVisibleByPolicy(member, isAdultContentVisible),
+            isAdult = memberContentPreferenceService.isAdultVisibleForQuery(member, isAdultContentVisible),
             contentType = contentType,
             offset = offset,
             limit = limit,

src/main/kotlin/kr/co/vividnext/sodalive/content/main/tab/home/AudioContentMainTabHomeService.kt

@@ -5,7 +5,7 @@ import kr.co.vividnext.sodalive.content.main.GetAudioContentRankingItem
 import kr.co.vividnext.sodalive.content.main.banner.AudioContentBannerService
 import kr.co.vividnext.sodalive.event.EventService
 import kr.co.vividnext.sodalive.member.Member
-import kr.co.vividnext.sodalive.member.contentpreference.isAdultVisibleByPolicy
+import kr.co.vividnext.sodalive.member.contentpreference.MemberContentPreferenceService
 import kr.co.vividnext.sodalive.notice.ServiceNoticeService
 import kr.co.vividnext.sodalive.rank.RankingService
 import org.springframework.stereotype.Service
@@ -19,7 +19,8 @@ class AudioContentMainTabHomeService(
     private val noticeService: ServiceNoticeService,
     private val bannerService: AudioContentBannerService,
     private val rankingService: RankingService,
-    private val eventService: EventService
+    private val eventService: EventService,
+    private val memberContentPreferenceService: MemberContentPreferenceService
 ) {
     fun fetchData(
         isAdultContentVisible: Boolean,
@@ -43,7 +44,9 @@ class AudioContentMainTabHomeService(
         val formattedLastMonday = startDate.format(startDateFormatter)
         val formattedLastSunday = endDate.format(endDateFormatter)
 
-        val isAdult = member?.let { isAdultVisibleByPolicy(it, isAdultContentVisible) } ?: false
+        val isAdult = member
+            ?.let { memberContentPreferenceService.isAdultVisibleForQuery(it, isAdultContentVisible) }
+            ?: false
 
         // 최근 공지사항
         val latestNotice = noticeService.getLatestNotice()
@@ -131,7 +134,9 @@ class AudioContentMainTabHomeService(
         contentType: ContentType,
         member: Member?
     ): List<GetAudioContentRankingItem> {
-        val isAdult = member?.let { isAdultVisibleByPolicy(it, isAdultContentVisible) } ?: false
+        val isAdult = member
+            ?.let { memberContentPreferenceService.isAdultVisibleForQuery(it, isAdultContentVisible) }
+            ?: false
 
         val currentDateTime = LocalDateTime.now()
         val startDate = currentDateTime

src/main/kotlin/kr/co/vividnext/sodalive/content/main/tab/replay/AudioContentMainTabLiveReplayService.kt

@@ -9,7 +9,7 @@ import kr.co.vividnext.sodalive.content.main.tab.AudioContentMainTabRepository
 import kr.co.vividnext.sodalive.content.main.tab.GetContentCurationResponse
 import kr.co.vividnext.sodalive.event.EventService
 import kr.co.vividnext.sodalive.member.Member
-import kr.co.vividnext.sodalive.member.contentpreference.isAdultVisibleByPolicy
+import kr.co.vividnext.sodalive.member.contentpreference.MemberContentPreferenceService
 import kr.co.vividnext.sodalive.rank.RankingService
 import org.springframework.stereotype.Service
 
@@ -20,14 +20,15 @@ class AudioContentMainTabLiveReplayService(
     private val contentRepository: AudioContentRepository,
     private val rankingService: RankingService,
     private val eventService: EventService,
-    private val curationRepository: AudioContentCurationQueryRepository
+    private val curationRepository: AudioContentCurationQueryRepository,
+    private val memberContentPreferenceService: MemberContentPreferenceService
 ) {
     fun fetchData(
         isAdultContentVisible: Boolean,
         contentType: ContentType,
         member: Member
     ): GetContentMainTabLiveReplayResponse {
-        val isAdult = isAdultVisibleByPolicy(member, isAdultContentVisible)
+        val isAdult = memberContentPreferenceService.isAdultVisibleForQuery(member, isAdultContentVisible)
         val memberId = member.id!!
         val theme = "다시듣기"
         val tabId = 6L

src/main/kotlin/kr/co/vividnext/sodalive/content/main/tab/series/AudioContentMainTabSeriesService.kt

@@ -8,7 +8,7 @@ import kr.co.vividnext.sodalive.content.series.ContentSeriesService
 import kr.co.vividnext.sodalive.content.series.GetSeriesListResponse
 import kr.co.vividnext.sodalive.event.EventService
 import kr.co.vividnext.sodalive.member.Member
-import kr.co.vividnext.sodalive.member.contentpreference.isAdultVisibleByPolicy
+import kr.co.vividnext.sodalive.member.contentpreference.MemberContentPreferenceService
 import kr.co.vividnext.sodalive.rank.RankingService
 import org.springframework.stereotype.Service
 import java.time.DayOfWeek
@@ -24,14 +24,15 @@ class AudioContentMainTabSeriesService(
     private val rankingService: RankingService,
     private val recommendSeriesRepository: RecommendSeriesRepository,
     private val eventService: EventService,
-    private val curationRepository: AudioContentCurationQueryRepository
+    private val curationRepository: AudioContentCurationQueryRepository,
+    private val memberContentPreferenceService: MemberContentPreferenceService
 ) {
     fun fetchData(
         isAdultContentVisible: Boolean,
         contentType: ContentType,
         member: Member
     ): GetContentMainTabSeriesResponse {
-        val isAdult = isAdultVisibleByPolicy(member, isAdultContentVisible)
+        val isAdult = memberContentPreferenceService.isAdultVisibleForQuery(member, isAdultContentVisible)
         val memberId = member.id!!
 
         // 메인 배너 (시리즈)

src/main/kotlin/kr/co/vividnext/sodalive/content/series/ContentSeriesService.kt

@@ -19,7 +19,7 @@ import kr.co.vividnext.sodalive.i18n.translation.LanguageTranslationTargetType
 import kr.co.vividnext.sodalive.i18n.translation.ResourceTranslationJobScheduler
 import kr.co.vividnext.sodalive.member.Member
 import kr.co.vividnext.sodalive.member.block.BlockMemberRepository
-import kr.co.vividnext.sodalive.member.contentpreference.isAdultVisibleByPolicy
+import kr.co.vividnext.sodalive.member.contentpreference.MemberContentPreferenceService
 import org.springframework.beans.factory.annotation.Value
 import org.springframework.stereotype.Service
 import org.springframework.transaction.annotation.Transactional
@@ -40,6 +40,7 @@ class ContentSeriesService(
     private val seriesGenreTranslationRepository: SeriesGenreTranslationRepository,
     private val contentTranslationRepository: ContentTranslationRepository,
     private val resourceTranslationJobScheduler: ResourceTranslationJobScheduler,
+    private val memberContentPreferenceService: MemberContentPreferenceService,
 
     @Value("\${cloud.aws.cloud-front.host}")
     private val coverImageHost: String
@@ -147,7 +148,7 @@ class ContentSeriesService(
         offset: Long = 0,
         limit: Long = 20
     ): GetSeriesListResponse {
-        val isAuth = isAdultVisibleByPolicy(member, isAdultContentVisible)
+        val isAuth = memberContentPreferenceService.isAdultVisibleForQuery(member, isAdultContentVisible)
 
         val totalCount = repository.getSeriesTotalCount(
             creatorId = creatorId,
@@ -185,7 +186,7 @@ class ContentSeriesService(
         offset: Long = 0,
         limit: Long = 20
     ): GetSeriesListResponse {
-        val isAuth = isAdultVisibleByPolicy(member, isAdultContentVisible)
+        val isAuth = memberContentPreferenceService.isAdultVisibleForQuery(member, isAdultContentVisible)
 
         val totalCount = repository.getSeriesByGenreTotalCount(
             genreId = genreId,
@@ -219,7 +220,7 @@ class ContentSeriesService(
     ): GetSeriesDetailResponse {
         val series = repository.getSeriesDetail(
             seriesId = seriesId,
-            isAuth = isAdultVisibleByPolicy(member, isAdultContentVisible),
+            isAuth = memberContentPreferenceService.isAdultVisibleForQuery(member, isAdultContentVisible),
             contentType = contentType
         ) ?: throw SodaException(messageKey = "series.error.invalid_series_retry")
 
@@ -364,7 +365,7 @@ class ContentSeriesService(
         offset: Long,
         limit: Long
     ): GetSeriesContentListResponse {
-        val isAdult = isAdultVisibleByPolicy(member, isAdultContentVisible)
+        val isAdult = memberContentPreferenceService.isAdultVisibleForQuery(member, isAdultContentVisible)
 
         val totalCount = seriesContentRepository.getContentCount(seriesId, isAdult = isAdult, contentType = contentType)
         val contentList = seriesContentRepository.getContentList(
@@ -427,7 +428,7 @@ class ContentSeriesService(
         contentType: ContentType,
         member: Member
     ): List<GetSeriesListResponse.SeriesListItem> {
-        val isAuth = isAdultVisibleByPolicy(member, isAdultContentVisible)
+        val isAuth = memberContentPreferenceService.isAdultVisibleForQuery(member, isAdultContentVisible)
         return repository.getRecommendSeriesListV2(
             imageHost = coverImageHost,
             isAuth = isAuth,

src/main/kotlin/kr/co/vividnext/sodalive/content/theme/AudioContentThemeService.kt

@@ -11,7 +11,7 @@ import kr.co.vividnext.sodalive.i18n.LangContext
 import kr.co.vividnext.sodalive.i18n.translation.LanguageTranslationTargetType
 import kr.co.vividnext.sodalive.i18n.translation.ResourceTranslationJobScheduler
 import kr.co.vividnext.sodalive.member.Member
-import kr.co.vividnext.sodalive.member.contentpreference.isAdultVisibleByPolicy
+import kr.co.vividnext.sodalive.member.contentpreference.MemberContentPreferenceService
 import org.springframework.stereotype.Service
 import org.springframework.transaction.annotation.Transactional
 
@@ -22,7 +22,8 @@ class AudioContentThemeService(
     private val contentThemeTranslationRepository: ContentThemeTranslationRepository,
 
     private val resourceTranslationJobScheduler: ResourceTranslationJobScheduler,
-    private val langContext: LangContext
+    private val langContext: LangContext,
+    private val memberContentPreferenceService: MemberContentPreferenceService
 ) {
     @Transactional(readOnly = true)
     fun getThemes(): List<GetAudioContentThemeResponse> {
@@ -100,7 +101,7 @@ class AudioContentThemeService(
         val totalCount = contentRepository.totalCountByTheme(
             memberId = member.id!!,
             theme = listOf(theme.theme),
-            isAdult = isAdultVisibleByPolicy(member, isAdultContentVisible),
+            isAdult = memberContentPreferenceService.isAdultVisibleForQuery(member, isAdultContentVisible),
             contentType = contentType
         )
 
@@ -108,7 +109,7 @@ class AudioContentThemeService(
             memberId = member.id!!,
             theme = listOf(theme.theme),
             sortType = sortType,
-            isAdult = isAdultVisibleByPolicy(member, isAdultContentVisible),
+            isAdult = memberContentPreferenceService.isAdultVisibleForQuery(member, isAdultContentVisible),
             contentType = contentType,
             offset = offset,
             limit = limit

src/main/kotlin/kr/co/vividnext/sodalive/deployment/DeploymentEndpoint.kt

@@ -0,0 +1,21 @@
+package kr.co.vividnext.sodalive.deployment
+
+import org.springframework.beans.factory.annotation.Value
+import org.springframework.boot.actuate.endpoint.annotation.Endpoint
+import org.springframework.boot.actuate.endpoint.annotation.ReadOperation
+import org.springframework.stereotype.Component
+
+@Component
+@Endpoint(id = "deployment")
+class DeploymentEndpoint(
+    @Value("\${deployment.artifact-version}")
+    private val artifactVersion: String,
+    @Value("\${deployment.config-commit}")
+    private val configCommit: String
+) {
+    @ReadOperation
+    fun deployment(): Map<String, String> = mapOf(
+        "application_artifact_version" to artifactVersion,
+        "config_commit" to configCommit
+    )
+}

src/main/kotlin/kr/co/vividnext/sodalive/fcm/FcmEvent.kt

@@ -25,7 +25,8 @@ enum class FcmDeepLinkValue(val value: String) {
     SERIES("series"),
     AUDITION("audition"),
     COMMUNITY("community"),
-    CHAT("chat")
+    CHAT("chat"),
+    GIFT_DETAIL("gift-detail")
 }
 
 class FcmEvent(
@@ -50,7 +51,7 @@ class FcmEvent(
     val creatorId: Long? = null,
     val auditionId: Long? = null,
     val deepLinkValue: FcmDeepLinkValue? = null,
-    val deepLinkId: Long? = null,
+    val deepLinkId: Any? = null,
     val deepLinkCommentPostId: Long? = null,
     val commentParentId: Long? = null,
     val myMemberId: Long? = null,

src/main/kotlin/kr/co/vividnext/sodalive/fcm/FcmService.kt

@@ -32,7 +32,7 @@ class FcmService(
         creatorId: Long? = null,
         auditionId: Long? = null,
         deepLinkValue: FcmDeepLinkValue? = null,
-        deepLinkId: Long? = null,
+        deepLinkId: Any? = null,
         deepLinkCommentPostId: Long? = null,
         chatType: String? = null
     ) {
@@ -118,7 +118,7 @@ class FcmService(
 
     private fun createDeepLink(
         deepLinkValue: FcmDeepLinkValue?,
-        deepLinkId: Long?,
+        deepLinkId: Any?,
         deepLinkCommentPostId: Long?
     ): String? {
         return buildDeepLink(serverEnv, deepLinkValue, deepLinkId, deepLinkCommentPostId)
@@ -194,7 +194,7 @@ class FcmService(
         fun buildDeepLink(
             serverEnv: String,
             deepLinkValue: FcmDeepLinkValue?,
-            deepLinkId: Long?,
+            deepLinkId: Any?,
             deepLinkCommentPostId: Long? = null
         ): String? {
             if (deepLinkValue == null || deepLinkId == null) {
@@ -222,7 +222,7 @@ class FcmService(
             creatorId: Long? = null,
             auditionId: Long? = null,
             deepLinkValue: FcmDeepLinkValue? = null,
-            deepLinkId: Long? = null,
+            deepLinkId: Any? = null,
             deepLinkCommentPostId: Long? = null,
             deepLink: String? = null,
             chatType: String? = null

src/main/kotlin/kr/co/vividnext/sodalive/fcm/notification/PushNotificationCategory.kt

@@ -6,6 +6,7 @@ enum class PushNotificationCategory(val code: String) {
     COMMUNITY("community"),
     MESSAGE("message"),
     AUDITION("audition"),
+    GIFT("gift"),
     SYSTEM("system");
 
     companion object {

src/main/kotlin/kr/co/vividnext/sodalive/live/room/LiveRoomService.kt

@@ -812,6 +812,14 @@ class LiveRoomService(
             )
         }
 
+        if (
+            member.role == MemberRole.CREATOR &&
+            room.member!!.id!! != member.id!! &&
+            !room.isAvailableJoinCreator
+        ) {
+            throw SodaException(messageKey = "live.room.not_found")
+        }
+
         if (room.member!!.id!! != member.id!! && !member.canEnter(room.genderRestriction)) {
             throw SodaException(messageKey = "live.room.gender_restricted")
         }
@@ -975,6 +983,18 @@ class LiveRoomService(
             throw SodaException(messageKey = "live.room.info_not_found")
         }
 
+        if (
+            member.role == MemberRole.CREATOR &&
+            room.member!!.id!! != member.id!! &&
+            !room.isAvailableJoinCreator
+        ) {
+            throw SodaException(messageKey = "live.room.not_found")
+        }
+
+        if (room.member!!.id!! != member.id!! && !member.canEnter(room.genderRestriction)) {
+            throw SodaException(messageKey = "live.room.gender_restricted")
+        }
+
         val currentTimeStamp = Date().time
         val expireTimestamp = (currentTimeStamp + (60 * 60 * 24 * 1000)) / 1000
 

src/main/kotlin/kr/co/vividnext/sodalive/member/contentpreference/MemberContentPreferenceCountryResolver.kt

@@ -3,7 +3,7 @@ package kr.co.vividnext.sodalive.member.contentpreference
 import kr.co.vividnext.sodalive.member.Member
 
 private val FORCED_KR_MEMBER_IDS = setOf(16L, 17L, 17958L, 44144L)
-private val FORCED_JP_MEMBER_IDS = setOf(2L, 29721L, 32050L, 37543L, 40850L)
+private val FORCED_JP_MEMBER_IDS = setOf(29721L, 32050L, 37543L, 40850L)
 
 fun resolveCountryCodeWithForcedMapping(member: Member?, requestCountryCode: String?): String {
     val memberId = member?.id

src/main/kotlin/kr/co/vividnext/sodalive/member/contentpreference/MemberContentPreferencePolicy.kt

@@ -1,21 +0,0 @@
-package kr.co.vividnext.sodalive.member.contentpreference
-
-import kr.co.vividnext.sodalive.member.Member
-import org.springframework.web.context.request.RequestContextHolder
-import org.springframework.web.context.request.ServletRequestAttributes
-
-@Deprecated("Use MemberContentPreferenceService.canViewAdultContent(member)")
-fun resolveCountryCodeByPolicy(member: Member): String {
-    val requestAttributes = RequestContextHolder.getRequestAttributes() as? ServletRequestAttributes
-    val requestCountryCode = requestAttributes?.request?.getHeader("CloudFront-Viewer-Country")
-    return resolveCountryCodeWithForcedMapping(member, requestCountryCode)
-}
-
-@Deprecated("Use MemberContentPreferenceService.canViewAdultContent(member)")
-fun isAdultVisibleByPolicy(member: Member, isAdultContentVisible: Boolean): Boolean {
-    return if (resolveCountryCodeByPolicy(member) == "KR") {
-        member.auth != null && isAdultContentVisible
-    } else {
-        isAdultContentVisible
-    }
-}

src/main/kotlin/kr/co/vividnext/sodalive/member/contentpreference/MemberContentPreferenceService.kt

@@ -157,6 +157,14 @@ class MemberContentPreferenceService(
         return getStoredPreference(member).isAdult
     }
 
+    fun isAdultVisibleForQuery(member: Member, isAdultContentVisible: Boolean): Boolean {
+        return calculateIsAdultForQuery(
+            member = member,
+            countryCode = resolveCountryCode(member),
+            isAdultContentVisible = isAdultContentVisible
+        )
+    }
+
     fun resolveCountryCode(member: Member?): String {
         if (member != null) requireMemberId(member)
         return resolveCountryCodeWithForcedMapping(member, countryContext.countryCode)

src/main/kotlin/kr/co/vividnext/sodalive/menu/MenuService.kt

@@ -1,6 +1,7 @@
 package kr.co.vividnext.sodalive.menu
 
 import kr.co.vividnext.sodalive.member.Member
+import kr.co.vividnext.sodalive.member.MemberRole
 import org.springframework.stereotype.Service
 
 @Service
@@ -8,6 +9,20 @@ class MenuService(
     private val repository: MenuRepository
 ) {
     fun getMenus(member: Member): List<GetMenuResponse> {
-        return repository.getMenu(member.role)
+        val menus = repository.getMenu(member.role)
+        if (member.role != MemberRole.ADMIN) return menus
+
+        return menus + giftManagementMenu
+    }
+
+    private companion object {
+        val giftManagementMenu = GetMenuResponse(
+            title = "선물함 관리",
+            items = listOf(
+                GetMenuResponse(title = "선물함 리스트", route = "/gift/list"),
+                GetMenuResponse(title = "선물 카테고리", route = "/gift/category"),
+                GetMenuResponse(title = "선물 사이즈", route = "/gift/size")
+            )
+        )
     }
 }

src/main/kotlin/kr/co/vividnext/sodalive/v2/api/admin/gift/adapter/in/web/AdminGiftController.kt

@@ -0,0 +1,106 @@
+package kr.co.vividnext.sodalive.v2.api.admin.gift.adapter.`in`.web
+
+import kr.co.vividnext.sodalive.common.ApiResponse
+import kr.co.vividnext.sodalive.v2.api.admin.gift.dto.AdminGiftCategoryRequest
+import kr.co.vividnext.sodalive.v2.api.admin.gift.dto.AdminGiftCategoryResponse
+import kr.co.vividnext.sodalive.v2.api.admin.gift.dto.AdminGiftDetailResponse
+import kr.co.vividnext.sodalive.v2.api.admin.gift.dto.AdminGiftListResponse
+import kr.co.vividnext.sodalive.v2.api.admin.gift.dto.AdminGiftMailboxRequest
+import kr.co.vividnext.sodalive.v2.api.admin.gift.dto.AdminGiftMailboxResponse
+import kr.co.vividnext.sodalive.v2.api.admin.gift.dto.AdminGiftMarkUndeliverableRequest
+import kr.co.vividnext.sodalive.v2.api.admin.gift.dto.AdminGiftOperationStatusResponse
+import kr.co.vividnext.sodalive.v2.api.admin.gift.dto.AdminGiftSizePriceRequest
+import kr.co.vividnext.sodalive.v2.api.admin.gift.dto.AdminGiftSizePriceResponse
+import kr.co.vividnext.sodalive.v2.gift.application.GiftAdminQueryService
+import kr.co.vividnext.sodalive.v2.gift.application.GiftAdminService
+import kr.co.vividnext.sodalive.v2.gift.domain.GiftSize
+import kr.co.vividnext.sodalive.v2.gift.domain.GiftStatus
+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.RestController
+
+@RestController
+@RequestMapping("/api/v2/admin")
+@PreAuthorize("hasRole('ADMIN')")
+class AdminGiftController(
+    private val service: GiftAdminService,
+    private val queryService: GiftAdminQueryService
+) {
+    @GetMapping("/gifts")
+    fun getGifts(
+        @RequestParam(required = false) status: GiftStatus?,
+        @RequestParam(required = false) applicationNo: String?,
+        @RequestParam(required = false) nickname: String?,
+        @RequestParam(defaultValue = "0") page: Int,
+        @RequestParam(defaultValue = "20") size: Int
+    ) = ApiResponse.ok(AdminGiftListResponse.from(queryService.getGifts(status, applicationNo, nickname, page, size)))
+
+    @GetMapping("/gifts/{applicationNo}")
+    fun getGiftDetail(@PathVariable applicationNo: String) = ApiResponse.ok(
+        AdminGiftDetailResponse.from(queryService.getGiftDetail(applicationNo))
+    )
+
+    @GetMapping("/gift-mailbox")
+    fun getMailbox() = ApiResponse.ok(service.getMailbox()?.let { AdminGiftMailboxResponse.from(it) })
+
+    @PutMapping("/gift-mailbox")
+    fun updateMailbox(@RequestBody request: AdminGiftMailboxRequest) = ApiResponse.ok(
+        AdminGiftMailboxResponse.from(service.updateMailbox(request.toCommand()))
+    )
+
+    @GetMapping("/gift-categories")
+    fun getCategories() = ApiResponse.ok(service.getCategories().map { AdminGiftCategoryResponse.from(it) })
+
+    @PostMapping("/gift-categories")
+    fun createCategory(@RequestBody request: AdminGiftCategoryRequest) = ApiResponse.ok(
+        AdminGiftCategoryResponse.from(service.createCategory(request.toCommand()))
+    )
+
+    @PutMapping("/gift-categories/{categoryId}")
+    fun updateCategory(
+        @PathVariable categoryId: Long,
+        @RequestBody request: AdminGiftCategoryRequest
+    ) = ApiResponse.ok(AdminGiftCategoryResponse.from(service.updateCategory(categoryId, request.toCommand())))
+
+    @DeleteMapping("/gift-categories/{categoryId}")
+    fun deleteCategory(@PathVariable categoryId: Long) = ApiResponse.ok(
+        AdminGiftCategoryResponse.from(service.deleteCategory(categoryId))
+    )
+
+    @GetMapping("/gift-size-prices")
+    fun getSizePrices() = ApiResponse.ok(service.getSizePrices().map { AdminGiftSizePriceResponse.from(it) })
+
+    @PutMapping("/gift-size-prices/{sizeCode}")
+    fun updateSizePrice(
+        @PathVariable sizeCode: GiftSize,
+        @RequestBody request: AdminGiftSizePriceRequest
+    ) = ApiResponse.ok(AdminGiftSizePriceResponse.from(service.updateSizePrice(sizeCode, request.toCommand())))
+
+    @PostMapping("/gifts/{applicationNo}/arrive-mailbox")
+    fun arriveMailbox(@PathVariable applicationNo: String) = ApiResponse.ok(
+        AdminGiftOperationStatusResponse.from(service.arriveMailbox(applicationNo))
+    )
+
+    @PostMapping("/gifts/{applicationNo}/complete-inspection")
+    fun completeInspection(@PathVariable applicationNo: String) = ApiResponse.ok(
+        AdminGiftOperationStatusResponse.from(service.completeInspection(applicationNo))
+    )
+
+    @PostMapping("/gifts/{applicationNo}/mark-undeliverable")
+    fun markUndeliverable(
+        @PathVariable applicationNo: String,
+        @RequestBody request: AdminGiftMarkUndeliverableRequest
+    ) = ApiResponse.ok(AdminGiftOperationStatusResponse.from(service.markUndeliverable(applicationNo, request.reason)))
+
+    @PostMapping("/gifts/{applicationNo}/complete-delivery")
+    fun completeDelivery(@PathVariable applicationNo: String) = ApiResponse.ok(
+        AdminGiftOperationStatusResponse.from(service.completeDelivery(applicationNo))
+    )
+}

src/main/kotlin/kr/co/vividnext/sodalive/v2/api/admin/gift/dto/AdminGiftRequest.kt

@@ -0,0 +1,57 @@
+package kr.co.vividnext.sodalive.v2.api.admin.gift.dto
+
+import kr.co.vividnext.sodalive.v2.gift.application.GiftCategoryCommand
+import kr.co.vividnext.sodalive.v2.gift.application.GiftMailboxCommand
+import kr.co.vividnext.sodalive.v2.gift.application.GiftSizePriceCommand
+
+data class AdminGiftCategoryRequest(
+    val classificationNumber: String,
+    val categoryCode: String,
+    val name: String,
+    val receiptCode: String,
+    val representativeItem: String,
+    val requiresDamageWaiver: Boolean,
+    val isActive: Boolean
+) {
+    fun toCommand() = GiftCategoryCommand(
+        classificationNumber = classificationNumber,
+        categoryCode = categoryCode,
+        name = name,
+        receiptCode = receiptCode,
+        representativeItem = representativeItem,
+        requiresDamageWaiver = requiresDamageWaiver,
+        isActive = isActive
+    )
+}
+
+data class AdminGiftSizePriceRequest(
+    val basePriceCan: Int,
+    val salePriceCan: Int,
+    val isActive: Boolean
+) {
+    fun toCommand() = GiftSizePriceCommand(
+        basePriceCan = basePriceCan,
+        salePriceCan = salePriceCan,
+        isActive = isActive
+    )
+}
+
+data class AdminGiftMailboxRequest(
+    val name: String,
+    val phoneNumber: String,
+    val zipCode: String,
+    val address: String,
+    val addressDetail: String?
+) {
+    fun toCommand() = GiftMailboxCommand(
+        name = name,
+        phoneNumber = phoneNumber,
+        zipCode = zipCode,
+        address = address,
+        addressDetail = addressDetail
+    )
+}
+
+data class AdminGiftMarkUndeliverableRequest(
+    val reason: String
+)

src/main/kotlin/kr/co/vividnext/sodalive/v2/api/admin/gift/dto/AdminGiftResponse.kt

@@ -0,0 +1,204 @@
+package kr.co.vividnext.sodalive.v2.api.admin.gift.dto
+
+import kr.co.vividnext.sodalive.extensions.toUtcIso
+import kr.co.vividnext.sodalive.v2.gift.application.AdminGiftDetailResult
+import kr.co.vividnext.sodalive.v2.gift.application.AdminGiftInboundDeliveryInfoResult
+import kr.co.vividnext.sodalive.v2.gift.application.AdminGiftListItemResult
+import kr.co.vividnext.sodalive.v2.gift.application.AdminGiftListResult
+import kr.co.vividnext.sodalive.v2.gift.application.AdminGiftMemberInfoResult
+import kr.co.vividnext.sodalive.v2.gift.application.AdminGiftProductInfoResult
+import kr.co.vividnext.sodalive.v2.gift.application.GiftCategoryResult
+import kr.co.vividnext.sodalive.v2.gift.application.GiftMailboxResult
+import kr.co.vividnext.sodalive.v2.gift.application.GiftOperationStatusResult
+import kr.co.vividnext.sodalive.v2.gift.application.GiftSizePriceResult
+import kr.co.vividnext.sodalive.v2.gift.domain.GiftStatus
+
+data class AdminGiftCategoryResponse(
+    val categoryId: Long,
+    val classificationNumber: String,
+    val categoryCode: String,
+    val name: String,
+    val receiptCode: String,
+    val representativeItem: String,
+    val requiresDamageWaiver: Boolean,
+    val isActive: Boolean
+) {
+    companion object {
+        fun from(result: GiftCategoryResult) = AdminGiftCategoryResponse(
+            categoryId = result.categoryId,
+            classificationNumber = result.classificationNumber,
+            categoryCode = result.categoryCode,
+            name = result.name,
+            receiptCode = result.receiptCode,
+            representativeItem = result.representativeItem,
+            requiresDamageWaiver = result.requiresDamageWaiver,
+            isActive = result.isActive
+        )
+    }
+}
+
+data class AdminGiftSizePriceResponse(
+    val sizeCode: String,
+    val name: String,
+    val basePriceCan: Int,
+    val salePriceCan: Int,
+    val isActive: Boolean
+) {
+    companion object {
+        fun from(result: GiftSizePriceResult) = AdminGiftSizePriceResponse(
+            sizeCode = result.sizeCode.name,
+            name = result.sizeName,
+            basePriceCan = result.basePriceCan,
+            salePriceCan = result.salePriceCan,
+            isActive = result.isActive
+        )
+    }
+}
+
+data class AdminGiftOperationStatusResponse(
+    val applicationNo: String,
+    val status: GiftStatus,
+    val statusName: String,
+    val occurredAt: String
+) {
+    companion object {
+        fun from(result: GiftOperationStatusResult) = AdminGiftOperationStatusResponse(
+            applicationNo = result.applicationNo,
+            status = result.status,
+            statusName = result.statusName,
+            occurredAt = result.occurredAt.toUtcIso()
+        )
+    }
+}
+
+data class AdminGiftMailboxResponse(
+    val name: String,
+    val address: String,
+    val phoneNumber: String
+) {
+    companion object {
+        fun from(result: GiftMailboxResult) = AdminGiftMailboxResponse(
+            name = result.name,
+            address = result.address,
+            phoneNumber = result.phoneNumber
+        )
+    }
+}
+
+data class AdminGiftListResponse(
+    val totalCount: Long,
+    val items: List<AdminGiftListItemResponse>,
+    val page: Int,
+    val size: Int,
+    val hasNext: Boolean
+) {
+    companion object {
+        fun from(result: AdminGiftListResult) = AdminGiftListResponse(
+            totalCount = result.totalCount,
+            items = result.items.map { AdminGiftListItemResponse.from(it) },
+            page = result.page,
+            size = result.size,
+            hasNext = result.hasNext
+        )
+    }
+}
+
+data class AdminGiftListItemResponse(
+    val applicationNo: String,
+    val senderNickname: String,
+    val recipientNickname: String,
+    val sizeCode: String,
+    val sizeName: String,
+    val categoryName: String,
+    val classificationNumber: String,
+    val courierCompanyName: String?,
+    val trackingNumber: String?,
+    val status: GiftStatus,
+    val statusName: String,
+    val availableActions: List<String>
+) {
+    companion object {
+        fun from(result: AdminGiftListItemResult) = AdminGiftListItemResponse(
+            applicationNo = result.applicationNo,
+            senderNickname = result.senderNickname,
+            recipientNickname = result.recipientNickname,
+            sizeCode = result.sizeCode,
+            sizeName = result.sizeName,
+            categoryName = result.categoryName,
+            classificationNumber = result.classificationNumber,
+            courierCompanyName = result.courierCompanyName,
+            trackingNumber = result.trackingNumber,
+            status = result.status,
+            statusName = result.statusName,
+            availableActions = result.availableActions
+        )
+    }
+}
+
+data class AdminGiftDetailResponse(
+    val applicationNo: String,
+    val senderInfo: AdminGiftMemberInfoResponse,
+    val recipientInfo: AdminGiftMemberInfoResponse,
+    val productInfo: AdminGiftProductInfoResponse,
+    val inboundDeliveryInfo: AdminGiftInboundDeliveryInfoResponse,
+    val status: GiftStatus,
+    val statusName: String,
+    val availableActions: List<String>
+) {
+    companion object {
+        fun from(result: AdminGiftDetailResult) = AdminGiftDetailResponse(
+            applicationNo = result.applicationNo,
+            senderInfo = AdminGiftMemberInfoResponse.from(result.senderInfo),
+            recipientInfo = AdminGiftMemberInfoResponse.from(result.recipientInfo),
+            productInfo = AdminGiftProductInfoResponse.from(result.productInfo),
+            inboundDeliveryInfo = AdminGiftInboundDeliveryInfoResponse.from(result.inboundDeliveryInfo),
+            status = result.status,
+            statusName = result.statusName,
+            availableActions = result.availableActions
+        )
+    }
+}
+
+data class AdminGiftMemberInfoResponse(
+    val nickname: String,
+    val name: String,
+    val phoneNumber: String,
+    val address: String
+) {
+    companion object {
+        fun from(result: AdminGiftMemberInfoResult) = AdminGiftMemberInfoResponse(
+            nickname = result.nickname,
+            name = result.name,
+            phoneNumber = result.phoneNumber,
+            address = result.address
+        )
+    }
+}
+
+data class AdminGiftProductInfoResponse(
+    val sizeCode: String,
+    val sizeName: String,
+    val categoryName: String,
+    val classificationNumber: String
+) {
+    companion object {
+        fun from(result: AdminGiftProductInfoResult) = AdminGiftProductInfoResponse(
+            sizeCode = result.sizeCode,
+            sizeName = result.sizeName,
+            categoryName = result.categoryName,
+            classificationNumber = result.classificationNumber
+        )
+    }
+}
+
+data class AdminGiftInboundDeliveryInfoResponse(
+    val courierCompanyName: String?,
+    val trackingNumber: String?
+) {
+    companion object {
+        fun from(result: AdminGiftInboundDeliveryInfoResult) = AdminGiftInboundDeliveryInfoResponse(
+            courierCompanyName = result.courierCompanyName,
+            trackingNumber = result.trackingNumber
+        )
+    }
+}

src/main/kotlin/kr/co/vividnext/sodalive/v2/api/gift/adapter/in/web/GiftController.kt

@@ -0,0 +1,153 @@
+package kr.co.vividnext.sodalive.v2.api.gift.adapter.`in`.web
+
+import kr.co.vividnext.sodalive.common.ApiResponse
+import kr.co.vividnext.sodalive.common.SodaException
+import kr.co.vividnext.sodalive.member.Member
+import kr.co.vividnext.sodalive.v2.api.gift.dto.GiftApplicationRequest
+import kr.co.vividnext.sodalive.v2.api.gift.dto.GiftApplicationResponse
+import kr.co.vividnext.sodalive.v2.api.gift.dto.GiftCancellationResponse
+import kr.co.vividnext.sodalive.v2.api.gift.dto.GiftDeliveryConfirmationResponse
+import kr.co.vividnext.sodalive.v2.api.gift.dto.GiftDetailResponse
+import kr.co.vividnext.sodalive.v2.api.gift.dto.GiftFormOptionsResponse
+import kr.co.vividnext.sodalive.v2.api.gift.dto.GiftListResponse
+import kr.co.vividnext.sodalive.v2.api.gift.dto.GiftRecipientAddressRegistrationRequest
+import kr.co.vividnext.sodalive.v2.api.gift.dto.GiftRecipientAddressRegistrationResponse
+import kr.co.vividnext.sodalive.v2.api.gift.dto.GiftReviewRequest
+import kr.co.vividnext.sodalive.v2.api.gift.dto.GiftReviewResponse
+import kr.co.vividnext.sodalive.v2.api.gift.dto.GiftTrackingRegistrationRequest
+import kr.co.vividnext.sodalive.v2.api.gift.dto.GiftTrackingRegistrationResponse
+import kr.co.vividnext.sodalive.v2.gift.application.GiftCommandService
+import kr.co.vividnext.sodalive.v2.gift.application.GiftQueryService
+import kr.co.vividnext.sodalive.v2.gift.domain.GiftListType
+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
+
+@RestController
+@RequestMapping("/api/v2/gifts")
+class GiftController(
+    private val queryService: GiftQueryService,
+    private val commandService: GiftCommandService
+) {
+    @GetMapping("/form-options")
+    fun getFormOptions() = ApiResponse.ok(GiftFormOptionsResponse.from(queryService.getFormOptions()))
+
+    @GetMapping
+    fun getGifts(
+        @AuthenticationPrincipal(expression = "#this == 'anonymousUser' ? null : member") member: Member?,
+        @RequestParam(defaultValue = "ALL") type: GiftListType,
+        @RequestParam(defaultValue = "0") page: Int,
+        @RequestParam(defaultValue = "20") size: Int
+    ) = ApiResponse.ok(
+        GiftListResponse.from(
+            queryService.getGifts(
+                memberId = member?.id ?: throw SodaException(messageKey = "common.error.bad_credentials"),
+                type = type,
+                page = page,
+                size = size
+            )
+        )
+    )
+
+    @GetMapping("/{applicationNo}")
+    fun getGiftDetail(
+        @AuthenticationPrincipal(expression = "#this == 'anonymousUser' ? null : member") member: Member?,
+        @PathVariable applicationNo: String
+    ) = ApiResponse.ok(
+        GiftDetailResponse.from(
+            queryService.getGiftDetail(
+                memberId = member?.id ?: throw SodaException(messageKey = "common.error.bad_credentials"),
+                applicationNo = applicationNo
+            )
+        )
+    )
+
+    @PostMapping
+    fun registerGift(
+        @AuthenticationPrincipal(expression = "#this == 'anonymousUser' ? null : member") member: Member?,
+        @RequestBody request: GiftApplicationRequest
+    ) = ApiResponse.ok(
+        GiftApplicationResponse.from(
+            commandService.registerGift(
+                member = member ?: throw SodaException(messageKey = "common.error.bad_credentials"),
+                command = request.toCommand()
+            )
+        )
+    )
+
+    @PostMapping("/{applicationNo}/cancel")
+    fun cancelGift(
+        @AuthenticationPrincipal(expression = "#this == 'anonymousUser' ? null : member") member: Member?,
+        @PathVariable applicationNo: String
+    ) = ApiResponse.ok(
+        GiftCancellationResponse.from(
+            commandService.cancelGift(
+                member = member ?: throw SodaException(messageKey = "common.error.bad_credentials"),
+                applicationNo = applicationNo
+            )
+        )
+    )
+
+    @PostMapping("/{applicationNo}/tracking")
+    fun registerTracking(
+        @AuthenticationPrincipal(expression = "#this == 'anonymousUser' ? null : member") member: Member?,
+        @PathVariable applicationNo: String,
+        @RequestBody request: GiftTrackingRegistrationRequest
+    ) = ApiResponse.ok(
+        GiftTrackingRegistrationResponse.from(
+            commandService.registerTracking(
+                member = member ?: throw SodaException(messageKey = "common.error.bad_credentials"),
+                applicationNo = applicationNo,
+                command = request.toCommand()
+            )
+        )
+    )
+
+    @PostMapping("/{applicationNo}/recipient-address")
+    fun registerRecipientAddress(
+        @AuthenticationPrincipal(expression = "#this == 'anonymousUser' ? null : member") member: Member?,
+        @PathVariable applicationNo: String,
+        @RequestBody request: GiftRecipientAddressRegistrationRequest
+    ) = ApiResponse.ok(
+        GiftRecipientAddressRegistrationResponse.from(
+            commandService.registerRecipientAddress(
+                member = member ?: throw SodaException(messageKey = "common.error.bad_credentials"),
+                applicationNo = applicationNo,
+                command = request.toCommand()
+            )
+        )
+    )
+
+    @PostMapping("/{applicationNo}/delivery-complete")
+    fun confirmDelivery(
+        @AuthenticationPrincipal(expression = "#this == 'anonymousUser' ? null : member") member: Member?,
+        @PathVariable applicationNo: String
+    ) = ApiResponse.ok(
+        GiftDeliveryConfirmationResponse.from(
+            commandService.confirmDelivery(
+                member = member ?: throw SodaException(messageKey = "common.error.bad_credentials"),
+                applicationNo = applicationNo
+            )
+        )
+    )
+
+    @PostMapping("/{applicationNo}/review")
+    fun writeReview(
+        @AuthenticationPrincipal(expression = "#this == 'anonymousUser' ? null : member") member: Member?,
+        @PathVariable applicationNo: String,
+        @RequestBody request: GiftReviewRequest
+    ) = ApiResponse.ok(
+        GiftReviewResponse.from(
+            commandService.writeReview(
+                member = member ?: throw SodaException(messageKey = "common.error.bad_credentials"),
+                applicationNo = applicationNo,
+                command = request.toCommand()
+            )
+        )
+    )
+}

src/main/kotlin/kr/co/vividnext/sodalive/v2/api/gift/dto/GiftApplicationRequest.kt

@@ -0,0 +1,32 @@
+package kr.co.vividnext.sodalive.v2.api.gift.dto
+
+import kr.co.vividnext.sodalive.v2.gift.application.GiftApplicationCommand
+import kr.co.vividnext.sodalive.v2.gift.domain.GiftSize
+
+data class GiftApplicationRequest(
+    val recipientMemberId: Long,
+    val senderName: String,
+    val senderPhoneNumber: String,
+    val senderZipCode: String,
+    val senderAddress: String,
+    val senderAddressDetail: String?,
+    val sizeCode: GiftSize,
+    val categoryId: Long,
+    val senderTermsAgreed: Boolean,
+    val senderPrivacyAgreed: Boolean,
+    val damageWaiverAgreed: Boolean
+) {
+    fun toCommand() = GiftApplicationCommand(
+        recipientMemberId = recipientMemberId,
+        senderName = senderName,
+        senderPhoneNumber = senderPhoneNumber,
+        senderZipCode = senderZipCode,
+        senderAddress = senderAddress,
+        senderAddressDetail = senderAddressDetail,
+        sizeCode = sizeCode,
+        categoryId = categoryId,
+        senderTermsAgreed = senderTermsAgreed,
+        senderPrivacyAgreed = senderPrivacyAgreed,
+        damageWaiverAgreed = damageWaiverAgreed
+    )
+}

src/main/kotlin/kr/co/vividnext/sodalive/v2/api/gift/dto/GiftRecipientAddressRegistrationRequest.kt

@@ -0,0 +1,23 @@
+package kr.co.vividnext.sodalive.v2.api.gift.dto
+
+import kr.co.vividnext.sodalive.v2.gift.application.GiftRecipientAddressRegistrationCommand
+
+data class GiftRecipientAddressRegistrationRequest(
+    val recipientName: String,
+    val recipientPhoneNumber: String,
+    val recipientZipCode: String,
+    val recipientAddress: String,
+    val recipientAddressDetail: String?,
+    val recipientTermsAgreed: Boolean,
+    val recipientPrivacyAgreed: Boolean
+) {
+    fun toCommand() = GiftRecipientAddressRegistrationCommand(
+        name = recipientName,
+        phoneNumber = recipientPhoneNumber,
+        zipCode = recipientZipCode,
+        address = recipientAddress,
+        addressDetail = recipientAddressDetail,
+        recipientTermsAgreed = recipientTermsAgreed,
+        recipientPrivacyAgreed = recipientPrivacyAgreed
+    )
+}

src/main/kotlin/kr/co/vividnext/sodalive/v2/api/gift/dto/GiftResponse.kt

@@ -0,0 +1,281 @@
+package kr.co.vividnext.sodalive.v2.api.gift.dto
+
+import kr.co.vividnext.sodalive.extensions.toUtcIso
+import kr.co.vividnext.sodalive.v2.gift.application.GiftApplicationResult
+import kr.co.vividnext.sodalive.v2.gift.application.GiftCancellationResult
+import kr.co.vividnext.sodalive.v2.gift.application.GiftDeliveryConfirmationResult
+import kr.co.vividnext.sodalive.v2.gift.application.GiftDetailResult
+import kr.co.vividnext.sodalive.v2.gift.application.GiftFormOptionsResult
+import kr.co.vividnext.sodalive.v2.gift.application.GiftListResult
+import kr.co.vividnext.sodalive.v2.gift.application.GiftRecipientAddressRegistrationResult
+import kr.co.vividnext.sodalive.v2.gift.application.GiftReviewResult
+import kr.co.vividnext.sodalive.v2.gift.application.GiftTrackingRegistrationResult
+
+data class GiftFormOptionsResponse(
+    val sizes: List<GiftSizeOptionResponse>,
+    val categories: List<GiftCategoryOptionResponse>
+) {
+    companion object {
+        fun from(result: GiftFormOptionsResult) = GiftFormOptionsResponse(
+            sizes = result.sizes.map {
+                GiftSizeOptionResponse(it.sizeCode.name, it.sizeName, it.basePriceCan, it.salePriceCan)
+            },
+            categories = result.categories.map {
+                GiftCategoryOptionResponse(it.categoryId, it.name, it.requiresDamageWaiver)
+            }
+        )
+    }
+}
+
+data class GiftSizeOptionResponse(
+    val sizeCode: String,
+    val name: String,
+    val basePriceCan: Int,
+    val salePriceCan: Int
+)
+
+data class GiftCategoryOptionResponse(
+    val categoryId: Long,
+    val name: String,
+    val requiresDamageWaiver: Boolean
+)
+
+data class GiftListResponse(
+    val totalCount: Long,
+    val items: List<GiftListItemResponse>,
+    val page: Int,
+    val size: Int,
+    val hasNext: Boolean
+) {
+    companion object {
+        fun from(result: GiftListResult) = GiftListResponse(
+            totalCount = result.totalCount,
+            items = result.items.map {
+                GiftListItemResponse(
+                    applicationNo = it.applicationNo,
+                    direction = it.direction.name,
+                    status = it.status.name,
+                    statusName = it.statusName,
+                    priceCan = it.priceCan,
+                    categoryName = it.categoryName,
+                    sizeName = it.sizeName,
+                    counterpartMemberId = it.counterpartMemberId,
+                    counterpartNickname = it.counterpartNickname,
+                    counterpartProfileImageUrl = it.counterpartProfileImageUrl,
+                    createdAt = it.createdAt?.toUtcIso()
+                )
+            },
+            page = result.page,
+            size = result.size,
+            hasNext = result.hasNext
+        )
+    }
+}
+
+data class GiftListItemResponse(
+    val applicationNo: String,
+    val direction: String,
+    val status: String,
+    val statusName: String,
+    val priceCan: Int,
+    val categoryName: String,
+    val sizeName: String,
+    val counterpartMemberId: Long,
+    val counterpartNickname: String,
+    val counterpartProfileImageUrl: String,
+    val createdAt: String?
+)
+
+data class GiftDetailResponse(
+    val applicationNo: String,
+    val direction: String,
+    val status: String,
+    val statusName: String,
+    val giftInfo: GiftDetailInfoResponse,
+    val senderInfo: GiftAddressResponse?,
+    val recipientAddress: GiftAddressResponse?,
+    val mailbox: GiftMailboxResponse?,
+    val trackingRequired: Boolean,
+    val recipientAddressRequired: Boolean,
+    val recipientAddressDeadlineAt: String?,
+    val delivery: GiftDeliveryInfoResponse,
+    val statusTimeline: List<GiftStatusTimelineResponse>
+) {
+    companion object {
+        fun from(result: GiftDetailResult) = GiftDetailResponse(
+            applicationNo = result.applicationNo,
+            direction = result.direction.name,
+            status = result.status.name,
+            statusName = result.statusName,
+            giftInfo = GiftDetailInfoResponse(
+                recipientCreatorNickname = result.giftInfo.recipientCreatorNickname,
+                senderNickname = result.giftInfo.senderNickname,
+                sizeName = result.giftInfo.sizeName,
+                categoryName = result.giftInfo.categoryName,
+                applicationNo = result.giftInfo.applicationNo,
+                paidCan = result.giftInfo.paidCan,
+                tracking = result.giftInfo.tracking,
+                shippingRequestedAt = result.giftInfo.shippingRequestedAt?.toUtcIso()
+            ),
+            senderInfo = result.senderInfo?.let { GiftAddressResponse(it.name, it.phoneNumber, it.address) },
+            recipientAddress = result.recipientAddress?.let { GiftAddressResponse(it.name, it.phoneNumber, it.address) },
+            mailbox = result.mailbox?.let { GiftMailboxResponse(it.name, it.address, it.phoneNumber) },
+            trackingRequired = result.trackingRequired,
+            recipientAddressRequired = result.recipientAddressRequired,
+            recipientAddressDeadlineAt = result.recipientAddressDeadlineAt?.toUtcIso(),
+            delivery = GiftDeliveryInfoResponse(
+                canceledAt = result.delivery.canceledAt?.toUtcIso(),
+                undeliverableAt = result.delivery.undeliverableAt?.toUtcIso(),
+                undeliverableReason = result.delivery.undeliverableReason
+            ),
+            statusTimeline = result.statusTimeline.map {
+                GiftStatusTimelineResponse(it.status.name, it.statusName, it.occurredAt?.toUtcIso())
+            }
+        )
+    }
+}
+
+data class GiftDetailInfoResponse(
+    val recipientCreatorNickname: String?,
+    val senderNickname: String?,
+    val sizeName: String,
+    val categoryName: String,
+    val applicationNo: String?,
+    val paidCan: Int?,
+    val tracking: String?,
+    val shippingRequestedAt: String?
+)
+
+data class GiftAddressResponse(
+    val name: String,
+    val phoneNumber: String,
+    val address: String
+)
+
+data class GiftMailboxResponse(
+    val name: String,
+    val address: String,
+    val phoneNumber: String
+)
+
+data class GiftDeliveryInfoResponse(
+    val canceledAt: String?,
+    val undeliverableAt: String?,
+    val undeliverableReason: String?
+)
+
+data class GiftStatusTimelineResponse(
+    val status: String,
+    val statusName: String,
+    val occurredAt: String?
+)
+
+data class GiftApplicationResponse(
+    val applicationNo: String,
+    val status: String,
+    val statusName: String,
+    val priceCan: Int,
+    val trackingDeadlineAt: String
+) {
+    companion object {
+        fun from(result: GiftApplicationResult) = GiftApplicationResponse(
+            applicationNo = result.applicationNo,
+            status = result.status.name,
+            statusName = result.statusName,
+            priceCan = result.priceCan,
+            trackingDeadlineAt = result.trackingDeadlineAt.toUtcIso()
+        )
+    }
+}
+
+data class GiftCancellationResponse(
+    val applicationNo: String,
+    val status: String,
+    val statusName: String,
+    val priceCan: Int,
+    val canceledAt: String
+) {
+    companion object {
+        fun from(result: GiftCancellationResult) = GiftCancellationResponse(
+            applicationNo = result.applicationNo,
+            status = result.status.name,
+            statusName = result.statusName,
+            priceCan = result.priceCan,
+            canceledAt = result.canceledAt.toUtcIso()
+        )
+    }
+}
+
+data class GiftTrackingRegistrationResponse(
+    val applicationNo: String,
+    val status: String,
+    val statusName: String,
+    val courierCompanyName: String,
+    val trackingNumber: String,
+    val trackingRegisteredAt: String,
+    val recipientAddressDeadlineAt: String
+) {
+    companion object {
+        fun from(result: GiftTrackingRegistrationResult) = GiftTrackingRegistrationResponse(
+            applicationNo = result.applicationNo,
+            status = result.status.name,
+            statusName = result.statusName,
+            courierCompanyName = result.courierCompanyName,
+            trackingNumber = result.trackingNumber,
+            trackingRegisteredAt = result.trackingRegisteredAt.toUtcIso(),
+            recipientAddressDeadlineAt = result.recipientAddressDeadlineAt.toUtcIso()
+        )
+    }
+}
+
+data class GiftRecipientAddressRegistrationResponse(
+    val applicationNo: String,
+    val status: String,
+    val statusName: String,
+    val recipientAddressRegisteredAt: String
+) {
+    companion object {
+        fun from(result: GiftRecipientAddressRegistrationResult) = GiftRecipientAddressRegistrationResponse(
+            applicationNo = result.applicationNo,
+            status = result.status.name,
+            statusName = result.statusName,
+            recipientAddressRegisteredAt = result.recipientAddressRegisteredAt.toUtcIso()
+        )
+    }
+}
+
+data class GiftDeliveryConfirmationResponse(
+    val applicationNo: String,
+    val status: String,
+    val statusName: String,
+    val deliveredAt: String
+) {
+    companion object {
+        fun from(result: GiftDeliveryConfirmationResult) = GiftDeliveryConfirmationResponse(
+            applicationNo = result.applicationNo,
+            status = result.status.name,
+            statusName = result.statusName,
+            deliveredAt = result.deliveredAt.toUtcIso()
+        )
+    }
+}
+
+data class GiftReviewResponse(
+    val reviewId: Long,
+    val applicationNo: String,
+    val rating: Int,
+    val keywords: List<String>,
+    val comment: String?,
+    val createdAt: String?
+) {
+    companion object {
+        fun from(result: GiftReviewResult) = GiftReviewResponse(
+            reviewId = result.reviewId,
+            applicationNo = result.applicationNo,
+            rating = result.rating,
+            keywords = result.keywords,
+            comment = result.comment,
+            createdAt = result.createdAt?.toUtcIso()
+        )
+    }
+}

src/main/kotlin/kr/co/vividnext/sodalive/v2/api/gift/dto/GiftReviewRequest.kt

@@ -0,0 +1,15 @@
+package kr.co.vividnext.sodalive.v2.api.gift.dto
+
+import kr.co.vividnext.sodalive.v2.gift.application.GiftReviewCommand
+
+data class GiftReviewRequest(
+    val rating: Int,
+    val keywords: List<String>,
+    val comment: String?
+) {
+    fun toCommand() = GiftReviewCommand(
+        rating = rating,
+        keywords = keywords,
+        comment = comment
+    )
+}

src/main/kotlin/kr/co/vividnext/sodalive/v2/api/gift/dto/GiftTrackingRegistrationRequest.kt

@@ -0,0 +1,13 @@
+package kr.co.vividnext.sodalive.v2.api.gift.dto
+
+import kr.co.vividnext.sodalive.v2.gift.application.GiftTrackingRegistrationCommand
+
+data class GiftTrackingRegistrationRequest(
+    val courierCompanyName: String,
+    val trackingNumber: String
+) {
+    fun toCommand() = GiftTrackingRegistrationCommand(
+        courierCompanyName = courierCompanyName,
+        trackingNumber = trackingNumber
+    )
+}

src/main/kotlin/kr/co/vividnext/sodalive/v2/api/home/application/HomeRecommendationFacade.kt

@@ -2,7 +2,9 @@ package kr.co.vividnext.sodalive.v2.api.home.application
 
 import kr.co.vividnext.sodalive.event.EventItem
 import kr.co.vividnext.sodalive.i18n.Lang
+import kr.co.vividnext.sodalive.member.Gender
 import kr.co.vividnext.sodalive.member.Member
+import kr.co.vividnext.sodalive.member.MemberRole
 import kr.co.vividnext.sodalive.member.contentpreference.MemberContentPreferenceService
 import kr.co.vividnext.sodalive.v2.api.common.dto.RecommendationBannerResponse
 import kr.co.vividnext.sodalive.v2.api.home.dto.recommendation.HomeActiveCreatorItem
@@ -53,7 +55,9 @@ class HomeRecommendationFacade(
                 lives = queryService.findLiveRecommendations(
                     limit = HOME_LIVE_LIMIT,
                     memberId = member?.id,
-                    includeAdultLives = includeAdult
+                    includeAdultLives = includeAdult,
+                    isViewerCreator = member?.role == MemberRole.CREATOR,
+                    effectiveViewerGender = member?.effectiveGender()
                 ).map { it.toItem() },
                 banners = queryService.findHomeBanners(
                     limit = HOME_BANNER_LIMIT,
@@ -125,7 +129,9 @@ class HomeRecommendationFacade(
                 offset = page.toOffset(size),
                 limit = size + 1,
                 memberId = member.id,
-                includeAdultLives = resolveAdultVisibility(member)
+                includeAdultLives = resolveAdultVisibility(member),
+                isViewerCreator = member.role == MemberRole.CREATOR,
+                effectiveViewerGender = member.effectiveGender()
             )
             fetched.toPage(page, size) { it.toItem() }
         }.onSuccess {
@@ -209,6 +215,10 @@ class HomeRecommendationFacade(
         return memberContentPreferenceService.canViewAdultContent(member)
     }
 
+    private fun Member.effectiveGender(): Gender {
+        return auth?.let { if (it.gender == 1) Gender.MALE else Gender.FEMALE } ?: gender
+    }
+
     private fun Int.toOffset(size: Int): Long = this.toLong() * size
 
     private fun <S, T> List<S>.toPage(

src/main/kotlin/kr/co/vividnext/sodalive/v2/api/home/live/application/HomeOnAirLiveFacade.kt

@@ -1,6 +1,8 @@
 package kr.co.vividnext.sodalive.v2.api.home.live.application
 
+import kr.co.vividnext.sodalive.member.Gender
 import kr.co.vividnext.sodalive.member.Member
+import kr.co.vividnext.sodalive.member.MemberRole
 import kr.co.vividnext.sodalive.member.contentpreference.MemberContentPreferenceService
 import kr.co.vividnext.sodalive.v2.api.home.live.dto.HomeOnAirLivePageResponse
 import kr.co.vividnext.sodalive.v2.api.home.live.dto.HomeOnAirLiveResponse
@@ -24,7 +26,9 @@ class HomeOnAirLiveFacade(
             offset = normalizedPage.toLong() * PAGE_SIZE,
             limit = PAGE_SIZE + 1,
             memberId = member.id,
-            includeAdultLives = memberContentPreferenceService.canViewAdultContent(member)
+            includeAdultLives = memberContentPreferenceService.canViewAdultContent(member),
+            isViewerCreator = member.role == MemberRole.CREATOR,
+            effectiveViewerGender = member.effectiveGender()
         )
         val items = fetched.take(PAGE_SIZE).map { it.toResponse() }
 
@@ -57,6 +61,10 @@ class HomeOnAirLiveFacade(
         return atOffset(ZoneOffset.UTC).toInstant().toString()
     }
 
+    private fun Member.effectiveGender(): Gender {
+        return auth?.let { if (it.gender == 1) Gender.MALE else Gender.FEMALE } ?: gender
+    }
+
     companion object {
         private const val PAGE_SIZE = 20
         private const val MAX_PAGE = 10_000

src/main/kotlin/kr/co/vividnext/sodalive/v2/creator/channel/live/application/CreatorChannelLiveQueryService.kt

@@ -58,7 +58,7 @@ class CreatorChannelLiveQueryService(
         validateCreatorRole(creator)
 
         val canViewAdultContent = memberContentPreferenceService.canViewAdultContent(viewer)
-        val isViewerCreator = viewerId == creatorId
+        val isViewerCreator = viewer.role == MemberRole.CREATOR
         val effectiveViewerGender = viewer.effectiveGender()
         val fetchedContents = queryPort.findLiveReplayAudioContents(
             creatorId = creatorId,

src/main/kotlin/kr/co/vividnext/sodalive/v2/gift/adapter/out/persistence/Gift.kt

@@ -0,0 +1,75 @@
+package kr.co.vividnext.sodalive.v2.gift.adapter.out.persistence
+
+import kr.co.vividnext.sodalive.common.BaseEntity
+import kr.co.vividnext.sodalive.v2.gift.domain.GiftSize
+import kr.co.vividnext.sodalive.v2.gift.domain.GiftStatus
+import java.time.LocalDateTime
+import javax.persistence.Column
+import javax.persistence.Entity
+import javax.persistence.EnumType
+import javax.persistence.Enumerated
+import javax.persistence.Table
+import javax.persistence.UniqueConstraint
+
+@Entity
+@Table(
+    name = "gift",
+    uniqueConstraints = [UniqueConstraint(name = "uk_gift_application_no", columnNames = ["application_no"])]
+)
+class Gift(
+    @Column(name = "application_no", nullable = false, length = 20)
+    val applicationNo: String,
+
+    @Column(name = "sender_member_id", nullable = false)
+    val senderMemberId: Long,
+
+    @Column(name = "recipient_member_id", nullable = false)
+    val recipientMemberId: Long,
+
+    @Enumerated(EnumType.STRING)
+    @Column(name = "status", nullable = false, length = 30)
+    var status: GiftStatus,
+
+    @Enumerated(EnumType.STRING)
+    @Column(name = "size_code", nullable = false, length = 20)
+    val sizeCode: GiftSize,
+
+    @Column(name = "category_id", nullable = false)
+    val categoryId: Long,
+
+    @Column(name = "category_name_snapshot", nullable = false, length = 50)
+    val categoryNameSnapshot: String,
+
+    @Column(name = "sale_price_can", nullable = false)
+    val salePriceCan: Int,
+
+    @Column(name = "can_usage_id", nullable = false)
+    val canUsageId: Long,
+
+    @Column(name = "sender_terms_agreed", nullable = false)
+    val senderTermsAgreed: Boolean,
+
+    @Column(name = "sender_privacy_agreed", nullable = false)
+    val senderPrivacyAgreed: Boolean,
+
+    @Column(name = "sender_terms_agreed_at", nullable = false)
+    val senderTermsAgreedAt: LocalDateTime,
+
+    @Column(name = "sender_privacy_agreed_at", nullable = false)
+    val senderPrivacyAgreedAt: LocalDateTime,
+
+    @Column(name = "recipient_terms_agreed", nullable = false)
+    var recipientTermsAgreed: Boolean = false,
+
+    @Column(name = "recipient_privacy_agreed", nullable = false)
+    var recipientPrivacyAgreed: Boolean = false,
+
+    @Column(name = "recipient_terms_agreed_at")
+    var recipientTermsAgreedAt: LocalDateTime? = null,
+
+    @Column(name = "recipient_privacy_agreed_at")
+    var recipientPrivacyAgreedAt: LocalDateTime? = null,
+
+    @Column(name = "damage_waiver_agreed", nullable = false)
+    val damageWaiverAgreed: Boolean = false
+) : BaseEntity()

src/main/kotlin/kr/co/vividnext/sodalive/v2/gift/adapter/out/persistence/GiftApplicationNoSequence.kt

@@ -0,0 +1,28 @@
+package kr.co.vividnext.sodalive.v2.gift.adapter.out.persistence
+
+import kr.co.vividnext.sodalive.common.BaseEntity
+import javax.persistence.Column
+import javax.persistence.Entity
+import javax.persistence.Table
+import javax.persistence.UniqueConstraint
+
+@Entity
+@Table(
+    name = "gift_application_no_sequence",
+    uniqueConstraints = [
+        UniqueConstraint(
+            name = "uk_gift_application_no_sequence_category_date",
+            columnNames = ["category_id", "sequence_date"]
+        )
+    ]
+)
+class GiftApplicationNoSequence(
+    @Column(name = "category_id", nullable = false)
+    val categoryId: Long,
+
+    @Column(name = "sequence_date", nullable = false, length = 6)
+    val sequenceDate: String,
+
+    @Column(name = "last_sequence", nullable = false)
+    var lastSequence: Int
+) : BaseEntity()

src/main/kotlin/kr/co/vividnext/sodalive/v2/gift/adapter/out/persistence/GiftApplicationNoSequenceRepository.kt

@@ -0,0 +1,25 @@
+package kr.co.vividnext.sodalive.v2.gift.adapter.out.persistence
+
+import org.springframework.data.jpa.repository.JpaRepository
+import org.springframework.data.jpa.repository.Lock
+import org.springframework.data.jpa.repository.Query
+import org.springframework.data.repository.query.Param
+import javax.persistence.LockModeType
+
+interface GiftApplicationNoSequenceRepository : JpaRepository<GiftApplicationNoSequence, Long> {
+    fun findByCategoryIdAndSequenceDate(categoryId: Long, sequenceDate: String): GiftApplicationNoSequence?
+
+    @Lock(LockModeType.PESSIMISTIC_WRITE)
+    @Query(
+        """
+        select s
+        from GiftApplicationNoSequence s
+        where s.categoryId = :categoryId
+          and s.sequenceDate = :sequenceDate
+        """
+    )
+    fun findByCategoryIdAndSequenceDateForUpdate(
+        @Param("categoryId") categoryId: Long,
+        @Param("sequenceDate") sequenceDate: String
+    ): GiftApplicationNoSequence?
+}

src/main/kotlin/kr/co/vividnext/sodalive/v2/gift/adapter/out/persistence/GiftCategory.kt

@@ -0,0 +1,39 @@
+package kr.co.vividnext.sodalive.v2.gift.adapter.out.persistence
+
+import kr.co.vividnext.sodalive.common.BaseEntity
+import javax.persistence.Column
+import javax.persistence.Entity
+import javax.persistence.Table
+import javax.persistence.UniqueConstraint
+
+@Entity
+@Table(
+    name = "gift_category",
+    uniqueConstraints = [
+        UniqueConstraint(name = "uk_gift_category_classification_number", columnNames = ["classification_number"]),
+        UniqueConstraint(name = "uk_gift_category_code", columnNames = ["category_code"]),
+        UniqueConstraint(name = "uk_gift_category_receipt_code", columnNames = ["receipt_code"])
+    ]
+)
+class GiftCategory(
+    @Column(name = "classification_number", nullable = false, length = 3)
+    var classificationNumber: String,
+
+    @Column(name = "category_code", nullable = false, length = 50)
+    val categoryCode: String,
+
+    @Column(name = "name", nullable = false, length = 50)
+    var name: String,
+
+    @Column(name = "receipt_code", nullable = false, length = 9)
+    var receiptCode: String,
+
+    @Column(name = "representative_item", nullable = false, length = 100)
+    var representativeItem: String,
+
+    @Column(name = "requires_damage_waiver", nullable = false)
+    var requiresDamageWaiver: Boolean = false,
+
+    @Column(name = "is_active", nullable = false)
+    var isActive: Boolean = true
+) : BaseEntity()

src/main/kotlin/kr/co/vividnext/sodalive/v2/gift/adapter/out/persistence/GiftCategoryRepository.kt

@@ -0,0 +1,7 @@
+package kr.co.vividnext.sodalive.v2.gift.adapter.out.persistence
+
+import org.springframework.data.jpa.repository.JpaRepository
+
+interface GiftCategoryRepository : JpaRepository<GiftCategory, Long> {
+    fun findByCategoryCode(categoryCode: String): GiftCategory?
+}

src/main/kotlin/kr/co/vividnext/sodalive/v2/gift/adapter/out/persistence/GiftDelivery.kt

@@ -0,0 +1,94 @@
+package kr.co.vividnext.sodalive.v2.gift.adapter.out.persistence
+
+import kr.co.vividnext.sodalive.common.BaseEntity
+import java.time.LocalDateTime
+import javax.persistence.Column
+import javax.persistence.Entity
+import javax.persistence.Table
+import javax.persistence.UniqueConstraint
+
+@Entity
+@Table(
+    name = "gift_delivery",
+    uniqueConstraints = [UniqueConstraint(name = "uk_gift_delivery_gift_id", columnNames = ["gift_id"])]
+)
+class GiftDelivery(
+    @Column(name = "gift_id", nullable = false)
+    val giftId: Long,
+
+    @Column(name = "sender_name", nullable = false, length = 50)
+    val senderName: String,
+
+    @Column(name = "sender_phone_number", nullable = false, length = 30)
+    val senderPhoneNumber: String,
+
+    @Column(name = "sender_zip_code", nullable = false, length = 20)
+    val senderZipCode: String,
+
+    @Column(name = "sender_address", nullable = false, length = 255)
+    val senderAddress: String,
+
+    @Column(name = "sender_address_detail", length = 255)
+    val senderAddressDetail: String? = null,
+
+    @Column(name = "recipient_name", length = 50)
+    var recipientName: String? = null,
+
+    @Column(name = "recipient_phone_number", length = 30)
+    var recipientPhoneNumber: String? = null,
+
+    @Column(name = "recipient_zip_code", length = 20)
+    var recipientZipCode: String? = null,
+
+    @Column(name = "recipient_address", length = 255)
+    var recipientAddress: String? = null,
+
+    @Column(name = "recipient_address_detail", length = 255)
+    var recipientAddressDetail: String? = null,
+
+    @Column(name = "courier_company_name", length = 50)
+    var courierCompanyName: String? = null,
+
+    @Column(name = "tracking_number", length = 100)
+    var trackingNumber: String? = null,
+
+    @Column(name = "tracking_deadline_at", nullable = false)
+    val trackingDeadlineAt: LocalDateTime,
+
+    @Column(name = "recipient_address_deadline_at")
+    var recipientAddressDeadlineAt: LocalDateTime? = null,
+
+    @Column(name = "tracking_deadline_reminder_sent_at")
+    var trackingDeadlineReminderSentAt: LocalDateTime? = null,
+
+    @Column(name = "recipient_address_deadline_reminder_sent_at")
+    var recipientAddressDeadlineReminderSentAt: LocalDateTime? = null,
+
+    @Column(name = "tracking_registered_at")
+    var trackingRegisteredAt: LocalDateTime? = null,
+
+    @Column(name = "arrived_at_mailbox_at")
+    var arrivedAtMailboxAt: LocalDateTime? = null,
+
+    @Column(name = "inspection_completed_at")
+    var inspectionCompletedAt: LocalDateTime? = null,
+
+    @Column(name = "delivered_at")
+    var deliveredAt: LocalDateTime? = null,
+
+    @Column(name = "canceled_at")
+    var canceledAt: LocalDateTime? = null,
+
+    @Column(name = "undeliverable_at")
+    var undeliverableAt: LocalDateTime? = null,
+
+    @Column(name = "undeliverable_reason", length = 255)
+    var undeliverableReason: String? = null
+) : BaseEntity() {
+    fun hasCompleteRecipientInformation() = listOf(
+        recipientName,
+        recipientPhoneNumber,
+        recipientZipCode,
+        recipientAddress
+    ).none { it.isNullOrBlank() }
+}

src/main/kotlin/kr/co/vividnext/sodalive/v2/gift/adapter/out/persistence/GiftDeliveryRepository.kt

@@ -0,0 +1,9 @@
+package kr.co.vividnext.sodalive.v2.gift.adapter.out.persistence
+
+import org.springframework.data.jpa.repository.JpaRepository
+
+interface GiftDeliveryRepository : JpaRepository<GiftDelivery, Long> {
+    fun findByGiftId(giftId: Long): GiftDelivery?
+
+    fun findByGiftIdIn(giftIds: Collection<Long>): List<GiftDelivery>
+}

src/main/kotlin/kr/co/vividnext/sodalive/v2/gift/adapter/out/persistence/GiftMailbox.kt

@@ -0,0 +1,33 @@
+package kr.co.vividnext.sodalive.v2.gift.adapter.out.persistence
+
+import javax.persistence.Column
+import javax.persistence.Entity
+import javax.persistence.Id
+import javax.persistence.Table
+
+@Entity
+@Table(name = "gift_mailbox")
+class GiftMailbox(
+    @Id
+    @Column(name = "id", nullable = false)
+    val id: Long = SINGLETON_ID,
+
+    @Column(name = "name", nullable = false, length = 50)
+    var name: String,
+
+    @Column(name = "phone_number", nullable = false, length = 30)
+    var phoneNumber: String,
+
+    @Column(name = "zip_code", nullable = false, length = 20)
+    var zipCode: String,
+
+    @Column(name = "address", nullable = false, length = 255)
+    var address: String,
+
+    @Column(name = "address_detail", length = 255)
+    var addressDetail: String?
+) {
+    companion object {
+        const val SINGLETON_ID = 1L
+    }
+}

src/main/kotlin/kr/co/vividnext/sodalive/v2/gift/adapter/out/persistence/GiftMailboxRepository.kt

@@ -0,0 +1,5 @@
+package kr.co.vividnext.sodalive.v2.gift.adapter.out.persistence
+
+import org.springframework.data.jpa.repository.JpaRepository
+
+interface GiftMailboxRepository : JpaRepository<GiftMailbox, Long>

src/main/kotlin/kr/co/vividnext/sodalive/v2/gift/adapter/out/persistence/GiftRepository.kt

@@ -0,0 +1,145 @@
+package kr.co.vividnext.sodalive.v2.gift.adapter.out.persistence
+
+import kr.co.vividnext.sodalive.v2.gift.domain.GiftStatus
+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 java.time.LocalDateTime
+
+interface GiftRepository : JpaRepository<Gift, Long> {
+    fun findByApplicationNo(applicationNo: String): Gift?
+
+    fun findBySenderMemberId(senderMemberId: Long, pageable: Pageable): Page<Gift>
+
+    fun findByRecipientMemberIdAndStatusIn(
+        recipientMemberId: Long,
+        statuses: Collection<GiftStatus>,
+        pageable: Pageable
+    ): Page<Gift>
+
+    fun findBySenderMemberIdOrRecipientMemberIdAndStatusIn(
+        senderMemberId: Long,
+        recipientMemberId: Long,
+        statuses: Collection<GiftStatus>,
+        pageable: Pageable
+    ): Page<Gift>
+
+    @Query(
+        value = """
+        select g
+        from Gift g
+          join Member sender on sender.id = g.senderMemberId
+          join Member recipient on recipient.id = g.recipientMemberId
+        where (:status is null or g.status = :status)
+          and (:applicationNo is null or g.applicationNo like concat('%', :applicationNo, '%'))
+          and (
+            :nickname is null
+            or sender.nickname like concat('%', :nickname, '%')
+            or recipient.nickname like concat('%', :nickname, '%')
+          )
+        """,
+        countQuery = """
+        select count(g)
+        from Gift g
+          join Member sender on sender.id = g.senderMemberId
+          join Member recipient on recipient.id = g.recipientMemberId
+        where (:status is null or g.status = :status)
+          and (:applicationNo is null or g.applicationNo like concat('%', :applicationNo, '%'))
+          and (
+            :nickname is null
+            or sender.nickname like concat('%', :nickname, '%')
+            or recipient.nickname like concat('%', :nickname, '%')
+          )
+        """
+    )
+    fun findAdminGifts(
+        @Param("status") status: GiftStatus?,
+        @Param("applicationNo") applicationNo: String?,
+        @Param("nickname") nickname: String?,
+        pageable: Pageable
+    ): Page<Gift>
+
+    @Query(
+        """
+        select g
+        from Gift g
+        where g.status = kr.co.vividnext.sodalive.v2.gift.domain.GiftStatus.RECEIVED
+          and exists (
+              select d.id
+              from GiftDelivery d
+              where d.giftId = g.id
+                and d.trackingDeadlineAt < :now
+          )
+        """
+    )
+    fun findReceivedGiftsWithTrackingDeadlineBefore(@Param("now") now: LocalDateTime): List<Gift>
+
+    @Query(
+        """
+        select g
+        from Gift g
+        where g.status in (
+            kr.co.vividnext.sodalive.v2.gift.domain.GiftStatus.TRACKING_REGISTERED,
+            kr.co.vividnext.sodalive.v2.gift.domain.GiftStatus.ARRIVED_AT_MAILBOX,
+            kr.co.vividnext.sodalive.v2.gift.domain.GiftStatus.INSPECTION_COMPLETED
+        )
+          and exists (
+              select d.id
+              from GiftDelivery d
+              where d.giftId = g.id
+                and d.recipientAddressDeadlineAt < :now
+                and d.recipientAddress is null
+          )
+        """
+    )
+    fun findGiftsWithRecipientAddressDeadlineBefore(
+        @Param("now") now: LocalDateTime
+    ): List<Gift>
+
+    @Query(
+        """
+        select g
+        from Gift g
+        where g.status = kr.co.vividnext.sodalive.v2.gift.domain.GiftStatus.RECEIVED
+          and exists (
+              select d.id
+              from GiftDelivery d
+              where d.giftId = g.id
+                and d.trackingDeadlineAt > :now
+                and d.trackingDeadlineAt <= :reminderUntil
+                and d.trackingDeadlineReminderSentAt is null
+          )
+        """
+    )
+    fun findReceivedGiftsWithTrackingDeadlineReminderDue(
+        @Param("now") now: LocalDateTime,
+        @Param("reminderUntil") reminderUntil: LocalDateTime
+    ): List<Gift>
+
+    @Query(
+        """
+        select g
+        from Gift g
+        where g.status in (
+            kr.co.vividnext.sodalive.v2.gift.domain.GiftStatus.TRACKING_REGISTERED,
+            kr.co.vividnext.sodalive.v2.gift.domain.GiftStatus.ARRIVED_AT_MAILBOX,
+            kr.co.vividnext.sodalive.v2.gift.domain.GiftStatus.INSPECTION_COMPLETED
+        )
+          and exists (
+              select d.id
+              from GiftDelivery d
+              where d.giftId = g.id
+                and d.recipientAddressDeadlineAt > :now
+                and d.recipientAddressDeadlineAt <= :reminderUntil
+                and d.recipientAddress is null
+                and d.recipientAddressDeadlineReminderSentAt is null
+          )
+        """
+    )
+    fun findGiftsWithRecipientAddressDeadlineReminderDue(
+        @Param("now") now: LocalDateTime,
+        @Param("reminderUntil") reminderUntil: LocalDateTime
+    ): List<Gift>
+}

src/main/kotlin/kr/co/vividnext/sodalive/v2/gift/adapter/out/persistence/GiftReview.kt

@@ -0,0 +1,29 @@
+package kr.co.vividnext.sodalive.v2.gift.adapter.out.persistence
+
+import kr.co.vividnext.sodalive.common.BaseEntity
+import javax.persistence.Column
+import javax.persistence.Entity
+import javax.persistence.Table
+import javax.persistence.UniqueConstraint
+
+@Entity
+@Table(
+    name = "gift_review",
+    uniqueConstraints = [UniqueConstraint(name = "uk_gift_review_gift_id", columnNames = ["gift_id"])]
+)
+class GiftReview(
+    @Column(name = "gift_id", nullable = false)
+    val giftId: Long,
+
+    @Column(name = "sender_member_id", nullable = false)
+    val senderMemberId: Long,
+
+    @Column(name = "rating", nullable = false)
+    val rating: Int,
+
+    @Column(name = "keywords", columnDefinition = "text")
+    var keywords: String? = null,
+
+    @Column(name = "comment", length = 255)
+    var comment: String? = null
+) : BaseEntity()

src/main/kotlin/kr/co/vividnext/sodalive/v2/gift/adapter/out/persistence/GiftReviewRepository.kt

@@ -0,0 +1,7 @@
+package kr.co.vividnext.sodalive.v2.gift.adapter.out.persistence
+
+import org.springframework.data.jpa.repository.JpaRepository
+
+interface GiftReviewRepository : JpaRepository<GiftReview, Long> {
+    fun findByGiftId(giftId: Long): GiftReview?
+}

src/main/kotlin/kr/co/vividnext/sodalive/v2/gift/adapter/out/persistence/GiftSizePrice.kt

@@ -0,0 +1,30 @@
+package kr.co.vividnext.sodalive.v2.gift.adapter.out.persistence
+
+import kr.co.vividnext.sodalive.common.BaseEntity
+import kr.co.vividnext.sodalive.v2.gift.domain.GiftSize
+import javax.persistence.Column
+import javax.persistence.Entity
+import javax.persistence.EnumType
+import javax.persistence.Enumerated
+import javax.persistence.Table
+import javax.persistence.UniqueConstraint
+
+@Entity
+@Table(
+    name = "gift_size_price",
+    uniqueConstraints = [UniqueConstraint(name = "uk_gift_size_price_size_code", columnNames = ["size_code"])]
+)
+class GiftSizePrice(
+    @Enumerated(EnumType.STRING)
+    @Column(name = "size_code", nullable = false, length = 20)
+    val sizeCode: GiftSize,
+
+    @Column(name = "base_price_can", nullable = false)
+    var basePriceCan: Int,
+
+    @Column(name = "sale_price_can", nullable = false)
+    var salePriceCan: Int,
+
+    @Column(name = "is_active", nullable = false)
+    var isActive: Boolean = true
+) : BaseEntity()

src/main/kotlin/kr/co/vividnext/sodalive/v2/gift/adapter/out/persistence/GiftSizePriceRepository.kt

@@ -0,0 +1,8 @@
+package kr.co.vividnext.sodalive.v2.gift.adapter.out.persistence
+
+import kr.co.vividnext.sodalive.v2.gift.domain.GiftSize
+import org.springframework.data.jpa.repository.JpaRepository
+
+interface GiftSizePriceRepository : JpaRepository<GiftSizePrice, Long> {
+    fun findBySizeCode(sizeCode: GiftSize): GiftSizePrice?
+}

src/main/kotlin/kr/co/vividnext/sodalive/v2/gift/adapter/out/scheduler/GiftScheduler.kt

@@ -0,0 +1,101 @@
+package kr.co.vividnext.sodalive.v2.gift.adapter.out.scheduler
+
+import kr.co.vividnext.sodalive.can.payment.CanPaymentService
+import kr.co.vividnext.sodalive.v2.gift.adapter.out.persistence.GiftDeliveryRepository
+import kr.co.vividnext.sodalive.v2.gift.adapter.out.persistence.GiftRepository
+import kr.co.vividnext.sodalive.v2.gift.application.GiftPushService
+import kr.co.vividnext.sodalive.v2.gift.domain.GiftStatus
+import org.redisson.api.RedissonClient
+import org.springframework.scheduling.annotation.Scheduled
+import org.springframework.stereotype.Component
+import org.springframework.transaction.annotation.Transactional
+import java.time.LocalDateTime
+import java.util.concurrent.TimeUnit
+
+@Component
+class GiftScheduler(
+    private val giftRepository: GiftRepository,
+    private val giftDeliveryRepository: GiftDeliveryRepository,
+    private val canPaymentService: CanPaymentService,
+    private val giftPushService: GiftPushService,
+    private val redissonClient: RedissonClient
+) {
+    @Scheduled(cron = "0 0 * * * *", zone = "Asia/Seoul")
+    @Transactional
+    fun runExpiredTrackingRegistrationGiftCancellation() {
+        val lock = redissonClient.getLock(EXPIRED_TRACKING_REGISTRATION_GIFTS_LOCK_KEY)
+
+        try {
+            if (lock.tryLock(0, -1, TimeUnit.SECONDS)) {
+                cancelExpiredTrackingRegistrationGifts(LocalDateTime.now())
+            }
+        } finally {
+            if (lock.isHeldByCurrentThread) {
+                lock.unlock()
+            }
+        }
+    }
+
+    @Transactional
+    fun cancelExpiredTrackingRegistrationGifts(now: LocalDateTime): Int {
+        val expiredGifts = giftRepository.findReceivedGiftsWithTrackingDeadlineBefore(now)
+        expiredGifts.forEach { gift ->
+            gift.status = GiftStatus.CANCELED
+            requireNotNull(giftDeliveryRepository.findByGiftId(requireNotNull(gift.id))).canceledAt = now
+            canPaymentService.refundGiftCan(gift.senderMemberId, gift.canUsageId)
+            giftPushService.sendAutoCanceledToSender(gift.applicationNo, gift.senderMemberId)
+        }
+
+        return expiredGifts.size
+    }
+
+    @Transactional
+    fun markExpiredRecipientAddressGiftsUndeliverable(now: LocalDateTime): Int {
+        val expiredGifts = giftRepository.findGiftsWithRecipientAddressDeadlineBefore(now)
+        expiredGifts.forEach { gift ->
+            gift.status = GiftStatus.UNDELIVERABLE
+            val delivery = requireNotNull(giftDeliveryRepository.findByGiftId(requireNotNull(gift.id)))
+            delivery.undeliverableAt = now
+            delivery.undeliverableReason = EXPIRED_RECIPIENT_ADDRESS_REASON
+        }
+
+        return expiredGifts.size
+    }
+
+    @Transactional
+    fun sendDeadlineReminderGifts(now: LocalDateTime): Int {
+        val reminderUntil = now.plusHours(DEADLINE_REMINDER_HOURS)
+        val trackingReminderCount = sendTrackingDeadlineReminders(now, reminderUntil)
+        val recipientAddressReminderCount = sendRecipientAddressDeadlineReminders(now, reminderUntil)
+
+        return trackingReminderCount + recipientAddressReminderCount
+    }
+
+    private fun sendTrackingDeadlineReminders(now: LocalDateTime, reminderUntil: LocalDateTime): Int {
+        val gifts = giftRepository.findReceivedGiftsWithTrackingDeadlineReminderDue(now, reminderUntil)
+        gifts.forEach { gift ->
+            val delivery = requireNotNull(giftDeliveryRepository.findByGiftId(requireNotNull(gift.id)))
+            delivery.trackingDeadlineReminderSentAt = now
+            giftPushService.sendTrackingDeadlineReminder(gift.applicationNo, gift.senderMemberId)
+        }
+
+        return gifts.size
+    }
+
+    private fun sendRecipientAddressDeadlineReminders(now: LocalDateTime, reminderUntil: LocalDateTime): Int {
+        val gifts = giftRepository.findGiftsWithRecipientAddressDeadlineReminderDue(now, reminderUntil)
+        gifts.forEach { gift ->
+            val delivery = requireNotNull(giftDeliveryRepository.findByGiftId(requireNotNull(gift.id)))
+            delivery.recipientAddressDeadlineReminderSentAt = now
+            giftPushService.sendRecipientAddressDeadlineReminder(gift.applicationNo, gift.recipientMemberId)
+        }
+
+        return gifts.size
+    }
+
+    private companion object {
+        const val DEADLINE_REMINDER_HOURS = 24L
+        const val EXPIRED_TRACKING_REGISTRATION_GIFTS_LOCK_KEY = "lock:gift-expired-tracking-registration-cancellation"
+        const val EXPIRED_RECIPIENT_ADDRESS_REASON = "배송지 미입력 기한 초과"
+    }
+}

src/main/kotlin/kr/co/vividnext/sodalive/v2/gift/application/GiftAdminQueryService.kt

@@ -0,0 +1,209 @@
+package kr.co.vividnext.sodalive.v2.gift.application
+
+import kr.co.vividnext.sodalive.common.SodaException
+import kr.co.vividnext.sodalive.member.Member
+import kr.co.vividnext.sodalive.member.MemberRepository
+import kr.co.vividnext.sodalive.v2.gift.adapter.out.persistence.Gift
+import kr.co.vividnext.sodalive.v2.gift.adapter.out.persistence.GiftCategory
+import kr.co.vividnext.sodalive.v2.gift.adapter.out.persistence.GiftCategoryRepository
+import kr.co.vividnext.sodalive.v2.gift.adapter.out.persistence.GiftDelivery
+import kr.co.vividnext.sodalive.v2.gift.adapter.out.persistence.GiftDeliveryRepository
+import kr.co.vividnext.sodalive.v2.gift.adapter.out.persistence.GiftRepository
+import kr.co.vividnext.sodalive.v2.gift.domain.GiftStatus
+import org.springframework.data.domain.PageRequest
+import org.springframework.data.domain.Sort
+import org.springframework.stereotype.Service
+import org.springframework.transaction.annotation.Transactional
+
+data class AdminGiftListResult(
+    val totalCount: Long,
+    val items: List<AdminGiftListItemResult>,
+    val page: Int,
+    val size: Int,
+    val hasNext: Boolean
+)
+
+data class AdminGiftListItemResult(
+    val applicationNo: String,
+    val senderNickname: String,
+    val recipientNickname: String,
+    val sizeCode: String,
+    val sizeName: String,
+    val categoryName: String,
+    val classificationNumber: String,
+    val courierCompanyName: String?,
+    val trackingNumber: String?,
+    val status: GiftStatus,
+    val statusName: String,
+    val availableActions: List<String>
+)
+
+data class AdminGiftDetailResult(
+    val applicationNo: String,
+    val senderInfo: AdminGiftMemberInfoResult,
+    val recipientInfo: AdminGiftMemberInfoResult,
+    val productInfo: AdminGiftProductInfoResult,
+    val inboundDeliveryInfo: AdminGiftInboundDeliveryInfoResult,
+    val status: GiftStatus,
+    val statusName: String,
+    val availableActions: List<String>
+)
+
+data class AdminGiftMemberInfoResult(
+    val nickname: String,
+    val name: String,
+    val phoneNumber: String,
+    val address: String
+)
+
+data class AdminGiftProductInfoResult(
+    val sizeCode: String,
+    val sizeName: String,
+    val categoryName: String,
+    val classificationNumber: String
+)
+
+data class AdminGiftInboundDeliveryInfoResult(
+    val courierCompanyName: String?,
+    val trackingNumber: String?
+)
+
+@Service
+class GiftAdminQueryService(
+    private val giftRepository: GiftRepository,
+    private val deliveryRepository: GiftDeliveryRepository,
+    private val categoryRepository: GiftCategoryRepository,
+    private val memberRepository: MemberRepository
+) {
+    @Transactional(readOnly = true)
+    fun getGifts(
+        status: GiftStatus?,
+        applicationNo: String?,
+        nickname: String?,
+        page: Int,
+        size: Int
+    ): AdminGiftListResult {
+        val normalizedPage = page.coerceAtLeast(0)
+        val normalizedSize = if (size <= 0) DEFAULT_PAGE_SIZE else size
+        val gifts = giftRepository.findAdminGifts(
+            status = status,
+            applicationNo = applicationNo?.takeIf { it.isNotBlank() },
+            nickname = nickname?.takeIf { it.isNotBlank() },
+            pageable = PageRequest.of(normalizedPage, normalizedSize, Sort.by(Sort.Direction.DESC, "createdAt", "id"))
+        )
+        val context = buildContext(gifts.content)
+
+        return AdminGiftListResult(
+            totalCount = gifts.totalElements,
+            items = gifts.content.map { gift -> gift.toListItem(context) },
+            page = normalizedPage,
+            size = normalizedSize,
+            hasNext = gifts.hasNext()
+        )
+    }
+
+    @Transactional(readOnly = true)
+    fun getGiftDetail(applicationNo: String): AdminGiftDetailResult {
+        val gift = giftRepository.findByApplicationNo(applicationNo) ?: throw invalidRequest()
+        val context = buildContext(listOf(gift))
+        val delivery = context.delivery(gift)
+        val sender = context.sender(gift)
+        val recipient = context.recipient(gift)
+        val category = context.category(gift)
+
+        return AdminGiftDetailResult(
+            applicationNo = gift.applicationNo,
+            senderInfo = AdminGiftMemberInfoResult(
+                nickname = sender.nickname,
+                name = delivery.senderName,
+                phoneNumber = delivery.senderPhoneNumber,
+                address = formatAddress(delivery.senderZipCode, delivery.senderAddress, delivery.senderAddressDetail)
+            ),
+            recipientInfo = AdminGiftMemberInfoResult(
+                nickname = recipient.nickname,
+                name = delivery.recipientName.orEmpty(),
+                phoneNumber = delivery.recipientPhoneNumber.orEmpty(),
+                address = delivery.recipientAddressResult()
+            ),
+            productInfo = AdminGiftProductInfoResult(
+                sizeCode = gift.sizeCode.name,
+                sizeName = gift.sizeCode.displayName,
+                categoryName = gift.categoryNameSnapshot,
+                classificationNumber = category.classificationNumber
+            ),
+            inboundDeliveryInfo = AdminGiftInboundDeliveryInfoResult(
+                courierCompanyName = delivery.courierCompanyName,
+                trackingNumber = delivery.trackingNumber
+            ),
+            status = gift.status,
+            statusName = gift.status.displayName,
+            availableActions = gift.status.availableActions(delivery)
+        )
+    }
+
+    private fun Gift.toListItem(context: GiftAdminQueryContext) = AdminGiftListItemResult(
+        applicationNo = applicationNo,
+        senderNickname = context.sender(this).nickname,
+        recipientNickname = context.recipient(this).nickname,
+        sizeCode = sizeCode.name,
+        sizeName = sizeCode.displayName,
+        categoryName = categoryNameSnapshot,
+        classificationNumber = context.category(this).classificationNumber,
+        courierCompanyName = context.delivery(this).courierCompanyName,
+        trackingNumber = context.delivery(this).trackingNumber,
+        status = status,
+        statusName = status.displayName,
+        availableActions = status.availableActions(context.delivery(this))
+    )
+
+    private fun GiftStatus.availableActions(delivery: GiftDelivery) = when (this) {
+        GiftStatus.TRACKING_REGISTERED -> listOf("ARRIVE_MAILBOX", "MARK_UNDELIVERABLE")
+        GiftStatus.ARRIVED_AT_MAILBOX -> listOf("COMPLETE_INSPECTION", "MARK_UNDELIVERABLE")
+        GiftStatus.INSPECTION_COMPLETED -> if (delivery.hasCompleteRecipientInformation()) {
+            listOf("COMPLETE_DELIVERY", "MARK_UNDELIVERABLE")
+        } else {
+            listOf("MARK_UNDELIVERABLE")
+        }
+        GiftStatus.RECEIVED, GiftStatus.DELIVERED, GiftStatus.UNDELIVERABLE, GiftStatus.CANCELED -> emptyList()
+    }
+
+    private fun GiftDelivery.recipientAddressResult(): String {
+        val zipCode = recipientZipCode ?: return ""
+        val address = recipientAddress ?: return ""
+        return formatAddress(zipCode, address, recipientAddressDetail)
+    }
+
+    private fun formatAddress(zipCode: String, address: String, detail: String?) =
+        "($zipCode) $address" + if (detail.isNullOrBlank()) "" else ", $detail"
+
+    private fun invalidRequest() = SodaException(messageKey = "common.error.invalid_request")
+
+    private fun buildContext(gifts: List<Gift>): GiftAdminQueryContext {
+        val giftIds = gifts.mapNotNull { it.id }
+        val memberIds = gifts.flatMap { listOf(it.senderMemberId, it.recipientMemberId) }.toSet()
+        val categoryIds = gifts.map { it.categoryId }.toSet()
+        return GiftAdminQueryContext(
+            deliveriesByGiftId = deliveryRepository.findByGiftIdIn(giftIds).associateBy { it.giftId },
+            membersById = memberRepository.findAllById(memberIds).associateBy { it.id ?: throw invalidRequest() },
+            categoriesById = categoryRepository.findAllById(categoryIds).associateBy { it.id ?: throw invalidRequest() }
+        )
+    }
+
+    private inner class GiftAdminQueryContext(
+        private val deliveriesByGiftId: Map<Long, GiftDelivery>,
+        private val membersById: Map<Long, Member>,
+        private val categoriesById: Map<Long, GiftCategory>
+    ) {
+        fun delivery(gift: Gift) = deliveriesByGiftId[gift.id] ?: throw invalidRequest()
+
+        fun sender(gift: Gift) = membersById[gift.senderMemberId] ?: throw invalidRequest()
+
+        fun recipient(gift: Gift) = membersById[gift.recipientMemberId] ?: throw invalidRequest()
+
+        fun category(gift: Gift) = categoriesById[gift.categoryId] ?: throw invalidRequest()
+    }
+
+    private companion object {
+        const val DEFAULT_PAGE_SIZE = 20
+    }
+}

src/main/kotlin/kr/co/vividnext/sodalive/v2/gift/application/GiftAdminService.kt

@@ -0,0 +1,290 @@
+package kr.co.vividnext.sodalive.v2.gift.application
+
+import kr.co.vividnext.sodalive.common.SodaException
+import kr.co.vividnext.sodalive.v2.gift.adapter.out.persistence.GiftCategory
+import kr.co.vividnext.sodalive.v2.gift.adapter.out.persistence.GiftCategoryRepository
+import kr.co.vividnext.sodalive.v2.gift.adapter.out.persistence.GiftDeliveryRepository
+import kr.co.vividnext.sodalive.v2.gift.adapter.out.persistence.GiftMailbox
+import kr.co.vividnext.sodalive.v2.gift.adapter.out.persistence.GiftMailboxRepository
+import kr.co.vividnext.sodalive.v2.gift.adapter.out.persistence.GiftRepository
+import kr.co.vividnext.sodalive.v2.gift.adapter.out.persistence.GiftSizePrice
+import kr.co.vividnext.sodalive.v2.gift.adapter.out.persistence.GiftSizePriceRepository
+import kr.co.vividnext.sodalive.v2.gift.domain.GiftSize
+import kr.co.vividnext.sodalive.v2.gift.domain.GiftStatus
+import org.springframework.data.repository.findByIdOrNull
+import org.springframework.stereotype.Service
+import org.springframework.transaction.annotation.Transactional
+import java.time.LocalDateTime
+
+data class GiftCategoryCommand(
+    val classificationNumber: String,
+    val categoryCode: String,
+    val name: String,
+    val receiptCode: String,
+    val representativeItem: String,
+    val requiresDamageWaiver: Boolean,
+    val isActive: Boolean
+)
+
+data class GiftCategoryResult(
+    val categoryId: Long,
+    val classificationNumber: String,
+    val categoryCode: String,
+    val name: String,
+    val receiptCode: String,
+    val representativeItem: String,
+    val requiresDamageWaiver: Boolean,
+    val isActive: Boolean
+)
+
+data class GiftSizePriceCommand(
+    val basePriceCan: Int,
+    val salePriceCan: Int,
+    val isActive: Boolean
+)
+
+data class GiftMailboxCommand(
+    val name: String,
+    val phoneNumber: String,
+    val zipCode: String,
+    val address: String,
+    val addressDetail: String?
+)
+
+data class GiftSizePriceResult(
+    val sizeCode: GiftSize,
+    val sizeName: String,
+    val basePriceCan: Int,
+    val salePriceCan: Int,
+    val isActive: Boolean
+)
+
+data class GiftOperationStatusResult(
+    val applicationNo: String,
+    val status: GiftStatus,
+    val statusName: String,
+    val occurredAt: LocalDateTime
+)
+
+@Service
+class GiftAdminService(
+    private val categoryRepository: GiftCategoryRepository,
+    private val sizePriceRepository: GiftSizePriceRepository,
+    private val giftRepository: GiftRepository,
+    private val giftDeliveryRepository: GiftDeliveryRepository,
+    private val giftMailboxRepository: GiftMailboxRepository,
+    private val giftPushService: GiftPushService
+) {
+    @Transactional(readOnly = true)
+    fun getMailbox(): GiftMailboxResult? = giftMailboxRepository.findByIdOrNull(GiftMailbox.SINGLETON_ID)?.toResult()
+
+    @Transactional
+    fun updateMailbox(command: GiftMailboxCommand): GiftMailboxResult {
+        validateMailbox(command)
+        val mailbox = giftMailboxRepository.findByIdOrNull(GiftMailbox.SINGLETON_ID)
+            ?: GiftMailbox(
+                name = command.name,
+                phoneNumber = command.phoneNumber,
+                zipCode = command.zipCode,
+                address = command.address,
+                addressDetail = command.addressDetail?.takeIf { it.isNotBlank() }
+            )
+        mailbox.name = command.name
+        mailbox.phoneNumber = command.phoneNumber
+        mailbox.zipCode = command.zipCode
+        mailbox.address = command.address
+        mailbox.addressDetail = command.addressDetail?.takeIf { it.isNotBlank() }
+        return giftMailboxRepository.save(mailbox).toResult()
+    }
+
+    @Transactional(readOnly = true)
+    fun getCategories(): List<GiftCategoryResult> = categoryRepository.findAll().map { it.toResult() }
+
+    @Transactional
+    fun createCategory(command: GiftCategoryCommand): GiftCategoryResult {
+        validateCategory(command)
+        return categoryRepository.save(
+            GiftCategory(
+                classificationNumber = command.classificationNumber,
+                categoryCode = command.categoryCode,
+                name = command.name,
+                receiptCode = command.receiptCode,
+                representativeItem = command.representativeItem,
+                requiresDamageWaiver = command.requiresDamageWaiver,
+                isActive = command.isActive
+            )
+        ).toResult()
+    }
+
+    @Transactional
+    fun updateCategory(categoryId: Long, command: GiftCategoryCommand): GiftCategoryResult {
+        validateCategory(command)
+        val category = categoryRepository.findByIdOrNull(categoryId) ?: throw invalidRequest()
+        category.classificationNumber = command.classificationNumber
+        category.name = command.name
+        category.receiptCode = command.receiptCode
+        category.representativeItem = command.representativeItem
+        category.requiresDamageWaiver = command.requiresDamageWaiver
+        category.isActive = command.isActive
+        return category.toResult()
+    }
+
+    @Transactional
+    fun deleteCategory(categoryId: Long): GiftCategoryResult {
+        val category = categoryRepository.findByIdOrNull(categoryId) ?: throw invalidRequest()
+        category.isActive = false
+        return category.toResult()
+    }
+
+    @Transactional(readOnly = true)
+    fun getSizePrices(): List<GiftSizePriceResult> = sizePriceRepository.findAll().map { it.toResult() }
+
+    @Transactional
+    fun updateSizePrice(sizeCode: GiftSize, command: GiftSizePriceCommand): GiftSizePriceResult {
+        validateSizePrice(command)
+        val sizePrice = sizePriceRepository.findBySizeCode(sizeCode)
+            ?: GiftSizePrice(sizeCode = sizeCode, basePriceCan = command.basePriceCan, salePriceCan = command.salePriceCan)
+        sizePrice.basePriceCan = command.basePriceCan
+        sizePrice.salePriceCan = command.salePriceCan
+        sizePrice.isActive = command.isActive
+        return sizePriceRepository.save(sizePrice).toResult()
+    }
+
+    @Transactional
+    fun arriveMailbox(applicationNo: String, now: LocalDateTime = LocalDateTime.now()): GiftOperationStatusResult {
+        val gift = giftRepository.findByApplicationNo(applicationNo) ?: throw invalidRequest()
+        if (gift.status != GiftStatus.TRACKING_REGISTERED) throw invalidRequest()
+        val delivery = giftDeliveryRepository.findByGiftId(requireNotNull(gift.id)) ?: throw invalidRequest()
+
+        gift.status = GiftStatus.ARRIVED_AT_MAILBOX
+        delivery.arrivedAtMailboxAt = now
+        giftPushService.sendArrivedAtMailboxToSender(gift.applicationNo, gift.senderMemberId)
+        giftPushService.sendArrivedAtMailboxToRecipient(gift.applicationNo, gift.recipientMemberId)
+
+        return GiftOperationStatusResult(gift.applicationNo, gift.status, gift.status.displayName, now)
+    }
+
+    @Transactional
+    fun completeInspection(applicationNo: String, now: LocalDateTime = LocalDateTime.now()): GiftOperationStatusResult {
+        val gift = giftRepository.findByApplicationNo(applicationNo) ?: throw invalidRequest()
+        if (gift.status != GiftStatus.ARRIVED_AT_MAILBOX) throw invalidRequest()
+        val delivery = giftDeliveryRepository.findByGiftId(requireNotNull(gift.id)) ?: throw invalidRequest()
+
+        gift.status = GiftStatus.INSPECTION_COMPLETED
+        delivery.inspectionCompletedAt = now
+        giftPushService.sendInspectionCompleted(gift.applicationNo, gift.recipientMemberId)
+
+        return GiftOperationStatusResult(gift.applicationNo, gift.status, gift.status.displayName, now)
+    }
+
+    @Transactional
+    fun markUndeliverable(
+        applicationNo: String,
+        reason: String,
+        now: LocalDateTime = LocalDateTime.now()
+    ): GiftOperationStatusResult {
+        val gift = giftRepository.findByApplicationNo(applicationNo) ?: throw invalidRequest()
+        if (gift.status !in UNDELIVERABLE_ALLOWED_STATUSES || reason.isBlank() || reason.length > 255) {
+            throw invalidRequest()
+        }
+        val delivery = giftDeliveryRepository.findByGiftId(requireNotNull(gift.id)) ?: throw invalidRequest()
+
+        gift.status = GiftStatus.UNDELIVERABLE
+        delivery.undeliverableAt = now
+        delivery.undeliverableReason = reason
+        giftPushService.sendUndeliverableToSender(gift.applicationNo, gift.senderMemberId)
+        giftPushService.sendUndeliverableToRecipient(gift.applicationNo, gift.recipientMemberId)
+
+        return GiftOperationStatusResult(gift.applicationNo, gift.status, gift.status.displayName, now)
+    }
+
+    @Transactional
+    fun completeDelivery(applicationNo: String, now: LocalDateTime = LocalDateTime.now()): GiftOperationStatusResult {
+        val gift = giftRepository.findByApplicationNo(applicationNo) ?: throw invalidRequest()
+        if (gift.status != GiftStatus.INSPECTION_COMPLETED) throw invalidRequest()
+        val delivery = giftDeliveryRepository.findByGiftId(requireNotNull(gift.id)) ?: throw invalidRequest()
+        if (!delivery.hasCompleteRecipientInformation()) throw invalidRequest()
+
+        gift.status = GiftStatus.DELIVERED
+        delivery.deliveredAt = now
+        giftPushService.sendDeliveredToSender(gift.applicationNo, gift.senderMemberId)
+        giftPushService.sendDeliveredToRecipient(gift.applicationNo, gift.recipientMemberId)
+
+        return GiftOperationStatusResult(gift.applicationNo, gift.status, gift.status.displayName, now)
+    }
+
+    private fun validateCategory(command: GiftCategoryCommand) {
+        if (
+            command.categoryCode.isBlank() ||
+            command.categoryCode.length > 50 ||
+            command.name.isBlank() ||
+            command.name.length > 50 ||
+            !CLASSIFICATION_NUMBER_REGEX.matches(command.classificationNumber) ||
+            !RECEIPT_CODE_REGEX.matches(command.receiptCode) ||
+            command.representativeItem.isBlank() ||
+            command.representativeItem.length > 100
+        ) {
+            throw invalidRequest()
+        }
+    }
+
+    private fun validateSizePrice(command: GiftSizePriceCommand) {
+        if (command.salePriceCan <= 0 || command.salePriceCan > command.basePriceCan) throw invalidRequest()
+    }
+
+    private fun validateMailbox(command: GiftMailboxCommand) {
+        if (
+            command.name.isBlank() ||
+            command.name.length > 50 ||
+            command.phoneNumber.isBlank() ||
+            command.phoneNumber.length > 30 ||
+            command.zipCode.isBlank() ||
+            command.zipCode.length > 20 ||
+            command.address.isBlank() ||
+            command.address.length > 255 ||
+            (command.addressDetail?.length ?: 0) > 255
+        ) {
+            throw invalidRequest()
+        }
+    }
+
+    private fun GiftCategory.toResult() = GiftCategoryResult(
+        categoryId = id ?: throw invalidRequest(),
+        classificationNumber = classificationNumber,
+        categoryCode = categoryCode,
+        name = name,
+        receiptCode = receiptCode,
+        representativeItem = representativeItem,
+        requiresDamageWaiver = requiresDamageWaiver,
+        isActive = isActive
+    )
+
+    private fun GiftSizePrice.toResult() = GiftSizePriceResult(
+        sizeCode = sizeCode,
+        sizeName = sizeCode.displayName,
+        basePriceCan = basePriceCan,
+        salePriceCan = salePriceCan,
+        isActive = isActive
+    )
+
+    private fun GiftMailbox.toResult() = GiftMailboxResult(
+        name = name,
+        address = formatAddress(zipCode, address, addressDetail),
+        phoneNumber = phoneNumber
+    )
+
+    private fun formatAddress(zipCode: String, address: String, detail: String?) =
+        "($zipCode) $address" + if (detail.isNullOrBlank()) "" else ", $detail"
+
+    private fun invalidRequest() = SodaException(messageKey = "common.error.invalid_request")
+
+    private companion object {
+        val UNDELIVERABLE_ALLOWED_STATUSES = setOf(
+            GiftStatus.TRACKING_REGISTERED,
+            GiftStatus.ARRIVED_AT_MAILBOX,
+            GiftStatus.INSPECTION_COMPLETED
+        )
+        val CLASSIFICATION_NUMBER_REGEX = Regex("\\d{3}")
+        val RECEIPT_CODE_REGEX = Regex("[A-Z]{1,9}")
+    }
+}

src/main/kotlin/kr/co/vividnext/sodalive/v2/gift/application/GiftApplicationNoGenerator.kt

@@ -0,0 +1,52 @@
+package kr.co.vividnext.sodalive.v2.gift.application
+
+import kr.co.vividnext.sodalive.common.SodaException
+import kr.co.vividnext.sodalive.v2.gift.adapter.out.persistence.GiftApplicationNoSequence
+import kr.co.vividnext.sodalive.v2.gift.adapter.out.persistence.GiftApplicationNoSequenceRepository
+import kr.co.vividnext.sodalive.v2.gift.adapter.out.persistence.GiftCategory
+import org.springframework.dao.DataIntegrityViolationException
+import org.springframework.stereotype.Service
+import org.springframework.transaction.PlatformTransactionManager
+import org.springframework.transaction.support.TransactionTemplate
+import java.time.LocalDateTime
+import java.time.ZoneId
+import java.time.format.DateTimeFormatter
+
+@Service
+class GiftApplicationNoGenerator(
+    private val repository: GiftApplicationNoSequenceRepository,
+    transactionManager: PlatformTransactionManager
+) {
+    private val transactionTemplate = TransactionTemplate(transactionManager)
+
+    fun generate(category: GiftCategory, now: LocalDateTime = LocalDateTime.now(SEOUL_ZONE)): String {
+        val categoryId = category.id ?: throw SodaException(messageKey = "common.error.invalid_request")
+        val sequenceDate = now.format(DATE_FORMATTER)
+        for (attempt in 1..MAX_RETRY_COUNT) {
+            try {
+                return transactionTemplate.execute {
+                    val sequence = repository.findByCategoryIdAndSequenceDateForUpdate(categoryId, sequenceDate)
+                        ?: repository.saveAndFlush(
+                            GiftApplicationNoSequence(
+                                categoryId = categoryId,
+                                sequenceDate = sequenceDate,
+                                lastSequence = 0
+                            )
+                        )
+                    sequence.lastSequence += 1
+                    "${category.receiptCode}-${category.classificationNumber}$sequenceDate" +
+                        sequence.lastSequence.toString().padStart(4, '0')
+                } ?: throw SodaException(messageKey = "common.error.invalid_request")
+            } catch (_: DataIntegrityViolationException) {
+                if (attempt == MAX_RETRY_COUNT) throw SodaException(messageKey = "gift.application_no.generate_failed")
+            }
+        }
+        throw SodaException(messageKey = "gift.application_no.generate_failed")
+    }
+
+    companion object {
+        private val SEOUL_ZONE = ZoneId.of("Asia/Seoul")
+        private val DATE_FORMATTER = DateTimeFormatter.ofPattern("yyMMdd")
+        private const val MAX_RETRY_COUNT = 3
+    }
+}

src/main/kotlin/kr/co/vividnext/sodalive/v2/gift/application/GiftCommandService.kt

@@ -0,0 +1,368 @@
+package kr.co.vividnext.sodalive.v2.gift.application
+
+import kr.co.vividnext.sodalive.can.payment.CanPaymentService
+import kr.co.vividnext.sodalive.common.SodaException
+import kr.co.vividnext.sodalive.member.Member
+import kr.co.vividnext.sodalive.member.MemberRepository
+import kr.co.vividnext.sodalive.v2.gift.adapter.out.persistence.Gift
+import kr.co.vividnext.sodalive.v2.gift.adapter.out.persistence.GiftCategoryRepository
+import kr.co.vividnext.sodalive.v2.gift.adapter.out.persistence.GiftDelivery
+import kr.co.vividnext.sodalive.v2.gift.adapter.out.persistence.GiftDeliveryRepository
+import kr.co.vividnext.sodalive.v2.gift.adapter.out.persistence.GiftRepository
+import kr.co.vividnext.sodalive.v2.gift.adapter.out.persistence.GiftReview
+import kr.co.vividnext.sodalive.v2.gift.adapter.out.persistence.GiftReviewRepository
+import kr.co.vividnext.sodalive.v2.gift.adapter.out.persistence.GiftSizePriceRepository
+import kr.co.vividnext.sodalive.v2.gift.domain.GiftSize
+import kr.co.vividnext.sodalive.v2.gift.domain.GiftStatus
+import org.springframework.data.repository.findByIdOrNull
+import org.springframework.stereotype.Service
+import org.springframework.transaction.annotation.Transactional
+import java.time.LocalDateTime
+
+data class GiftApplicationCommand(
+    val recipientMemberId: Long,
+    val senderName: String,
+    val senderPhoneNumber: String,
+    val senderZipCode: String,
+    val senderAddress: String,
+    val senderAddressDetail: String?,
+    val sizeCode: GiftSize,
+    val categoryId: Long,
+    val senderTermsAgreed: Boolean,
+    val senderPrivacyAgreed: Boolean,
+    val damageWaiverAgreed: Boolean
+)
+
+data class GiftApplicationResult(
+    val applicationNo: String,
+    val status: GiftStatus,
+    val statusName: String,
+    val priceCan: Int,
+    val trackingDeadlineAt: LocalDateTime
+)
+
+data class GiftCancellationResult(
+    val applicationNo: String,
+    val status: GiftStatus,
+    val statusName: String,
+    val priceCan: Int,
+    val canceledAt: LocalDateTime
+)
+
+data class GiftTrackingRegistrationCommand(
+    val courierCompanyName: String,
+    val trackingNumber: String
+)
+
+data class GiftTrackingRegistrationResult(
+    val applicationNo: String,
+    val status: GiftStatus,
+    val statusName: String,
+    val courierCompanyName: String,
+    val trackingNumber: String,
+    val trackingRegisteredAt: LocalDateTime,
+    val recipientAddressDeadlineAt: LocalDateTime
+)
+
+data class GiftRecipientAddressRegistrationCommand(
+    val name: String,
+    val phoneNumber: String,
+    val zipCode: String,
+    val address: String,
+    val addressDetail: String?,
+    val recipientTermsAgreed: Boolean,
+    val recipientPrivacyAgreed: Boolean
+)
+
+data class GiftRecipientAddressRegistrationResult(
+    val applicationNo: String,
+    val status: GiftStatus,
+    val statusName: String,
+    val recipientAddressRegisteredAt: LocalDateTime
+)
+
+data class GiftDeliveryConfirmationResult(
+    val applicationNo: String,
+    val status: GiftStatus,
+    val statusName: String,
+    val deliveredAt: LocalDateTime
+)
+
+data class GiftReviewCommand(
+    val rating: Int,
+    val keywords: List<String>,
+    val comment: String?
+)
+
+data class GiftReviewResult(
+    val reviewId: Long,
+    val applicationNo: String,
+    val rating: Int,
+    val keywords: List<String>,
+    val comment: String?,
+    val createdAt: LocalDateTime?
+)
+
+@Service
+class GiftCommandService(
+    private val giftRepository: GiftRepository,
+    private val deliveryRepository: GiftDeliveryRepository,
+    private val reviewRepository: GiftReviewRepository,
+    private val categoryRepository: GiftCategoryRepository,
+    private val sizePriceRepository: GiftSizePriceRepository,
+    private val memberRepository: MemberRepository,
+    private val applicationNoGenerator: GiftApplicationNoGenerator,
+    private val canPaymentService: CanPaymentService,
+    private val giftPushService: GiftPushService,
+    private val now: () -> LocalDateTime = { LocalDateTime.now() }
+) {
+    @Transactional
+    fun registerGift(member: Member, command: GiftApplicationCommand): GiftApplicationResult {
+        validate(command)
+        val senderMemberId = member.id ?: throw invalidRequest()
+        memberRepository.findCreatorByIdOrNull(command.recipientMemberId) ?: throw invalidRequest()
+        val category = categoryRepository.findByIdOrNull(command.categoryId)?.takeIf { it.isActive } ?: throw invalidRequest()
+        if (category.requiresDamageWaiver && !command.damageWaiverAgreed) throw invalidRequest()
+        val sizePrice = sizePriceRepository.findBySizeCode(command.sizeCode)?.takeIf { it.isActive } ?: throw invalidRequest()
+        val appliedAt = now()
+        val trackingDeadlineAt = appliedAt.plusDays(3)
+        val applicationNo = applicationNoGenerator.generate(category, appliedAt)
+        val canUsageId = canPaymentService.spendGiftCan(
+            senderMemberId,
+            sizePrice.salePriceCan,
+            member.container.ifBlank { "web" }
+        )
+        val gift = giftRepository.save(
+            Gift(
+                applicationNo = applicationNo,
+                senderMemberId = senderMemberId,
+                recipientMemberId = command.recipientMemberId,
+                status = GiftStatus.RECEIVED,
+                sizeCode = command.sizeCode,
+                categoryId = category.id ?: throw invalidRequest(),
+                categoryNameSnapshot = category.name,
+                salePriceCan = sizePrice.salePriceCan,
+                canUsageId = canUsageId,
+                senderTermsAgreed = command.senderTermsAgreed,
+                senderPrivacyAgreed = command.senderPrivacyAgreed,
+                senderTermsAgreedAt = appliedAt,
+                senderPrivacyAgreedAt = appliedAt,
+                damageWaiverAgreed = command.damageWaiverAgreed
+            )
+        )
+        deliveryRepository.save(
+            GiftDelivery(
+                giftId = gift.id ?: throw invalidRequest(),
+                senderName = command.senderName,
+                senderPhoneNumber = command.senderPhoneNumber,
+                senderZipCode = command.senderZipCode,
+                senderAddress = command.senderAddress,
+                senderAddressDetail = command.senderAddressDetail,
+                trackingDeadlineAt = trackingDeadlineAt
+            )
+        )
+        return GiftApplicationResult(
+            applicationNo = applicationNo,
+            status = GiftStatus.RECEIVED,
+            statusName = GiftStatus.RECEIVED.displayName,
+            priceCan = sizePrice.salePriceCan,
+            trackingDeadlineAt = trackingDeadlineAt
+        )
+    }
+
+    @Transactional
+    fun writeReview(member: Member, applicationNo: String, command: GiftReviewCommand): GiftReviewResult {
+        val senderMemberId = member.id ?: throw invalidRequest()
+        val gift = giftRepository.findByApplicationNo(applicationNo) ?: throw invalidRequest()
+        val giftId = gift.id ?: throw invalidRequest()
+        if (
+            gift.senderMemberId != senderMemberId ||
+            gift.status != GiftStatus.DELIVERED ||
+            reviewRepository.findByGiftId(giftId) != null
+        ) {
+            throw invalidRequest()
+        }
+        validate(command)
+
+        val review = reviewRepository.save(
+            GiftReview(
+                giftId = giftId,
+                senderMemberId = senderMemberId,
+                rating = command.rating,
+                keywords = command.keywords.joinToString(","),
+                comment = command.comment
+            )
+        )
+
+        return GiftReviewResult(
+            reviewId = review.id ?: throw invalidRequest(),
+            applicationNo = gift.applicationNo,
+            rating = review.rating,
+            keywords = review.keywords?.takeIf { it.isNotBlank() }?.split(",") ?: emptyList(),
+            comment = review.comment,
+            createdAt = review.createdAt
+        )
+    }
+
+    @Transactional
+    fun cancelGift(member: Member, applicationNo: String): GiftCancellationResult {
+        val senderMemberId = member.id ?: throw invalidRequest()
+        val gift = giftRepository.findByApplicationNo(applicationNo) ?: throw invalidRequest()
+        if (gift.senderMemberId != senderMemberId || gift.status != GiftStatus.RECEIVED) throw invalidRequest()
+
+        val canceledAt = now()
+        gift.status = GiftStatus.CANCELED
+        deliveryRepository.findByGiftId(gift.id ?: throw invalidRequest())?.canceledAt = canceledAt
+        canPaymentService.refundGiftCan(senderMemberId, gift.canUsageId)
+
+        return GiftCancellationResult(
+            applicationNo = gift.applicationNo,
+            status = gift.status,
+            statusName = gift.status.displayName,
+            priceCan = gift.salePriceCan,
+            canceledAt = canceledAt
+        )
+    }
+
+    @Transactional
+    fun registerTracking(
+        member: Member,
+        applicationNo: String,
+        command: GiftTrackingRegistrationCommand
+    ): GiftTrackingRegistrationResult {
+        val senderMemberId = member.id ?: throw invalidRequest()
+        val gift = giftRepository.findByApplicationNo(applicationNo) ?: throw invalidRequest()
+        if (gift.senderMemberId != senderMemberId || gift.status != GiftStatus.RECEIVED) throw invalidRequest()
+        validate(command)
+        val delivery = deliveryRepository.findByGiftId(gift.id ?: throw invalidRequest()) ?: throw invalidRequest()
+        val trackingRegisteredAt = now()
+        val recipientAddressDeadlineAt = trackingRegisteredAt.plusDays(7)
+
+        gift.status = GiftStatus.TRACKING_REGISTERED
+        delivery.courierCompanyName = command.courierCompanyName
+        delivery.trackingNumber = command.trackingNumber
+        delivery.trackingRegisteredAt = trackingRegisteredAt
+        delivery.recipientAddressDeadlineAt = recipientAddressDeadlineAt
+        giftPushService.sendTrackingRegisteredToRecipient(gift.applicationNo, gift.recipientMemberId)
+
+        return GiftTrackingRegistrationResult(
+            applicationNo = gift.applicationNo,
+            status = gift.status,
+            statusName = gift.status.displayName,
+            courierCompanyName = command.courierCompanyName,
+            trackingNumber = command.trackingNumber,
+            trackingRegisteredAt = trackingRegisteredAt,
+            recipientAddressDeadlineAt = recipientAddressDeadlineAt
+        )
+    }
+
+    @Transactional
+    fun registerRecipientAddress(
+        member: Member,
+        applicationNo: String,
+        command: GiftRecipientAddressRegistrationCommand
+    ): GiftRecipientAddressRegistrationResult {
+        val recipientMemberId = member.id ?: throw invalidRequest()
+        val gift = giftRepository.findByApplicationNo(applicationNo) ?: throw invalidRequest()
+        if (gift.recipientMemberId != recipientMemberId || gift.status !in RECIPIENT_ADDRESS_REGISTRABLE_STATUSES) {
+            throw invalidRequest()
+        }
+        validate(command)
+        val delivery = deliveryRepository.findByGiftId(gift.id ?: throw invalidRequest()) ?: throw invalidRequest()
+        val registeredAt = now()
+
+        delivery.recipientName = command.name
+        delivery.recipientPhoneNumber = command.phoneNumber
+        delivery.recipientZipCode = command.zipCode
+        delivery.recipientAddress = command.address
+        delivery.recipientAddressDetail = command.addressDetail
+        gift.recipientTermsAgreed = command.recipientTermsAgreed
+        gift.recipientPrivacyAgreed = command.recipientPrivacyAgreed
+        gift.recipientTermsAgreedAt = registeredAt
+        gift.recipientPrivacyAgreedAt = registeredAt
+
+        return GiftRecipientAddressRegistrationResult(
+            applicationNo = gift.applicationNo,
+            status = gift.status,
+            statusName = gift.status.displayName,
+            recipientAddressRegisteredAt = registeredAt
+        )
+    }
+
+    @Transactional
+    fun confirmDelivery(member: Member, applicationNo: String): GiftDeliveryConfirmationResult {
+        val recipientMemberId = member.id ?: throw invalidRequest()
+        val gift = giftRepository.findByApplicationNo(applicationNo) ?: throw invalidRequest()
+        if (gift.recipientMemberId != recipientMemberId || gift.status != GiftStatus.INSPECTION_COMPLETED) {
+            throw invalidRequest()
+        }
+        val delivery = deliveryRepository.findByGiftId(gift.id ?: throw invalidRequest()) ?: throw invalidRequest()
+        val deliveredAt = now()
+
+        gift.status = GiftStatus.DELIVERED
+        delivery.deliveredAt = deliveredAt
+
+        return GiftDeliveryConfirmationResult(
+            applicationNo = gift.applicationNo,
+            status = gift.status,
+            statusName = gift.status.displayName,
+            deliveredAt = deliveredAt
+        )
+    }
+
+    private fun validate(command: GiftApplicationCommand) {
+        if (
+            command.senderName.isBlank() ||
+            command.senderPhoneNumber.isBlank() ||
+            command.senderZipCode.isBlank() ||
+            command.senderAddress.isBlank() ||
+            !command.senderTermsAgreed ||
+            !command.senderPrivacyAgreed
+        ) {
+            throw invalidRequest()
+        }
+    }
+
+    private fun validate(command: GiftTrackingRegistrationCommand) {
+        if (
+            command.courierCompanyName.isBlank() ||
+            command.courierCompanyName.length > 50 ||
+            command.trackingNumber.isBlank()
+        ) {
+            throw invalidRequest()
+        }
+    }
+
+    private fun validate(command: GiftRecipientAddressRegistrationCommand) {
+        if (
+            command.name.isBlank() ||
+            command.phoneNumber.isBlank() ||
+            command.zipCode.isBlank() ||
+            command.address.isBlank() ||
+            !command.recipientTermsAgreed ||
+            !command.recipientPrivacyAgreed
+        ) {
+            throw invalidRequest()
+        }
+    }
+
+    private fun validate(command: GiftReviewCommand) {
+        if (
+            command.rating !in 1..5 ||
+            command.keywords.any { it.length > 255 } ||
+            (command.comment?.length ?: 0) > 255
+        ) {
+            throw invalidRequest()
+        }
+    }
+
+    private fun invalidRequest() = SodaException(messageKey = "common.error.invalid_request")
+
+    private companion object {
+        val RECIPIENT_ADDRESS_REGISTRABLE_STATUSES = setOf(
+            GiftStatus.TRACKING_REGISTERED,
+            GiftStatus.ARRIVED_AT_MAILBOX,
+            GiftStatus.INSPECTION_COMPLETED
+        )
+    }
+}

src/main/kotlin/kr/co/vividnext/sodalive/v2/gift/application/GiftPushService.kt

@@ -0,0 +1,126 @@
+package kr.co.vividnext.sodalive.v2.gift.application
+
+import kr.co.vividnext.sodalive.fcm.FcmDeepLinkValue
+import kr.co.vividnext.sodalive.fcm.FcmEvent
+import kr.co.vividnext.sodalive.fcm.FcmEventType
+import kr.co.vividnext.sodalive.fcm.notification.PushNotificationCategory
+import org.springframework.context.ApplicationEventPublisher
+import org.springframework.stereotype.Service
+
+@Service
+class GiftPushService(
+    private val applicationEventPublisher: ApplicationEventPublisher
+) {
+    fun sendTrackingDeadlineReminder(applicationNo: String, memberId: Long) {
+        publishGiftPush(
+            memberId = memberId,
+            applicationNo = applicationNo,
+            title = "운송장 번호를 입력해 주세요",
+            message = "24시간 이내에 운송장 번호를 등록해 주세요.\n기한 내 등록하지 않으면 신청이 자동 취소됩니다."
+        )
+    }
+
+    fun sendRecipientAddressDeadlineReminder(applicationNo: String, memberId: Long) {
+        publishGiftPush(
+            memberId = memberId,
+            applicationNo = applicationNo,
+            title = "배송지 입력 기한이 1일 남았어요",
+            message = "24시간 안에 배송지를 입력해 주세요.\n입력하지 않으면 선물은 반송되지 않고 폐기돼요"
+        )
+    }
+
+    fun sendAutoCanceledToSender(applicationNo: String, memberId: Long) {
+        publishGiftPush(
+            memberId = memberId,
+            applicationNo = applicationNo,
+            title = "선물 신청이 자동 취소됐어요",
+            message = "신청 후 3일 이내에 운송장 번호가 등록되지 않아 신청이 취소됐어요.\n사용한 캔은 모두 환불되었습니다."
+        )
+    }
+
+    fun sendTrackingRegisteredToRecipient(applicationNo: String, memberId: Long) {
+        publishGiftPush(
+            memberId = memberId,
+            applicationNo = applicationNo,
+            title = "팬이 보낸 선물이 있어요!",
+            message = "7일 이내에 배송지를 입력해 주세요.\n기간이 지나면 선물을 받을 수 없어요"
+        )
+    }
+
+    fun sendArrivedAtMailboxToSender(applicationNo: String, memberId: Long) {
+        publishGiftPush(
+            memberId = memberId,
+            applicationNo = applicationNo,
+            title = "선물이 사서함에 도착했어요",
+            message = "보내주신 선물이 소다라이브 사서함에 도착했어요.\n안전하게 전달할 수 있도록 선물을 확인하고 있어요."
+        )
+    }
+
+    fun sendArrivedAtMailboxToRecipient(applicationNo: String, memberId: Long) {
+        publishGiftPush(
+            memberId = memberId,
+            applicationNo = applicationNo,
+            title = "선물이 사서함에 도착했어요",
+            message = "팬이 보낸 선물을 검수하고 있어요.\n검수가 끝나면 다시 알려드릴게요"
+        )
+    }
+
+    fun sendInspectionCompleted(applicationNo: String, memberId: Long) {
+        publishGiftPush(
+            memberId = memberId,
+            applicationNo = applicationNo,
+            title = "선물 검수가 완료됐어요",
+            message = "확인된 선물을 빠른 시일 내에 입력하신 배송지로 보내드릴게요."
+        )
+    }
+
+    fun sendUndeliverableToSender(applicationNo: String, memberId: Long) {
+        publishGiftPush(
+            memberId = memberId,
+            applicationNo = applicationNo,
+            title = "선물을 전달할 수 없어요",
+            message = "도착한 선물이 선물 접수 규격에 맞지 않아 크리에이터에게 전달할 수 없어요.\n자세한 사유는 신청 상세에서 확인해 주세요."
+        )
+    }
+
+    fun sendUndeliverableToRecipient(applicationNo: String, memberId: Long) {
+        publishGiftPush(
+            memberId = memberId,
+            applicationNo = applicationNo,
+            title = "전달할 수 없는 선물이 있어요",
+            message = "검수 결과 선물 정책에 맞지 않아 해당 선물은 배송되지 않아요.\n자세한 사유를 확인해 주세요."
+        )
+    }
+
+    fun sendDeliveredToSender(applicationNo: String, memberId: Long) {
+        publishGiftPush(
+            memberId = memberId,
+            applicationNo = applicationNo,
+            title = "선물이 전달됐어요",
+            message = "보내주신 선물이 크리에이터에게 안전하게 전달됐어요."
+        )
+    }
+
+    fun sendDeliveredToRecipient(applicationNo: String, memberId: Long) {
+        publishGiftPush(
+            memberId = memberId,
+            applicationNo = applicationNo,
+            title = "선물이 도착했어요!",
+            message = "팬이 보낸 선물이 배송지에 도착했어요.\n지금 확인해 보세요."
+        )
+    }
+
+    private fun publishGiftPush(memberId: Long, applicationNo: String, title: String, message: String) {
+        applicationEventPublisher.publishEvent(
+            FcmEvent(
+                type = FcmEventType.INDIVIDUAL,
+                category = PushNotificationCategory.GIFT,
+                title = title,
+                message = message,
+                deepLinkValue = FcmDeepLinkValue.GIFT_DETAIL,
+                deepLinkId = applicationNo,
+                recipients = listOf(memberId)
+            )
+        )
+    }
+}

src/main/kotlin/kr/co/vividnext/sodalive/v2/gift/application/GiftQueryService.kt

@@ -0,0 +1,308 @@
+package kr.co.vividnext.sodalive.v2.gift.application
+
+import kr.co.vividnext.sodalive.common.SodaException
+import kr.co.vividnext.sodalive.member.Member
+import kr.co.vividnext.sodalive.member.MemberRepository
+import kr.co.vividnext.sodalive.v2.gift.adapter.out.persistence.Gift
+import kr.co.vividnext.sodalive.v2.gift.adapter.out.persistence.GiftCategoryRepository
+import kr.co.vividnext.sodalive.v2.gift.adapter.out.persistence.GiftDelivery
+import kr.co.vividnext.sodalive.v2.gift.adapter.out.persistence.GiftDeliveryRepository
+import kr.co.vividnext.sodalive.v2.gift.adapter.out.persistence.GiftMailbox
+import kr.co.vividnext.sodalive.v2.gift.adapter.out.persistence.GiftMailboxRepository
+import kr.co.vividnext.sodalive.v2.gift.adapter.out.persistence.GiftRepository
+import kr.co.vividnext.sodalive.v2.gift.adapter.out.persistence.GiftSizePriceRepository
+import kr.co.vividnext.sodalive.v2.gift.domain.GiftDirection
+import kr.co.vividnext.sodalive.v2.gift.domain.GiftListType
+import kr.co.vividnext.sodalive.v2.gift.domain.GiftStatus
+import org.springframework.beans.factory.annotation.Value
+import org.springframework.data.domain.PageRequest
+import org.springframework.data.domain.Sort
+import org.springframework.data.repository.findByIdOrNull
+import org.springframework.stereotype.Service
+import org.springframework.transaction.annotation.Transactional
+import java.time.LocalDateTime
+
+data class GiftFormOptionsResult(
+    val sizes: List<GiftSizePriceResult>,
+    val categories: List<GiftCategoryResult>
+)
+
+data class GiftListResult(
+    val totalCount: Long,
+    val items: List<GiftListItemResult>,
+    val page: Int,
+    val size: Int,
+    val hasNext: Boolean
+)
+
+data class GiftListItemResult(
+    val applicationNo: String,
+    val direction: GiftDirection,
+    val status: GiftStatus,
+    val statusName: String,
+    val priceCan: Int,
+    val categoryName: String,
+    val sizeName: String,
+    val counterpartMemberId: Long,
+    val counterpartNickname: String,
+    val counterpartProfileImageUrl: String,
+    val createdAt: LocalDateTime?
+)
+
+data class GiftDetailResult(
+    val applicationNo: String,
+    val direction: GiftDirection,
+    val status: GiftStatus,
+    val statusName: String,
+    val giftInfo: GiftDetailInfoResult,
+    val senderInfo: GiftAddressResult?,
+    val recipientAddress: GiftAddressResult?,
+    val mailbox: GiftMailboxResult?,
+    val trackingRequired: Boolean,
+    val recipientAddressRequired: Boolean,
+    val recipientAddressDeadlineAt: LocalDateTime?,
+    val delivery: GiftDeliveryInfoResult,
+    val statusTimeline: List<GiftStatusTimelineResult>
+)
+
+data class GiftDetailInfoResult(
+    val recipientCreatorNickname: String?,
+    val senderNickname: String?,
+    val sizeName: String,
+    val categoryName: String,
+    val applicationNo: String?,
+    val paidCan: Int?,
+    val tracking: String?,
+    val shippingRequestedAt: LocalDateTime?
+)
+
+data class GiftAddressResult(
+    val name: String,
+    val phoneNumber: String,
+    val address: String
+)
+
+data class GiftMailboxResult(
+    val name: String,
+    val address: String,
+    val phoneNumber: String
+)
+
+data class GiftDeliveryInfoResult(
+    val canceledAt: LocalDateTime?,
+    val undeliverableAt: LocalDateTime?,
+    val undeliverableReason: String?
+)
+
+data class GiftStatusTimelineResult(
+    val status: GiftStatus,
+    val statusName: String,
+    val occurredAt: LocalDateTime?
+)
+
+@Service
+class GiftQueryService(
+    private val categoryRepository: GiftCategoryRepository,
+    private val sizePriceRepository: GiftSizePriceRepository,
+    private val giftRepository: GiftRepository,
+    private val deliveryRepository: GiftDeliveryRepository,
+    private val memberRepository: MemberRepository,
+    private val giftMailboxRepository: GiftMailboxRepository,
+    @Value("\${cloud.aws.cloud-front.host}")
+    private val cloudFrontHost: String
+) {
+    @Transactional(readOnly = true)
+    fun getFormOptions() = GiftFormOptionsResult(
+        sizes = sizePriceRepository.findAll().filter { it.isActive }.map {
+            GiftSizePriceResult(it.sizeCode, it.sizeCode.displayName, it.basePriceCan, it.salePriceCan, it.isActive)
+        },
+        categories = categoryRepository.findAll().filter { it.isActive }.map {
+            GiftCategoryResult(
+                categoryId = it.id!!,
+                classificationNumber = it.classificationNumber,
+                categoryCode = it.categoryCode,
+                name = "${it.name}/${it.representativeItem}",
+                receiptCode = it.receiptCode,
+                representativeItem = it.representativeItem,
+                requiresDamageWaiver = it.requiresDamageWaiver,
+                isActive = it.isActive
+            )
+        }
+    )
+
+    @Transactional(readOnly = true)
+    fun getGifts(memberId: Long, type: GiftListType, page: Int, size: Int): GiftListResult {
+        val normalizedPage = page.coerceAtLeast(0)
+        val normalizedSize = if (size <= 0) DEFAULT_PAGE_SIZE else size
+        val pageable = PageRequest.of(normalizedPage, normalizedSize, Sort.by(Sort.Direction.DESC, "createdAt", "id"))
+        val gifts = when (type) {
+            GiftListType.SENT -> giftRepository.findBySenderMemberId(memberId, pageable)
+            GiftListType.RECEIVED -> giftRepository.findByRecipientMemberIdAndStatusIn(
+                memberId,
+                RECIPIENT_VISIBLE_STATUSES,
+                pageable
+            )
+            GiftListType.ALL -> giftRepository.findBySenderMemberIdOrRecipientMemberIdAndStatusIn(
+                memberId,
+                memberId,
+                RECIPIENT_VISIBLE_STATUSES,
+                pageable
+            )
+        }
+
+        val membersById = memberRepository.findAllById(
+            gifts.content.flatMap { listOf(it.senderMemberId, it.recipientMemberId) }.toSet()
+        ).associateBy { it.id ?: throw invalidRequest() }
+
+        return GiftListResult(
+            totalCount = gifts.totalElements,
+            items = gifts.content.map { it.toGiftListItem(memberId, membersById) },
+            page = normalizedPage,
+            size = normalizedSize,
+            hasNext = gifts.hasNext()
+        )
+    }
+
+    @Transactional(readOnly = true)
+    fun getGiftDetail(memberId: Long, applicationNo: String): GiftDetailResult {
+        val gift = giftRepository.findByApplicationNo(applicationNo) ?: throw invalidRequest()
+        val delivery = deliveryRepository.findByGiftId(gift.id ?: throw invalidRequest()) ?: throw invalidRequest()
+        val direction = gift.directionFor(memberId)
+        val sender = memberRepository.findByIdOrNull(gift.senderMemberId) ?: throw invalidRequest()
+        val recipient = memberRepository.findByIdOrNull(gift.recipientMemberId) ?: throw invalidRequest()
+        val recipientAddress = if (direction == GiftDirection.RECEIVED) delivery.toRecipientAddressResult() else null
+
+        return GiftDetailResult(
+            applicationNo = gift.applicationNo,
+            direction = direction,
+            status = gift.status,
+            statusName = gift.status.displayName,
+            giftInfo = GiftDetailInfoResult(
+                recipientCreatorNickname = recipient.nickname.takeIf { direction == GiftDirection.SENT },
+                senderNickname = sender.nickname.takeIf { direction == GiftDirection.RECEIVED },
+                sizeName = gift.sizeCode.displayName,
+                categoryName = gift.categoryNameSnapshot,
+                applicationNo = gift.applicationNo.takeIf { direction == GiftDirection.SENT },
+                paidCan = gift.salePriceCan.takeIf { direction == GiftDirection.SENT },
+                tracking = delivery.tracking().takeIf { direction == GiftDirection.SENT },
+                shippingRequestedAt = gift.createdAt.takeIf { direction == GiftDirection.RECEIVED }
+            ),
+            senderInfo = delivery.toSenderInfo().takeIf { direction == GiftDirection.SENT },
+            recipientAddress = recipientAddress,
+            mailbox = mailboxFor(direction, gift.status),
+            trackingRequired = direction == GiftDirection.SENT && gift.status == GiftStatus.RECEIVED,
+            recipientAddressRequired = direction == GiftDirection.RECEIVED && recipientAddress == null &&
+                gift.status !in TERMINAL_STATUSES,
+            recipientAddressDeadlineAt = delivery.recipientAddressDeadlineAt,
+            delivery = GiftDeliveryInfoResult(
+                canceledAt = delivery.canceledAt,
+                undeliverableAt = delivery.undeliverableAt,
+                undeliverableReason = delivery.undeliverableReason
+            ),
+            statusTimeline = gift.toStatusTimeline(delivery)
+        )
+    }
+
+    private fun Gift.toGiftListItem(memberId: Long, membersById: Map<Long, Member>): GiftListItemResult {
+        val direction = if (senderMemberId == memberId) GiftDirection.SENT else GiftDirection.RECEIVED
+        val counterpartId = if (direction == GiftDirection.SENT) recipientMemberId else senderMemberId
+        val counterpart = membersById[counterpartId] ?: throw invalidRequest()
+
+        return GiftListItemResult(
+            applicationNo = applicationNo,
+            direction = direction,
+            status = status,
+            statusName = status.displayName,
+            priceCan = salePriceCan,
+            categoryName = categoryNameSnapshot,
+            sizeName = sizeCode.displayName,
+            counterpartMemberId = counterpartId,
+            counterpartNickname = counterpart.nickname,
+            counterpartProfileImageUrl = counterpart.profileImageUrl(),
+            createdAt = createdAt
+        )
+    }
+
+    private fun Member.profileImageUrl() = if (profileImage.isNullOrBlank()) {
+        "$cloudFrontHost/profile/default-profile.png"
+    } else {
+        "$cloudFrontHost/$profileImage"
+    }
+
+    private fun Gift.directionFor(memberId: Long) = when {
+        senderMemberId == memberId -> GiftDirection.SENT
+        recipientMemberId == memberId && status in RECIPIENT_VISIBLE_STATUSES -> GiftDirection.RECEIVED
+        else -> throw invalidRequest()
+    }
+
+    private fun GiftDelivery.toSenderInfo() = GiftAddressResult(
+        name = senderName,
+        phoneNumber = senderPhoneNumber,
+        address = formatAddress(senderZipCode, senderAddress, senderAddressDetail)
+    )
+
+    private fun GiftDelivery.toRecipientAddressResult(): GiftAddressResult? {
+        val name = recipientName ?: return null
+        val phoneNumber = recipientPhoneNumber ?: return null
+        val zipCode = recipientZipCode ?: return null
+        val address = recipientAddress ?: return null
+
+        return GiftAddressResult(name, phoneNumber, formatAddress(zipCode, address, recipientAddressDetail))
+    }
+
+    private fun mailboxFor(direction: GiftDirection, status: GiftStatus): GiftMailboxResult? {
+        if (direction != GiftDirection.SENT || status in TERMINAL_STATUSES) return null
+        return giftMailboxRepository.findByIdOrNull(GiftMailbox.SINGLETON_ID)?.let {
+            GiftMailboxResult(
+                name = it.name,
+                address = formatAddress(it.zipCode, it.address, it.addressDetail),
+                phoneNumber = it.phoneNumber
+            )
+        }
+    }
+
+    private fun GiftDelivery.tracking() = if (courierCompanyName != null && trackingNumber != null) {
+        "${courierCompanyName}_$trackingNumber"
+    } else {
+        null
+    }
+
+    private fun Gift.toStatusTimeline(delivery: GiftDelivery) = NORMAL_PROGRESS_STATUSES.map { timelineStatus ->
+        GiftStatusTimelineResult(
+            status = timelineStatus,
+            statusName = timelineStatus.displayName,
+            occurredAt = when (timelineStatus) {
+                GiftStatus.RECEIVED -> createdAt
+                GiftStatus.TRACKING_REGISTERED -> delivery.trackingRegisteredAt
+                GiftStatus.ARRIVED_AT_MAILBOX -> delivery.arrivedAtMailboxAt
+                GiftStatus.INSPECTION_COMPLETED -> delivery.inspectionCompletedAt
+                GiftStatus.DELIVERED -> delivery.deliveredAt
+                GiftStatus.UNDELIVERABLE, GiftStatus.CANCELED -> null
+            }
+        )
+    }
+
+    private fun formatAddress(zipCode: String, address: String, detail: String?) =
+        "($zipCode) $address" + if (detail.isNullOrBlank()) "" else ", $detail"
+
+    private fun invalidRequest() = SodaException(messageKey = "common.error.invalid_request")
+
+    private companion object {
+        const val DEFAULT_PAGE_SIZE = 20
+        val RECIPIENT_VISIBLE_STATUSES = setOf(
+            GiftStatus.TRACKING_REGISTERED,
+            GiftStatus.ARRIVED_AT_MAILBOX,
+            GiftStatus.INSPECTION_COMPLETED,
+            GiftStatus.DELIVERED,
+            GiftStatus.UNDELIVERABLE
+        )
+        val NORMAL_PROGRESS_STATUSES = listOf(
+            GiftStatus.RECEIVED,
+            GiftStatus.TRACKING_REGISTERED,
+            GiftStatus.ARRIVED_AT_MAILBOX,
+            GiftStatus.INSPECTION_COMPLETED,
+            GiftStatus.DELIVERED
+        )
+        val TERMINAL_STATUSES = setOf(GiftStatus.DELIVERED, GiftStatus.UNDELIVERABLE, GiftStatus.CANCELED)
+    }
+}

src/main/kotlin/kr/co/vividnext/sodalive/v2/gift/domain/GiftListType.kt

@@ -0,0 +1,12 @@
+package kr.co.vividnext.sodalive.v2.gift.domain
+
+enum class GiftListType {
+    ALL,
+    SENT,
+    RECEIVED
+}
+
+enum class GiftDirection {
+    SENT,
+    RECEIVED
+}

src/main/kotlin/kr/co/vividnext/sodalive/v2/gift/domain/GiftSize.kt

@@ -0,0 +1,12 @@
+package kr.co.vividnext.sodalive.v2.gift.domain
+
+enum class GiftSize(
+    val displayName: String,
+    val maxTotalLengthCm: Int,
+    val maxWeightKg: Int,
+    val defaultPriceCan: Int
+) {
+    SMALL("소형", 100, 5, 100),
+    MEDIUM("중형", 120, 15, 150),
+    LARGE("대형", 160, 20, 200)
+}

src/main/kotlin/kr/co/vividnext/sodalive/v2/gift/domain/GiftStatus.kt

@@ -0,0 +1,11 @@
+package kr.co.vividnext.sodalive.v2.gift.domain
+
+enum class GiftStatus(val displayName: String) {
+    RECEIVED("접수 완료"),
+    TRACKING_REGISTERED("발송 확인"),
+    ARRIVED_AT_MAILBOX("사서함 도착"),
+    INSPECTION_COMPLETED("검수 완료"),
+    DELIVERED("전달 완료"),
+    UNDELIVERABLE("전달 불가"),
+    CANCELED("신청 취소")
+}

src/main/kotlin/kr/co/vividnext/sodalive/v2/recommendation/adapter/out/persistence/DefaultHomeRecommendationQueryRepository.kt

@@ -22,7 +22,9 @@ import kr.co.vividnext.sodalive.explorer.profile.creatorCommunity.QCreatorCommun
 import kr.co.vividnext.sodalive.explorer.profile.creatorCommunity.comment.QCreatorCommunityComment.creatorCommunityComment
 import kr.co.vividnext.sodalive.explorer.profile.creatorCommunity.like.QCreatorCommunityLike.creatorCommunityLike
 import kr.co.vividnext.sodalive.i18n.Lang
+import kr.co.vividnext.sodalive.live.room.GenderRestriction
 import kr.co.vividnext.sodalive.live.room.QLiveRoom.liveRoom
+import kr.co.vividnext.sodalive.member.Gender
 import kr.co.vividnext.sodalive.member.MemberKind
 import kr.co.vividnext.sodalive.member.MemberRole
 import kr.co.vividnext.sodalive.member.QMember
@@ -58,7 +60,9 @@ class DefaultHomeRecommendationQueryRepository(
         offset: Long,
         limit: Int,
         memberId: Long?,
-        includeAdultLives: Boolean
+        includeAdultLives: Boolean,
+        isViewerCreator: Boolean,
+        effectiveViewerGender: Gender?
     ): List<HomeLiveRecommendationRecord> {
         return queryFactory
             .select(
@@ -79,6 +83,8 @@ class DefaultHomeRecommendationQueryRepository(
                 liveRoom.channelName.isNotNull,
                 liveRoom.channelName.isNotEmpty,
                 includeAdultLiveCondition(includeAdultLives),
+                genderLiveCondition(memberId, effectiveViewerGender),
+                creatorJoinLiveCondition(memberId, isViewerCreator),
                 notBlockedCreatorCondition(memberId, member.id),
                 member.isActive.isTrue
             )
@@ -1294,6 +1300,21 @@ class DefaultHomeRecommendationQueryRepository(
         return if (includeAdultLives) null else liveRoom.isAdult.isFalse
     }
 
+    private fun genderLiveCondition(viewerId: Long?, effectiveViewerGender: Gender?): BooleanExpression? {
+        if (effectiveViewerGender == null || effectiveViewerGender == Gender.NONE) return null
+        val genderCondition = when (effectiveViewerGender) {
+            Gender.MALE -> liveRoom.genderRestriction.`in`(GenderRestriction.ALL, GenderRestriction.MALE_ONLY)
+            Gender.FEMALE -> liveRoom.genderRestriction.`in`(GenderRestriction.ALL, GenderRestriction.FEMALE_ONLY)
+            Gender.NONE -> return null
+        }
+        return viewerId?.let { genderCondition.or(liveRoom.member.id.eq(it)) } ?: genderCondition
+    }
+
+    private fun creatorJoinLiveCondition(viewerId: Long?, isViewerCreator: Boolean): BooleanExpression? {
+        if (!isViewerCreator || viewerId == null) return null
+        return liveRoom.isAvailableJoinCreator.isTrue.or(liveRoom.member.id.eq(viewerId))
+    }
+
     private fun excludeAiCharacterCondition(excludeCharacterIds: List<Long>): BooleanExpression? {
         return if (excludeCharacterIds.isEmpty()) null else chatCharacter.id.notIn(excludeCharacterIds)
     }

src/main/kotlin/kr/co/vividnext/sodalive/v2/recommendation/application/HomeRecommendationQueryService.kt

@@ -2,6 +2,7 @@ package kr.co.vividnext.sodalive.v2.recommendation.application
 
 import kr.co.vividnext.sodalive.i18n.Lang
 import kr.co.vividnext.sodalive.i18n.LangContext
+import kr.co.vividnext.sodalive.member.Gender
 import kr.co.vividnext.sodalive.v2.common.domain.CreatorActivityType
 import kr.co.vividnext.sodalive.v2.creator.channel.community.translation.application.CreatorCommunityTranslationService
 import kr.co.vividnext.sodalive.v2.recommendation.domain.RecommendationSnapshotWindowPolicy
@@ -41,9 +42,18 @@ class HomeRecommendationQueryService(
         offset: Long = 0,
         limit: Int = DEFAULT_LIVE_LIMIT,
         memberId: Long? = null,
-        includeAdultLives: Boolean = false
+        includeAdultLives: Boolean = false,
+        isViewerCreator: Boolean = false,
+        effectiveViewerGender: Gender? = null
     ): List<HomeLiveRecommendationRecord> {
-        return queryPort.findLiveRecommendations(offset, limit, memberId, includeAdultLives)
+        return queryPort.findLiveRecommendations(
+            offset,
+            limit,
+            memberId,
+            includeAdultLives,
+            isViewerCreator,
+            effectiveViewerGender
+        )
     }
 
     fun findHomeBanners(

src/main/kotlin/kr/co/vividnext/sodalive/v2/recommendation/port/out/HomeRecommendationQueryPort.kt

@@ -1,6 +1,7 @@
 package kr.co.vividnext.sodalive.v2.recommendation.port.out
 
 import kr.co.vividnext.sodalive.i18n.Lang
+import kr.co.vividnext.sodalive.member.Gender
 import kr.co.vividnext.sodalive.v2.common.domain.CreatorActivityType
 import java.time.LocalDateTime
 
@@ -9,7 +10,9 @@ interface HomeRecommendationQueryPort {
         offset: Long = 0,
         limit: Int,
         memberId: Long? = null,
-        includeAdultLives: Boolean = false
+        includeAdultLives: Boolean = false,
+        isViewerCreator: Boolean = false,
+        effectiveViewerGender: Gender? = null
     ): List<HomeLiveRecommendationRecord>
 
     fun findHomeBanners(

src/main/kotlin/kr/co/vividnext/sodalive/v2/usercreatorchat/controller/UserCreatorChatController.kt

@@ -28,7 +28,7 @@ class UserCreatorChatController(
         @RequestBody request: CreateUserCreatorChatRoomRequest
     ) = run {
         if (member == null) throw SodaException(messageKey = "common.error.bad_credentials")
-        ApiResponse.ok(service.createOrGetRoom(member, request.creatorId))
+        ApiResponse.ok(service.createOrGetRoom(member, request.recipientMemberId()))
     }
 
     @GetMapping("/{roomId}/open")

src/main/kotlin/kr/co/vividnext/sodalive/v2/usercreatorchat/dto/UserCreatorChatDtos.kt

@@ -1,8 +1,18 @@
 package kr.co.vividnext.sodalive.v2.usercreatorchat.dto
 
+import kr.co.vividnext.sodalive.common.SodaException
+
 data class CreateUserCreatorChatRoomRequest(
-    val creatorId: Long
-)
+    val recipientId: Long? = null,
+    val creatorId: Long? = null
+) {
+    fun recipientMemberId(): Long {
+        if (recipientId != null && creatorId != null && recipientId != creatorId) {
+            throw SodaException(messageKey = "common.error.invalid_request")
+        }
+        return recipientId ?: creatorId ?: throw SodaException(messageKey = "common.error.invalid_request")
+    }
+}
 
 data class CreateUserCreatorChatRoomResponse(
     val roomId: Long

src/main/kotlin/kr/co/vividnext/sodalive/v2/usercreatorchat/service/UserCreatorChatService.kt

@@ -59,20 +59,20 @@ class UserCreatorChatService(
     private val cloudFrontHost: String
 ) {
     @Transactional
-    fun createOrGetRoom(member: Member, creatorId: Long): CreateUserCreatorChatRoomResponse {
-        val creator = memberRepository.findById(creatorId).orElseThrow {
+    fun createOrGetRoom(member: Member, recipientId: Long): CreateUserCreatorChatRoomResponse {
+        val recipient = memberRepository.findById(recipientId).orElseThrow {
             SodaException(messageKey = "message.error.recipient_not_found")
         }
-        validateRecipient(member, creator)
+        validateRecipient(member, recipient)
 
-        val existingRoom = roomRepository.findActiveRoomByParticipantMemberIds(member.id!!, creator.id!!)
+        val existingRoom = roomRepository.findActiveRoomByParticipantMemberIds(member.id!!, recipient.id!!)
         if (existingRoom != null) {
             return CreateUserCreatorChatRoomResponse(roomId = existingRoom.id!!)
         }
 
         val room = roomRepository.save(UserCreatorChatRoom())
         participantRepository.save(UserCreatorChatParticipant(room, member))
-        participantRepository.save(UserCreatorChatParticipant(room, creator))
+        participantRepository.save(UserCreatorChatParticipant(room, recipient))
         return CreateUserCreatorChatRoomResponse(roomId = room.id!!)
     }
 

src/main/resources/application.yml

@@ -1,8 +1,28 @@
 server:
+    port: 8080
     shutdown: graceful
     env: ${SERVER_ENV}
     forward-headers-strategy: framework
 
+management:
+    server:
+        port: 8082
+    endpoints:
+        web:
+            exposure:
+                include: health,deployment
+    endpoint:
+        health:
+            probes:
+                enabled: true
+                add-additional-paths: true
+            show-details: never
+            show-components: never
+
+deployment:
+    artifact-version: ${DEPLOY_ARTIFACT_VERSION:local}
+    config-commit: ${DEPLOY_CONFIG_COMMIT:0000000000000000000000000000000000000000}
+
 logging:
     level:
         com:

src/test/kotlin/kr/co/vividnext/sodalive/can/CanControllerIntegrationTest.kt

@@ -0,0 +1,78 @@
+package kr.co.vividnext.sodalive.can
+
+import kr.co.vividnext.sodalive.common.CountryContext
+import kr.co.vividnext.sodalive.member.Member
+import kr.co.vividnext.sodalive.support.EmbeddedRedisInitializer
+import org.junit.jupiter.api.Assertions.assertEquals
+import org.junit.jupiter.api.BeforeEach
+import org.junit.jupiter.api.DisplayName
+import org.junit.jupiter.params.ParameterizedTest
+import org.junit.jupiter.params.provider.CsvSource
+import org.springframework.beans.factory.annotation.Autowired
+import org.springframework.boot.test.context.SpringBootTest
+import org.springframework.test.annotation.DirtiesContext
+import org.springframework.test.context.ContextConfiguration
+import org.springframework.transaction.annotation.Transactional
+import java.math.BigDecimal
+import javax.persistence.EntityManager
+
+@SpringBootTest(properties = ["spring.cache.type=none"])
+@ContextConfiguration(initializers = [EmbeddedRedisInitializer::class])
+@DirtiesContext(classMode = DirtiesContext.ClassMode.AFTER_CLASS)
+@Transactional
+class CanControllerIntegrationTest @Autowired constructor(
+    private val controller: CanController,
+    private val countryContext: CountryContext,
+    private val entityManager: EntityManager
+) {
+    @BeforeEach
+    fun setUp() {
+        listOf("KRW", "USD", "JPY").forEach { currency ->
+            entityManager.persist(
+                Can(
+                    title = "test-$currency",
+                    can = 100,
+                    rewardCan = 0,
+                    price = BigDecimal("100"),
+                    currency = currency,
+                    status = CanStatus.SALE
+                )
+            )
+        }
+        entityManager.flush()
+        entityManager.clear()
+    }
+
+    @ParameterizedTest
+    @CsvSource(
+        "2, KR, KRW",
+        "2, US, USD",
+        "2, JP, USD",
+        "2, , USD",
+        "4, KR, JPY",
+        "4, US, JPY",
+        "44144, KR, JPY",
+        "44144, US, JPY",
+        "3, KR, KRW",
+        "3, US, USD",
+        ", KR, KRW",
+        ", US, USD",
+        ", , USD"
+    )
+    @DisplayName("회원 2는 국가별 통화를 사용하고 기존 JPY 예외와 일반·비로그인 조회는 유지한다")
+    fun shouldSelectCurrencyByCountryExceptRemainingForcedMembers(
+        memberId: Long?,
+        countryCode: String?,
+        expectedCurrency: String
+    ) {
+        val member = memberId?.let { id ->
+            Member(nickname = "test-$id", password = "").apply { this.id = id }
+        }
+        countryContext.setCountryCode(countryCode)
+
+        val response = controller.getCans(member)
+
+        assertEquals(true, response.success)
+        assertEquals(listOf(expectedCurrency), response.data?.map { it.currency })
+    }
+}

src/test/kotlin/kr/co/vividnext/sodalive/content/AudioContentServiceTest.kt

@@ -23,6 +23,7 @@ import kr.co.vividnext.sodalive.i18n.translation.ResourceTranslationJobScheduler
 import kr.co.vividnext.sodalive.member.Member
 import kr.co.vividnext.sodalive.member.MemberRepository
 import kr.co.vividnext.sodalive.member.block.BlockMemberRepository
+import kr.co.vividnext.sodalive.member.contentpreference.MemberContentPreferenceService
 import kr.co.vividnext.sodalive.v2.home.following.application.HomeFollowingNewsPublishService
 import kr.co.vividnext.sodalive.v2.recommendation.application.CreatorContentViewHistoryService
 import org.junit.jupiter.api.Assertions.assertEquals
@@ -63,6 +64,7 @@ class AudioContentServiceTest {
     private lateinit var applicationEventPublisher: ApplicationEventPublisher
     private lateinit var contentThemeTranslationRepository: ContentThemeTranslationRepository
     private lateinit var homeFollowingNewsPublishService: HomeFollowingNewsPublishService
+    private lateinit var memberContentPreferenceService: MemberContentPreferenceService
 
     private lateinit var service: AudioContentService
 
@@ -88,6 +90,7 @@ class AudioContentServiceTest {
         applicationEventPublisher = Mockito.mock(ApplicationEventPublisher::class.java)
         contentThemeTranslationRepository = Mockito.mock(ContentThemeTranslationRepository::class.java)
         homeFollowingNewsPublishService = Mockito.mock(HomeFollowingNewsPublishService::class.java)
+        memberContentPreferenceService = Mockito.mock(MemberContentPreferenceService::class.java)
 
         service = AudioContentService(
             repository = repository,
@@ -113,6 +116,7 @@ class AudioContentServiceTest {
             langContext = LangContext(),
             contentThemeTranslationRepository = contentThemeTranslationRepository,
             homeFollowingNewsPublishService = homeFollowingNewsPublishService,
+            memberContentPreferenceService = memberContentPreferenceService,
             audioContentBucket = "audio-bucket",
             coverImageBucket = "cover-bucket",
             coverImageHost = "https://cdn.test"

src/test/kotlin/kr/co/vividnext/sodalive/deployment/DeploymentEndpointInjectedValueIntegrationTest.kt

@@ -0,0 +1,50 @@
+package kr.co.vividnext.sodalive.deployment
+
+import kr.co.vividnext.sodalive.support.EmbeddedRedisInitializer
+import org.junit.jupiter.api.Assertions.assertEquals
+import org.junit.jupiter.api.DisplayName
+import org.junit.jupiter.api.Test
+import org.springframework.beans.factory.annotation.Autowired
+import org.springframework.boot.test.context.SpringBootTest
+import org.springframework.boot.test.web.client.TestRestTemplate
+import org.springframework.boot.test.web.server.LocalManagementPort
+import org.springframework.http.HttpStatus
+import org.springframework.test.annotation.DirtiesContext
+import org.springframework.test.context.ContextConfiguration
+
+@SpringBootTest(
+    webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT,
+    properties = [
+        "management.server.port=0",
+        "deployment.artifact-version=1.2.3-20260914",
+        "deployment.config-commit=1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d",
+        "spring.datasource.url=jdbc:h2:mem:deployment-endpoint-injected-integration;" +
+            "MODE=MySQL;DATABASE_TO_UPPER=false;NON_KEYWORDS=VALUE;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE"
+    ]
+)
+@ContextConfiguration(initializers = [EmbeddedRedisInitializer::class])
+@DirtiesContext(classMode = DirtiesContext.ClassMode.AFTER_CLASS)
+class DeploymentEndpointInjectedValueIntegrationTest @Autowired constructor(
+    private val restTemplate: TestRestTemplate
+) {
+    @LocalManagementPort
+    private var managementPort: Int = 0
+
+    @Test
+    @DisplayName("배포 식별자가 주입되면 /actuator/deployment는 주입된 값을 반환한다")
+    fun shouldReturnInjectedDeploymentIdentity() {
+        val response = restTemplate.getForEntity(
+            "http://localhost:$managementPort/actuator/deployment",
+            Map::class.java
+        )
+
+        assertEquals(HttpStatus.OK, response.statusCode)
+        assertEquals(
+            mapOf(
+                "application_artifact_version" to "1.2.3-20260914",
+                "config_commit" to "1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d"
+            ),
+            response.body
+        )
+    }
+}

src/test/kotlin/kr/co/vividnext/sodalive/deployment/DeploymentEndpointIntegrationTest.kt

@@ -0,0 +1,85 @@
+package kr.co.vividnext.sodalive.deployment
+
+import kr.co.vividnext.sodalive.support.EmbeddedRedisInitializer
+import org.junit.jupiter.api.Assertions.assertEquals
+import org.junit.jupiter.api.Assertions.assertFalse
+import org.junit.jupiter.api.Assertions.assertNotEquals
+import org.junit.jupiter.api.DisplayName
+import org.junit.jupiter.api.Test
+import org.springframework.beans.factory.annotation.Autowired
+import org.springframework.boot.test.context.SpringBootTest
+import org.springframework.boot.test.web.client.TestRestTemplate
+import org.springframework.boot.test.web.server.LocalManagementPort
+import org.springframework.boot.test.web.server.LocalServerPort
+import org.springframework.http.HttpStatus
+import org.springframework.test.annotation.DirtiesContext
+import org.springframework.test.context.ContextConfiguration
+
+@SpringBootTest(
+    webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT,
+    properties = [
+        "management.server.port=0",
+        "spring.datasource.url=jdbc:h2:mem:deployment-endpoint-integration;" +
+            "MODE=MySQL;DATABASE_TO_UPPER=false;NON_KEYWORDS=VALUE;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE"
+    ]
+)
+@ContextConfiguration(initializers = [EmbeddedRedisInitializer::class])
+@DirtiesContext(classMode = DirtiesContext.ClassMode.AFTER_CLASS)
+class DeploymentEndpointIntegrationTest @Autowired constructor(
+    private val restTemplate: TestRestTemplate
+) {
+    @LocalServerPort
+    private var serverPort: Int = 0
+
+    @LocalManagementPort
+    private var managementPort: Int = 0
+
+    @Test
+    @DisplayName("애플리케이션 포트의 /readyz는 인증 없이 200을 반환한다")
+    fun shouldReturnOkWhenReadyzIsCalledOnServerPort() {
+        val response = restTemplate.getForEntity("http://localhost:$serverPort/readyz", String::class.java)
+
+        assertEquals(HttpStatus.OK, response.statusCode)
+    }
+
+    @Test
+    @DisplayName("management 포트의 /actuator/health/readiness는 인증 없이 200을 반환한다")
+    fun shouldReturnOkWhenReadinessProbeIsCalledOnManagementPort() {
+        val response = restTemplate.getForEntity(
+            "http://localhost:$managementPort/actuator/health/readiness",
+            String::class.java
+        )
+
+        assertEquals(HttpStatus.OK, response.statusCode)
+    }
+
+    @Test
+    @DisplayName("환경변수가 없으면 /actuator/deployment는 기본 배포 식별자를 snake_case로 반환한다")
+    fun shouldReturnDefaultDeploymentIdentityWhenEnvironmentVariablesAreNotProvided() {
+        val response = restTemplate.getForEntity(
+            "http://localhost:$managementPort/actuator/deployment",
+            Map::class.java
+        )
+
+        assertEquals(HttpStatus.OK, response.statusCode)
+        assertEquals(
+            mapOf(
+                "application_artifact_version" to "local",
+                "config_commit" to "0000000000000000000000000000000000000000"
+            ),
+            response.body
+        )
+    }
+
+    @Test
+    @DisplayName("애플리케이션 포트에서는 /actuator/deployment에 접근할 수 없다")
+    fun shouldNotExposeDeploymentEndpointOnServerPort() {
+        val response = restTemplate.getForEntity(
+            "http://localhost:$serverPort/actuator/deployment",
+            String::class.java
+        )
+
+        assertNotEquals(HttpStatus.OK, response.statusCode)
+        assertFalse(response.body?.contains("application_artifact_version") ?: false)
+    }
+}

src/test/kotlin/kr/co/vividnext/sodalive/live/room/LiveRoomServiceTest.kt

@@ -0,0 +1,429 @@
+package kr.co.vividnext.sodalive.live.room
+
+import com.fasterxml.jackson.databind.ObjectMapper
+import kr.co.vividnext.sodalive.agora.RtcTokenBuilder
+import kr.co.vividnext.sodalive.agora.RtmTokenBuilder
+import kr.co.vividnext.sodalive.aws.s3.S3Uploader
+import kr.co.vividnext.sodalive.can.CanRepository
+import kr.co.vividnext.sodalive.can.charge.ChargeRepository
+import kr.co.vividnext.sodalive.can.payment.CanPaymentService
+import kr.co.vividnext.sodalive.can.use.UseCanCalculateRepository
+import kr.co.vividnext.sodalive.common.SodaException
+import kr.co.vividnext.sodalive.explorer.ExplorerQueryRepository
+import kr.co.vividnext.sodalive.explorer.profile.CreatorDonationRankingService
+import kr.co.vividnext.sodalive.fcm.PushTokenRepository
+import kr.co.vividnext.sodalive.i18n.LangContext
+import kr.co.vividnext.sodalive.i18n.SodaMessageSource
+import kr.co.vividnext.sodalive.live.reservation.LiveReservationRepository
+import kr.co.vividnext.sodalive.live.room.cancel.LiveRoomCancelRepository
+import kr.co.vividnext.sodalive.live.room.info.LiveRoomInfo
+import kr.co.vividnext.sodalive.live.room.info.LiveRoomInfoRedisRepository
+import kr.co.vividnext.sodalive.live.room.kickout.LiveRoomKickOutService
+import kr.co.vividnext.sodalive.live.room.menu.LiveRoomMenuService
+import kr.co.vividnext.sodalive.live.room.visit.LiveRoomVisitService
+import kr.co.vividnext.sodalive.live.roulette.NewRouletteRepository
+import kr.co.vividnext.sodalive.live.signature.SignatureCanRepository
+import kr.co.vividnext.sodalive.live.tag.LiveTagRepository
+import kr.co.vividnext.sodalive.member.Gender
+import kr.co.vividnext.sodalive.member.Member
+import kr.co.vividnext.sodalive.member.MemberRepository
+import kr.co.vividnext.sodalive.member.MemberRole
+import kr.co.vividnext.sodalive.member.auth.Auth
+import kr.co.vividnext.sodalive.member.block.BlockMemberRepository
+import kr.co.vividnext.sodalive.member.contentpreference.MemberContentPreferenceService
+import org.junit.jupiter.api.Assertions.assertEquals
+import org.junit.jupiter.api.BeforeEach
+import org.junit.jupiter.api.DisplayName
+import org.junit.jupiter.api.Test
+import org.junit.jupiter.api.assertThrows
+import org.mockito.Mockito
+import java.time.LocalDateTime
+import java.util.Optional
+
+class LiveRoomServiceTest {
+    private lateinit var repository: LiveRoomRepository
+    private lateinit var roomInfoRepository: LiveRoomInfoRedisRepository
+    private lateinit var canPaymentService: CanPaymentService
+    private lateinit var memberRepository: MemberRepository
+    private lateinit var blockMemberRepository: BlockMemberRepository
+    private lateinit var explorerQueryRepository: ExplorerQueryRepository
+    private lateinit var rouletteRepository: NewRouletteRepository
+    private lateinit var pushTokenRepository: PushTokenRepository
+    private lateinit var rtcTokenBuilder: RtcTokenBuilder
+    private lateinit var rtmTokenBuilder: RtmTokenBuilder
+    private lateinit var service: LiveRoomService
+
+    @BeforeEach
+    fun setup() {
+        repository = mock()
+        roomInfoRepository = mock()
+        canPaymentService = mock()
+        memberRepository = mock()
+        blockMemberRepository = mock()
+        explorerQueryRepository = mock()
+        rouletteRepository = mock()
+        pushTokenRepository = mock()
+        rtcTokenBuilder = mock()
+        rtmTokenBuilder = mock()
+
+        service = LiveRoomService(
+            menuService = mock<LiveRoomMenuService>(),
+            messageSource = mock<SodaMessageSource>(),
+            langContext = LangContext(),
+            repository = repository,
+            rouletteRepository = rouletteRepository,
+            roomInfoRepository = roomInfoRepository,
+            roomCancelRepository = mock<LiveRoomCancelRepository>(),
+            kickOutService = mock<LiveRoomKickOutService>(),
+            blockMemberRepository = blockMemberRepository,
+            signatureCanRepository = mock<SignatureCanRepository>(),
+            applicationEventPublisher = mock(),
+            useCanCalculateRepository = mock<UseCanCalculateRepository>(),
+            reservationRepository = mock<LiveReservationRepository>(),
+            explorerQueryRepository = explorerQueryRepository,
+            creatorDonationRankingService = mock<CreatorDonationRankingService>(),
+            roomVisitService = mock<LiveRoomVisitService>(),
+            canPaymentService = canPaymentService,
+            chargeRepository = mock<ChargeRepository>(),
+            pushTokenRepository = pushTokenRepository,
+            memberRepository = memberRepository,
+            tagRepository = mock<LiveTagRepository>(),
+            memberContentPreferenceService = mock<MemberContentPreferenceService>(),
+            canRepository = mock<CanRepository>(),
+            objectMapper = ObjectMapper(),
+            s3Uploader = mock<S3Uploader>(),
+            rtcTokenBuilder = rtcTokenBuilder,
+            rtmTokenBuilder = rtmTokenBuilder,
+            agoraAppId = "test-agora-app-id",
+            agoraAppCertificate = "test-agora-app-certificate",
+            coverImageBucket = "test-cover-image-bucket",
+            cloudFrontHost = "https://test-cloudfront-host"
+        )
+    }
+
+    @Test
+    @DisplayName("다른 크리에이터는 크리에이터 입장 제한 방에 입장할 수 없다")
+    fun shouldRejectDifferentCreatorBeforePaymentOrRoomInfoMutation() {
+        val owner = createMember(id = 1L, role = MemberRole.CREATOR)
+        val enteringCreator = createMember(id = 2L, role = MemberRole.CREATOR).also { it.pgChargeCan = 10 }
+        val room = createRoom(owner = owner, price = 10)
+        prepareAllowedEntry(room)
+        Mockito.`when`(memberRepository.findById(enteringCreator.id!!)).thenReturn(Optional.of(enteringCreator))
+
+        val exception = assertThrows<SodaException> {
+            service.enterLive(EnterOrQuitLiveRoomRequest(roomId = room.id!!, container = "web"), enteringCreator)
+        }
+
+        assertEquals("live.room.not_found", exception.messageKey)
+        Mockito.verifyNoInteractions(roomInfoRepository, canPaymentService)
+    }
+
+    @Test
+    @DisplayName("성별 제한에 맞지 않는 일반 사용자는 입장할 수 없다")
+    fun shouldRejectGenderMismatchedUserBeforePaymentOrRoomInfoMutation() {
+        val owner = createMember(id = 1L, role = MemberRole.CREATOR)
+        val member = createMember(id = 2L, gender = Gender.FEMALE)
+        val room = createRoom(owner = owner, price = 10, genderRestriction = GenderRestriction.MALE_ONLY)
+        Mockito.`when`(repository.getLiveRoom(room.id!!)).thenReturn(room)
+
+        val exception = assertThrows<SodaException> {
+            service.enterLive(EnterOrQuitLiveRoomRequest(roomId = room.id!!, container = "web"), member)
+        }
+
+        assertEquals("live.room.gender_restricted", exception.messageKey)
+        Mockito.verifyNoInteractions(roomInfoRepository, canPaymentService)
+    }
+
+    @Test
+    @DisplayName("방 생성자는 크리에이터 및 성별 제한과 무관하게 입장할 수 있다")
+    fun shouldAllowRoomOwner() {
+        val owner = createMember(id = 1L, role = MemberRole.CREATOR, gender = Gender.MALE)
+        val room = createRoom(owner = owner, genderRestriction = GenderRestriction.FEMALE_ONLY)
+        val roomInfo = prepareAllowedEntry(room)
+
+        service.enterLive(EnterOrQuitLiveRoomRequest(roomId = room.id!!, container = "web"), owner)
+
+        assertEquals(1, roomInfo.speakerCount)
+        Mockito.verify(roomInfoRepository).save(roomInfo)
+    }
+
+    @Test
+    @DisplayName("일반 사용자는 조건에 맞으면 크리에이터 입장 제한 방에 입장할 수 있다")
+    fun shouldAllowEligibleUser() {
+        val owner = createMember(id = 1L, role = MemberRole.CREATOR)
+        val member = createMember(id = 2L, gender = Gender.MALE)
+        val room = createRoom(owner = owner, genderRestriction = GenderRestriction.MALE_ONLY)
+        val roomInfo = prepareAllowedEntry(room)
+
+        service.enterLive(EnterOrQuitLiveRoomRequest(roomId = room.id!!, container = "web"), member)
+
+        assertEquals(1, roomInfo.listenerCount)
+        Mockito.verify(roomInfoRepository).save(roomInfo)
+    }
+
+    @Test
+    @DisplayName("성별 미설정 사용자는 기존 성별 제한 정책대로 입장할 수 있다")
+    fun shouldAllowUserWithNoGender() {
+        val owner = createMember(id = 1L, role = MemberRole.CREATOR)
+        val member = createMember(id = 2L, gender = Gender.NONE)
+        val room = createRoom(owner = owner, genderRestriction = GenderRestriction.MALE_ONLY)
+        val roomInfo = prepareAllowedEntry(room)
+
+        service.enterLive(EnterOrQuitLiveRoomRequest(roomId = room.id!!, container = "web"), member)
+
+        assertEquals(1, roomInfo.listenerCount)
+        Mockito.verify(roomInfoRepository).save(roomInfo)
+    }
+
+    @Test
+    @DisplayName("다른 크리에이터는 제한 방 정보 조회로 토큰을 발급받을 수 없다")
+    fun shouldRejectDifferentCreatorFromRoomInfoBeforeTokenGeneration() {
+        val owner = createMember(id = 1L, role = MemberRole.CREATOR)
+        val viewer = createMember(id = 2L, role = MemberRole.CREATOR)
+        val room = createRoom(owner = owner)
+        prepareSuccessfulRoomInfo(room)
+
+        val exception = assertThrows<SodaException> {
+            service.getRoomInfo(roomId = room.id!!, member = viewer)
+        }
+
+        assertEquals("live.room.not_found", exception.messageKey)
+        Mockito.verifyNoInteractions(rtcTokenBuilder, rtmTokenBuilder)
+    }
+
+    @Test
+    @DisplayName("성별 제한에 맞지 않는 사용자는 방 정보 조회로 토큰을 발급받을 수 없다")
+    fun shouldRejectGenderMismatchedNonOwnerFromRoomInfoBeforeTokenGeneration() {
+        val owner = createMember(id = 1L, role = MemberRole.CREATOR)
+        val viewer = createMember(id = 2L, gender = Gender.FEMALE)
+        val room = createRoom(owner = owner, genderRestriction = GenderRestriction.MALE_ONLY)
+        prepareSuccessfulRoomInfo(room)
+
+        val exception = assertThrows<SodaException> {
+            service.getRoomInfo(roomId = room.id!!, member = viewer)
+        }
+
+        assertEquals("live.room.gender_restricted", exception.messageKey)
+        Mockito.verifyNoInteractions(rtcTokenBuilder, rtmTokenBuilder)
+    }
+
+    @Test
+    @DisplayName("크리에이터와 성별 제한이 함께 적용되면 크리에이터 제한을 먼저 반환한다")
+    fun shouldPrioritizeCreatorRestrictionOverGenderRestrictionInRoomInfo() {
+        val owner = createMember(id = 1L, role = MemberRole.CREATOR)
+        val viewer = createMember(id = 2L, role = MemberRole.CREATOR, gender = Gender.FEMALE)
+        val room = createRoom(owner = owner, genderRestriction = GenderRestriction.MALE_ONLY)
+        prepareSuccessfulRoomInfo(room)
+
+        val exception = assertThrows<SodaException> {
+            service.getRoomInfo(roomId = room.id!!, member = viewer)
+        }
+
+        assertEquals("live.room.not_found", exception.messageKey)
+        Mockito.verifyNoInteractions(rtcTokenBuilder, rtmTokenBuilder)
+    }
+
+    @Test
+    @DisplayName("입장 거절 뒤 같은 제한 방 정보 조회도 토큰을 발급하지 않는다")
+    fun shouldNotGenerateTokensAfterEnterLiveRejectsDifferentCreator() {
+        val owner = createMember(id = 1L, role = MemberRole.CREATOR)
+        val viewer = createMember(id = 2L, role = MemberRole.CREATOR)
+        val room = createRoom(owner = owner)
+        prepareSuccessfulRoomInfo(room)
+        Mockito.`when`(repository.getLiveRoom(room.id!!)).thenReturn(room)
+
+        val enterException = assertThrows<SodaException> {
+            service.enterLive(EnterOrQuitLiveRoomRequest(roomId = room.id!!, container = "web"), viewer)
+        }
+        val roomInfoException = assertThrows<SodaException> {
+            service.getRoomInfo(roomId = room.id!!, member = viewer)
+        }
+
+        assertEquals("live.room.not_found", enterException.messageKey)
+        assertEquals("live.room.not_found", roomInfoException.messageKey)
+        Mockito.verifyNoInteractions(rtcTokenBuilder, rtmTokenBuilder)
+    }
+
+    @Test
+    @DisplayName("방 생성자는 모든 크리에이터와 성별 제한이 있어도 방 정보 토큰을 발급받는다")
+    fun shouldAllowRoomOwnerToGetRoomInfoTokens() {
+        val owner = createMember(id = 1L, role = MemberRole.CREATOR, gender = Gender.MALE)
+        val room = createRoom(owner = owner, genderRestriction = GenderRestriction.FEMALE_ONLY)
+        prepareSuccessfulRoomInfo(room)
+
+        assertTokenizedRoomInfo(room, owner)
+    }
+
+    @Test
+    @DisplayName("성별이 맞는 일반 사용자는 제한 방 정보 토큰을 발급받는다")
+    fun shouldAllowGenderMatchedUserToGetRoomInfoTokens() {
+        val owner = createMember(id = 1L, role = MemberRole.CREATOR)
+        val viewer = createMember(id = 2L, gender = Gender.MALE)
+        val room = createRoom(owner = owner, genderRestriction = GenderRestriction.MALE_ONLY)
+        prepareSuccessfulRoomInfo(room)
+
+        assertTokenizedRoomInfo(room, viewer)
+    }
+
+    @Test
+    @DisplayName("크리에이터 입장이 허용된 다른 크리에이터는 방 정보 토큰을 발급받는다")
+    fun shouldAllowDifferentCreatorWhenCreatorJoiningIsEnabledToGetRoomInfoTokens() {
+        val owner = createMember(id = 1L, role = MemberRole.CREATOR)
+        val viewer = createMember(id = 2L, role = MemberRole.CREATOR, gender = Gender.MALE)
+        val room = createRoom(
+            owner = owner,
+            isAvailableJoinCreator = true,
+            genderRestriction = GenderRestriction.MALE_ONLY
+        )
+        prepareSuccessfulRoomInfo(room)
+
+        assertTokenizedRoomInfo(room, viewer)
+    }
+
+    @Test
+    @DisplayName("인증 성별은 프로필 성별보다 우선하여 방 정보 제한을 판정한다")
+    fun shouldUseAuthGenderBeforeProfileGenderForRoomInfoTokens() {
+        val owner = createMember(id = 1L, role = MemberRole.CREATOR)
+        val viewer = createMember(id = 2L, gender = Gender.MALE)
+        viewer.auth = Auth(
+            name = "viewer",
+            birth = "20000101",
+            uniqueCi = "unique-ci",
+            di = "di",
+            gender = 2
+        )
+        val room = createRoom(owner = owner, genderRestriction = GenderRestriction.FEMALE_ONLY)
+        prepareSuccessfulRoomInfo(room)
+
+        assertTokenizedRoomInfo(room, viewer)
+    }
+
+    @Test
+    @DisplayName("성별 미설정 사용자는 기존 정책대로 방 정보 토큰을 발급받는다")
+    fun shouldAllowUserWithNoGenderToGetRoomInfoTokens() {
+        val owner = createMember(id = 1L, role = MemberRole.CREATOR)
+        val viewer = createMember(id = 2L, gender = Gender.NONE)
+        val room = createRoom(owner = owner, genderRestriction = GenderRestriction.MALE_ONLY)
+        prepareSuccessfulRoomInfo(room)
+
+        assertTokenizedRoomInfo(room, viewer)
+    }
+
+    @Test
+    @DisplayName("상호 차단된 사용자는 기존 방 정보 예외로 토큰을 발급받을 수 없다")
+    fun shouldRejectMutuallyBlockedUserFromRoomInfoBeforeTokenGeneration() {
+        val owner = createMember(id = 1L, role = MemberRole.CREATOR)
+        val viewer = createMember(id = 2L, gender = Gender.MALE)
+        val room = createRoom(owner = owner, genderRestriction = GenderRestriction.MALE_ONLY)
+        prepareSuccessfulRoomInfo(room)
+        Mockito.`when`(blockMemberRepository.isBlocked(Mockito.anyLong(), Mockito.anyLong())).thenReturn(true)
+
+        val exception = assertThrows<SodaException> {
+            service.getRoomInfo(roomId = room.id!!, member = viewer)
+        }
+
+        assertEquals("live.room.info_not_found", exception.messageKey)
+        Mockito.verifyNoInteractions(rtcTokenBuilder, rtmTokenBuilder)
+    }
+
+    private fun prepareAllowedEntry(room: LiveRoom): LiveRoomInfo {
+        val roomInfo = LiveRoomInfo(roomId = room.id!!)
+        Mockito.`when`(repository.getLiveRoom(room.id!!)).thenReturn(room)
+        Mockito.`when`(roomInfoRepository.findById(room.id!!)).thenReturn(Optional.of(roomInfo))
+        Mockito.`when`(roomInfoRepository.save(roomInfo)).thenReturn(roomInfo)
+        return roomInfo
+    }
+
+    private fun prepareSuccessfulRoomInfo(room: LiveRoom): LiveRoomInfo {
+        val roomInfo = LiveRoomInfo(roomId = room.id!!)
+        room.member!!.isVisibleDonationRank = false
+        room.channelName = "SODA_LIVE_CHANNEL_TEST"
+
+        Mockito.`when`(roomInfoRepository.findById(room.id!!)).thenReturn(Optional.of(roomInfo))
+        Mockito.`when`(repository.findById(room.id!!)).thenReturn(Optional.of(room))
+        Mockito.`when`(blockMemberRepository.isBlocked(Mockito.anyLong(), Mockito.anyLong())).thenReturn(false)
+        Mockito.`when`(
+            rtcTokenBuilder.buildTokenWithUid(
+                Mockito.anyString(),
+                Mockito.anyString(),
+                Mockito.anyString(),
+                Mockito.anyString(),
+                Mockito.anyInt()
+            )
+        ).thenReturn("rtc-token")
+        Mockito.`when`(
+            rtmTokenBuilder.buildToken(
+                Mockito.anyString(),
+                Mockito.anyString(),
+                Mockito.anyString(),
+                Mockito.anyInt()
+            )
+        ).thenReturn("rtm-token")
+        Mockito.`when`(explorerQueryRepository.getNotificationUserIds(room.member!!.id!!)).thenReturn(emptyList())
+        Mockito.`when`(rouletteRepository.findByCreatorId(room.member!!.id!!)).thenReturn(emptyList())
+        Mockito.`when`(pushTokenRepository.findByMemberId(room.member!!.id!!)).thenReturn(emptyList())
+        return roomInfo
+    }
+
+    private fun assertTokenizedRoomInfo(room: LiveRoom, member: Member) {
+        val response = service.getRoomInfo(roomId = room.id!!, member = member)
+
+        assertEquals(room.channelName, response.channelName)
+        assertEquals("rtc-token", response.rtcToken)
+        assertEquals("rtm-token", response.rtmToken)
+        assertEquals("rtc-token", response.v2vWorkerToken)
+        Mockito.verify(rtcTokenBuilder, Mockito.times(2)).buildTokenWithUid(
+            Mockito.anyString(),
+            Mockito.anyString(),
+            Mockito.anyString(),
+            Mockito.anyString(),
+            Mockito.anyInt()
+        )
+        Mockito.verify(rtmTokenBuilder).buildToken(
+            Mockito.anyString(),
+            Mockito.anyString(),
+            Mockito.anyString(),
+            Mockito.anyInt()
+        )
+    }
+
+    private fun createRoom(
+        owner: Member,
+        price: Int = 0,
+        isAvailableJoinCreator: Boolean = false,
+        genderRestriction: GenderRestriction = GenderRestriction.ALL
+    ): LiveRoom {
+        return LiveRoom(
+            title = "test room",
+            notice = "test notice",
+            beginDateTime = LocalDateTime.now(),
+            numberOfPeople = 10,
+            coverImage = "cover/image.png",
+            isAdult = false,
+            price = price,
+            isAvailableJoinCreator = isAvailableJoinCreator,
+            genderRestriction = genderRestriction
+        ).also {
+            it.id = 100L
+            it.member = owner
+        }
+    }
+
+    private fun createMember(
+        id: Long,
+        role: MemberRole = MemberRole.USER,
+        gender: Gender = Gender.NONE
+    ): Member {
+        return Member(
+            email = "member$id@test.com",
+            password = "password",
+            nickname = "member$id",
+            gender = gender,
+            role = role
+        ).also { it.id = id }
+    }
+
+    private inline fun <reified T> mock(): T {
+        return Mockito.mock(T::class.java)
+    }
+}

src/test/kotlin/kr/co/vividnext/sodalive/member/contentpreference/MemberContentPreferenceIntegrationTest.kt

@@ -29,7 +29,7 @@ class MemberContentPreferenceIntegrationTest @Autowired constructor(
     private val entityManager: EntityManager
 ) {
     companion object {
-        private val FORCED_MEMBER_IDS = setOf(2L, 16L, 17L, 29721L, 32050L, 37543L, 40850L)
+        private val FORCED_MEMBER_IDS = setOf(16L, 17L, 29721L, 32050L, 37543L, 40850L)
     }
 
     private lateinit var service: MemberContentPreferenceService
@@ -184,7 +184,7 @@ class MemberContentPreferenceIntegrationTest @Autowired constructor(
         countryContext.setCountryCode("US")
 
         val jpMember = Member(email = "jp@test.com", password = "password", nickname = "jp-member")
-            .apply { id = 2L }
+            .apply { id = 29721L }
         val jpMemberNew = Member(email = "jp-new@test.com", password = "password", nickname = "jp-member-new")
             .apply { id = 37543L }
         val krMember = Member(email = "kr@test.com", password = "password", nickname = "kr-member")

src/test/kotlin/kr/co/vividnext/sodalive/member/contentpreference/MemberContentPreferencePolicyTest.kt

@@ -1,89 +0,0 @@
-package kr.co.vividnext.sodalive.member.contentpreference
-
-import kr.co.vividnext.sodalive.member.Member
-import org.junit.jupiter.api.AfterEach
-import org.junit.jupiter.api.Assertions.assertEquals
-import org.junit.jupiter.api.Assertions.assertFalse
-import org.junit.jupiter.api.Assertions.assertTrue
-import org.junit.jupiter.api.DisplayName
-import org.junit.jupiter.api.Test
-import org.springframework.mock.web.MockHttpServletRequest
-import org.springframework.web.context.request.RequestContextHolder
-import org.springframework.web.context.request.ServletRequestAttributes
-
-class MemberContentPreferencePolicyTest {
-    @AfterEach
-    fun cleanup() {
-        RequestContextHolder.resetRequestAttributes()
-    }
-
-    @Test
-    @DisplayName("요청 국가 헤더를 기준으로 국가 코드를 계산한다")
-    fun shouldResolveCountryCodeByRequestHeader() {
-        setRequestCountry(" us ")
-        val member = createMember(id = 200L, countryCode = "KR")
-
-        assertEquals("US", resolveCountryCodeByPolicy(member))
-    }
-
-    @Test
-    @DisplayName("강제 매핑 대상 회원 ID는 요청 국가 헤더보다 우선한다")
-    fun shouldPrioritizeForcedCountryMapping() {
-        setRequestCountry("US")
-
-        val forcedJpMember = createMember(id = 2L, countryCode = "KR")
-        val forcedJpMemberNew = createMember(id = 37543L, countryCode = "KR")
-        val forcedKrMember = createMember(id = 16L, countryCode = "US")
-
-        assertEquals("JP", resolveCountryCodeByPolicy(forcedJpMember))
-        assertEquals("JP", resolveCountryCodeByPolicy(forcedJpMemberNew))
-        assertEquals("KR", resolveCountryCodeByPolicy(forcedKrMember))
-    }
-
-    @Test
-    @DisplayName("요청 국가가 KR이면 인증 미완료 사용자는 성인 노출이 false다")
-    fun shouldHideAdultContentForKrWithoutAuth() {
-        setRequestCountry("KR")
-        val member = createMember(id = 1L, countryCode = "US")
-
-        assertFalse(isAdultVisibleByPolicy(member, isAdultContentVisible = true))
-    }
-
-    @Test
-    @DisplayName("요청 국가가 KR이 아니면 멤버 countryCode와 무관하게 전달값을 사용한다")
-    fun shouldIgnoreStoredCountryCodeWhenRequestCountryIsNotKr() {
-        setRequestCountry("US")
-        val member = createMember(id = 201L, countryCode = "KR")
-
-        assertTrue(isAdultVisibleByPolicy(member, isAdultContentVisible = true))
-    }
-
-    @Test
-    @DisplayName("요청 컨텍스트가 없으면 KR fallback 정책을 사용한다")
-    fun shouldFallbackToKrWhenRequestContextIsMissing() {
-        RequestContextHolder.resetRequestAttributes()
-        val member = createMember(id = 202L, countryCode = "US")
-
-        assertEquals("KR", resolveCountryCodeByPolicy(member))
-        assertFalse(isAdultVisibleByPolicy(member, isAdultContentVisible = true))
-    }
-
-    private fun setRequestCountry(countryCode: String?) {
-        val request = MockHttpServletRequest()
-        if (countryCode != null) {
-            request.addHeader("CloudFront-Viewer-Country", countryCode)
-        }
-        RequestContextHolder.setRequestAttributes(ServletRequestAttributes(request))
-    }
-
-    private fun createMember(id: Long, countryCode: String?): Member {
-        return Member(
-            email = "member$id@test.com",
-            password = "password",
-            nickname = "member$id"
-        ).apply {
-            this.id = id
-            this.countryCode = countryCode
-        }
-    }
-}

src/test/kotlin/kr/co/vividnext/sodalive/member/contentpreference/MemberContentPreferenceServiceTest.kt

@@ -61,10 +61,10 @@ class MemberContentPreferenceServiceTest {
     @Test
     @DisplayName("회원 ID 강제 매핑(JP)이 헤더보다 우선 적용된다")
     fun shouldResolveCountryCodeByForcedJapanMappingFirst() {
-        val member = createMember(id = 2L)
+        val member = createMember(id = 29721L)
         val preference = createPreference(member)
         countryContext.setCountryCode("US")
-        Mockito.`when`(repository.findByMemberId(2L)).thenReturn(preference)
+        Mockito.`when`(repository.findByMemberId(29721L)).thenReturn(preference)
 
         val result = service.getStoredPreference(member)
 
@@ -449,6 +449,58 @@ class MemberContentPreferenceServiceTest {
         assertTrue(service.calculateIsAdultForQuery(noAuthMember, "US", true))
     }
 
+    @Test
+    @DisplayName("로그인 회원의 접속 국가 코드는 공백과 소문자를 정규화하고 없으면 KR로 계산된다")
+    fun shouldNormalizeCountryCodeForLoggedInMember() {
+        val member = createMember(id = 2400L)
+
+        countryContext.setCountryCode(" us ")
+        assertEquals("US", service.resolveCountryCode(member))
+
+        countryContext.setCountryCode(" ")
+        assertEquals("KR", service.resolveCountryCode(member))
+
+        countryContext.setCountryCode(null)
+        assertEquals("KR", service.resolveCountryCode(member))
+    }
+
+    @Test
+    @DisplayName("조회용 성인 노출 여부는 접속 국가와 인증 여부로 계산된다")
+    fun shouldCalculateIsAdultVisibleForQueryByCountryAndAuth() {
+        val noAuthMember = createMember(id = 2300L, withAuth = false)
+        val authMember = createMember(id = 2301L, withAuth = true)
+
+        countryContext.setCountryCode("KR")
+        assertFalse(service.isAdultVisibleForQuery(noAuthMember, isAdultContentVisible = true))
+        assertTrue(service.isAdultVisibleForQuery(authMember, isAdultContentVisible = true))
+
+        countryContext.setCountryCode("US")
+        assertTrue(service.isAdultVisibleForQuery(noAuthMember, isAdultContentVisible = true))
+        assertFalse(service.isAdultVisibleForQuery(authMember, isAdultContentVisible = false))
+    }
+
+    @Test
+    @DisplayName("비KR 요청에서는 회원의 저장 국가와 무관하게 전달한 성인 노출값을 사용한다")
+    fun shouldIgnoreStoredCountryCodeWhenRequestCountryIsNotKr() {
+        val member = createMember(id = 2401L, withAuth = false).apply {
+            countryCode = "KR"
+        }
+        countryContext.setCountryCode("US")
+
+        assertEquals("US", service.resolveCountryCode(member))
+        assertTrue(service.isAdultVisibleForQuery(member, isAdultContentVisible = true))
+        assertFalse(service.isAdultVisibleForQuery(member, isAdultContentVisible = false))
+    }
+
+    @Test
+    @DisplayName("조회용 성인 노출 여부도 회원 ID 강제 매핑이 헤더보다 우선 적용된다")
+    fun shouldApplyForcedCountryMappingForIsAdultVisibleForQuery() {
+        val forcedKrMember = createMember(id = 16L, withAuth = false)
+        countryContext.setCountryCode("US")
+
+        assertFalse(service.isAdultVisibleForQuery(forcedKrMember, isAdultContentVisible = true))
+    }
+
     @Test
     @DisplayName("성인 콘텐츠 조회 가능 여부는 저장 preference의 조회용 성인 정책 결과를 반환한다")
     fun shouldReturnStoredPreferenceAdultPolicyForCanViewAdultContent() {