feat(creator): 오디오 탭을 추가한다

2026-07-04 16:40:35 +09:00
parent 6600cd43c1
commit c4c18341a6
12 changed files with 955 additions and 77 deletions
--- a/docs/20260704_크리에이터_채널_오디오_탭/plan-task.md
+++ b/docs/20260704_크리에이터_채널_오디오_탭/plan-task.md
@@ -0,0 +1,143 @@
+# 크리에이터 채널 오디오 탭 구현 계획
+
+## 기준 문서
+
+- PRD: `docs/20260704_크리에이터_채널_오디오_탭/prd.md`
+- 기존 라이브 탭 PRD: `docs/20260703_크리에이터_채널_라이브_탭/prd.md`
+- 기존 라이브 탭 구현 계획: `docs/20260703_크리에이터_채널_라이브_탭/plan-task.md`
+- 코드 스타일: `docs/agent-guides/code-style.md`
+- 빌드/검증: `docs/agent-guides/build-test-verification.md`
+- Figma 전체 화면: `290:9015`, `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=290-9015&m=dev`
+- Figma 소장률: `290:9029`, `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=290-9029&m=dev`
+- Figma Empty: `290:8965`, `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=290-8965&m=dev`
+- Figma 본인 채널 CTA: `665:19008`, `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=665-19008&m=dev`
+
+## 구현 원칙
+
+- 기존 `CreatorChannelView`의 공통 shell, header, sticky tab-bar, title bar 동작은 유지한다.
+- `CreatorChannelTab.audio` 콘텐츠만 신규 `CreatorChannelAudioTabView`로 교체한다.
+- `ContentSort`, `CreatorChannelSortBar`, `CreatorChannelSortBottomSheet`, `CapsuleTabBar`, `CreatorChannelAudioContentListItem`을 재사용한다.
+- 전체 테마는 API 모델에 섞지 않고 오디오 탭 표시 모델에서만 합성한다.
+- `themeId == nil`이면 query parameter를 보내지 않는다.
+- `duration == nil` 또는 빈 문자열인 콘텐츠는 ViewModel에서 목록에 포함하지 않는다.
+- 본인 채널 CTA는 기존 `showAudioContentUpload()` 흐름을 재사용한다.
+
+## 주요 대상 파일
+
+### 생성
+- `SodaLive/Sources/V2/CreatorChannel/Audio/Models/CreatorChannelAudioTabResponse.swift`
+- `SodaLive/Sources/V2/CreatorChannel/Audio/Repository/CreatorChannelAudioApi.swift`
+- `SodaLive/Sources/V2/CreatorChannel/Audio/Repository/CreatorChannelAudioRepository.swift`
+- `SodaLive/Sources/V2/CreatorChannel/Audio/CreatorChannelAudioViewModel.swift`
+- `SodaLive/Sources/V2/CreatorChannel/Audio/CreatorChannelAudioTabView.swift`
+- `SodaLive/Sources/V2/CreatorChannel/Audio/Components/CreatorChannelAudioOwnershipRateView.swift`
+- `SodaLive/Sources/V2/CreatorChannel/Audio/Components/CreatorChannelAudioUploadButton.swift`
+
+### 수정
+- `SodaLive/Sources/V2/CreatorChannel/CreatorChannelView.swift`
+- `SodaLive/Sources/I18n/I18n.swift`
+- 필요 시 `SodaLive.xcodeproj/project.pbxproj`
+
+## TASK 체크리스트
+
+### Phase 1: 문서와 API 모델
+
+- [x] **Task 1.1: PRD와 계획 문서 생성**
+  - 대상 파일:
+    - 생성: `docs/20260704_크리에이터_채널_오디오_탭/prd.md`
+    - 생성: `docs/20260704_크리에이터_채널_오디오_탭/plan-task.md`
+  - 검증 기준:
+    - 실행 명령: `rg "290:9015|290:9029|290:8965|665:19008|CreatorChannelAudioTabResponse" docs/20260704_크리에이터_채널_오디오_탭`
+    - 기대 결과: Figma URL과 응답 모델 요구사항이 문서에 기록된다.
+
+- [x] **Task 1.2: 오디오 탭 Response model 생성**
+  - 대상 파일:
+    - 생성: `SodaLive/Sources/V2/CreatorChannel/Audio/Models/CreatorChannelAudioTabResponse.swift`
+  - 작업 내용:
+    - `CreatorChannelAudioTabResponse`와 `CreatorChannelAudioThemeResponse`를 `Decodable`로 생성한다.
+    - `CreatorChannelAudioTabResponse.audioContents`는 기존 `[CreatorChannelAudioContentResponse]`를 사용한다.
+  - 검증 기준:
+    - 실행 명령: `rg "struct CreatorChannelAudioTabResponse|audioContentCount|paidAudioContentCount|purchasedAudioContentCount|purchasedAudioContentRate|themes|audioContents|themeId: Int\\?|struct CreatorChannelAudioThemeResponse" SodaLive/Sources/V2/CreatorChannel/Audio/Models/CreatorChannelAudioTabResponse.swift`
+
+### Phase 2: API, Repository, ViewModel
+
+- [x] **Task 2.1: 오디오 탭 API endpoint 생성**
+  - 대상 파일:
+    - 생성: `SodaLive/Sources/V2/CreatorChannel/Audio/Repository/CreatorChannelAudioApi.swift`
+  - 작업 내용:
+    - `CreatorChannelAudioApi.getAudio(creatorId:page:size:sort:themeId:)`를 만든다.
+    - path는 `/api/v2/creator-channels/{creatorId}/audio`로 구성한다.
+    - `themeId`는 nil이 아닐 때만 query에 포함한다.
+  - 검증 기준:
+    - 실행 명령: `rg "CreatorChannelAudioApi|getAudio|/api/v2/creator-channels/|/audio|themeId|URLEncoding.queryString" SodaLive/Sources/V2/CreatorChannel/Audio/Repository/CreatorChannelAudioApi.swift`
+
+- [x] **Task 2.2: 오디오 탭 Repository 생성**
+  - 대상 파일:
+    - 생성: `SodaLive/Sources/V2/CreatorChannel/Audio/Repository/CreatorChannelAudioRepository.swift`
+  - 작업 내용:
+    - `MoyaProvider<CreatorChannelAudioApi>`를 사용하는 `getAudio(...)` publisher를 제공한다.
+  - 검증 기준:
+    - 실행 명령: `rg "CreatorChannelAudioRepository|MoyaProvider<CreatorChannelAudioApi>|AnyPublisher<Response, MoyaError>|getAudio" SodaLive/Sources/V2/CreatorChannel/Audio/Repository/CreatorChannelAudioRepository.swift`
+
+- [x] **Task 2.3: 오디오 탭 ViewModel 생성**
+  - 대상 파일:
+    - 생성: `SodaLive/Sources/V2/CreatorChannel/Audio/CreatorChannelAudioViewModel.swift`
+  - 작업 내용:
+    - 상태는 loading, response, filtered `audioContents`, selectedSort, selectedTheme, page, size, hasNext, hasLoaded, error toast를 둔다.
+    - `displayThemes`에서 전체 항목을 맨 앞에 합성한다.
+    - 정렬/테마 변경 시 첫 페이지부터 다시 조회한다.
+    - `duration`이 없는 콘텐츠는 `visibleAudioContents`에 포함하지 않는다.
+  - 검증 기준:
+    - 실행 명령: `rg "CreatorChannelAudioViewModel|displayThemes|selectedTheme|fetchFirstPage|fetchNextPageIfNeeded|selectSort|selectTheme|compactMap|duration" SodaLive/Sources/V2/CreatorChannel/Audio/CreatorChannelAudioViewModel.swift`
+
+### Phase 3: Figma 섹션별 UI
+
+- [x] **Task 3.1: Theme CapsuleTabBar 적용**
+  - 대상 파일:
+    - 생성: `SodaLive/Sources/V2/CreatorChannel/Audio/CreatorChannelAudioTabView.swift`
+  - 검증 기준:
+    - 실행 명령: `rg "CapsuleTabBar|displayThemes|selectedTheme" SodaLive/Sources/V2/CreatorChannel/Audio/CreatorChannelAudioTabView.swift`
+
+- [x] **Task 3.2: 소장률 UI 구현**
+  - 대상 파일:
+    - 생성: `SodaLive/Sources/V2/CreatorChannel/Audio/Components/CreatorChannelAudioOwnershipRateView.swift`
+  - 검증 기준:
+    - 실행 명령: `rg "CreatorChannelAudioOwnershipRateView|purchasedAudioContentRate|purchasedAudioContentCount|paidAudioContentCount|ProgressView|progress" SodaLive/Sources/V2/CreatorChannel/Audio/Components/CreatorChannelAudioOwnershipRateView.swift`
+
+- [x] **Task 3.3: 콘텐츠 목록과 empty 구현**
+  - 대상 파일:
+    - 수정: `SodaLive/Sources/V2/CreatorChannel/Audio/CreatorChannelAudioTabView.swift`
+    - 수정: `SodaLive/Sources/I18n/I18n.swift`
+  - 검증 기준:
+    - 실행 명령: `rg "CreatorChannelAudioContentListItem|audioEmptyMessage|fetchNextPageIfNeeded|isEmptyState" SodaLive/Sources/V2/CreatorChannel/Audio/CreatorChannelAudioTabView.swift SodaLive/Sources/I18n/I18n.swift`
+
+- [x] **Task 3.4: 본인 채널 CTA 구현**
+  - 대상 파일:
+    - 생성: `SodaLive/Sources/V2/CreatorChannel/Audio/Components/CreatorChannelAudioUploadButton.swift`
+  - 검증 기준:
+    - 실행 명령: `rg "CreatorChannelAudioUploadButton|ic_new_upload_audio|uploadAudioContent|Capsule|frame\\(maxWidth: \\.infinity" SodaLive/Sources/V2/CreatorChannel/Audio/Components/CreatorChannelAudioUploadButton.swift`
+
+### Phase 4: CreatorChannelView 연결과 검증
+
+- [x] **Task 4.1: 오디오 탭 콘텐츠와 CTA 연결**
+  - 대상 파일:
+    - 수정: `SodaLive/Sources/V2/CreatorChannel/CreatorChannelView.swift`
+  - 검증 기준:
+    - 실행 명령: `rg "CreatorChannelAudioTabView|viewModel\\.selectedTab == \\.audio|CreatorChannelAudioUploadButton|showAudioContentUpload" SodaLive/Sources/V2/CreatorChannel/CreatorChannelView.swift`
+
+- [ ] **Task 4.2: 프로젝트 파일 등록과 정적 검증**
+  - 대상 파일:
+    - 확인/수정: `SodaLive.xcodeproj/project.pbxproj`
+  - 검증 기준:
+    - 실행 명령: `git diff --check -- docs/20260704_크리에이터_채널_오디오_탭 SodaLive/Sources/V2/CreatorChannel SodaLive/Sources/I18n/I18n.swift SodaLive.xcodeproj/project.pbxproj`
+    - 기대 결과: 공백 오류 없이 성공한다.
+    - 실행 명령: `xcodebuild -workspace "SodaLive.xcworkspace" -scheme "SodaLive-dev" -configuration Debug build`
+    - 기대 결과: 빌드 성공.
+
+## 검증 기록
+
+- 2026-07-04: `get_design_context`와 `get_screenshot`으로 Figma `290:9015`, `290:9029`, `290:8965`, `665:19008`을 확인했다.
+- 2026-07-04: `rg`와 `sed`로 기존 라이브 탭, 정렬 컴포넌트, `CapsuleTabBar`, 오디오 콘텐츠 item, 본인 채널 CTA 흐름을 확인했다.
+- 2026-07-04: `git diff --check -- docs/20260704_크리에이터_채널_오디오_탭 SodaLive/Sources/V2/CreatorChannel SodaLive/Sources/I18n/I18n.swift SodaLive.xcodeproj/project.pbxproj` 실행 결과 출력 없이 성공했다.
+- 2026-07-04: `xcodebuild -workspace "SodaLive.xcworkspace" -scheme "SodaLive-dev" -configuration Debug build`는 `SodaLive.xcworkspace`를 workspace로 인식하지 못해 실패했다.
+- 2026-07-04: 대체로 `xcodebuild -project "SodaLive.xcodeproj" -scheme "SodaLive-dev" -configuration Debug build`를 샌드박스 밖에서 실행했다. SwiftPM 패키지 해석과 외부 패키지 컴파일은 진행됐으나 기존 외부 모듈 `Bootpay`, `BootpayUI`, `AgoraRtmKit`, `GoogleSignIn`, `YandexMobileAds`를 찾지 못해 앱 타깃 SwiftDriver 단계에서 실패했다.
--- a/docs/20260704_크리에이터_채널_오디오_탭/prd.md
+++ b/docs/20260704_크리에이터_채널_오디오_탭/prd.md
@@ -0,0 +1,121 @@
+# PRD: 크리에이터 채널 오디오 탭
+
+## 1. Overview
+크리에이터 채널 공통 shell의 `오디오` 탭에서 크리에이터의 오디오 콘텐츠 목록, 테마 필터, 정렬, 소장률 정보를 제공한다. 상단 title bar, header, sticky tab-bar는 기존 크리에이터 채널 홈 구현을 재사용하고, tab-bar 아래 콘텐츠만 오디오 탭 전용 API 응답으로 구성한다.
+
+API는 `GET /api/v2/creator-channels/{creatorId}/audio`를 사용한다. 기본 query는 `page=0`, `size=20`, `sort=LATEST`이며 `themeId`는 전체 선택 상태에서 보내지 않는다. 서버 응답의 `themes`에는 전체 항목이 포함되지 않으므로 클라이언트에서 맨 앞에 전체 탭을 추가한다.
+
+Figma 참조:
+- 전체 화면: `290:9015`, `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=290-9015&m=dev`
+- 소장률: `290:9029`, `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=290-9029&m=dev`
+- Empty: `290:8965`, `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=290-8965&m=dev`
+- 본인 채널 CTA: `665:19008`, `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=665-19008&m=dev`
+
+## 2. Problem
+- 현재 `CreatorChannelTab.audio`는 placeholder로 표시되어 실제 오디오 목록, 테마 필터, 소장률, 페이지네이션이 없다.
+- 오디오 탭은 라이브 탭과 같은 정렬 선택 UX를 사용해야 하지만, 테마 필터와 소장률 표시 조건이 추가된다.
+- 본인 채널에서는 일반 사용자용 소장률 대신 오디오 업로드 CTA를 제공해야 한다.
+
+## 3. Goals
+- `CreatorChannelTab.audio` 선택 시 오디오 탭 API를 호출하고 응답 데이터로 화면을 구성한다.
+- `page`, `size`, `sort`, 선택된 `themeId`를 query parameter로 전달한다.
+- 기본값은 `page=0`, `size=20`, `sort=LATEST`, `themeId=nil`이다.
+- theme list는 `CapsuleTabBar`를 사용하고, 맨 앞에 전체 항목을 합성한다.
+- 정렬 선택 방식은 라이브 탭과 동일한 `CreatorChannelSortBar` + `CreatorChannelSortBottomSheet`를 재사용한다.
+- 콘텐츠 item은 `CreatorChannelAudioContentListItem`을 재사용한다.
+- 전체 테마이고 본인 채널이 아닐 때만 소장률 UI를 표시한다.
+- 본인 채널의 오디오 탭에는 `ic_new_upload_audio` 아이콘을 쓰는 하단 CTA를 표시한다.
+
+## 4. Non-Goals
+- 크리에이터 채널 공통 shell, header, sticky tab-bar 동작을 다시 설계하지 않는다.
+- 오디오 콘텐츠 상세, 구매, 재생, 업로드 화면 자체를 새로 구현하지 않는다.
+- 신규 정렬 enum을 추가하지 않고 기존 `ContentSort`를 재사용한다.
+- `CreatorChannelAudioContentListItem`의 표시 규칙을 이번 범위에서 재설계하지 않는다.
+- Figma localhost asset URL을 앱 코드에 직접 사용하지 않는다.
+- `Pods/**`, `generated/**`, `build/**`는 수정하지 않는다.
+
+## 5. Core Requirements
+
+### 5.1 API
+- Method: `GET`
+- Path: `/api/v2/creator-channels/{creatorId}/audio`
+- Path parameter: `creatorId`
+- Query parameters:
+  - `sort`
+  - `page`
+  - `size`
+  - `themeId`
+- `themeId == nil`이면 query parameter에서 제외한다.
+- 응답 래퍼는 기존 패턴대로 `ApiResponse<CreatorChannelAudioTabResponse>`로 디코딩한다.
+
+```kotlin
+data class CreatorChannelAudioTabResponse(
+    val audioContentCount: Int,
+    val paidAudioContentCount: Int,
+    val purchasedAudioContentCount: Int,
+    val purchasedAudioContentRate: Double,
+    val themes: List<CreatorChannelAudioThemeResponse>,
+    val audioContents: List<CreatorChannelAudioContentResponse>,
+    val sort: ContentSort,
+    val themeId: Long?,
+    val page: Int,
+    val size: Int,
+    val hasNext: Boolean
+)
+
+data class CreatorChannelAudioThemeResponse(
+    val themeId: Long,
+    val themeName: String
+)
+```
+
+- `ContentSort`와 `CreatorChannelAudioContentResponse`는 기존 타입을 재사용한다.
+- Kotlin `Long`은 기존 V2 모델 관례대로 Swift `Int`로 선언한다.
+
+### 5.2 Theme filter
+- 서버 응답 `themes` 앞에 클라이언트 전용 전체 항목을 추가한다.
+- 서버 응답 `themeId == nil`이면 전체가 선택된 상태여야 한다.
+- 테마 선택 시 첫 페이지부터 다시 조회한다.
+- 전체 선택 시 `themeId`를 보내지 않는다.
+
+### 5.3 Ownership rate
+- 소장률 UI는 전체 테마이고 본인 채널이 아닐 때만 표시한다.
+- 테마별 필터 상태에서는 표시하지 않는다.
+- 본인 채널에서는 표시하지 않는다.
+- `purchasedAudioContentRate`는 percent 값으로 내려오므로 그대로 `%` 문구에 사용한다.
+- 우측 카운트는 `purchasedAudioContentCount/paidAudioContentCount개` 형식으로 표시한다.
+- progress 값은 `purchasedAudioContentRate / 100`을 0...1로 clamp해서 사용한다.
+
+### 5.4 Audio contents
+- `audioContents` 중 `duration == nil` 또는 빈 문자열인 콘텐츠는 숨긴다.
+- Empty 상태 판정은 서버의 `audioContentCount == 0` 기준으로 한다.
+- Empty 문구는 `크리에이터가 오디오를 준비 중입니다.\n기대해 주세요!`를 표시하고, UI 표시 방식은 라이브 탭 empty와 동일하게 한다.
+- 목록 하단 도달 시 `hasNext == true`이면 `page + 1`을 조회해 append한다.
+
+### 5.5 Own channel CTA
+- 본인 채널이면 소장률 UI를 숨긴다.
+- 본인 채널이고 `selectedTab == .audio`일 때 하단 고정 CTA를 표시한다.
+- CTA 표시 방식은 라이브 탭의 `라이브 시작하기` CTA와 동일한 full-width capsule 버튼이다.
+- CTA icon은 `ic_new_upload_audio`를 사용한다.
+- CTA tap은 기존 `showAudioContentUpload()` 흐름을 재사용한다.
+
+## 6. Success Criteria
+- 오디오 탭 진입 시 `GET /api/v2/creator-channels/{creatorId}/audio?page=0&size=20&sort=LATEST`가 호출되고, 전체 선택 상태에서는 `themeId`가 전송되지 않는다.
+- `themes` 앞에 전체 탭이 표시되고, 응답 `themeId == nil`이면 전체가 선택된다.
+- 테마 선택 시 선택한 `themeId`로 첫 페이지를 다시 조회한다.
+- 정렬 선택 UI와 동작은 라이브 탭과 동일하다.
+- 본인 채널이 아니고 전체 테마일 때만 소장률 UI가 표시된다.
+- 본인 채널이거나 테마 필터 상태이면 소장률 UI가 표시되지 않는다.
+- `duration`이 없는 콘텐츠는 목록에 표시되지 않는다.
+- `audioContentCount == 0`이면 라이브 탭과 같은 방식으로 오디오 empty 문구가 표시된다.
+- 본인 채널의 오디오 탭 하단에는 `ic_new_upload_audio` 아이콘을 쓰는 CTA가 표시되고 오디오 콘텐츠 업로드로 이동한다.
+
+## 7. Technical Constraints
+- 기능 변경은 `SodaLive/Sources/V2/CreatorChannel/**` 하위에서 해결한다.
+- 오디오 탭 전용 View, ViewModel, Repository, API, 모델은 `SodaLive/Sources/V2/CreatorChannel/Audio/**` 아래에 둔다.
+- 공용 item, sort bar, sort bottom sheet, `CapsuleTabBar`는 기존 구현을 재사용한다.
+- 신규 문구는 `SodaLive/Sources/I18n/I18n.swift`에 ko/en/ja를 추가한다.
+
+## 8. Verification Notes
+- 2026-07-04: Figma `get_design_context`와 `get_screenshot`으로 `290:9015`, `290:9029`, `290:8965`, `665:19008`을 확인했다.
+- 2026-07-04: `CreatorChannelLiveTabView`, `CreatorChannelLiveViewModel`, `CreatorChannelSortBar`, `CapsuleTabBar`, `CreatorChannelAudioContentListItem` 기존 구현을 확인해 재사용 경계를 확정했다.