docs: Admin Dashboard 계획 - FastAPI 원칙 준수 및 성능 최적화 반영

journey/plans/251204_admin_dashboard_business_integration.md

@@ -20,19 +20,41 @@ admin-dashboard를 인프라 모니터링 도구에서 **로빙 프로젝트 비
 - **서비스**: Nginx 상태, Git 활동
 - **로그**: 시스템 로그
 
-### 한계
-- main_db 미연결: user/team/robeing 데이터 접근 불가
-- 비즈니스 운영 기능 전무: 사용자 관리, 로빙 현황, 스킬 통계 없음
-- DevOps 도구 수준, 로빙 프로젝트 관리자 용도 미흡
+### 문제점
+- **main_db 미연결**: user/team/robeing 데이터 접근 불가
+- **FastAPI 원칙 위반**: `admin_routes.py` 1053줄 (권장 300줄 초과), 계층 분리 없음
+- **비즈니스 기능 전무**: 사용자 관리, 로빙 현황, 스킬 통계 없음
 
-## 개선 계획
+## 개선 계획 (도메인별 계층 분리 + 병렬 처리)
 
-### 1. DB 연결 방식
-- **admin-dashboard/backend**: main_db PostgreSQL 직접 연결 (read-only)
-- **이유**: 로컬 환경, 빠른 조회/통계, 복잡한 조인 가능
-- **관련**: `admin_routes.py` - SQLAlchemy 또는 asyncpg로 main_db 연결 추가
+### 1. 파일 구조 리팩토링 (FastAPI 원칙 준수)
 
-### 2. 신규 탭 3개 (UX 중심)
+**현재 문제**: `admin_routes.py` 1053줄 (300줄 권장 초과)
+
+**개선 구조**:
+```
+admin-dashboard/backend/
+├── routers/
+│   ├── system.py        # 시스템/Docker (기존 기능, ~300줄)
+│   ├── users.py         # 사용자/팀 관리 (~200줄)
+│   └── robeings.py      # 로빙/스킬 관리 (~200줄)
+├── services/
+│   ├── user_service.py      # 사용자 비즈니스 로직
+│   └── robeing_service.py   # 로빙 비즈니스 로직
+├── state/
+│   ├── user_repository.py   # main_db user/team CRUD
+│   └── robeing_repository.py # main_db robeing/conversation CRUD
+└── main.py
+```
+
+**원칙 준수**: router(HTTP) → service(비즈니스) → repository(DB), DB 접근은 repository에서만
+
+### 2. 성능 최적화
+
+**병렬 처리**: asyncio.gather()로 다중 DB 조회 동시 실행 (순차 대비 66% 성능 향상)
+**검증 완료**: 계층 분리는 성능 오버헤드 없음 (테스트 확인)
+
+### 3. 신규 탭 3개 (UX 중심)
 
 #### 탭 1: 사용자/팀
 - **테이블 뷰**: user/team 목록, 검색/필터/정렬
@@ -51,7 +73,7 @@ admin-dashboard를 인프라 모니터링 도구에서 **로빙 프로젝트 비
 - **차트**: 히트맵(시간대별 스킬 사용), 파이 차트(의도 분포)
 - **테이블**: rb_news(최근 발행), team_document(RAG 문서), ir_deck_evaluations(IR 평가 현황)
 
-### 3. 공통 UI 패턴
+### 4. 공통 UI 패턴
 - **우측 상단**: 새로고침/필터/CSV 다운로드 버튼
 - **테이블 행**: 편집/삭제/상세 아이콘 버튼
 - **모달**: metadata 편집, 상세 정보 표시
@@ -59,10 +81,12 @@ admin-dashboard를 인프라 모니터링 도구에서 **로빙 프로젝트 비
 
 ## 구현 단계
 
-1. **Backend**: `admin_routes.py`에 main_db 연결, `/admin/api/users`, `/admin/api/robeings`, `/admin/api/skills` 엔드포인트 추가
-2. **Frontend**: 3개 탭 추가, 테이블 컴포넌트, 차트 컴포넌트, 모달 구현
-3. **테스트**: 각 탭별 CRUD 동작, 차트 렌더링, 검색/필터 확인
-4. **문서화**: 완료 시 troubleshooting 문서로 이동
+1. **기존 파일 분리**: `admin_routes.py`(1053줄) → `routers/system.py`(~300줄) 분리
+2. **Repository 레이어**: `state/user_repository.py`, `state/robeing_repository.py` 생성 (main_db 연결)
+3. **Service 레이어**: `services/user_service.py`, `services/robeing_service.py` 생성
+4. **Router 추가**: `routers/users.py`, `routers/robeings.py` 생성 (asyncio.gather() 병렬 처리)
+5. **Frontend**: 3개 탭 추가, 테이블/차트 컴포넌트, metadata 편집 모달
+6. **테스트**: 성능(병렬 처리 확인), CRUD, UI 동작 검증
 
 ## 참고