Merge branch 'main' of https://git.ro-being.com/ivada_Ro-being/DOCS

2025-12-25 23:41:03 +09:00 · 2025-12-25 23:41:03 +09:00 · a859cbfa8d
commit a859cbfa8d
parent 2a55f87276 2beffa30c6
1 changed files with 177 additions and 0 deletions
--- a/journey/plans/251225_admin_dashboard_code_refactoring.md
+++ b/journey/plans/251225_admin_dashboard_code_refactoring.md
@ -0,0 +1,177 @@
+# 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`
+