feat(content): 추천 전체보기를 연결한다

2026-07-07 11:54:31 +09:00
parent b33aed94c6
commit 981c02a8e1
18 changed files with 1169 additions and 294 deletions
--- a/docs/20260707_메인_콘텐츠_추천_전체보기/prd.md
+++ b/docs/20260707_메인_콘텐츠_추천_전체보기/prd.md
@@ -0,0 +1,211 @@
+# PRD: 메인 콘텐츠 추천 전체보기
+
+## 1. Overview
+메인 하단 `콘텐츠` 탭의 내부 `추천` 탭에서 일부 콘텐츠 섹션에 전체보기 action을 추가한다. `새로 올라온 오디오`, `오직 보이스온에서만`, `무료 오디오`, `포인트 오디오`는 하단 `콘텐츠` 탭 내부의 상단 `전체` 탭으로 전환해 해당 타입과 정렬 상태를 보여준다.
+
+`New&Hot`은 기존 전체 탭이 아니라 신규 콘텐츠 전체보기 화면을 만들어 `GET /api/v2/contents` API를 적용한다. `New&Hot`은 탭 외부 화면 전환이므로 `AppStep` route로 추가한다. 신규 화면은 Figma `482:15105` 기준으로 상단 title bar와 2열 오디오 카드 grid를 제공하고, 목록에는 스크롤 페이징을 적용한다.
+
+Figma 참조:
+- 신규 콘텐츠 전체보기 화면: `482:15105`, `https://www.figma.com/design/HmN1yNdJ3EIpqknFL0Hkab/-%EA%B3%B5%EC%9C%A0%EC%9A%A9-%EB%B3%B4%EC%9D%B4%EC%8A%A4%EC%98%A8-UI-UX-%EA%B8%B0%ED%9A%8D%EB%AC%B8%EC%84%9C?node-id=482-15105&m=dev`
+
+## 2. Problem
+- 현재 V2 `MainContentRecommendationView`의 추천 섹션 title은 전체보기 action을 받지 않아 chevron이 표시되지 않는다.
+- `SectionTitle`은 이미 action을 제공하면 chevron을 표시할 수 있으므로, 섹션별 전체보기 이동 callback을 연결해야 한다.
+- 대부분의 추천 섹션 전체보기는 이미 구현된 하단 `콘텐츠` 탭 내부 `전체` 탭으로 대체할 수 있지만, `New&Hot`은 별도 API와 별도 화면이 필요하다.
+- 신규 `GET /api/v2/contents` 응답은 기존 `AudioCardResponse` / `MainContentAudioResponse`와 필드명이 일부 달라 adapter 또는 전용 모델이 필요하다.
+
+## 3. Goals
+- 추천 탭에서 전체보기가 필요한 섹션에 action을 추가해 title 우측 chevron을 표시한다.
+- `새로 올라온 오디오` 전체보기는 하단 `콘텐츠` 탭의 상단 `전체` 탭에서 `오디오` 타입, `최신순` 정렬로 전환한다.
+- `오직 보이스온에서만` 전체보기는 하단 `콘텐츠` 탭의 상단 `전체` 탭에서 `오리지널` 타입, `최신순` 정렬로 전환한다.
+- `무료 오디오` 전체보기는 하단 `콘텐츠` 탭의 상단 `전체` 탭에서 `무료` 타입, `인기순` 정렬로 전환한다.
+- `포인트 오디오` 전체보기는 하단 `콘텐츠` 탭의 상단 `전체` 탭에서 `포인트` 타입, `인기순` 정렬로 전환한다.
+- `New&Hot` 전체보기는 `AppStep` route 기반 신규 콘텐츠 전체보기 화면으로 이동하고 `type = NEW_AND_HOT_AUDIO`를 요청한다.
+- 신규 전체보기 화면은 `GET /api/v2/contents`를 호출하고 기본 query 값은 `page = 0`, `size = 20`, `type = NEW_AND_HOT_AUDIO`로 둔다.
+- 신규 전체보기 화면은 `hasNext == true`일 때 다음 page를 append한다.
+- 신규 전체보기 화면의 오디오 카드는 V2 공용 `AudioContentThumbnailCard` 재사용을 우선한다.
+
+## 4. Non-Goals
+- 실제 구현과 Xcode 프로젝트 수정은 이번 PRD 작성 범위에 포함하지 않는다.
+- 추천 탭의 기존 API `GET /api/v2/audio/recommendations` 응답 구조를 변경하지 않는다.
+- `새로 올라온 오디오`, `오직 보이스온에서만`, `무료 오디오`, `포인트 오디오`용 별도 전체보기 화면을 새로 만들지 않는다.
+- `처음부터 함께 성장!` 섹션과 `FIRST_AUDIO_CONTENT` 전체보기 진입은 이번 범위에 포함하지 않는다.
+- `콘텐츠 탭 - 전체`의 기존 API `GET /api/v2/audio/contents` 명세를 변경하지 않는다.
+- API 명세에 없는 신규 `type` 값을 임의로 추가하지 않는다.
+- Figma localhost asset URL을 앱 코드에 직접 사용하지 않는다.
+- 외부 라이브러리를 추가하지 않는다.
+- `Pods/**`, `generated/**`, `build/**`는 수정하지 않는다.
+
+## 5. Target Users
+- 추천 탭에서 관심 섹션의 콘텐츠를 더 많이 탐색하려는 사용자
+- 새롭거나 반응이 좋은 오디오를 연속해서 보고 싶은 사용자
+- 첫 콘텐츠, 무료, 포인트, 오리지널 등 조건별 콘텐츠를 빠르게 훑고 상세로 이동하려는 사용자
+
+## 6. User Stories
+- 사용자는 추천 탭 섹션 title 우측 chevron을 눌러 해당 섹션의 전체 콘텐츠를 보고 싶다.
+- 사용자는 `새로 올라온 오디오` 전체보기에서 최신 오디오 목록을 바로 보고 싶다.
+- 사용자는 `무료 오디오`와 `포인트 오디오` 전체보기에서 인기순 목록을 바로 보고 싶다.
+- 사용자는 `New&Hot` 전체보기에서 Figma처럼 2열 카드 목록을 스크롤하며 더 많은 콘텐츠를 보고 싶다.
+- 사용자는 전체보기 목록의 콘텐츠 카드를 누르면 기존 오디오 상세 화면으로 이동하기를 기대한다.
+
+## 7. Core Requirements
+
+### 7.1 추천 탭 섹션 action
+- 전체보기 action이 필요한 섹션은 title 우측 chevron을 표시한다.
+- `SectionTitle(title:action:)`의 기존 chevron 표시 동작을 우선 재사용한다.
+- action이 없는 섹션은 기존처럼 chevron을 표시하지 않는다.
+- 기존 추천 섹션의 empty 조건은 유지한다. 섹션 item이 비어 화면에 보이지 않는 경우 chevron도 표시하지 않는다.
+
+대상 섹션과 이동 규칙:
+- `새로 올라온 오디오`
+  - 이동 대상: 하단 `콘텐츠` 탭 내부 상단 `전체` 탭
+  - 초기 타입: `MainContentAllType.audio`
+  - 초기 정렬: `ContentSort.latest`
+- `오직 보이스온에서만`
+  - 이동 대상: 하단 `콘텐츠` 탭 내부 상단 `전체` 탭
+  - 초기 타입: `MainContentAllType.original`
+  - 초기 정렬: `ContentSort.latest`
+- `무료 오디오`
+  - 이동 대상: 하단 `콘텐츠` 탭 내부 상단 `전체` 탭
+  - 초기 타입: `MainContentAllType.free`
+  - 초기 정렬: `ContentSort.popular`
+- `포인트 오디오`
+  - 이동 대상: 하단 `콘텐츠` 탭 내부 상단 `전체` 탭
+  - 초기 타입: `MainContentAllType.point`
+  - 초기 정렬: `ContentSort.popular`
+- `New&Hot`
+  - 이동 대상: `AppStep` route 기반 신규 콘텐츠 전체보기 화면
+  - API type: `ContentOverviewType.newAndHotAudio`
+
+### 7.2 신규 콘텐츠 전체보기 API
+- Method: `GET`
+- Path: `/api/v2/contents`
+- 인증: 기존 V2 API 인증 헤더 패턴을 따른다.
+- 응답 래퍼: 기존 V2 관례대로 `ApiResponse<ContentOverviewPageResponse>` 디코딩을 우선한다.
+
+Query parameter:
+- `page: Int`
+- `size: Int`
+- `type: ContentOverviewType`
+
+기본값:
+- `page = 0`
+- `size = 20`
+- `type = NEW_AND_HOT_AUDIO`
+
+Swift enum:
+```swift
+enum ContentOverviewType: String, Decodable, Encodable, Hashable {
+    case newAndHotAudio = "NEW_AND_HOT_AUDIO"
+}
+```
+
+Swift response model:
+```swift
+struct ContentOverviewPageResponse: Decodable {
+    let type: ContentOverviewType
+    let items: [ContentOverviewItemResponse]
+    let page: Int
+    let size: Int
+    let hasNext: Bool
+}
+
+struct ContentOverviewItemResponse: Decodable, Identifiable {
+    let contentId: Int
+    let title: String
+    let coverImage: String?
+    let price: Int
+    let isPointAvailable: Bool
+    let creatorNickname: String
+    let isAdult: Bool
+    let isFirstContent: Bool
+    let isOriginalSeries: Bool
+
+    var id: Int { contentId }
+}
+```
+
+### 7.3 신규 콘텐츠 전체보기 화면
+- 화면은 `SodaLive/Sources/V2/**` 하위에 신규 `View`, `ViewModel`, `Repository`, `Models`를 작성한다.
+- 신규 화면은 `AppStep`에 route를 추가하고 `ContentView`에서 해당 route를 화면에 매핑한다.
+- 화면 title은 `New&Hot`으로 표시한다.
+- Figma 기준 상단 title bar는 좌측 back chevron과 title을 가진다.
+- 콘텐츠 목록은 2열 grid로 표시한다.
+- 각 카드는 정사각형 cover image, title, creator nickname, 태그를 표시한다.
+- 카드 태그는 응답 필드에 따라 기존 `AudioContentThumbnailCard`의 태그 표시 규칙을 따른다.
+  - `isOriginalSeries == true`: original tag
+  - `isFirstContent == true`: first tag
+  - `isPointAvailable == true`: point tag
+  - `price == 0`: free tag
+  - `isAdult == true`: adult tag
+- 카드 tap 시 `contentId`로 기존 오디오 상세 화면에 진입한다.
+- 첫 페이지 로딩, 빈 목록, 실패, pagination loading 상태는 기존 V2 콘텐츠 탭 패턴을 따른다.
+
+### 7.4 Paging
+- `page = 0` 응답은 기존 목록을 교체한다.
+- `page > 0` 응답은 기존 목록 뒤에 append한다.
+- `hasNext == false`이면 추가 요청을 막는다.
+- 이미 다음 페이지를 로딩 중이면 중복 요청을 막는다.
+- 첫 페이지 실패 시 empty/error 상태를 표시한다.
+- 다음 페이지 실패 시 기존 목록은 유지하고 toast 또는 error message를 표시한다.
+
+### 7.5 하단 콘텐츠 탭 내부 전체 탭 전환
+- `New&Hot`을 제외한 추천 섹션 전체보기는 별도 route를 추가하지 않고 하단 `콘텐츠` 탭 내부에서 처리한다.
+- 추천 탭에서 하단 `콘텐츠` 탭 내부 상단 `전체` 탭으로 이동할 때 `MainContentView`의 내부 탭을 `.all`로 전환한다.
+- 전환 직후 `MainContentAllViewModel`에 목표 타입과 정렬을 적용하고 첫 페이지를 다시 요청한다.
+- 같은 타입/정렬 상태로 다시 진입하는 경우 불필요한 중복 요청은 피한다.
+- 기존 `MainContentAllViewModel` 상태 유지 구조는 보존하되, 추천 섹션 전체보기 진입 시 명시적으로 선택 상태를 갱신할 수 있어야 한다.
+
+## 8. Reusable V2 Candidates
+- `SodaLive/Sources/V2/Component/SectionTitle.swift`
+  - `action`이 있으면 `ic_chevron_right`를 표시하므로 추천 섹션 title chevron에 재사용 가능하다.
+- `SodaLive/Sources/V2/Component/AudioContent/AudioContentThumbnailCard.swift`
+  - Figma 신규 전체보기의 2열 오디오 카드와 태그 표시 구조가 일치한다.
+  - `ContentOverviewItemResponse`를 `AudioContentThumbnailCardItem`으로 바꾸는 initializer 추가만으로 재사용 가능하다.
+- `SodaLive/Sources/V2/Main/Content/All/MainContentAllView.swift`
+  - 하단 `콘텐츠` 탭 내부 상단 `전체` 탭 전환 대상 화면으로 재사용한다.
+  - 외부에서 초기 타입/정렬을 주입하거나 갱신하는 API가 필요하다.
+- `SodaLive/Sources/V2/Main/Content/All/MainContentAllViewModel.swift`
+  - 타입/정렬 선택, 첫 페이지 reload, append paging 구조가 이미 있다.
+  - 추천 전체보기 진입용 `apply(type:sort:)` 같은 최소 API 추가 후보이다.
+- `SodaLive/Sources/V2/Main/Content/Recommendation/Components/MainContentAudioHorizontalCardSection.swift`
+  - `새로 올라온 오디오`, `무료 오디오`, `포인트 오디오` 섹션에 action parameter를 추가하는 후보이다.
+- `SodaLive/Sources/V2/Main/Content/Recommendation/Components/MainContentAudioListCarouselSection.swift`
+  - `New&Hot` 섹션에 action parameter를 추가하는 후보이다.
+- `SodaLive/Sources/V2/Main/Content/Recommendation/Components/MainContentVoiceOnOnlySection.swift`
+  - `오직 보이스온에서만` 섹션에 action parameter를 추가하는 후보이다.
+- `SodaLive/Sources/V2/Component/DefaultTitleBar.swift` / `SodaLive/Sources/V2/Component/TitleBar.swift`
+  - 신규 전체보기 화면 title bar 재사용 후보이다. Figma의 좌측 back chevron 구조와 정확히 맞지 않으면 기존 title bar 패턴 안에서 최소 확장한다.
+- `SodaLive/Sources/V2/Main/Content/Recommendation/Repository/MainContentRecommendationApi.swift`
+  - V2 Moya `TargetType`, bearer token header 패턴 참고 대상이다.
+- `SodaLive/Sources/V2/Main/Content/All/Repository/MainContentAllApi.swift`
+  - query parameter 기반 V2 API 구현 패턴 참고 대상이다.
+- `SodaLive/Sources/V2/Main/Content/Recommendation/Components/MainContentAudioEmptyStateView.swift`
+  - 신규 전체보기의 빈 목록/실패 상태 재사용 후보이다.
+
+## 9. Technical Constraints
+- 기능 변경은 `SodaLive/Sources/**`, 신규 V2 코드는 `SodaLive/Sources/V2/**` 하위에서 해결한다.
+- 공용 컴포넌트 변경은 재사용성이 명확할 때만 `SodaLive/Sources/V2/Component/**`에서 최소 수정한다.
+- 특정 화면 내부에서만 쓰는 컴포넌트는 해당 화면 폴더 하위 `Components`에 둔다.
+- 기존 navigation은 `AppState.shared.setAppStep(step:)` 패턴을 따른다.
+- `New&Hot` 신규 전체보기 화면은 탭 외부 전환이므로 `AppStep`과 `ContentView` mapping을 추가한다.
+- `New&Hot`을 제외한 섹션 전체보기는 `AppStep` route를 추가하지 않고 `MainContentView` 내부 탭 상태 변경으로 처리한다.
+- 인증 헤더는 기존 V2 API와 동일하게 `Authorization: Bearer <token>` 패턴을 따른다.
+- `Long` id는 기존 V2 모델 관례에 맞춰 Swift `Int`를 우선 사용한다.
+- 기존 `AudioContentThumbnailCard`는 `imageUrl` 필드명을 사용하므로 `coverImage` adapter가 필요하다.
+- 구현 시 빌드/검증 명령은 `docs/agent-guides/build-test-verification.md`를 따른다.
+
+## 10. Success Criteria
+- 전체보기 대상 추천 섹션 title 우측에 chevron이 표시된다.
+- `새로 올라온 오디오` chevron tap 시 하단 `콘텐츠` 탭 내부 상단 `전체 > 오디오 > 최신순` 상태로 전환된다.
+- `오직 보이스온에서만` chevron tap 시 하단 `콘텐츠` 탭 내부 상단 `전체 > 오리지널 > 최신순` 상태로 전환된다.
+- `무료 오디오` chevron tap 시 하단 `콘텐츠` 탭 내부 상단 `전체 > 무료 > 인기순` 상태로 전환된다.
+- `포인트 오디오` chevron tap 시 하단 `콘텐츠` 탭 내부 상단 `전체 > 포인트 > 인기순` 상태로 전환된다.
+- `New&Hot` chevron tap 시 `AppStep` route로 신규 전체보기 화면에 진입하고 `GET /api/v2/contents?page=0&size=20&type=NEW_AND_HOT_AUDIO`를 요청한다.
+- 신규 전체보기 화면은 Figma 기준 2열 오디오 card grid, title bar, back navigation을 제공한다.
+- 신규 전체보기 화면은 `hasNext` 기반 다음 페이지 append를 제공한다.
+- 신규 전체보기 화면의 card tap은 기존 오디오 상세 이동과 동일하게 동작한다.
+- 기존 추천 탭 섹션의 item tap, banner tap, series tap 동작은 회귀하지 않는다.
+
+## 11. Open Questions
+- 신규 API 실패 시 toast 문구와 empty state 문구의 정확한 I18n 문구는 확인이 필요하다.