From 0415fa937792234bba3cf29c433317fc6067453a Mon Sep 17 00:00:00 2001 From: caadiq Date: Mon, 12 Jan 2026 19:03:12 +0900 Subject: [PATCH] =?UTF-8?q?=EB=AC=B8=EC=84=9C:=20=EA=B3=A1=20=EC=83=81?= =?UTF-8?q?=EC=84=B8=20=ED=99=94=EB=A9=B4=20=EA=B5=AC=ED=98=84=20=EB=82=B4?= =?UTF-8?q?=EC=9A=A9=20=EC=B6=94=EA=B0=80=20(handover.md,=20PROJECT=5FSTRU?= =?UTF-8?q?CTURE.md)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/PROJECT_STRUCTURE.md | 80 +++++++++++++++++++++++++++++++-------- docs/handover.md | 18 ++++++++- 2 files changed, 81 insertions(+), 17 deletions(-) diff --git a/docs/PROJECT_STRUCTURE.md b/docs/PROJECT_STRUCTURE.md index 532ea57..47a33d5 100644 --- a/docs/PROJECT_STRUCTURE.md +++ b/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 추천 검색어 시스템 구현 | -| `9c2ff74` | Admin Schedule 추천 검색어 연동 + 빈 상태 드롭다운 숨김 | -| `2ad5341` | Mobile Schedule 추천 검색어 API 연동 | -| `8e3cab9` | 기본 카테고리 보호 및 ID 재정렬 | -| `de2e02f` | 모바일 앨범 상세 UI 개선 | -| `d6bc8d7` | 모바일 앨범 갤러리 UI 대폭 개선 (Swiper, 뒤로가기 등) | -| `bf6b7f7` | 앱: 앨범 화면 2열 그리드 레이아웃 개선, 탭 전환 시 앨범 스택 리셋 | +| 커밋 | 설명 | +| --------- | ---------------------------------------------------------- | +| `7e570d3` | 모바일 곡 상세: 뒤로가기 헤더 제거 | +| `db6949d` | 모바일 곡 상세: YouTube 전체화면 시 자동 가로 회전 시도 | +| `5f2c86b` | 모바일 곡 상세: 가사 더보기/접기 기능 추가, 하단 여백 조정 | +| `e5d4036` | 모바일: 곡 상세 화면 구현 (TrackDetail 페이지) | +| `67cd681` | PC 곡 상세: TITLE 배지를 노래 제목 옆으로 이동 | +| `0232edc` | PC 곡 상세: 수록곡 섹션 디자인 개선 | +| `4e52f79` | 백엔드: 트랙 상세 API 라우트 순서 수정 | +| `b18183a` | 웹: PC 곡 상세 화면 구현 (TrackDetail 페이지) | +| `dc65858` | 웹: AlbumDetail, AlbumGallery 페이지 useQuery로 리팩토링 | ### 주요 변경 사항 -1. **추천 검색어 시스템**: Redis bi-gram 기반 자동완성 -2. **모바일 앨범 갤러리**: Swiper ViewPager + LightboxIndicator -3. **뒤로가기 처리**: History API로 모달/라이트박스 닫기 -4. **카테고리 보호**: 시스템 기본 카테고리 삭제 방지 -5. **앱 앨범 스택 리셋**: 탭 전환 시 목록으로 자동 복귀 +1. **곡 상세 화면 (PC/Mobile)**: 트랙 정보, 크레딧, 가사, 수록곡 목록, 뮤직비디오 임베드 +2. **트랙 상세 API**: `/api/albums/by-name/:albumName/track/:trackTitle` 엔드포인트 추가 +3. **useQuery 리팩토링**: AlbumDetail, AlbumGallery 페이지에 @tanstack/react-query 적용 +4. **모바일 UX 개선**: 가사 더보기/접기, YouTube 전체화면 시 자동 가로 회전 + +--- + +## 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')` diff --git a/docs/handover.md b/docs/handover.md index e6dcd22..9ec101a 100644 --- a/docs/handover.md +++ b/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" ```