feat(home): 랭킹 순위 UI를 추가한다

2026-06-30 16:17:02 +09:00
parent 6e3a7b21f7
commit 66dc8b29cb
5 changed files with 359 additions and 3 deletions
--- a/SodaLive.xcodeproj/project.pbxproj
+++ b/SodaLive.xcodeproj/project.pbxproj
@@ -284,6 +284,12 @@
 		402D60172BE273BC00766777 /* LiveRoomDonationResponse.swift in Sources */ = {isa = PBXBuildFile; fileRef = 402D60152BE273BC00766777 /* LiveRoomDonationResponse.swift */; };
 		402ECE152FF396E200B4FC34 /* MainHomeRankChangeBadge.swift in Sources */ = {isa = PBXBuildFile; fileRef = 402ECE132FF396E200B4FC34 /* MainHomeRankChangeBadge.swift */; };
 		402ECE162FF396E200B4FC34 /* MainHomeRankChangeBadge.swift in Sources */ = {isa = PBXBuildFile; fileRef = 402ECE132FF396E200B4FC34 /* MainHomeRankChangeBadge.swift */; };
+		402ECE1A2FF39F0900B4FC34 /* MainHomeRankingEmptyStateView.swift in Sources */ = {isa = PBXBuildFile; fileRef = 402ECE182FF39F0900B4FC34 /* MainHomeRankingEmptyStateView.swift */; };
+		402ECE1B2FF39F0900B4FC34 /* MainHomeRankingRow.swift in Sources */ = {isa = PBXBuildFile; fileRef = 402ECE192FF39F0900B4FC34 /* MainHomeRankingRow.swift */; };
+		402ECE1C2FF39F0900B4FC34 /* MainHomeRankingCard.swift in Sources */ = {isa = PBXBuildFile; fileRef = 402ECE172FF39F0900B4FC34 /* MainHomeRankingCard.swift */; };
+		402ECE1D2FF39F0900B4FC34 /* MainHomeRankingEmptyStateView.swift in Sources */ = {isa = PBXBuildFile; fileRef = 402ECE182FF39F0900B4FC34 /* MainHomeRankingEmptyStateView.swift */; };
+		402ECE1E2FF39F0900B4FC34 /* MainHomeRankingRow.swift in Sources */ = {isa = PBXBuildFile; fileRef = 402ECE192FF39F0900B4FC34 /* MainHomeRankingRow.swift */; };
+		402ECE1F2FF39F0900B4FC34 /* MainHomeRankingCard.swift in Sources */ = {isa = PBXBuildFile; fileRef = 402ECE172FF39F0900B4FC34 /* MainHomeRankingCard.swift */; };
 		402FE16B2D50CD99004CFE30 /* AuthResponse.swift in Sources */ = {isa = PBXBuildFile; fileRef = 402FE16A2D50CD99004CFE30 /* AuthResponse.swift */; };
 		402FE16C2D50CD99004CFE30 /* AuthResponse.swift in Sources */ = {isa = PBXBuildFile; fileRef = 402FE16A2D50CD99004CFE30 /* AuthResponse.swift */; };
 		403085AA2D1188B700CB61DE /* GenerateUrlResponse.swift in Sources */ = {isa = PBXBuildFile; fileRef = 403085A92D1188B700CB61DE /* GenerateUrlResponse.swift */; };
@@ -1793,6 +1799,9 @@
 		402C5F192CE24A6B00C07A3E /* LiveRoomHeartRankingItemView.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = LiveRoomHeartRankingItemView.swift; sourceTree = "<group>"; };
 		402D60152BE273BC00766777 /* LiveRoomDonationResponse.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = LiveRoomDonationResponse.swift; sourceTree = "<group>"; };
 		402ECE132FF396E200B4FC34 /* MainHomeRankChangeBadge.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = MainHomeRankChangeBadge.swift; sourceTree = "<group>"; };
+		402ECE172FF39F0900B4FC34 /* MainHomeRankingCard.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = MainHomeRankingCard.swift; sourceTree = "<group>"; };
+		402ECE182FF39F0900B4FC34 /* MainHomeRankingEmptyStateView.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = MainHomeRankingEmptyStateView.swift; sourceTree = "<group>"; };
+		402ECE192FF39F0900B4FC34 /* MainHomeRankingRow.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = MainHomeRankingRow.swift; sourceTree = "<group>"; };
 		402FE16A2D50CD99004CFE30 /* AuthResponse.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = AuthResponse.swift; sourceTree = "<group>"; };
 		403085A92D1188B700CB61DE /* GenerateUrlResponse.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = GenerateUrlResponse.swift; sourceTree = "<group>"; };
 		4033CC6B2D2D096B00412C24 /* AuditionApplicantRecordingView.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = AuditionApplicantRecordingView.swift; sourceTree = "<group>"; };
@@ -2850,6 +2859,9 @@
 		402ECE142FF396E200B4FC34 /* Components */ = {
 			isa = PBXGroup;
 			children = (
+				402ECE172FF39F0900B4FC34 /* MainHomeRankingCard.swift */,
+				402ECE182FF39F0900B4FC34 /* MainHomeRankingEmptyStateView.swift */,
+				402ECE192FF39F0900B4FC34 /* MainHomeRankingRow.swift */,
 				402ECE132FF396E200B4FC34 /* MainHomeRankChangeBadge.swift */,
 			);
 			path = Components;
@@ -5508,6 +5520,9 @@
 				40B93F912A83D94600AE29E2 /* LiveRecommendApi.swift in Sources */,
 				409143492A856CC500EEBFB1 /* NotificationSettingsDialog.swift in Sources */,
 				40B93F4B2A83B97100AE29E2 /* LiveView.swift in Sources */,
+				402ECE1D2FF39F0900B4FC34 /* MainHomeRankingEmptyStateView.swift in Sources */,
+				402ECE1E2FF39F0900B4FC34 /* MainHomeRankingRow.swift in Sources */,
+				402ECE1F2FF39F0900B4FC34 /* MainHomeRankingCard.swift in Sources */,
 				409144622A86221C00EEBFB1 /* UserBlockConfirmDialogView.swift in Sources */,
 				40285B9A2BFB9418006C5BD6 /* CanChargeTempRequest.swift in Sources */,
 				406A11C22A971FCA00D3BD2B /* GetAudioContentOrderListResponse.swift in Sources */,
@@ -6336,6 +6351,9 @@
 				40B93F622A83BC6300AE29E2 /* LiveViewModel.swift in Sources */,
 				40B640632E1FE9B400D0E4E4 /* AudioContentMainItem.swift in Sources */,
 				406B61BD2E66D60B005DEE6B /* ChatRoomEnterResponse.swift in Sources */,
+				402ECE1A2FF39F0900B4FC34 /* MainHomeRankingEmptyStateView.swift in Sources */,
+				402ECE1B2FF39F0900B4FC34 /* MainHomeRankingRow.swift in Sources */,
+				402ECE1C2FF39F0900B4FC34 /* MainHomeRankingCard.swift in Sources */,
 				400EA79E2A8A0EB9004992CF /* LiveReservationAllView.swift in Sources */,
 				4091435A2A85861400EEBFB1 /* GetLiveReservationResponse.swift in Sources */,
 				400EA7F62A8A7426004992CF /* LiveRoomKickOutRequest.swift in Sources */,
--- a/SodaLive/Sources/V2/Main/Home/Ranking/Components/MainHomeRankingCard.swift
+++ b/SodaLive/Sources/V2/Main/Home/Ranking/Components/MainHomeRankingCard.swift
@@ -0,0 +1,193 @@
+import SwiftUI
+
+struct MainHomeRankingCard: View {
+    let item: MainHomeCreatorRankingItem
+    let showRankChange: Bool
+    let columnsPerRow: Int
+    let onTapCreator: (Int) -> Void
+
+    init(
+        item: MainHomeCreatorRankingItem,
+        showRankChange: Bool,
+        columnsPerRow: Int = 1,
+        onTapCreator: @escaping (Int) -> Void = { _ in }
+    ) {
+        self.item = item
+        self.showRankChange = showRankChange
+        self.columnsPerRow = columnsPerRow
+        self.onTapCreator = onTapCreator
+    }
+
+    var body: some View {
+        Button {
+            onTapCreator(item.creatorId)
+        } label: {
+            GeometryReader { proxy in
+                let side = min(proxy.size.width, proxy.size.height)
+
+                ZStack(alignment: .topLeading) {
+                    profileImage(size: CGSize(width: side, height: side))
+
+                    LinearGradient(
+                        colors: [Color.black.opacity(0), Color.black.opacity(0.72)],
+                        startPoint: .top,
+                        endPoint: .bottom
+                    )
+
+                    rankColumn(side: side)
+                        .padding(.leading, rankColumnLeadingPadding(side))
+                        .padding(.top, rankColumnTopPadding(side))
+
+                    VStack {
+                        Spacer()
+
+                        Text(item.nickname)
+                            .appFont(size: nicknameFontSize(side), weight: .bold)
+                            .foregroundColor(.white)
+                            .lineLimit(1)
+                            .truncationMode(.tail)
+                            .frame(maxWidth: .infinity, alignment: .center)
+                            .padding(.horizontal, nicknameHorizontalPadding(side))
+                            .padding(.bottom, nicknameBottomPadding(side))
+                    }
+                }
+                .clipShape(RoundedRectangle(cornerRadius: SodaSpacing.s14, style: .continuous))
+            }
+            .aspectRatio(1, contentMode: .fit)
+        }
+        .buttonStyle(.plain)
+    }
+
+    private func profileImage(size: CGSize) -> some View {
+        DownsampledKFImage(url: URL(string: item.profileImageUrl ?? ""), size: size)
+            .background(Color.gray800)
+    }
+
+    private func rankText(side: CGFloat) -> some View {
+        Text("\(item.rank)")
+            .appFont(size: rankFontSize(side), family: .pattaya)
+            .foregroundStyle(
+                LinearGradient(
+                    colors: [.white, Color.gray200],
+                    startPoint: .top,
+                    endPoint: .bottom
+                )
+            )
+            .shadow(color: Color.black.opacity(0.48), radius: 2)
+    }
+
+    private func rankColumn(side: CGFloat) -> some View {
+        VStack(alignment: .center, spacing: rankColumnSpacing) {
+            rankText(side: side)
+                .frame(maxWidth: .infinity, alignment: .center)
+
+            MainHomeRankChangeBadge(
+                showRankChange: showRankChange,
+                rankChange: item.rankChange,
+                isNew: item.isNew
+            )
+            .frame(maxWidth: .infinity, alignment: .center)
+        }
+        .frame(width: rankColumnWidth(side), alignment: .center)
+    }
+
+    private var rankColumnSpacing: CGFloat {
+        switch columnsPerRow {
+        case 1:
+            return -20
+        case 2:
+            return -10
+        case 3:
+            return -5
+        default:
+            return -20
+        }
+    }
+
+    private func rankFontSize(_ side: CGFloat) -> CGFloat {
+        max(32, side * 0.26)
+    }
+
+    private func nicknameFontSize(_ side: CGFloat) -> CGFloat {
+        max(16, side * 0.085)
+    }
+
+    private func rankColumnWidth(_ side: CGFloat) -> CGFloat {
+        max(49, side * 0.19)
+    }
+
+    private func rankColumnLeadingPadding(_ side: CGFloat) -> CGFloat {
+        max(0, side * 0.035)
+    }
+
+    private func rankColumnTopPadding(_ side: CGFloat) -> CGFloat {
+        max(-8, side * 0.02)
+    }
+
+    private func nicknameHorizontalPadding(_ side: CGFloat) -> CGFloat {
+        max(SodaSpacing.s12, side * 0.11)
+    }
+
+    private func nicknameBottomPadding(_ side: CGFloat) -> CGFloat {
+        max(SodaSpacing.s16, side * 0.09)
+    }
+}
+
+struct MainHomeRankingCard_Previews: PreviewProvider {
+    private static let previewImageUrl = "https://picsum.photos/500/500"
+
+    static var previews: some View {
+        VStack(spacing: SodaSpacing.s20) {
+            MainHomeRankingCard(
+                item: previewItem(rank: 1, rankChange: 5, isNew: false),
+                showRankChange: true
+            )
+            .frame(width: 374)
+
+            HStack(spacing: SodaSpacing.s8) {
+                MainHomeRankingCard(
+                    item: previewItem(rank: 2, rankChange: -3, isNew: false),
+                    showRankChange: true,
+                    columnsPerRow: 2
+                )
+                MainHomeRankingCard(
+                    item: previewItem(rank: 3, rankChange: 0, isNew: false),
+                    showRankChange: true,
+                    columnsPerRow: 2
+                )
+            }
+
+            HStack(spacing: SodaSpacing.s8) {
+                MainHomeRankingCard(
+                    item: previewItem(rank: 8, rankChange: nil, isNew: true),
+                    showRankChange: true,
+                    columnsPerRow: 3
+                )
+                MainHomeRankingCard(
+                    item: previewItem(rank: 9, rankChange: 2, isNew: false),
+                    showRankChange: false,
+                    columnsPerRow: 3
+                )
+                MainHomeRankingCard(
+                    item: previewItem(rank: 10, rankChange: nil, isNew: false),
+                    showRankChange: true,
+                    columnsPerRow: 3
+                )
+            }
+        }
+        .padding(SodaSpacing.s20)
+        .background(Color.black)
+        .previewLayout(.sizeThatFits)
+    }
+
+    private static func previewItem(rank: Int, rankChange: Int?, isNew: Bool) -> MainHomeCreatorRankingItem {
+        MainHomeCreatorRankingItem(
+            rank: rank,
+            rankChange: rankChange,
+            isNew: isNew,
+            creatorId: rank,
+            nickname: "크리에이터이름",
+            profileImageUrl: previewImageUrl
+        )
+    }
+}
--- a/SodaLive/Sources/V2/Main/Home/Ranking/Components/MainHomeRankingEmptyStateView.swift
+++ b/SodaLive/Sources/V2/Main/Home/Ranking/Components/MainHomeRankingEmptyStateView.swift
@@ -0,0 +1,26 @@
+import SwiftUI
+
+struct MainHomeRankingEmptyStateView: View {
+    var body: some View {
+        VStack {
+            Spacer()
+
+            Text(I18n.HomeRanking.emptyStateMessage)
+                .appFont(.body5)
+                .foregroundColor(Color.gray500)
+                .multilineTextAlignment(.center)
+
+            Spacer()
+        }
+        .frame(maxWidth: .infinity)
+        .background(Color.black)
+    }
+}
+
+struct MainHomeRankingEmptyStateView_Previews: PreviewProvider {
+    static var previews: some View {
+        MainHomeRankingEmptyStateView()
+            .frame(width: 390, height: 320)
+            .previewLayout(.sizeThatFits)
+    }
+}
--- a/SodaLive/Sources/V2/Main/Home/Ranking/Components/MainHomeRankingRow.swift
+++ b/SodaLive/Sources/V2/Main/Home/Ranking/Components/MainHomeRankingRow.swift
@@ -0,0 +1,105 @@
+import SwiftUI
+
+struct MainHomeRankingRow: View {
+    let item: MainHomeCreatorRankingItem
+    let showRankChange: Bool
+    let onTapCreator: (Int) -> Void
+
+    init(
+        item: MainHomeCreatorRankingItem,
+        showRankChange: Bool,
+        onTapCreator: @escaping (Int) -> Void = { _ in }
+    ) {
+        self.item = item
+        self.showRankChange = showRankChange
+        self.onTapCreator = onTapCreator
+    }
+
+    var body: some View {
+        Button {
+            onTapCreator(item.creatorId)
+        } label: {
+            GeometryReader { proxy in
+                let rowHeight = proxy.size.height
+                let imageSide = rowHeight * 0.8
+
+                HStack(alignment: .center, spacing: SodaSpacing.s14) {
+                    rankColumn
+
+                    DownsampledKFImage(
+                        url: URL(string: item.profileImageUrl ?? ""),
+                        size: CGSize(width: imageSide, height: imageSide)
+                    )
+                    .background(Color.gray800)
+                    .aspectRatio(1, contentMode: .fit)
+                    .clipShape(RoundedRectangle(cornerRadius: SodaSpacing.s14, style: .continuous))
+
+                    Text(item.nickname)
+                        .appFont(.heading4)
+                        .foregroundColor(.white)
+                        .lineLimit(1)
+                        .truncationMode(.tail)
+                        .frame(maxWidth: .infinity, alignment: .leading)
+                }
+                .padding(.horizontal, SodaSpacing.s14)
+                .padding(.vertical, rowHeight * 0.1)
+            }
+            .aspectRatio(3.74, contentMode: .fit)
+            .background(Color.black)
+        }
+        .buttonStyle(.plain)
+    }
+
+    private var rankColumn: some View {
+        VStack(alignment: .center, spacing: 0) {
+            Text("\(item.rank)")
+                .appFont(size: 40, family: .pattaya)
+                .foregroundStyle(
+                    LinearGradient(
+                        colors: [.white, Color.gray200],
+                        startPoint: .top,
+                        endPoint: .bottom
+                    )
+                )
+                .shadow(color: Color.black.opacity(0.48), radius: 2)
+                .lineLimit(1)
+                .frame(maxWidth: .infinity, alignment: .center)
+
+            MainHomeRankChangeBadge(
+                showRankChange: showRankChange,
+                rankChange: item.rankChange,
+                isNew: item.isNew
+            )
+            .frame(maxWidth: .infinity, alignment: .center)
+        }
+        .frame(width: 49, alignment: .center)
+    }
+}
+
+struct MainHomeRankingRow_Previews: PreviewProvider {
+    private static let previewImageUrl = "https://picsum.photos/500/500"
+
+    static var previews: some View {
+        VStack(spacing: SodaSpacing.s8) {
+            MainHomeRankingRow(item: previewItem(rank: 11, rankChange: 5, isNew: false), showRankChange: true)
+            MainHomeRankingRow(item: previewItem(rank: 12, rankChange: -3, isNew: false), showRankChange: true)
+            MainHomeRankingRow(item: previewItem(rank: 13, rankChange: 0, isNew: false), showRankChange: true)
+            MainHomeRankingRow(item: previewItem(rank: 14, rankChange: nil, isNew: true), showRankChange: true)
+            MainHomeRankingRow(item: previewItem(rank: 15, rankChange: 2, isNew: false), showRankChange: false)
+        }
+        .padding(SodaSpacing.s20)
+        .background(Color.black)
+        .previewLayout(.sizeThatFits)
+    }
+
+    private static func previewItem(rank: Int, rankChange: Int?, isNew: Bool) -> MainHomeCreatorRankingItem {
+        MainHomeCreatorRankingItem(
+            rank: rank,
+            rankChange: rankChange,
+            isNew: isNew,
+            creatorId: rank,
+            nickname: "크리에이터이름",
+            profileImageUrl: previewImageUrl
+        )
+    }
+}
--- a/docs/20260630_메인_홈_랭킹_탭/plan-task.md
+++ b/docs/20260630_메인_홈_랭킹_탭/plan-task.md
@@ -175,7 +175,7 @@

 ### Phase 5: 순위별 랭킹 UI 컴포넌트

- [ ] **Task 5.1: 1~10위 공용 카드 컴포넌트 생성**
+- [x] **Task 5.1: 1~10위 공용 카드 컴포넌트 생성**
  - 대상 파일:
    - 생성: `SodaLive/Sources/V2/Main/Home/Ranking/Components/MainHomeRankingCard.swift`
    - 확인: `SodaLive/Sources/V2/Component/Creator/CreatorProfileItem.swift`
@@ -197,7 +197,7 @@
    - 실행 명령: `rg "struct MainHomeRankingCard|DownsampledKFImage|LinearGradient|item.rank|MainHomeRankChangeBadge|onTapCreator\\(item.creatorId\\)|aspectRatio|PreviewProvider|rankChange: 5|rankChange: -|rankChange: 0|isNew: true|showRankChange: false" SodaLive/Sources/V2/Main/Home/Ranking/Components/MainHomeRankingCard.swift`
    - 기대 결과: 1~10위 카드가 하나의 공용 컴포넌트로 구현되고, 서버 rank와 공용 badge를 사용하며, 전체 크기는 부모 layout에 의해 결정되고 조건별 Preview가 확인된다.

- [ ] **Task 5.2: 11위 이상 row 컴포넌트 생성**
+- [x] **Task 5.2: 11위 이상 row 컴포넌트 생성**
  - 대상 파일:
    - 생성: `SodaLive/Sources/V2/Main/Home/Ranking/Components/MainHomeRankingRow.swift`
  - 작업 내용:
@@ -213,7 +213,7 @@
    - 실행 명령: `rg "struct MainHomeRankingRow|DownsampledKFImage|item.rank|MainHomeRankChangeBadge|onTapCreator\\(item.creatorId\\)|aspectRatio|PreviewProvider|rankChange: 5|rankChange: -|rankChange: 0|isNew: true|showRankChange: false" SodaLive/Sources/V2/Main/Home/Ranking/Components/MainHomeRankingRow.swift`
    - 기대 결과: row형 순위 UI가 서버 rank와 공용 badge를 사용하고, 전체 크기는 반응형 제약으로 구성되며 조건별 Preview가 확인된다.

- [ ] **Task 5.3: empty state 컴포넌트 생성**
+- [x] **Task 5.3: empty state 컴포넌트 생성**
  - 대상 파일:
    - 생성: `SodaLive/Sources/V2/Main/Home/Ranking/Components/MainHomeRankingEmptyStateView.swift`
  - 작업 내용:
@@ -359,3 +359,17 @@
  - 검증 메모:
    - 문서의 Phase 4 정적 검색 기준으로 아이콘명, 조건별 Preview, `abs()` 사용을 확인
    - Figma badge 배경 기준 확인 후 `Color.gray900`(`#202020`) 배경, horizontal padding 4, corner radius 4를 `MainHomeRankChangeBadge`에 반영
+
+- 2026-06-30 Phase 5 진행:
+  - 목적: 랭킹 순위별 UI 조립에 사용할 카드/row/empty state 컴포넌트 추가
+  - 확인한 기준:
+    - Figma `24:5659`, `24:5670` 기준 카드/row 구조 확인
+    - 기존 V2 추천 탭의 `DownsampledKFImage`, `LinearGradient`, `SodaSpacing`, `Color.gray*`, `.buttonStyle(.plain)` 사용 관례 확인
+  - 변경 내용:
+    - `MainHomeRankingCard` 추가: 1~10위 공용 카드, 서버 `item.rank`, 하단 dim gradient, `MainHomeRankChangeBadge`, creator tap callback 사용
+    - `MainHomeRankingRow` 추가: 11위 이상 row, 서버 `item.rank`, 프로필 이미지, nickname, `MainHomeRankChangeBadge`, creator tap callback 사용
+    - `MainHomeRankingEmptyStateView` 추가: `I18n.HomeRanking.emptyStateMessage`를 검정 배경 위에 표시
+    - Phase 5 Preview에 상승, 하락, 변동 없음, 신규 진입, 순위 변화 숨김 상태 추가
+  - 검증 메모:
+    - 문서의 Phase 5 정적 검색 기준으로 카드/row/empty state 필수 심볼과 Preview 상태를 확인
+    - 카드/row 루트 container에 고정 숫자 `frame(width:)`, `frame(height:)`를 두지 않고, 카드 전체 비율은 `aspectRatio` 기반으로 구성