docs(creator): 채널 홈 API 구조 정렬 계획을 추가한다

docs/20260617_크리에이터_채널_홈_API_구조정렬/prd.md

@@ -0,0 +1,130 @@
+# PRD: 크리에이터 채널 홈 API 구조 정렬
+
+## 1. Overview
+기존 `GET /api/v2/creator-channels/{creatorId}/home` API의 endpoint와 응답 계약을 유지하면서, 공개 API 조립 계층을 `kr.co.vividnext.sodalive.v2.api.creator.channel.home`으로 옮기고 재사용 가능한 조회/정책/port/repository 책임을 API 패키지 밖 도메인 패키지로 정렬한다.
+
+---
+
+## 2. Problem
+- 기존 크리에이터 채널 홈 API는 controller와 response DTO가 `kr.co.vividnext.sodalive.v2.creator.channel` 하위에 있어, 현재 라이브 탭 API가 따르는 `v2.api.*` 공개 조립 계층 구조와 맞지 않는다.
+- 라이브 탭 API는 `kr.co.vividnext.sodalive.v2.api.creator.channel.live`와 `kr.co.vividnext.sodalive.v2.creator.channel.live`로 공개 API와 도메인 조회 책임을 분리했지만, 홈 API는 같은 v2 공개 API 설계와 패키지 경계가 어긋나 있다.
+- 공개 API DTO가 도메인 패키지 안에 남아 있으면 도메인 패키지가 API 응답 계약을 소유하는 형태가 되어 이후 탭별 API 확장 시 의존 방향이 혼동될 수 있다.
+- 구조 정렬 과정에서 기존 controller를 제거하지 않고 새 controller를 추가하면 `GET /api/v2/creator-channels/{creatorId}/home` mapping 충돌이 발생할 수 있다.
+
+---
+
+## 3. Goals
+- 기존 홈 API endpoint `GET /api/v2/creator-channels/{creatorId}/home`을 유지한다.
+- 기존 홈 API 응답 필드명과 필드 의미를 변경하지 않는다.
+- 홈 API의 controller, facade, response DTO를 `kr.co.vividnext.sodalive.v2.api.creator.channel.home` 하위 공개 API 조립 계층으로 이동한다.
+- 홈 API의 조회 service, 순수 정책, port, repository는 API 패키지 밖 도메인 패키지에 둔다.
+- 도메인 패키지가 `kr.co.vividnext.sodalive.v2.api.*`에 의존하지 않도록 보장한다.
+- 새 API controller 이동 시 기존 `v2.creator.channel.adapter.in.web.CreatorChannelHomeController`로 인한 Spring mapping 충돌이 없도록 기존 controller 제거 또는 이동 범위를 명확히 한다.
+- 기존 홈 API controller, facade 또는 service, repository 회귀 테스트를 유지하고 새 패키지 구조에 맞게 이동한다.
+- 검증 결과와 의존성 확인 결과를 `plan-task.md`에 누적 기록할 수 있게 한다.
+
+---
+
+## 4. Non-Goals
+- 홈 API 기능 추가는 하지 않는다.
+- 홈 API 응답 스키마 확장, 필드명 변경, 필드 의미 변경은 하지 않는다.
+- 기존 공개 endpoint path, HTTP method, 인증 정책은 변경하지 않는다.
+- 라이브 탭 API(`v2.api.creator.channel.live`, `v2.creator.channel.live`) 구현은 리팩토링 대상이 아니다.
+- 오디오, 시리즈, 커뮤니티, 팬 Talk, 후원 탭별 전체보기 API는 이번 범위에 포함하지 않는다.
+- 불필요한 공용화, 신규 추상화, 도메인 정책 재설계는 하지 않는다.
+- DB schema, 운영 DDL, 마이그레이션은 포함하지 않는다.
+
+---
+
+## 5. Target Users
+- 앱 클라이언트: 기존 홈 API 계약을 그대로 호출하는 클라이언트
+- 서버 개발자: v2 공개 API 조립 계층과 도메인 조회 계층의 의존 방향을 일관되게 유지해야 하는 개발자
+- QA/릴리즈 담당자: 리팩토링 후 기존 홈 API 동작 회귀 여부를 확인해야 하는 담당자
+
+---
+
+## 6. User Stories
+- 앱 클라이언트는 기존과 동일하게 `GET /api/v2/creator-channels/{creatorId}/home`을 호출하고 동일한 응답 필드와 의미를 받고 싶다.
+- 서버 개발자는 홈 API controller와 response DTO가 `v2.api.creator.channel.home`에 있어 공개 API 조립 계층을 쉽게 찾고 싶다.
+- 서버 개발자는 도메인 조회 service와 repository가 `v2.api.*`에 의존하지 않는다는 것을 검색 명령으로 확인하고 싶다.
+- 서버 개발자는 기존 홈 API controller가 남아 새 controller와 mapping 충돌을 일으키지 않는지 테스트와 검색으로 확인하고 싶다.
+
+---
+
+## 7. Core Features
+
+### Feature A. 공개 API 조립 계층 이동
+
+#### Requirements
+- `CreatorChannelHomeController`는 `kr.co.vividnext.sodalive.v2.api.creator.channel.home.adapter.in.web` 하위로 이동한다.
+- 홈 API facade는 `kr.co.vividnext.sodalive.v2.api.creator.channel.home.application` 하위에 둔다.
+- `CreatorChannelHomeResponse`와 하위 response DTO는 `kr.co.vividnext.sodalive.v2.api.creator.channel.home.dto` 하위로 이동한다.
+- controller는 기존 endpoint `GET /api/v2/creator-channels/{creatorId}/home`을 그대로 제공한다.
+- controller는 기존과 동일하게 인증 회원을 요구하고, 비회원은 `common.error.bad_credentials` 계열 오류를 반환한다.
+- facade는 공개 API 응답 DTO 조립 책임만 갖고 도메인 조회 service를 호출한다.
+- 기존 `kr.co.vividnext.sodalive.v2.creator.channel.adapter.in.web.CreatorChannelHomeController`는 남기지 않는다.
+
+#### Edge Cases
+- 새 controller와 기존 controller가 동시에 bean으로 등록되어 같은 path mapping을 제공하면 안 된다.
+
+### Feature B. 도메인 조회 계층 정렬
+
+#### Requirements
+- 홈 API 조회 service, 순수 정책, domain model, port, repository는 `kr.co.vividnext.sodalive.v2.creator.channel.home` 하위로 정렬한다.
+- 도메인 조회 계층은 API response DTO를 import하지 않는다.
+- 도메인 조회 계층은 API facade나 controller를 import하지 않는다.
+- 의존 방향은 항상 `v2.api.creator.channel.home -> v2.creator.channel.home`이다.
+- repository는 기존 QueryDSL 조회 의미와 정책을 변경하지 않는다.
+
+#### Edge Cases
+- 라이브 탭 API의 `v2.api.creator.channel.live`, `v2.creator.channel.live` 패키지는 이번 구조 정렬 대상이 아니므로 동작 변경 없이 import 영향만 확인한다.
+
+### Feature C. 공개 계약 보존 회귀 검증
+
+#### Requirements
+- 홈 API 최상위 응답 필드는 기존과 동일하게 유지한다.
+  - `creator`
+  - `currentLive`
+  - `latestAudioContent`
+  - `channelDonations`
+  - `notices`
+  - `schedules`
+  - `audioContents`
+  - `series`
+  - `communities`
+  - `fanTalk`
+  - `introduce`
+  - `activity`
+  - `sns`
+- 기존 하위 DTO 필드명과 의미를 변경하지 않는다.
+- controller 테스트는 기존 endpoint와 대표 JSON field path를 검증한다.
+- facade 또는 service 테스트는 도메인 조회 결과가 기존 응답 DTO로 변환되는 흐름을 검증한다.
+- repository 테스트는 기존 조회 정책 회귀를 유지한다.
+- `./gradlew ktlintCheck`를 실행하고 결과를 계획 문서에 기록한다.
+
+#### Edge Cases
+- response DTO 패키지 이동으로 Jackson `@JsonProperty`가 누락되어 `is*` 필드명이 바뀌면 안 된다.
+
+---
+
+## 8. Technical Constraints
+- 언어/런타임은 Kotlin + Java 17을 유지한다.
+- 빌드와 검증은 Gradle Wrapper(`./gradlew`)를 사용한다.
+- Spring Boot 2.7.14, JUnit 5, MockMvc, QueryDSL 기존 관례를 따른다.
+- 패키지 구조는 `docs/agent-guides/코드스타일.md`의 공개 API 조립 계층과 도메인 패키지 의존 방향 규칙을 따른다.
+- 테스트는 `docs/agent-guides/테스트스타일.md`의 RED, GREEN, REFACTOR 절차를 따른다.
+- 문서와 검증 기록은 `docs/agent-guides/작업절차.md`, `docs/agent-guides/문서유지보수.md`를 따른다.
+
+---
+
+## 9. Metrics
+- 홈 API endpoint와 응답 계약 회귀 테스트 통과 여부
+- facade 또는 service 단위 테스트 통과 여부
+- repository 단위 테스트 통과 여부
+- `./gradlew ktlintCheck` 통과 여부
+- 도메인 패키지의 `v2.api.*` import 검색 결과 0건 여부
+
+---
+
+## 10. Open Questions
+- 없음. 이번 범위는 동작 보존 리팩토링이며, 응답 계약이나 기능 정책 변경은 포함하지 않는다.