fromis_9/docs/frontend-improvement.md

프론트엔드 개선 계획서

1. 현재 문제점

1.1 API 구조

현재 구조:
api/
├── common/client.js          # fetch 래퍼
├── index.js                  # 통합 export (혼란)
├── pc/
│   ├── admin/                # 관리자 API
│   ├── common/members.js     # PC 공통?
│   └── public/               # 공개 API (어드민 함수도 섞여있음)

문제점:

• PC와 모바일이 같은 API를 사용하는데 pc/ 폴더 안에 있음
• api/pc/public/schedules.js에 어드민 API 함수도 포함됨
• transformSchedule 함수가 여러 파일에 중복
• api/index.js에서 같은 함수가 여러 번 export됨

1.2 컴포넌트 구조

현재 구조:
components/
├── common/           # 공통 (OK)
├── mobile/           # 모바일 (폴더 구분 없음)
├── pc/
│   ├── admin/        # 관리자 (schedule 폴더만 있음)
│   └── public/       # 공개 (폴더 구분 없음)

문제점:

• admin/과 public/ 내부에 기능별 폴더 구분이 없음
• 파일이 많아지면 찾기 어려움

1.3 중복 코드

• getMemberList: 16개 파일에서 사용, 일부는 로컬 정의
• decodeHtmlEntities: 여러 파일에 중복 정의
• transformSchedule: api/pc/public/schedules.js, api/pc/admin/schedules.js에 중복
• Schedules.jsx에 유틸 함수들이 로컬로 재정의됨

1.4 대형 파일

파일	라인 수	문제
AlbumPhotos.jsx	1536	업로드, 관리, 일괄편집이 한 파일에
Schedules.jsx	1471	중복 유틸 함수, 컴포넌트 미분리
ScheduleForm.jsx	1046	폼 로직과 UI가 섞여있음
ScheduleDict.jsx	714	테이블과 모달이 한 파일에
AlbumForm.jsx	631	트랙/티저 관리가 인라인

---

2. 개선 계획

2.1 API 구조 개선

개선 후:
api/
├── client.js                 # fetch 래퍼
├── transforms.js             # 공통 변환 함수
├── public/                   # 공개 API (PC/Mobile 공용)
│   ├── schedules.js
│   ├── albums.js
│   └── members.js
└── admin/                    # 관리자 API
    ├── schedules.js
    ├── albums.js
    ├── members.js
    ├── categories.js
    ├── bots.js
    └── stats.js

2.2 컴포넌트 구조 개선

개선 후:
components/
├── common/                   # 공통 (유지)
├── mobile/
│   ├── layout/               # Layout, Header, BottomNav
│   └── schedule/             # ScheduleCard, BirthdayCard 등
├── pc/
│   ├── public/
│   │   ├── layout/           # Layout, Header, Footer
│   │   └── schedule/         # Calendar, ScheduleCard 등
│   └── admin/
│       ├── layout/           # Layout, Header
│       ├── common/           # ConfirmDialog, DatePicker 등
│       ├── schedule/         # CategorySelector 등
│       └── album/            # PhotoUploader 등

2.3 중복 코드 제거

utils/schedule.js 통합 사용

• Schedules.jsx의 로컬 함수들 제거
• 모든 곳에서 @/utils/schedule import

utils/format.js에 decodeHtmlEntities 통합

• 중복 정의 제거

api/transforms.js 생성

• transformSchedule 함수 통합

2.4 대형 파일 분리

AlbumPhotos.jsx (1536줄)

pages/pc/admin/albums/
├── AlbumPhotos.jsx           # 메인 (상태 관리)
├── components/
│   ├── PhotoUploader.jsx     # 업로드 UI
│   ├── PhotoGrid.jsx         # 사진 그리드
│   ├── PhotoPreview.jsx      # 미리보기 모달
│   └── BulkEditTools.jsx     # 일괄 편집 도구
└── hooks/
    └── usePhotoUpload.js     # 업로드 로직

Schedules.jsx (1471줄)

pages/pc/admin/schedules/
├── Schedules.jsx             # 메인
├── components/
│   ├── ScheduleList.jsx      # 목록 (가상화)
│   ├── ScheduleSearch.jsx    # 검색 UI
│   └── MonthNavigator.jsx    # 월 선택
└── hooks/
    └── useScheduleList.js    # 목록 조회 로직

ScheduleForm.jsx (1046줄)

pages/pc/admin/schedules/
├── ScheduleForm.jsx          # 메인
└── components/
    ├── BasicInfoForm.jsx     # 기본 정보
    ├── MemberSelector.jsx    # 멤버 선택
    └── SourceInput.jsx       # 출처 입력

---

3. 작업 순서

Phase 1: 구조 정리 (비파괴적) ✅ 완료

1. API 구조 개선 (폴더 재배치)
   • api/pc/, api/common/ → api/public/, api/admin/
2. 미사용 코드 제거
   • utils/format.js, utils/date.js 미사용 함수
   • constants/index.js 미사용 상수
   • 미사용 hooks, stores
3. 컴포넌트 폴더 구조화 (layout/, common/, schedule/ 등)
4. CATEGORY_ID 하드코딩 제거
   • constants에서 삭제
   • 카테고리 API 데이터의 name으로 비교하도록 변경
5. 봇 관리 페이지 애니메이션 추가
   • 페이지 stagger 애니메이션
   • 통계 카드 AnimatedNumber

Phase 2: 대형 파일 분리

1. Schedules.jsx 분리
2. ScheduleForm.jsx 분리
3. AlbumPhotos.jsx 분리
4. ScheduleDict.jsx 분리
5. AlbumForm.jsx 분리

Phase 3: 추가 개선

1. 관리자 페이지용 에러 페이지 추가 (404)
2. 모든 페이지 동작 확인
3. 빌드 확인

---

4. 삭제된 항목

constants/index.js

• CATEGORY_ID (하드코딩 → API name 비교로 변경)
• CATEGORY_NAMES (미사용)
• ALBUM_TYPES (미사용)
• SOCIAL_LINKS.tiktok (불필요)
• SOCIAL_LINKS.fancafe (불필요)

API 구조

• api/pc/ 폴더 → api/public/, api/admin/으로 변경 완료
• api/common/ → api/client.js로 통합 완료

utils

• format.js: formatNumber, formatViewCount, formatFileSize, formatDuration, truncateText
• date.js: nowKST, parseDateKST, isPast, isFuture

hooks

• useCalendar, useLightbox, useMediaQuery, useScheduleFiltering, useScheduleSearch

stores

• useUIStore