fromis_9/docs/refactoring.md

Backend Refactoring Plan

백엔드 코드 품질 개선을 위한 리팩토링 계획서

완료된 작업

1단계: 설정 통합 (config 정리) ✅ 완료

• 카테고리 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 쿼리 최적화 ✅ 완료

• 앨범 목록 조회 시 트랙 한 번에 조회로 변경
• 스케줄 멤버 조회 - 이미 최적화됨 (확인 완료)

수정된 파일:

• src/routes/albums/index.js - GET /api/albums에서 트랙 조회 최적화

---

3단계: 서비스 레이어 분리 ✅ 완료

• src/services/album.js 생성
• src/services/schedule.js 생성
• 라우트에서 서비스 호출로 변경

---

4단계: 에러 처리 통일 ✅ 완료

• 에러 응답 유틸리티 생성 (src/utils/error.js)
• reply.status() → reply.code() 통일

---

5단계: 중복 코드 제거 ✅ 완료

• 스케줄러 상태 업데이트 로직 통합 (handleSyncResult 함수)
• youtube/index.js 하드코딩된 카테고리 ID → config 사용

---

추가 작업 목록

6단계: 매직 넘버 config 이동 ✅ 완료

• 이미지 크기/품질 설정 (services/image.js)
• X 기본 사용자명 (routes/admin/x.js, routes/schedules/index.js, services/schedule.js)
• 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단계: 순차 쿼리 → 병렬 처리 ✅ 완료

• services/album.js getAlbumDetails - tracks, teasers, photos 병렬 조회
• routes/albums/photos.js - 멤버 INSERT 배치 처리

수정된 파일:

• src/services/album.js - Promise.all로 3개 쿼리 병렬 실행
• src/routes/albums/photos.js - for loop → VALUES ? 배치 INSERT

---

8단계: meilisearch 카테고리 ID 상수화 ✅ 완료

• services/meilisearch/index.js - 하드코딩된 2, 3 → CATEGORY_IDS 사용

수정된 파일:

• src/services/meilisearch/index.js - CATEGORY_IDS.YOUTUBE, CATEGORY_IDS.X 사용

---

9단계: 응답 형식 통일 ✅ 완료

• routes/schedules/suggestions.js - {success, message} → {error} 또는 {message} 형식으로 통일

수정된 파일:

• src/routes/schedules/suggestions.js - 응답 형식 통일

---

10단계: 로거 통일 ✅ 완료

• src/utils/logger.js 생성
• 모든 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단계: 대형 핸들러 분리 ✅ 완료

• 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줄 감소)

---

진행 상황

단계	작업	상태
1단계	설정 통합	✅ 완료
2단계	N+1 쿼리 최적화	✅ 완료
3단계	서비스 레이어 분리	✅ 완료
4단계	에러 처리 통일	✅ 완료
5단계	중복 코드 제거	✅ 완료
6단계	매직 넘버 config 이동	✅ 완료
7단계	순차→병렬 쿼리	✅ 완료
8단계	meilisearch 카테고리 ID	✅ 완료
9단계	응답 형식 통일	✅ 완료
10단계	로거 통일	✅ 완료
11단계	대형 핸들러 분리	✅ 완료

---

참고사항

• 각 단계별로 커밋 후 다음 단계 진행
• 기존 API 응답 형식은 유지
• 프론트엔드 수정 불필요하도록 진행