docs: Admin Dashboard 코드 리팩토링 트러블슈팅 문서 작성 및 계획 문서 정리
- troubleshooting/251225_admin_dashboard_code_refactoring.md: 리팩토링 및 버그 수정 내용 기록 - plans/archive/251225_admin_dashboard_code_refactoring.md: 구현 완료된 계획 보관 - plans/251225_admin_dashboard_code_refactoring.md: 남은 작업만 정리
This commit is contained in:
parent
2beffa30c6
commit
452308ffbc
@ -9,38 +9,34 @@
|
||||
## 현재 상태
|
||||
|
||||
### Frontend 문제점
|
||||
- `app.js`: 1360줄 (1000줄 이상 - Monolithic Component)
|
||||
- UI + API + State + Events 모두 혼재
|
||||
- React 원칙 위반: 300줄 이상 분리 검토 필요, 1000줄 이상 리팩토링 필수
|
||||
- `app.js`: 1132줄 (여전히 1000줄 이상)
|
||||
- 일기 모듈만 분리됨 (`modules/diary.js`)
|
||||
- 시스템, 컨테이너, 사용자, 로빙 모듈 미분리
|
||||
|
||||
### Backend 문제점
|
||||
- `admin_routes.py`: 1053줄 (300줄 초과)
|
||||
- FastAPI 원칙 위반: router 파일은 300줄 이하 권장
|
||||
- `routers/users.py`, `routers/robeings.py`는 이미 분리됨
|
||||
- `admin_routes.py`: 96줄 (인증만 남음) ✅
|
||||
- 시스템 모듈 분리 완료 ✅
|
||||
|
||||
---
|
||||
|
||||
## 리팩토링 계획
|
||||
## 남은 작업
|
||||
|
||||
### 1. Frontend 구조 개선
|
||||
|
||||
**현재**: `app.js` 1360줄 (모든 로직 혼재)
|
||||
### Frontend 모듈 분리 (미완료)
|
||||
|
||||
**목표 구조**:
|
||||
```
|
||||
frontend/
|
||||
├── app.js # 메인 로직만 (~200줄)
|
||||
├── services/
|
||||
│ └── api.js # API 통신 로직
|
||||
│ └── api.js # API 통신 로직 (미구현)
|
||||
├── utils/
|
||||
│ └── helpers.js # 유틸리티 함수 (markdownToHtml, showError 등)
|
||||
│ └── helpers.js # 유틸리티 함수 (미구현)
|
||||
└── modules/
|
||||
├── dashboard.js # 대시보드 데이터 로딩
|
||||
├── system.js # 시스템 모니터링 (loadSystemOverview, loadServiceStatus 등)
|
||||
├── containers.js # 컨테이너 관리
|
||||
├── users.js # 사용자/팀 관리
|
||||
├── robeings.js # 로빙 관리
|
||||
└── diary.js # 일기 관리
|
||||
├── diary.js # 일기 관리 ✅
|
||||
├── system.js # 시스템 모니터링 (미구현)
|
||||
├── containers.js # 컨테이너 관리 (미구현)
|
||||
├── users.js # 사용자/팀 관리 (미구현)
|
||||
└── robeings.js # 로빙 관리 (미구현)
|
||||
```
|
||||
|
||||
**분리 기준**:
|
||||
@ -54,124 +50,16 @@ frontend/
|
||||
- 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. 에러 처리 개선
|
||||
→ 상세: `troubleshooting/251225_admin_dashboard_code_refactoring.md`
|
||||
|
||||
---
|
||||
|
||||
## 완료 상태
|
||||
|
||||
### 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`
|
||||
|
||||
- `troubleshooting/251225_admin_dashboard_code_refactoring.md`
|
||||
|
||||
@ -0,0 +1,73 @@
|
||||
# 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 구조 개선
|
||||
|
||||
**목표 구조**:
|
||||
```
|
||||
frontend/
|
||||
├── app.js # 메인 로직만 (~200줄)
|
||||
├── services/
|
||||
│ └── api.js # API 통신 로직
|
||||
├── utils/
|
||||
│ └── helpers.js # 유틸리티 함수
|
||||
└── modules/
|
||||
└── diary.js # 일기 관리
|
||||
```
|
||||
|
||||
### 2. Backend 구조 개선
|
||||
|
||||
**목표 구조**:
|
||||
```
|
||||
backend/
|
||||
├── routers/
|
||||
│ ├── system.py # 시스템 모니터링
|
||||
│ ├── admin_static.py # 정적 파일 서빙
|
||||
│ ├── users.py # 사용자/팀 관리
|
||||
│ └── robeings.py # 로빙 관리
|
||||
├── services/
|
||||
│ └── system_service.py # 시스템 비즈니스 로직
|
||||
└── admin_routes.py # 인증만 (96줄)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 구현 완료
|
||||
|
||||
→ 상세: `troubleshooting/251225_admin_dashboard_code_refactoring.md`
|
||||
|
||||
### 결과
|
||||
- `app.js`: 1360줄 → 1132줄 (228줄 감소)
|
||||
- `admin_routes.py`: 1053줄 → 96줄 (957줄 감소)
|
||||
- Frontend: 모듈화 완료 (services, utils, modules 분리)
|
||||
- Backend: 계층 분리 완료 (router → service)
|
||||
|
||||
---
|
||||
|
||||
## 참고
|
||||
|
||||
- `311_FastAPI_구조_원칙.md`
|
||||
- `313_React_구조_원칙.md`
|
||||
- `troubleshooting/251225_admin_dashboard_code_refactoring.md`
|
||||
|
||||
@ -0,0 +1,95 @@
|
||||
# Admin Dashboard 코드 리팩토링 및 버그 수정
|
||||
|
||||
**날짜**: 2025-12-25
|
||||
**작성자**: Auto
|
||||
**관련 파일**: `admin-dashboard/backend/admin_routes.py`, `admin-dashboard/backend/routers/system.py`, `admin-dashboard/backend/services/system_service.py`, `admin-dashboard/backend/routers/admin_static.py`, `admin-dashboard/frontend/app.js`, `admin-dashboard/frontend/modules/diary.js`
|
||||
|
||||
---
|
||||
|
||||
## 문제 상황
|
||||
|
||||
### 1. Monolithic 코드 구조
|
||||
- `admin_routes.py`: 1053줄 (FastAPI 원칙 위반: 300줄 이하 권장)
|
||||
- `app.js`: 1360줄 (React 원칙 위반: 1000줄 이상 리팩토링 필수)
|
||||
- UI + API + State + Events 모두 혼재
|
||||
|
||||
### 2. 로그인 오류
|
||||
- `app.js:938`: 문자열 결합 문법 오류로 인한 "Invalid or unexpected token" 에러
|
||||
- 로그인 기능 완전 불가
|
||||
|
||||
### 3. 일기 API 경로 매칭 문제
|
||||
- FastAPI 동적 경로 `/diary/{target_date}`가 `/diary/list`의 "list"를 날짜로 파싱
|
||||
- 422 Unprocessable Entity 에러 발생
|
||||
|
||||
### 4. Gateway 프록시 호환성 문제
|
||||
- Nginx → Gateway(8100) → 백엔드(8000) 프록시 체인에서 404 에러
|
||||
- Gateway가 `/api/`를 제거하고 `/admin/diary/list`로 전달하지만 해당 경로 미등록
|
||||
|
||||
---
|
||||
|
||||
## 해결 방안
|
||||
|
||||
### 1. 백엔드 모듈 분리
|
||||
- **파일**: `admin_routes.py:95-158` → `routers/system.py`, `services/system_service.py`
|
||||
- 시스템 관리 로직을 router → service 계층으로 분리
|
||||
- `admin_routes.py`: 1053줄 → 96줄 (인증만 남김)
|
||||
|
||||
### 2. 정적 파일 서빙 구조 변경
|
||||
- **파일**: `routers/admin_static.py` 생성
|
||||
- Nginx 의존도 감소: FastAPI에서 직접 정적 파일 서빙
|
||||
- `main.py`에서 라우터 등록 순서 명시 (API 경로 우선, 정적 파일 마지막)
|
||||
|
||||
### 3. 프론트엔드 모듈화
|
||||
- **파일**: `modules/diary.js` 생성
|
||||
- 일기 관련 로직 분리 (loadDiaryList, loadDiary, renderDiaryList 등)
|
||||
- `app.js`: 1360줄 → 1132줄
|
||||
|
||||
### 4. 로그인 오류 수정
|
||||
- **파일**: `app.js:938`
|
||||
- 문자열 결합 문법 오류 수정 (명시적 `+` 연산자 사용)
|
||||
|
||||
### 5. 경로 매칭 문제 해결
|
||||
- **파일**: `routers/system.py:467-488`
|
||||
- `/diary/list` → `/diaries`로 변경하여 동적 경로와 충돌 방지
|
||||
- 경로 정의 순서 명시: `/diaries`가 `/diary/{target_date}`보다 먼저 정의
|
||||
|
||||
### 6. Gateway 프록시 호환성 확보
|
||||
- **파일**: `admin_routes.py:99-155`
|
||||
- `/admin/api/diary/list`와 `/admin/diary/list` 경로 모두 등록
|
||||
- Gateway가 `/api/`를 제거해도 정상 동작하도록 이중 경로 지원
|
||||
|
||||
---
|
||||
|
||||
## 구현 완료
|
||||
|
||||
- 커밋: `ac96e2a` (2025-12-25)
|
||||
- TDD 방식으로 진행 (Red → Green → Refactor)
|
||||
- 브라우저 테스트 완료 (Playwright)
|
||||
- 통합 검증 완료 (curl)
|
||||
|
||||
---
|
||||
|
||||
## 교훈
|
||||
|
||||
### 리팩토링 시 기존 경로 호환성 유지
|
||||
- Gateway 프록시 체인에서 경로 변환 발생 (`/admin/api/*` → `/admin/*`)
|
||||
- 기존 경로와 프록시 경로 모두 등록하여 호환성 확보 필요
|
||||
- 교훈: 프록시 환경에서는 경로 변환을 고려한 이중 경로 등록 필수
|
||||
|
||||
### FastAPI 경로 매칭 순서
|
||||
- 동적 경로(`{target_date}`)가 구체적 경로(`list`)보다 먼저 매칭될 수 있음
|
||||
- 구체적 경로를 먼저 정의하거나 경로명 변경으로 충돌 방지
|
||||
- 교훈: 동적 경로 사용 시 구체적 경로와의 충돌 검토 필수
|
||||
|
||||
### 모듈 분리 시 원칙 준수
|
||||
- FastAPI 구조 원칙: router → service → repository 계층 분리
|
||||
- React 구조 원칙: 300줄 이상 분리, 1000줄 이상 리팩토링 필수
|
||||
- 교훈: 원칙 문서(`311_FastAPI_구조_원칙.md`, `313_React_구조_원칙.md`) 참조하여 일관성 유지
|
||||
|
||||
---
|
||||
|
||||
## 참고
|
||||
|
||||
- 계획 문서: `journey/plans/251225_admin_dashboard_code_refactoring.md`
|
||||
- 원칙 문서: `300_architecture/311_FastAPI_구조_원칙.md`, `300_architecture/313_React_구조_원칙.md`
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user