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 | 1536 | 미분리 |
| Schedules.jsx | 1465 | 1159 | ✅ 분리 완료 |
| ScheduleForm.jsx | 1047 | 765 | ✅ 분리 완료 |
| ScheduleDict.jsx | 714 | 572 | ✅ 분리 완료 |
| AlbumForm.jsx | 631 | 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/         # ✅ 추가된 컴포넌트들:
│       │   ├── AdminScheduleCard.jsx
│       │   ├── CategorySelector.jsx
│       │   ├── ScheduleItem.jsx      # 일정 아이템 (리스트용)
│       │   ├── LocationSearchDialog.jsx  # 장소 검색 모달
│       │   ├── MemberSelector.jsx    # 멤버 선택 UI
│       │   └── ImageUploader.jsx     # 이미지 업로드
│       └── 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. [x] API 구조 개선 (폴더 재배치)
   - `api/pc/`, `api/common/` → `api/public/`, `api/admin/`
2. [x] 미사용 코드 제거
   - utils/format.js, utils/date.js 미사용 함수
   - constants/index.js 미사용 상수
   - 미사용 hooks, stores
3. [x] 컴포넌트 폴더 구조화 (layout/, common/, schedule/ 등)
4. [x] CATEGORY_ID 하드코딩 제거
   - constants에서 삭제
   - 카테고리 API 데이터의 `name`으로 비교하도록 변경
5. [x] 봇 관리 페이지 애니메이션 추가
   - 페이지 stagger 애니메이션
   - 통계 카드 AnimatedNumber

### Phase 2: 대형 파일 분리 (진행 중)
1. [x] Schedules.jsx 분리 (1465줄 → 1159줄, 306줄 감소)
   - `ScheduleItem.jsx` 컴포넌트 추출
   - 검색 모드와 일반 모드에서 공통 사용
2. [x] ScheduleForm.jsx 분리 (1047줄 → 765줄, 282줄 감소)
   - `LocationSearchDialog.jsx` 추출 (장소 검색 모달)
   - `MemberSelector.jsx` 추출 (멤버 선택 UI)
   - `ImageUploader.jsx` 추출 (이미지 업로드 및 드래그앤드롭)
3. [x] ScheduleDict.jsx 분리 (714줄 → 572줄, 142줄 감소)
   - `WordItem.jsx` 추출 (단어 테이블 행 컴포넌트)
   - `POS_TAGS` 상수 함께 분리
4. [ ] AlbumPhotos.jsx 분리 (1536줄, 구조 복잡)
5. [ ] AlbumForm.jsx 분리 (631줄)

### Phase 3: 추가 개선
1. [x] 관리자 페이지용 에러 페이지 추가 (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