[Feat] #166 - 서재 화면 구현 (내 서재·타유저 서재·조회 V2 계약)

[Naknakk]

💡 Issue

closed #166

💭 Summary

서재 화면(LibraryFeature)을 새로 구현했습니다. 내 서재와 타유저 서재 두 화면이고, 이 화면을 붙이면서 필요해진 조회 V2 계약과 UI 공용 컴포넌트 정리를 함께 담았습니다.

🔑 Key Changes

LibraryFeature (신규)

• 내 서재는 탭 콘텐츠, 타유저 서재는 push 화면입니다. 작품 목록을 그리드/리스트로 본다는 뼈대가 같아 셀과 정렬 시트를 공유하고, 상단 구성과 필터 유무가 다릅니다(타유저 서재는 정렬만).
• 내 서재: 필터 칩 7종(관심 + 시트 필터 6종), 그리드/리스트 캡슐 세그먼트, 카운트·알림관리·정렬 행.
• 필터 시트는 6탭(읽기상태·장르·연재상태·별점·매력포인트·키워드)에 별점 범위 슬라이더가 붙습니다. 시트는 필터 복사본을 편집하고 "작품 찾기"에서 부모로 올립니다(ReadingPeriodSheet 패턴). 시트 높이가 고정이라 탭 콘텐츠가 남은 공간을 차지하고 넘치면 그 안에서 스크롤합니다.
• 커서 무한 스크롤. 필터·정렬을 빠르게 여러 번 바꿔도 목록이 꼬이지 않도록 요청에 세대 번호를 매기고, 응답 시점에 세대가 다르면 버립니다(늦게 온 이전 결과가 새 목록을 덮는 것 방지).
• 에러 3분화: 첫 페이지 실패는 헤더만 남기고 실패 뷰로 대체, 더보기·키워드 실패는 토스트, 인증 만료는 onAuthenticationRequired 콜백.
• 빈 상태 2분화: 서재가 빈 것("웹소설 찾기" CTA)과 필터로 0건인 것("해당하는 작품이 없어요")은 사용자가 할 행동이 달라 분리했습니다.
• 인증 만료 처리가 두 화면에서 다릅니다. 내 서재는 탭이라 다시 들어오면 onAppear로 복구되지만, 타유저 서재는 push라 그 경로가 없어 그대로 두면 "보관함이 비어있어요"로 굳고 재시도 버튼도 없습니다. 타유저 서재는 인증 만료도 실패 뷰로 덮습니다.
• 그리드↔리스트 스크롤 위치 분리: 스크롤 뷰 하나에서 콘텐츠만 갈아끼우면 SwiftUI가 정체성을 유지해 contentOffset이 두 모드에 공유됩니다(그리드에서 내린 만큼 리스트도 내려감). 배포 타깃이 iOS 17이라 ScrollPosition(18+)을 쓸 수 없어 두 스크롤 뷰를 동시에 살려두고 숨기는 방식으로 해결했습니다.
• requiresAuthentication 신호는 View가 소비 후 되돌립니다. 서재는 탭 콘텐츠라 VM이 앱 세션 내내 살아서, 신호가 굳으면 2회차 만료가 조용히 삼켜집니다(push 후 dismiss되는 NovelDetail·NovelReview와 다른 지점).
• Demo: mock 시나리오 + 실서버 모드(키워드 캐시 준비 후 화면 세움).

Domain (NovelDomain)

• CursorPaginated 추가 — 서재는 페이지 번호가 아니라 서버 발급 커서(nextCursor)를 그대로 왕복합니다.
• LibrarySortType 추가(6종: 등록 최신·오래된순, 작품명, 읽은 날짜, 별점 높은·낮은순). 공용 SortType(2종)과 별개이며, 타유저 서재도 같은 6종을 씁니다.
• LibraryRatingFilter 추가 — 범위 + "별점 없음" 2가지 형태로, 검색의 NovelRatingThreshold(이상 4단계)와 다른 타입입니다. 전체 범위(0.0~5.0)는 setRatingRange가 nil로 정규화해 "필터 없음"의 표현을 하나로 유지합니다.
• MyLibraryFilter 확장 — 시트 필터 6종 + 관심 토글 + 정렬. clearAll()(시트 "초기화")은 시트 필터 6종만 리셋하고 관심·정렬은 유지합니다(시트 소속이 아님).
• LoadMyLibraryKeywordsUseCase 신규 — 필터 시트 키워드 탭 데이터(내가 서재 작품에 등록한 키워드).
• LoadMyLibraryUseCase·LoadUserLibraryUseCase가 (filter:cursor:) + 키워드 캐시를 받도록 바뀌었습니다.
• 테스트: 필터 정책(추가·제거·중복·경계값·정규화·초기화 범위), 조회 UseCase 3종(커서 전달·전체 개수·에러·키워드 캐시 폴백).

Data (NovelData)

• 서재 조회 V2 엔드포인트(/users/{id}/novels/v2) 연동 — UserLibraryV2Query, 응답 DTO 2종 추가.
• 내 서재와 타유저 서재가 같은 엔드포인트를 씁니다. 차이는 경로에 넣는 userID뿐이고(내 서재는 저장된 userID, 타유저는 인자로 받은 UserID) 쿼리·응답·매퍼를 공유합니다.
• V2 쿼리 주의점: 미적용 필터는 nil로 보내 파라미터를 생략합니다(빈 배열을 넣으면 ?genres=로 직렬화돼 서버가 [""] 필터로 오해). isInterest는 true일 때만 전송합니다(false를 보내면 "비관심만" 필터가 됨). genres는 영문 라벨, keywords는 한글 이름으로 검색 API의 keywordIds와 다릅니다.
• 서버가 서재 응답의 키워드를 이름만 내려줘서, 전체 키워드 캐시에서 ID를 찾아 Keyword로 복원합니다.
• 구 V1 경로(/users/{id}/novels)는 타유저 서재를 V2로 옮기면서 호출자가 사라졌습니다. V1은 lastUserNovelId: 0 하드코딩이라 애초에 첫 페이지 고정·필터 무시였습니다.
• Networking: JSON body 로그를 가독성 있게 정렬(DefaultNetworkLogger).

UI (WSSComponent·DesignSystem)

• WSSAsyncImage·WSSNovelCoverImage 추가: AsyncImage는 뷰 정체성이 바뀔 때마다 .empty phase부터 다시 시작해 캐시 히트여도 placeholder가 한 프레임 번쩍입니다(목록 셀 재활용·모드 토글에서 매번 도짐). 디코딩된 UIImage를 인메모리 캐시에 두고 렌더 경로에서 동기 조회하도록 만들어 첫 프레임부터 실제 표지가 나옵니다. NovelDetail 대형 표지가 자체 prefetch로 풀던 문제를 컴포넌트로 일반화한 것이라, 그쪽 복제 코드는 제거했습니다.
• enableSwipeBack 추가: 커스텀 헤더를 쓰려고 네비바를 숨기면(.toolbar(.hidden, for: .navigationBar)) iOS가 스와이프 뒤로가기도 함께 끕니다. 이를 되살리는 코드가 NovelDetailFeature·LibraryFeature에 각각 복제돼 있다가 한쪽만 고쳐지며 갈라져 사고가 나서, WSSComponent로 통합했습니다.
  • 기존에는 제스처 delegate를 별도 Coordinator가 갖고 화면을 떠날 때 반납하는 구조였는데, UIGestureRecognizer.delegate가 약한 참조라 그 객체가 해제되면 nil이 되고 UIKit이 스스로 되돌리지 않습니다. 그러면 shouldBegin 기본값(YES)이 적용돼 루트에서도 pop 전환이 시작되고 내비게이션이 얼어붙습니다(앱 재시작 외 복구 불가). 지금은 네비게이션 컨트롤러 자신이 delegate를 맡습니다 — 스택이 사는 내내 살아 있어 반납·경합 가드·복제본 동기화가 통째로 필요 없어집니다.
  • delegate를 맡은 대가로 UIKit 기본 판단을 직접 챙깁니다: 루트 가드, 전환 진행 중 차단, 뒤로가기 버튼을 숨긴 화면 차단. 마지막 것은 NovelReviewView가 "작성 중 나가면 확인 알럿"을 그 성질에 기대고 있어 빠뜨리면 초안이 확인 없이 사라집니다. 두 modifier가 서로 다른 플래그를 건드린다는 점(.toolbar(.hidden)은 hidesBackButton = false, .navigationBarBackButtonHidden(true)는 true)은 시뮬레이터 로그로 확인했습니다.
• 테두리 stroke → strokeBorder 전면 전환: stroke는 선을 shape 경로 중앙에 그려 lineWidth 1이면 0.5pt가 프레임 밖으로 나갑니다. 컴포넌트를 ScrollView 안에 넣는 순간 바깥 절반이 클립돼 테두리가 잘려 보입니다(서재 필터 칩·필터 시트 키워드 칩에서 발생). 공용 컴포넌트는 어디에 놓일지 모르니 기본값을 strokeBorder로 잡았습니다.
• 아이콘 추가 — icAlarm · icBookRegister · icReset · icHeartFilledStroke.

Tuist·문서

• library 모듈 등록.
• LibraryFeature·NovelData·NovelDomain·WSSComponent·UI·Feature CLAUDE.md, README, ARCHITECTURE, BUILD_AND_TEST 갱신.
• new-feature 스킬에 동작 계약 게이트를 추가했습니다(design-gap-checklist). 정적 Figma로는 안 잡히는 것(스크롤 고정 영역·로딩/빈/실패 분화·탭 결과 등)을 구현 전에 질문으로 확정하고, 모듈 CLAUDE.md의 "화면 동작 계약" 절에 정본으로 남기는 흐름입니다. 이번 타유저 서재에서 실제로 사용했습니다.

📱 Simulation

🧑‍🧒‍🧒 To Reviewer

확인 부탁드릴 것

• 스와이프 뒤로가기는 손으로 확인이 필요합니다. 시뮬레이터 자동화로는 판정 함수가 아예 호출되지 않아 검증이 안 되고, 이 delegate는 화면 하나가 아니라 네비게이션 스택 전체에 영향을 줍니다.
  • 타유저 서재를 다녀온 뒤, 네비바가 보이는 일반 화면에서 스와이프가 정상인지
  • 셀을 탭해 화면 전환 애니메이션이 도는 중 스와이프 → 스택이 깨지지 않는지
  • 리뷰 작성 화면에서 입력 후 스와이프 → "그만하기" 알럿이 떠야 합니다(그냥 닫히면 초안 손실). App 조립이 없어 지금은 재현되지 않지만, 작품 상세 → 리뷰 작성이 한 스택에 묶이면 실제가 됩니다.
• enableSwipeBack은 UINavigationController에 제스처 준수를 붙이는 방식이라 import만으로 앱 전역에 영향이 갑니다(다른 컴포넌트는 쓸 때만 영향). 정의는 WSSComponent 한 곳에만 두고 UI 레이어에 둔 근거를 Projects/UI/CLAUDE.md에 적었는데, 이 판단에 이견 있으시면 말씀해 주세요. 대안으로 associated object 방식이 있으나 지금 구조를 바꿀 만큼 급하진 않다고 봤습니다.
• 서재 정렬을 6종으로 한 것은 Figma 시안("최신 순" 공용 2종)과 다른 의도된 결정입니다. 타유저 서재도 6종으로 맞췄습니다.
• MyLibraryFilter 정책 테스트와 조회 UseCase 테스트가 이번에 추가됐습니다. 테스트 그린 확인 부탁드립니다.

App 조립 시 주의

• fetchKeywords()는 네트워크를 타지 않고 로컬 캐시만 읽습니다. 앱 시작 시 syncKeywords()를 먼저 호출하지 않으면 서재·작품 상세의 키워드가 오류 없이 빈 채로 뜹니다. 화면에 에러가 안 나타나 원인 찾기 어려운 종류라 NovelDomain/CLAUDE.md에 적어뒀습니다.
• Projects/App/에 아직 UseCase 조립 코드가 없어 Demo 앱이 그 역할을 합니다(다른 Feature 모듈과 동일한 상황).

후속으로 넘기는 것

• NovelData에 구 V1 조회 코드(getUserLibraryNovels·UserLibraryQuery·UserLibraryNovelsResponse·libraryNovels(from:))가 호출자 없이 public으로 남아 있습니다. 주워 쓰면 첫 페이지 고정·필터 무시를 그대로 물려받아 문서에 경고만 달아뒀고, 정리는 별도로 하겠습니다.
• 타유저 서재를 떠날 때 진행 중인 요청을 취소하지 않습니다. 죽은 화면에 쓰는 것뿐이라 크래시는 아니고 자원 문제입니다.
• 서재 필터 칩은 화면 전용 크기(h30)라 WSSComponent WSSFilterButton(h33)과 다릅니다. 디자인이 화면별로 다르게 잡힌 결과라 컴포넌트로 합치지 않았습니다.

※ Reference

구 WSSiOS(UIKit)를 기준으로 삼은 것들입니다.

• 필터 시트 레이아웃 — LibraryFilterView. 시트 높이가 고정인데 탭마다 콘텐츠 높이가 크게 달라, 탭 영역이 남은 공간을 차지하고 넘치면 그 안에서 스크롤하는 구조를 그대로 따랐습니다.
• 별점 슬라이더 — WSSRangeSlider. 트랙을 핸들 반지름만큼 안쪽으로 잡아 0.0/5.0에서 핸들이 잘리지 않게 합니다.
• 스와이프 뒤로가기 — UIViewController+.swift(swipeBackGesture() + gestureRecognizerShouldBegin). "반납하지 않고 각 뷰컨트롤러가 delegate를 맡는다"는 아이디어의 출처입니다.