caadiq/fromis_9
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: 관리자 마이그레이션 계획서 추가 및 완료된 문서 삭제

Browse source 
- 관리자 페이지 마이그레이션 계획서 추가 (admin-migration.md)
- 완료된 백엔드 리팩토링 문서 삭제
- 완료된 코드 개선 문서 삭제
- 파비콘 복사

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
caadiq 2026-01-22 18:27:52 +09:00
parent 772eda21e0
commit 58f359adfa
4 changed files with 542 additions and 1331 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

542
docs/admin-migration.md Normal file
View file

@ -0,0 +1,542 @@
# 관리자 페이지 마이그레이션 계획서
## 개요
- **목표**: `frontend/src/pages/pc/admin/` → `frontend-temp/src/pages/admin/`
- **현재 규모**: 12개 파일, 약 7,535 LOC
- **방식**: 일반 페이지와 동일한 Strangler Fig Pattern 적용
- **특이사항**: PC 전용 (모바일 관리자 페이지 없음)
---
## 현재 구조 분석
### 관리자 페이지 (12개)
| 파일 | LOC | 설명 | 복잡도 |
|------|-----|------|--------|
| AdminLogin.jsx | 168 | 로그인 폼 | 낮음 |
| AdminDashboard.jsx | 167 | 대시보드 (통계) | 낮음 |
| AdminMembers.jsx | 180 | 멤버 목록 | 낮음 |
| AdminMemberEdit.jsx | 382 | 멤버 수정 폼 | 중간 |
| AdminAlbums.jsx | 222 | 앨범 목록 | 낮음 |
| AdminAlbumForm.jsx | 666 | 앨범 생성/수정 폼 | 높음 |
| AdminAlbumPhotos.jsx | 1,538 | 사진 업로드 (SSE) | 매우 높음 |
| AdminSchedule.jsx | 1,465 | 일정 목록/검색 | 매우 높음 |
| AdminScheduleForm.jsx | 1,173 | 일정 생성/수정 폼 | 높음 |
| AdminScheduleCategory.jsx | 463 | 카테고리 관리 | 중간 |
| AdminScheduleDict.jsx | 664 | 일정 사전 관리 | 중간 |
| AdminScheduleBots.jsx | 447 | 봇 관리 | 중간 |
### 관리자 컴포넌트 (3개)
| 파일 | 설명 |
|------|------|
| AdminLayout.jsx | 관리자 레이아웃 (헤더 + 본문) |
| AdminHeader.jsx | 관리자 헤더 (네비게이션) |
| NumberPicker.jsx | 숫자 입력 컴포넌트 |
### 관리자 API (8개)
| 파일 | 설명 |
|------|------|
| auth.js | 로그인/인증 |
| albums.js | 앨범 CRUD |
| members.js | 멤버 CRUD |
| schedules.js | 일정 CRUD |
| categories.js | 카테고리 CRUD |
| suggestions.js | 검색어 추천 관리 |
| bots.js | 봇 관리 |
| stats.js | 통계 조회 |
---
## 마이그레이션 전략
### 우선순위
복잡도와 의존성을 고려하여 순차적으로 진행:
1. **1단계**: 폴더 구조 재편 (기존 파일을 새 구조로 이동)
2. **2단계**: 관리자 기반 설정 (레이아웃, API, 인증)
3. **3단계**: 간단한 페이지 (로그인, 대시보드, 멤버)
4. **4단계**: 앨범 관리
5. **5단계**: 일정 관리 (가장 복잡)
### 코딩 가이드라인
공개 영역과 동일한 패턴 적용:
- `useQuery` / `useMutation` 사용
- 서비스 레이어 분리
- 공통 컴포넌트 재사용
- TypeScript JSDoc 타입 정의
---
## 1단계: 폴더 구조 재편
기존 frontend-temp 파일들을 새로운 구조로 이동합니다.
### 1.1 현재 구조 → 새 구조
```
현재 → 새 구조
─────────────────────────────────────────────────────────
api/
├── client.js → api/common/client.js
├── index.js → (삭제, 각 폴더별 index.js로 대체)
├── auth.js → api/pc/admin/auth.js
├── schedules.js → api/pc/public/schedules.js
├── albums.js → api/pc/public/albums.js
└── members.js → api/pc/common/members.js
components/
├── common/ → components/common/
│ ├── Loading.jsx
│ ├── ErrorBoundary.jsx
│ ├── ErrorMessage.jsx
│ ├── Toast.jsx
│ ├── Lightbox.jsx
│ └── ...
├── pc/ → components/pc/public/
│ ├── Layout.jsx
│ ├── Header.jsx
│ ├── Footer.jsx
│ ├── Calendar.jsx
│ └── ScheduleCard.jsx
└── mobile/ → components/mobile/
├── Layout.jsx
├── Header.jsx
├── BottomNav.jsx
└── ...
hooks/
├── useMediaQuery.js → hooks/common/useMediaQuery.js
├── useLightbox.js → hooks/common/useLightbox.js
├── useCalendar.js → hooks/common/useCalendar.js
├── useAdminAuth.js → hooks/pc/admin/useAdminAuth.js
└── ...
pages/
├── home/pc/ → pages/pc/public/home/
├── home/mobile/ → pages/mobile/home/
├── schedule/pc/ → pages/pc/public/schedule/
├── schedule/mobile/ → pages/mobile/schedule/
├── album/pc/ → pages/pc/public/album/
├── album/mobile/ → pages/mobile/album/
├── members/pc/ → pages/pc/public/members/
└── members/mobile/ → pages/mobile/members/
```
### 1.2 import 경로 업데이트
파일 이동 후 모든 import 경로를 새 구조에 맞게 수정합니다.
```javascript
// Before
import { fetchApi } from '@/api/client';
import Loading from '@/components/common/Loading';
import Calendar from '@/components/pc/Calendar';
// After
import { fetchApi } from '@/api/common/client';
import Loading from '@/components/common/Loading';
import Calendar from '@/components/pc/public/Calendar';
```
### 1.3 index.js 파일 생성
각 폴더에 re-export용 index.js 생성:
```javascript
// api/pc/public/index.js
export * from './schedules';
export * from './albums';
// api/pc/admin/index.js
export * from './auth';
export * from './schedules';
// ...
```
---
## 2단계: 관리자 기반 설정
### 2.1 관리자 API 추가
**원칙**: 조회(GET)는 공개 API 재사용, CUD(Create/Update/Delete)는 관리자 API
```
api/
├── common/ # PC, Mobile 공통
│ └── client.js # fetch 래퍼 (fetchApi, fetchAuthApi)
│
├── pc/
│ ├── common/ # PC 내 공통 (public + admin 공유)
│ │ └── members.js # 멤버 조회 (일정 폼에서도 사용)
│ ├── public/ # PC 공개 API
│ │ ├── schedules.js
│ │ └── albums.js
│ └── admin/ # PC 관리자 API
│ ├── auth.js
│ ├── schedules.js
│ ├── albums.js
│ ├── members.js
│ ├── categories.js
│ ├── suggestions.js
│ ├── bots.js
│ └── stats.js
│
└── mobile/ # 모바일 (pc/public과 동일 API 사용 가능)
```
**사용 예시**:
```javascript
// PC 공개 페이지
import { fetchSchedules } from '@/api/pc/public';
// PC 관리자 페이지 - 조회는 pc/common 또는 pc/public 재사용
import { fetchMembers } from '@/api/pc/common';
import { createSchedule } from '@/api/pc/admin';
// 모바일 페이지
import { fetchSchedules } from '@/api/pc/public'; // 동일 API 재사용
```
### 2.2 관리자 레이아웃
`components/pc/admin/` 폴더 구조:
```
components/pc/admin/
├── Layout.jsx # AdminLayout
├── Header.jsx # AdminHeader (네비게이션)
└── NumberPicker.jsx
```
### 2.3 인증 훅 수정
현재 `useAdminAuth.js`를 관리자 전용으로 확장:
- 토큰 검증
- 자동 로그아웃
- 권한 체크
---
## 3단계: 간단한 페이지
### 3.1 AdminLogin
- 로그인 폼 컴포넌트화
- `useMutation`으로 로그인 처리
- 에러 처리 표준화
### 3.2 AdminDashboard
- 통계 API 호출 (`useQuery`)
- 차트/카드 컴포넌트화
- 로딩/에러 상태 처리
### 3.3 AdminMembers / AdminMemberEdit
- 멤버 목록 테이블
- 멤버 수정 폼
- 이미지 업로드 처리
---
## 4단계: 앨범 관리
### 4.1 AdminAlbums
- 앨범 목록 테이블
- 삭제 확인 모달
- 정렬/필터링
### 4.2 AdminAlbumForm
폼 필드:
- 기본 정보 (이름, 발매일, 타입)
- 트랙 목록 (동적 추가/삭제)
- 티저 목록 (동적 추가/삭제)
- 앨범 커버 업로드
컴포넌트 분리:
```
components/pc/admin/album/
├── AlbumBasicForm.jsx # 기본 정보
├── TrackListForm.jsx # 트랙 관리
├── TeaserListForm.jsx # 티저 관리
└── CoverUploader.jsx # 커버 업로드
```
### 4.3 AdminAlbumPhotos
가장 복잡한 페이지:
- SSE 스트리밍 업로드
- 진행률 표시
- 멤버 태깅
- 드래그 앤 드롭
훅 분리:
```
hooks/pc/admin/
├── usePhotoUpload.js # SSE 업로드 로직
├── usePhotoList.js # 사진 목록 관리
└── useMemberTag.js # 멤버 태깅
```
---
## 5단계: 일정 관리
### 5.1 AdminSchedule
기능:
- 일정 목록 (가상 스크롤)
- 검색/필터링
- 일괄 삭제
훅 재사용:
- `useScheduleSearch` (공개 영역과 동일)
- `useScheduleFiltering` (공개 영역과 동일)
### 5.2 AdminScheduleForm
폼 필드:
- 기본 정보 (제목, 날짜, 시간)
- 카테고리 선택
- 멤버 선택
- 출처 정보
- 카테고리별 추가 필드 (YouTube, X)
컴포넌트 분리:
```
components/pc/admin/schedule/
├── ScheduleBasicForm.jsx # 기본 정보
├── CategorySelect.jsx # 카테고리 선택
├── MemberSelect.jsx # 멤버 다중 선택
├── SourceInput.jsx # 출처 입력
├── YouTubeForm.jsx # YouTube 영상 정보
└── XForm.jsx # X 게시글 정보
```
### 5.3 AdminScheduleCategory
- 카테고리 CRUD
- 색상 선택기
- 순서 변경 (드래그)
### 5.4 AdminScheduleDict
- 일정 사전 관리
- 자동완성 데이터
### 5.5 AdminScheduleBots
- 봇 목록/상태
- 동기화 실행
- 로그 확인
---
## 목표 구조
```
frontend-temp/src/
├── api/
│ ├── common/ # PC, Mobile 공통
│ │ └── client.js # fetch 래퍼
│ ├── pc/
│ │ ├── common/ # PC 내 공통 (public + admin 공유)
│ │ │ └── members.js # 멤버 조회 (폼에서 공유)
│ │ ├── public/ # PC 공개 API
│ │ │ ├── schedules.js
│ │ │ └── albums.js
│ │ └── admin/ # PC 관리자 API
│ │ ├── auth.js
│ │ ├── schedules.js
│ │ ├── albums.js
│ │ ├── members.js
│ │ ├── categories.js
│ │ ├── suggestions.js
│ │ ├── bots.js
│ │ └── stats.js
│ └── mobile/ # 모바일 API
│ └── (public과 동일하게 사용)
│
├── components/
│ ├── common/ # PC, Mobile 공통
│ │ ├── Loading.jsx
│ │ ├── ErrorBoundary.jsx
│ │ ├── ErrorMessage.jsx
│ │ ├── Toast.jsx
│ │ └── Lightbox/
│ ├── pc/
│ │ ├── common/ # PC 내 공통
│ │ │ └── (필요시)
│ │ ├── public/ # PC 공개 컴포넌트
│ │ │ ├── Layout.jsx
│ │ │ ├── Header.jsx
│ │ │ ├── Footer.jsx
│ │ │ ├── Calendar.jsx
│ │ │ └── ScheduleCard.jsx
│ │ └── admin/ # PC 관리자 컴포넌트
│ │ ├── Layout.jsx
│ │ ├── Header.jsx
│ │ ├── NumberPicker.jsx
│ │ ├── ConfirmDialog.jsx
│ │ ├── album/
│ │ │ ├── AlbumBasicForm.jsx
│ │ │ ├── TrackListForm.jsx
│ │ │ ├── TeaserListForm.jsx
│ │ │ └── CoverUploader.jsx
│ │ └── schedule/
│ │ ├── ScheduleBasicForm.jsx
│ │ ├── CategorySelect.jsx
│ │ ├── MemberSelect.jsx
│ │ ├── SourceInput.jsx
│ │ ├── YouTubeForm.jsx
│ │ └── XForm.jsx
│ └── mobile/ # 모바일 컴포넌트
│ ├── Layout.jsx
│ ├── Header.jsx
│ ├── BottomNav.jsx
│ ├── Calendar.jsx
│ └── ScheduleCard.jsx
│
├── hooks/
│ ├── common/ # PC, Mobile 공통
│ │ ├── useMediaQuery.js
│ │ ├── useLightbox.js
│ │ └── useCalendar.js
│ ├── pc/
│ │ ├── common/ # PC 내 공통
│ │ │ └── (필요시)
│ │ ├── public/ # PC 공개 훅
│ │ │ └── (필요시)
│ │ └── admin/ # PC 관리자 훅
│ │ ├── useAdminAuth.js
│ │ ├── usePhotoUpload.js
│ │ ├── usePhotoList.js
│ │ └── useMemberTag.js
│ └── mobile/ # 모바일 훅
│ └── (필요시)
│
├── pages/
│ ├── pc/
│ │ ├── public/ # PC 공개 페이지
│ │ │ ├── Home.jsx
│ │ │ ├── Schedule.jsx
│ │ │ ├── Album.jsx
│ │ │ └── Members.jsx
│ │ └── admin/ # PC 관리자 페이지
│ │ ├── Login.jsx
│ │ ├── Dashboard.jsx
│ │ ├── Members.jsx
│ │ ├── MemberEdit.jsx
│ │ ├── Albums.jsx
│ │ ├── AlbumForm.jsx
│ │ ├── AlbumPhotos.jsx
│ │ ├── Schedule.jsx
│ │ ├── ScheduleForm.jsx
│ │ ├── ScheduleCategory.jsx
│ │ ├── ScheduleDict.jsx
│ │ └── ScheduleBots.jsx
│ └── mobile/ # 모바일 페이지
│ ├── Home.jsx
│ ├── Schedule.jsx
│ ├── Album.jsx
│ └── Members.jsx
│
├── stores/ # 전역 상태 (플랫)
│ ├── useAuthStore.js
│ ├── useScheduleStore.js
│ └── useUIStore.js
│
├── utils/ # 유틸리티 (플랫)
│ ├── date.js
│ ├── format.js
│ └── schedule.js
│
└── constants/ # 상수 (플랫)
└── index.js
```
---
## 작업 체크리스트
### 1단계: 폴더 구조 재편
- [ ] api/ 구조 변경 (common/, pc/common/, pc/public/, pc/admin/)
- [ ] components/ 구조 변경 (common/, pc/public/, pc/admin/, mobile/)
- [ ] hooks/ 구조 변경 (common/, pc/admin/)
- [ ] pages/ 구조 변경 (pc/public/, pc/admin/, mobile/)
- [ ] 모든 import 경로 업데이트
- [ ] 각 폴더에 index.js 생성 (re-export)
- [ ] 빌드 및 동작 확인
### 2단계: 관리자 기반 설정
- [ ] 관리자 API 마이그레이션 (api/pc/admin/)
- [ ] AdminLayout 마이그레이션 (components/pc/admin/)
- [ ] AdminHeader 마이그레이션 (components/pc/admin/)
- [ ] useAdminAuth 훅 이동 (hooks/pc/admin/)
- [ ] 관리자 라우트 설정 (App.jsx)
### 3단계: 간단한 페이지
- [ ] AdminLogin 마이그레이션
- [ ] AdminDashboard 마이그레이션
- [ ] AdminMembers 마이그레이션
- [ ] AdminMemberEdit 마이그레이션
### 4단계: 앨범 관리
- [ ] AdminAlbums 마이그레이션
- [ ] AdminAlbumForm 마이그레이션
- [ ] AdminAlbumPhotos 마이그레이션 (SSE 처리 포함)
### 5단계: 일정 관리
- [ ] AdminSchedule 마이그레이션
- [ ] AdminScheduleForm 마이그레이션
- [ ] AdminScheduleCategory 마이그레이션
- [ ] AdminScheduleDict 마이그레이션
- [ ] AdminScheduleBots 마이그레이션
### 6단계: 검증
- [ ] 공개 페이지 동작 확인 (PC/Mobile)
- [ ] 로그인/로그아웃 테스트
- [ ] 멤버 CRUD 테스트
- [ ] 앨범 CRUD 테스트
- [ ] 앨범 사진 업로드 테스트
- [ ] 일정 CRUD 테스트
- [ ] YouTube/X 일정 등록 테스트
- [ ] 카테고리 관리 테스트
- [ ] 봇 관리 테스트
---
## 예상 효과
| 항목 | Before | After | 개선 |
|------|--------|-------|------|
| 총 LOC | ~7,535 | ~5,500 | -27% |
| 중복 코드 | 30%+ | <10% | 공통 훅/컴포넌트 활용 |
| 컴포넌트 분리 | 12개 대형 파일 | 30개+ 작은 파일 | 유지보수성 향상 |
---
## 주의사항
1. **SSE 스트리밍**: AdminAlbumPhotos의 SSE 업로드는 별도 훅으로 분리하여 처리
2. **인증 처리**: 모든 관리자 API 호출에 토큰 자동 첨부
3. **에러 처리**: 401 에러 시 자동 로그아웃 및 리다이렉트
4. **폼 검증**: React Hook Form 또는 자체 검증 로직 사용
5. **낙관적 업데이트**: 목록 삭제 등에 useMutation의 onMutate 활용
---
## 참고
- 기존 문서: [frontend-refactoring.md](./frontend-refactoring.md)
- API 명세: [api.md](./api.md)
- 개발 가이드: [development.md](./development.md)

276
docs/backend-refactoring.md
View file

@ -1,276 +0,0 @@
# Backend Refactoring Plan
백엔드 코드 품질 개선을 위한 리팩토링 계획서
## 완료된 작업
### 1단계: 설정 통합 (config 정리) ✅ 완료
- [x] 카테고리 ID 상수 통합 (`CATEGORY_IDS`)
**수정된 파일:**
- `src/config/index.js` - `CATEGORY_IDS` 상수 추가
- `src/routes/admin/youtube.js` - config에서 import
- `src/routes/admin/x.js` - config에서 import
- `src/routes/schedules/index.js` - 하드코딩된 2, 3, 8 → 상수로 변경
---
### 2단계: N+1 쿼리 최적화 ✅ 완료
- [x] 앨범 목록 조회 시 트랙 한 번에 조회로 변경
- [x] 스케줄 멤버 조회 - 이미 최적화됨 (확인 완료)
**수정된 파일:**
- `src/routes/albums/index.js` - GET /api/albums에서 트랙 조회 최적화
---
### 3단계: 서비스 레이어 분리 ✅ 완료
- [x] `src/services/album.js` 생성
- [x] `src/services/schedule.js` 생성
- [x] 라우트에서 서비스 호출로 변경
---
### 4단계: 에러 처리 통일 ✅ 완료
- [x] 에러 응답 유틸리티 생성 (`src/utils/error.js`)
- [x] `reply.status()` → `reply.code()` 통일
---
### 5단계: 중복 코드 제거 ✅ 완료
- [x] 스케줄러 상태 업데이트 로직 통합 (handleSyncResult 함수)
- [x] youtube/index.js 하드코딩된 카테고리 ID → config 사용
---
## 추가 작업 목록
### 6단계: 매직 넘버 config 이동 ✅ 완료
- [x] 이미지 크기/품질 설정 (`services/image.js`)
- [x] X 기본 사용자명 (`routes/admin/x.js`, `routes/schedules/index.js`, `services/schedule.js`)
- [x] Meilisearch 최소 점수 (`services/meilisearch/index.js`)
**수정된 파일:**
- `src/config/index.js` - `image`, `x`, `meilisearch.minScore` 추가
- `src/services/image.js` - config에서 이미지 크기/품질 참조
- `src/services/meilisearch/index.js` - config에서 minScore 참조
- `src/routes/admin/x.js` - config에서 defaultUsername 참조
- `src/routes/schedules/index.js` - config에서 defaultUsername 참조
- `src/services/schedule.js` - config에서 defaultUsername 참조
---
### 7단계: 순차 쿼리 → 병렬 처리 ✅ 완료
- [x] `services/album.js` getAlbumDetails - tracks, teasers, photos 병렬 조회
- [x] `routes/albums/photos.js` - 멤버 INSERT 배치 처리
**수정된 파일:**
- `src/services/album.js` - Promise.all로 3개 쿼리 병렬 실행
- `src/routes/albums/photos.js` - for loop → VALUES ? 배치 INSERT
---
### 8단계: meilisearch 카테고리 ID 상수화 ✅ 완료
- [x] `services/meilisearch/index.js` - 하드코딩된 2, 3 → CATEGORY_IDS 사용
**수정된 파일:**
- `src/services/meilisearch/index.js` - CATEGORY_IDS.YOUTUBE, CATEGORY_IDS.X 사용
---
### 9단계: 응답 형식 통일 ✅ 완료
- [x] `routes/schedules/suggestions.js` - `{success, message}` → `{error}` 또는 `{message}` 형식으로 통일
**수정된 파일:**
- `src/routes/schedules/suggestions.js` - 응답 형식 통일
---
### 10단계: 로거 통일 ✅ 완료
- [x] `src/utils/logger.js` 생성
- [x] 모든 `console.error/log` → logger 또는 fastify.log 사용
**수정된 파일:**
- `src/utils/logger.js` - 로거 유틸리티 생성 (createLogger)
- `src/services/image.js` - logger 사용
- `src/services/meilisearch/index.js` - logger 사용
- `src/services/suggestions/index.js` - logger 사용
- `src/services/suggestions/morpheme.js` - logger 사용
- `src/routes/albums/photos.js` - fastify.log 사용
- `src/routes/schedules/index.js` - fastify.log 사용
- `src/routes/schedules/suggestions.js` - fastify.log 사용
---
### 11단계: 대형 핸들러 분리 ✅ 완료
- [x] `routes/albums/index.js` POST/PUT/DELETE → 서비스 함수로 분리
- [ ] `routes/albums/photos.js` POST - SSE 스트리밍으로 인해 분리 보류
**수정된 파일:**
- `src/services/album.js` - createAlbum, updateAlbum, deleteAlbum, insertTracks 추가
- `src/routes/albums/index.js` - 서비스 함수 호출로 변경 (80줄 감소)
---
### 12단계: 트랜잭션 헬퍼 추상화 ✅ 완료
- [x] `src/utils/transaction.js` 생성 - withTransaction 함수
- [x] 반복되는 트랜잭션 패턴 추상화 적용
**수정된 파일:**
- `src/utils/transaction.js` - 트랜잭션 헬퍼 유틸리티 생성
- `src/services/album.js` - createAlbum, updateAlbum, deleteAlbum에 withTransaction 적용
- `src/routes/albums/photos.js` - DELETE 핸들러에 withTransaction 적용
- `src/routes/albums/teasers.js` - DELETE 핸들러에 withTransaction 적용
---
### 13단계: Swagger/OpenAPI 문서화 개선 ✅ 완료
- [x] `src/schemas/index.js` 생성 - 공통 스키마 정의
- [x] `src/app.js` - Swagger components에 스키마 등록
- [x] 태그 추가 (admin/youtube, admin/x, admin/bots)
**수정된 파일:**
- `src/schemas/index.js` - JSON Schema 정의 (Error, Success, Album, Schedule 등)
- `src/app.js` - Swagger 설정에 스키마 컴포넌트 추가
---
### 14단계: 입력 검증 강화 (JSON Schema) ✅ 완료
- [x] 라우트에 params, querystring, body, response 스키마 추가
- [x] 상세 description 추가로 API 문서 품질 향상
**수정된 파일:**
- `src/routes/albums/index.js` - GET/POST/PUT/DELETE 스키마 추가
- `src/routes/schedules/index.js` - 검색/조회/삭제 스키마 추가
- `src/routes/admin/youtube.js` - 영상 조회/일정 등록/수정 스키마 추가
- `src/routes/admin/x.js` - 게시글 조회/일정 등록 스키마 추가
- `src/routes/admin/bots.js` - 봇 관리 스키마 추가
---
### 15단계: 스키마 파일 분리 ✅ 완료
- [x] 단일 스키마 파일을 도메인별로 분리
- [x] Re-export 패턴으로 기존 import 호환성 유지
**생성된 파일:**
- `src/schemas/common.js` - 공통 스키마 (errorResponse, successResponse, paginationQuery, idParam)
- `src/schemas/album.js` - 앨범 관련 스키마
- `src/schemas/schedule.js` - 일정 관련 스키마
- `src/schemas/admin.js` - 관리자 API 스키마 (YouTube, X)
- `src/schemas/member.js` - 멤버 스키마
- `src/schemas/auth.js` - 인증 스키마
- `src/schemas/index.js` - 모든 스키마 re-export
---
### 16단계: 에러 처리 일관성 ✅ 완료
- [x] 모든 라우트에 try/catch 적용
- [x] 에러 응답 패턴 통일
**수정된 파일:**
- `src/routes/schedules/index.js` - 모든 핸들러에 try/catch 추가
---
### 17단계: 중복 코드 제거 (멤버 조회) ✅ 완료
- [x] 멤버 조회 로직을 서비스로 분리
- [x] 앨범 존재 확인 로직 통합
**생성된 파일:**
- `src/services/member.js` - getAllMembers, getMemberByName, getMemberBasicByName
**수정된 파일:**
- `src/services/album.js` - getAlbumByName, getAlbumById 추가
- `src/routes/members/index.js` - 서비스 호출로 변경 (약 50줄 감소)
- `src/routes/albums/index.js` - 서비스 호출로 변경
---
### 18단계: 이미지 처리 최적화 ✅ 완료
- [x] 이미지 메타데이터 중복 처리 제거
- [x] processImage에서 메타데이터 함께 반환
- [x] sharp 인스턴스 재사용 (clone() 사용)
**수정된 파일:**
- `src/services/image.js` - processImage 함수 개선, uploadAlbumPhoto 중복 조회 제거
---
### 19단계: Redis 캐시 확대 ✅ 완료
- [x] 캐시 유틸리티 생성 (`src/utils/cache.js`)
- [x] 멤버 목록 캐싱 (10분 TTL)
- [x] 멤버 수정 시 캐시 무효화
- [x] 카테고리 목록 캐싱 (1시간 TTL)
- [x] 앨범 목록 캐싱 (10분 TTL)
- [x] 앨범 상세 캐싱 (10분 TTL)
- [x] 앨범 생성/수정/삭제 시 캐시 무효화
- [ ] 일정 상세 조회 - X 프로필이 별도 캐시 사용하므로 보류
**생성된 파일:**
- `src/utils/cache.js` - getOrSet, invalidate, invalidatePattern, cacheKeys, TTL 상수
**수정된 파일:**
- `src/services/member.js` - getAllMembers에 캐시 적용, invalidateMemberCache 추가
- `src/services/schedule.js` - getCategories에 캐시 적용
- `src/services/album.js` - getAlbumsWithTracks, getAlbumDetails에 캐시 적용, invalidateAlbumCache 추가
- `src/routes/members/index.js` - Redis 캐시 사용, 수정 시 캐시 무효화
- `src/routes/schedules/index.js` - 카테고리 조회 시 캐시 사용
- `src/routes/albums/index.js` - 캐시 사용, 생성/수정/삭제 시 캐시 무효화
---
### 20단계: 서비스 레이어 확대 ✅ 완료
- [x] schedules 라우트의 DB 쿼리를 서비스로 분리
- [x] 일관된 서비스 패턴 적용
**수정된 파일:**
- `src/services/schedule.js` - getCategories, getScheduleDetail 함수 추가
- `src/routes/schedules/index.js` - 서비스 호출로 변경 (약 70줄 감소)
---
### 21단계: 검색 페이징 최적화 ✅ 완료
- [x] 라우트에서 중복 slice 제거
- [x] 내부 검색 한도와 페이징 파라미터 분리
- [x] searchSchedules에 offset/limit 직접 전달
**수정된 파일:**
- `src/services/meilisearch/index.js` - SEARCH_LIMIT 분리, 기본 limit 100으로 변경
- `src/routes/schedules/index.js` - handleSearch에서 중복 slice 제거
---
## 진행 상황
| 단계 | 작업 | 상태 |
|------|------|------|
| 1단계 | 설정 통합 | ✅ 완료 |
| 2단계 | N+1 쿼리 최적화 | ✅ 완료 |
| 3단계 | 서비스 레이어 분리 | ✅ 완료 |
| 4단계 | 에러 처리 통일 | ✅ 완료 |
| 5단계 | 중복 코드 제거 | ✅ 완료 |
| 6단계 | 매직 넘버 config 이동 | ✅ 완료 |
| 7단계 | 순차→병렬 쿼리 | ✅ 완료 |
| 8단계 | meilisearch 카테고리 ID | ✅ 완료 |
| 9단계 | 응답 형식 통일 | ✅ 완료 |
| 10단계 | 로거 통일 | ✅ 완료 |
| 11단계 | 대형 핸들러 분리 | ✅ 완료 |
| 12단계 | 트랜잭션 헬퍼 추상화 | ✅ 완료 |
| 13단계 | Swagger/OpenAPI 문서화 | ✅ 완료 |
| 14단계 | 입력 검증 강화 (JSON Schema) | ✅ 완료 |
| 15단계 | 스키마 파일 분리 | ✅ 완료 |
| 16단계 | 에러 처리 일관성 | ✅ 완료 |
| 17단계 | 중복 코드 제거 (멤버 조회) | ✅ 완료 |
| 18단계 | 이미지 처리 최적화 | ✅ 완료 |
| 19단계 | Redis 캐시 확대 | ✅ 완료 |
| 20단계 | 서비스 레이어 확대 | ✅ 완료 |
| 21단계 | 검색 페이징 최적화 | ✅ 완료 |
---
## 참고사항
- 각 단계별로 커밋 후 다음 단계 진행
- 기존 API 응답 형식은 유지
- 프론트엔드 수정 불필요하도록 진행
- API 문서는 `/docs`에서 확인 가능 (Scalar API Reference)

1055
docs/code-improvements.md
View file

File diff suppressed because it is too large Load diff

BIN
frontend-temp/public/favicon.ico Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 234 KiB