fromis_9/docs/migration.md

# Express → Fastify 마이그레이션

## 개요

`backend-backup/` (Express) → `backend/` (Fastify)로 마이그레이션 진행 중

## 완료된 작업

### 서버 기반
- [x] Fastify 앱 구조 (`src/app.js`, `src/server.js`)
- [x] 플러그인 시스템 (`src/plugins/`)
  - db.js (MariaDB)
  - redis.js
  - auth.js (JWT)
  - meilisearch.js
  - scheduler.js (봇 스케줄러)

### API 라우트 (`src/routes/`)
- [x] 인증 (`/api/auth`)
  - POST /login - 로그인
  - GET /me - 현재 사용자 정보
- [x] 멤버 (`/api/members`)
  - GET / - 목록 조회
  - GET /:name - 상세 조회
  - PUT /:name - 수정 (이미지 업로드 포함)
- [x] 앨범 (`/api/albums`)
  - GET / - 목록 조회
  - GET /:id - ID로 조회
  - GET /by-name/:name - 이름으로 조회
  - GET /by-name/:albumName/track/:trackTitle - 트랙 조회
  - POST / - 생성
  - PUT /:id - 수정
  - DELETE /:id - 삭제
  - 사진 관리 (`/api/albums/:id/photos`)
    - GET / - 목록
    - POST / - 업로드
    - PUT /:photoId - 수정
    - DELETE /:photoId - 삭제
  - 티저 관리 (`/api/albums/:id/teasers`)
    - GET / - 목록
    - POST / - 업로드
    - DELETE /:teaserId - 삭제
- [x] 일정 (`/api/schedules`) - 조회만
  - GET / - 월별 조회 (생일 포함)
  - GET /?search= - Meilisearch 검색
  - GET /:id - 상세 조회
  - POST /sync-search - Meilisearch 동기화
- [x] 추천 검색어 (`/api/schedules/suggestions`)
  - GET / - 추천 검색어 조회
  - kiwi-nlp 형태소 분석
  - bi-gram 자동완성
  - 초성 검색
- [x] 통계 (`/api/stats`)
  - GET / - 대시보드 통계

### 서비스 (`src/services/`)
- [x] YouTube 봇 (`services/youtube/`)
  - 영상 자동 수집
  - 채널별 필터링 (제목 필터, 멤버 추출)
- [x] X(Twitter) 봇 (`services/x/`)
  - Nitter 스크래핑
  - 이미지 URL 추출
- [x] Meilisearch 검색 (`services/meilisearch/`)
  - 일정 검색
  - 전체 동기화
- [x] 추천 검색어 (`services/suggestions/`)
  - 형태소 분석
  - bi-gram 빈도
- [x] 이미지 업로드 (`services/image.js`)
  - 앨범 커버
  - 멤버 이미지
  - 앨범 사진/티저

## 남은 작업

### 관리자 API (admin.js에서 마이그레이션 필요)
- [ ] 일정 CRUD
  - POST /api/schedules - 생성
  - PUT /api/schedules/:id - 수정
  - DELETE /api/schedules/:id - 삭제
- [ ] 일정 카테고리 CRUD
  - GET /api/schedule-categories - 목록
  - POST /api/schedule-categories - 생성
  - PUT /api/schedule-categories/:id - 수정
  - DELETE /api/schedule-categories/:id - 삭제
  - PUT /api/schedule-categories-order - 순서 변경
- [ ] 봇 관리 API
  - GET /api/bots - 봇 목록
  - POST /api/bots/:id/start - 봇 시작
  - POST /api/bots/:id/stop - 봇 정지
  - POST /api/bots/:id/sync-all - 전체 동기화
- [ ] 카카오 장소 검색 프록시
  - GET /api/kakao/places - 장소 검색
- [ ] YouTube 할당량 관리
  - POST /api/quota-alert - Webhook 수신
  - GET /api/quota-warning - 경고 상태 조회
  - DELETE /api/quota-warning - 경고 해제

### 기타 기능
- [ ] X 프로필 조회 (`/api/schedules/x-profile/:username`)
- [ ] 어드민 사전 관리 (형태소 분석용 사전)

## 파일 비교표

| Express (backend-backup) | Fastify (backend) | 상태 |
|--------------------------|-------------------|------|
| routes/admin.js (로그인) | routes/auth.js | 완료 |
| routes/admin.js (앨범 CRUD) | routes/albums/index.js | 완료 |
| routes/admin.js (사진/티저) | routes/albums/photos.js, teasers.js | 완료 |
| routes/admin.js (멤버 수정) | routes/members/index.js | 완료 |
| routes/admin.js (일정 CRUD) | - | 미완료 |
| routes/admin.js (카테고리) | - | 미완료 |
| routes/admin.js (봇 관리) | - | 미완료 |
| routes/admin.js (카카오) | - | 미완료 |
| routes/admin.js (할당량) | - | 미완료 |
| routes/albums.js | routes/albums/index.js | 완료 |
| routes/members.js | routes/members/index.js | 완료 |
| routes/schedules.js | routes/schedules/index.js | 부분 완료 |
| routes/stats.js | routes/stats/index.js | 완료 |
| services/youtube-bot.js | services/youtube/ | 완료 |
| services/youtube-scheduler.js | plugins/scheduler.js | 완료 |
| services/x-bot.js | services/x/ | 완료 |
| services/meilisearch.js | services/meilisearch/ | 완료 |
| services/meilisearch-bot.js | services/meilisearch/ | 완료 |
| services/suggestions.js | services/suggestions/ | 완료 |

## 참고 사항

- 기존 Express 코드는 `backend-backup/` 폴더에 보존
- 마이그레이션 시 기존 코드 참조하여 동일 기능 구현
- DB 스키마 변경 사항:
  - `tracks` → `album_tracks` (이름 변경)
  - `venues` → `concert_venues` (이름 변경)