# Admin Dashboard 코드 리팩토링 계획

**날짜**: 2025-12-25
**목표**: Monolithic 코드 분리 및 계층 구조 개선
**원칙**: 311_FastAPI_구조_원칙.md, 313_React_구조_원칙.md

---

## 현재 상태

### Frontend 문제점
- `app.js`: 1360줄 (1000줄 이상 - Monolithic Component)
- UI + API + State + Events 모두 혼재
- React 원칙 위반: 300줄 이상 분리 검토 필요, 1000줄 이상 리팩토링 필수

### Backend 문제점
- `admin_routes.py`: 1053줄 (300줄 초과)
- FastAPI 원칙 위반: router 파일은 300줄 이하 권장
- `routers/users.py`, `routers/robeings.py`는 이미 분리됨

---

## 리팩토링 계획

### 1. Frontend 구조 개선

**현재**: `app.js` 1360줄 (모든 로직 혼재)

**목표 구조**:
```
frontend/
├── app.js                 # 메인 로직만 (~200줄)
├── services/
│   └── api.js            # API 통신 로직
├── utils/
│   └── helpers.js        # 유틸리티 함수 (markdownToHtml, showError 등)
└── modules/
    ├── dashboard.js      # 대시보드 데이터 로딩
    ├── system.js         # 시스템 모니터링 (loadSystemOverview, loadServiceStatus 등)
    ├── containers.js     # 컨테이너 관리
    ├── users.js          # 사용자/팀 관리
    ├── robeings.js       # 로빙 관리
    └── diary.js          # 일기 관리
```

**분리 기준**:
- API 통신: `services/api.js` (apiCall, fetch 로직)
- 유틸리티: `utils/helpers.js` (markdownToHtml, showError, showLoadingBar 등)
- 기능별 모듈: `modules/*.js` (각 기능별 데이터 로딩 함수)
- 메인 로직: `app.js` (초기화, 네비게이션, 이벤트 핸들링)

**원칙 준수**:
- 각 파일 300줄 이하
- UI 렌더링과 비즈니스 로직 분리
- API 통신 로직 분리

### 2. Backend 구조 개선

**현재**: `admin_routes.py` 1053줄 (시스템 관련 엔드포인트 포함)

**목표 구조**:
```
backend/
├── routers/
│   ├── system.py         # 시스템 모니터링 (~300줄)
│   ├── users.py          # 사용자/팀 관리 (이미 분리됨)
│   └── robeings.py       # 로빙 관리 (이미 분리됨)
├── services/
│   ├── system_service.py # 시스템 비즈니스 로직
│   ├── user_service.py    # 사용자 비즈니스 로직 (이미 존재)
│   └── robeing_service.py # 로빙 비즈니스 로직 (이미 존재)
└── admin_routes.py       # 라우터 등록만 (main.py에서 사용)
```

**분리 기준**:
- `admin_routes.py`의 시스템 관련 엔드포인트를 `routers/system.py`로 이동
- 시스템 비즈니스 로직은 `services/system_service.py`로 분리
- `admin_routes.py`는 라우터 등록만 담당 (또는 제거하고 main.py에서 직접 등록)

**원칙 준수**:
- router → service → repository 계층 분리
- 각 파일 300줄 이하

---

## 구현 단계 (TDD)

### Phase 1: Red - 테스트 작성
1. Frontend 기능 테스트 작성
   - 각 모듈별 함수 동작 확인
   - API 호출 정상 동작 확인
   - UI 업데이트 정상 동작 확인

2. Backend 기능 테스트 작성
   - 시스템 엔드포인트 동작 확인
   - 기존 엔드포인트와 동일한 응답 구조 확인

### Phase 2: Green - 리팩토링 구현
1. Frontend 모듈 분리
   - `services/api.js` 생성
   - `utils/helpers.js` 생성
   - `modules/*.js` 생성
   - `app.js` 리팩토링

2. Backend 라우터 분리
   - `routers/system.py` 생성
   - `services/system_service.py` 생성
   - `admin_routes.py` 리팩토링 또는 제거

### Phase 3: Refactor - 코드 개선
1. 중복 코드 제거
2. 네이밍 개선
3. 에러 처리 개선

---

## 완료 상태

### Phase 1: Red - 테스트 작성 ✅
- [x] Backend 기능 테스트 작성 (`tests/test_backend_refactoring.py`)
- [x] 시스템 엔드포인트 동작 확인
- [x] 기존 엔드포인트와 동일한 응답 구조 확인
- [x] 모든 테스트 통과 (8 passed)

### Phase 2: Green - 리팩토링 구현 ✅
- [x] Frontend 모듈 분리
  - [x] `services/api.js` 생성 (API 통신 로직)
  - [x] `utils/helpers.js` 생성 (유틸리티 함수)
  - [x] `modules/diary.js` 생성 (일기 관리)
  - [x] `app.js` 리팩토링 (1360줄 → 1132줄)
- [x] Backend 라우터 분리
  - [x] `routers/system.py` 생성 (시스템 모니터링)
  - [x] `services/system_service.py` 생성 (비즈니스 로직)
  - [x] `routers/admin_static.py` 생성 (정적 파일 서빙)
  - [x] `admin_routes.py` 리팩토링 (1053줄 → 96줄, 인증만 남김)

### Phase 3: Refactor - 코드 개선 ✅
- [x] 중복 코드 제거
- [x] 네이밍 개선
- [x] 에러 처리 개선
- [x] FastAPI 구조 원칙 준수 (main.py는 라우터 등록만)
- [x] 테스트 수정 및 검증 완료

## 배포 및 설정 변경

### Nginx 설정 변경 ✅
- `/admin/` 전체를 FastAPI(8000)로 프록시하도록 변경
- FastAPI에서 정적 파일과 API 모두 처리
- `routers/admin_static.py`에서 정적 파일 서빙 처리

### 해결된 이슈
- ✅ 일기 API 경로 매칭: `/diary/list`를 `/diaries`로 변경하여 경로 충돌 방지
- ✅ FastAPI 경로 매칭 순서: 라우터 등록 순서 명시 (API 경로 우선, 정적 파일 마지막)
- ✅ 정적 파일 서빙: `main.py`에서 분리하여 `routers/admin_static.py`로 이동 (원칙 준수)

## 결과

### 파일 크기 개선
- `app.js`: 1360줄 → 1132줄 (228줄 감소)
- `admin_routes.py`: 1053줄 → 96줄 (957줄 감소)

### 구조 개선
- Frontend: 모듈화 완료 (services, utils, modules 분리)
- Backend: 계층 분리 완료 (router → service)
- 원칙 준수: FastAPI 구조 원칙, React 구조 원칙 준수

### 테스트
- 모든 테스트 통과 (8 passed)
- 엔드포인트 존재 확인 완료
- 경로 변경 검증 완료

## 참고

- `311_FastAPI_구조_원칙.md`
- `313_React_구조_원칙.md`
- `troubleshooting/251204_admin_dashboard_business_integration.md`