ivada-infra/DOCS

Fork 0

happybell80 56b48f81ff docs: Admin Dashboard 계획에 API 스키마 및 페이지네이션 전략 추가

2025-12-04 16:58:45 +09:00

5.4 KiB

Raw Blame History

Admin Dashboard 비즈니스 통합 계획

날짜: 2025-12-04
작성자: Auto
관련 파일:

admin-dashboard/backend/admin_routes.py
admin-dashboard/frontend/index.html

목표

admin-dashboard를 인프라 모니터링 도구에서 로빙 프로젝트 비즈니스 관리 도구로 확장.

현재 상태

기존 기능 (4개 탭)

대시보드: 시스템 메트릭(CPU/메모리/디스크/업타임), Chart.js 그래프
컨테이너: Docker 컨테이너 목록, 로그 조회, 재시작
서비스: Nginx 상태, Git 활동
로그: 시스템 로그

문제점

main_db 미연결: user/team/robeing 데이터 접근 불가
FastAPI 원칙 위반: admin_routes.py 1053줄 (권장 300줄 초과), 계층 분리 없음
비즈니스 기능 전무: 사용자 관리, 로빙 현황, 스킬 통계 없음

개선 계획 (도메인별 계층 분리 + 병렬 처리)

1. 파일 구조 리팩토링 (FastAPI 원칙 준수)

현재 문제: 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. API 스키마 정의 (schemas/)

패턴 참고: auth-server의 WorkspaceResponse/WorkspaceCreate 구조

User 스키마:

UserResponse: id, email, name, username, metadata(dict), is_active, last_login_at
UserUpdate: name, metadata (부분 업데이트)
UserList: items(list[UserResponse]), total, page, limit

Robeing 스키마:

RobeingResponse: id, team_id, name, level, stats(memory/compute/react/empathy/leadership)
RobeingStats: 대화 빈도, 스킬 사용 횟수, 감정 트렌드

공통:

PaginationParams: limit(기본 50), offset(기본 0)
ErrorResponse: detail(str), code(int)
metadata JSONB는 dict[str, Any]로 직렬화

3. 페이지네이션 전략

기본 방식: limit/offset 파라미터 (단순 구현, admin 용도 충분)

모든 리스트 API: ?limit=50&offset=0 기본값
응답: {"items": [...], "total": int, "page": int, "limit": int}

대용량 테이블 처리:

conversation_log(수만 건): 날짜 범위 필터 필수 (?start_date=&end_date=)
emotion_readings: 시간대별 집계 쿼리 (GROUP BY), 원본 데이터 페이지네이션
rb_news/team_document: created_at DESC 인덱스 활용

프론트엔드 UI: 페이지 번호 버튼 (1, 2, 3... 10) + 이전/다음 향후 고려: cursor 기반 페이지네이션 (성능 우수, 구현 복잡)

4. 성능 최적화

병렬 처리: asyncio.gather()로 다중 DB 조회 동시 실행 (순차 대비 66% 성능 향상) 검증 완료: 계층 분리는 성능 오버헤드 없음 (테스트 확인)

5. 신규 탭 3개 (UX 중심)

탭 1: 사용자/팀

테이블 뷰: user/team 목록, 검색/필터/정렬
컬럼: email, name, username, metadata(nickname/position), is_active, last_login_at
액션 버튼: 편집(metadata 수정 모달), 상세보기(OAuth 연동 상태), 비활성화
통계 카드: 총 사용자 수, 활성 사용자, 팀별 사용자 분포

탭 2: 로빙

테이블 뷰: robeing 목록(team_id, name, level)
시각화: 레이더 차트(memory/compute/react/empathy/leadership), 레벨 분포 막대 그래프
액션: 로빙 상세(대화 빈도, 스킬 사용 이력), 팀별 비교
통계 카드: 총 로빙 수, 평균 레벨, 팀별 활동량(conversation_log 기반)

탭 3: 스킬/의도

대시보드: 의도 분류 통계(intents), 스킬 실행 횟수(뉴스/이메일/IR분석), LLM 호출 추이
차트: 히트맵(시간대별 스킬 사용), 파이 차트(의도 분포)
테이블: rb_news(최근 발행), team_document(RAG 문서), ir_deck_evaluations(IR 평가 현황)

6. 공통 UI 패턴

우측 상단: 새로고침/필터/CSV 다운로드 버튼
테이블 행: 편집/삭제/상세 아이콘 버튼
모달: metadata 편집, 상세 정보 표시
차트: Chart.js, 일/주/월 필터

구현 단계

기존 파일 분리: admin_routes.py(1053줄) → routers/system.py(~300줄) 분리
Repository 레이어: state/user_repository.py, state/robeing_repository.py 생성 (main_db 연결)
Service 레이어: services/user_service.py, services/robeing_service.py 생성
Router 추가: routers/users.py, routers/robeings.py 생성 (asyncio.gather() 병렬 처리)
Frontend: 3개 탭 추가, 테이블/차트 컴포넌트, metadata 편집 모달
테스트: 성능(병렬 처리 확인), CRUD, UI 동작 검증

참고

문서 작성 원칙: DOCS/book/300_architecture/312_문서_작성_원칙.md
기존 admin 리팩토링: DOCS/journey/troubleshooting/251117_admin_dashboard_standard_deployment_refactoring.md

5.4 KiB Raw Blame History