문서: 곡 상세 화면 구현 내용 추가 (handover.md, PROJECT_STRUCTURE.md)

docs/PROJECT_STRUCTURE.md

@@ -781,22 +781,72 @@ npx expo run:android --variant release
 
 ## 16. 오늘 작업 요약 (2026-01-11 ~ 2026-01-12)
 
-### 커밋 히스토리
+### 최근 커밋 히스토리
 
-| 커밋      | 설명                                                              |
+| 커밋      | 설명                                                       |
-| --------- | ----------------------------------------------------------------- |
+| --------- | ---------------------------------------------------------- |
-| `727b05f` | Redis 기반 bi-gram 추천 검색어 시스템 구현                        |
+| `7e570d3` | 모바일 곡 상세: 뒤로가기 헤더 제거                         |
-| `9c2ff74` | Admin Schedule 추천 검색어 연동 + 빈 상태 드롭다운 숨김           |
+| `db6949d` | 모바일 곡 상세: YouTube 전체화면 시 자동 가로 회전 시도    |
-| `2ad5341` | Mobile Schedule 추천 검색어 API 연동                              |
+| `5f2c86b` | 모바일 곡 상세: 가사 더보기/접기 기능 추가, 하단 여백 조정 |
-| `8e3cab9` | 기본 카테고리 보호 및 ID 재정렬                                   |
+| `e5d4036` | 모바일: 곡 상세 화면 구현 (TrackDetail 페이지)             |
-| `de2e02f` | 모바일 앨범 상세 UI 개선                                          |
+| `67cd681` | PC 곡 상세: TITLE 배지를 노래 제목 옆으로 이동             |
-| `d6bc8d7` | 모바일 앨범 갤러리 UI 대폭 개선 (Swiper, 뒤로가기 등)             |
+| `0232edc` | PC 곡 상세: 수록곡 섹션 디자인 개선                        |
-| `bf6b7f7` | 앱: 앨범 화면 2열 그리드 레이아웃 개선, 탭 전환 시 앨범 스택 리셋 |
+| `4e52f79` | 백엔드: 트랙 상세 API 라우트 순서 수정                     |
+| `b18183a` | 웹: PC 곡 상세 화면 구현 (TrackDetail 페이지)              |
+| `dc65858` | 웹: AlbumDetail, AlbumGallery 페이지 useQuery로 리팩토링   |
 
 ### 주요 변경 사항
 
-1. **추천 검색어 시스템**: Redis bi-gram 기반 자동완성
+1. **곡 상세 화면 (PC/Mobile)**: 트랙 정보, 크레딧, 가사, 수록곡 목록, 뮤직비디오 임베드
-2. **모바일 앨범 갤러리**: Swiper ViewPager + LightboxIndicator
+2. **트랙 상세 API**: `/api/albums/by-name/:albumName/track/:trackTitle` 엔드포인트 추가
-3. **뒤로가기 처리**: History API로 모달/라이트박스 닫기
+3. **useQuery 리팩토링**: AlbumDetail, AlbumGallery 페이지에 @tanstack/react-query 적용
-4. **카테고리 보호**: 시스템 기본 카테고리 삭제 방지
+4. **모바일 UX 개선**: 가사 더보기/접기, YouTube 전체화면 시 자동 가로 회전
-5. **앱 앨범 스택 리셋**: 탭 전환 시 목록으로 자동 복귀
+
+---
+
+## 17. 곡 상세 화면 (TrackDetail)
+
+### API 엔드포인트
+
+| 엔드포인트                                         | 메서드 | 설명                  |
+| -------------------------------------------------- | ------ | --------------------- |
+| `/api/albums/by-name/:albumName/track/:trackTitle` | GET    | 트랙 상세 + 앨범 정보 |
+
+### 반환 데이터
+
+```json
+{
+  "id": 1,
+  "title": "LIKE YOU BETTER",
+  "track_number": 1,
+  "is_title_track": 1,
+  "duration": "3:05",
+  "lyrics": "...",
+  "lyricist": "Tomy, HANIHAS(XYXX), ...",
+  "composer": "HONEY NOISE, ...",
+  "arranger": "...",
+  "music_video_url": "https://youtube.com/...",
+  "album": {
+    "id": 7,
+    "title": "From Our 20's",
+    "album_type": "미니 6집",
+    "cover_medium_url": "..."
+  },
+  "otherTracks": [...]
+}
+```
+
+### 파일 구조
+
+| 플랫폼 | 파일 경로                                          | 주요 기능                       |
+| ------ | -------------------------------------------------- | ------------------------------- |
+| PC     | `frontend/src/pages/pc/public/TrackDetail.jsx`     | 크레딧, 가사, 수록곡, MV 임베드 |
+| Mobile | `frontend/src/pages/mobile/public/TrackDetail.jsx` | 가사 더보기/접기, 자동 회전     |
+
+### 주요 기능
+
+- **뮤직비디오 임베드**: is_title_track인 경우 YouTube 영상 표시
+- **크레딧 줄바꿈**: 쉼표 기준으로 각 항목 분리
+- **가사 더보기 (모바일)**: 기본 일부만 표시, 버튼으로 전체 펼침
+- **수록곡 목록 (PC)**: 현재 곡 강조, 재생 시간 표시
+- **자동 가로 회전 (모바일)**: YouTube 전체화면 시 `screen.orientation.lock('landscape')`

docs/handover.md

@@ -1,6 +1,7 @@
 # fromis_9 프로젝트 인수인계서
 
 ## 프로젝트 개요
+
 fromis_9 K-pop 아이돌 팬사이트 - 웹 프론트엔드, 백엔드 API, 모바일 앱으로 구성
 
 ---
@@ -20,15 +21,17 @@ fromis_9 K-pop 아이돌 팬사이트 - 웹 프론트엔드, 백엔드 API, 모
 ## 2. 웹 프론트엔드 (`/frontend`)
 
 ### 기술 스택
+
 - React + Vite
 - TailwindCSS
 - framer-motion (애니메이션)
 
 ### 주요 경로
+
 - `src/pages/` - 페이지 컴포넌트
-  - `public/` - 공개 페이지 (Home, Members, Album 등)
+  - `pc/public/` - PC 공개 페이지 (Home, Members, Album, AlbumDetail, TrackDetail 등)
   - `mobile/public/` - 모바일 전용 페이지
-  - `admin/` - 관리자 페이지
+  - `pc/admin/` - 관리자 페이지
 - `src/api/` - API 호출 함수
 - `src/components/` - 재사용 컴포넌트
 
@@ -37,11 +40,13 @@ fromis_9 K-pop 아이돌 팬사이트 - 웹 프론트엔드, 백엔드 API, 모
 ## 3. 백엔드 (`/backend`)
 
 ### 기술 스택
+
 - Express.js
 - MariaDB (mysql2)
 - RustFS (파일 스토리지)
 
 ### 주요 경로
+
 - `routes/` - API 라우트
   - `public/` - 공개 API
   - `admin/` - 관리자 API
@@ -52,12 +57,14 @@ fromis_9 K-pop 아이돌 팬사이트 - 웹 프론트엔드, 백엔드 API, 모
 ## 4. 모바일 앱 (`/app`)
 
 ### 기술 스택
+
 - **Expo** (React Native)
 - **TypeScript**
 - React Navigation (탭 + 스택 네비게이션)
 - expo-blur, expo-linear-gradient (UI 효과)
 
 ### 주요 경로
+
 ```
 app/src/
 ├── api/               # API 호출 함수
@@ -80,6 +87,7 @@ app/src/
 ```
 
 ### 네비게이션 구조
+
 ```
 TabNavigator (하단 탭)
 ├── HomeTab → HomeScreen
@@ -92,17 +100,20 @@ TabNavigator (하단 탭)
 ```
 
 ### 주요 기능
+
 - **탭 전환 시 앨범 스택 리셋**: 다른 탭 갔다가 앨범 탭 클릭 시 목록으로 돌아감
 - **AlbumGalleryScreen**: 웹과 1:1 동일한 컨셉포토 갤러리 (PagerView 라이트박스, 다운로드)
 - **MembersScreen**: 바텀시트 모달, 전 멤버 흑백 처리
 
 ### 개발 서버 실행
+
 ```bash
 cd /docker/fromis_9/app
 npx expo start --lan
 ```
 
 ### APK 빌드
+
 ```bash
 npx expo run:android --variant release
 # 또는 로컬 빌드
@@ -114,12 +125,14 @@ npx expo run:android --variant release
 ## 5. 분석 절차
 
 ### 5.1 코드 전수 조사
+
 ```bash
 # 프로젝트 구조 확인
 find /docker/fromis_9 -type f -name "*.js" -o -name "*.jsx" -o -name "*.ts" -o -name "*.tsx" | head -50
 ```
 
 ### 5.2 DB 구조 파악
+
 ```bash
 # .env에서 DB 정보 확인
 cat /docker/fromis_9/.env
@@ -135,6 +148,7 @@ DESCRIBE [table_name];
 ```
 
 ### 5.3 Caddy 설정 확인
+
 ```bash
 cat /docker/caddy/Caddyfile | grep -A 20 "fromis9"
 ```