klaus/sodalive-backend-spring-boot
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
24a61e4d78f26e54bb37acf43b7efc8e7f96d7c3
sodalive-backend-spring-boot/docs/20260617_크리에이터_채널_홈_API_구조정렬/prd.md

7.6 KiB
Raw Blame History

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

  • 없음. 이번 범위는 동작 보존 리팩토링이며, 응답 계약이나 기능 정책 변경은 포함하지 않는다.