happybell80 7b8739528c docs: Admin Dashboard 비즈니스 통합 완료 및 캐싱 전략 원칙 추가

- troubleshooting: 계층 분리, Gateway 프록시, 브라우저 캐시 해결 과정
- React 원칙: 프론트엔드 캐싱 전략 섹션 추가 (버전 파라미터 필수)

2025-12-04 17:45:39 +09:00

2.6 KiB

Raw Blame History

Admin Dashboard 비즈니스 통합 - 사용자/팀 및 로빙 관리 기능 추가

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

admin-dashboard/backend/routers/users.py
admin-dashboard/backend/routers/robeings.py
admin-dashboard/frontend/app.js:747-843
robeing-gateway/app/routers/admin.py:48-57

문제 상황

기존 한계

admin-dashboard는 인프라 모니터링만 제공 (시스템/Docker/nginx)
main_db 미연결로 사용자/팀/로빙 데이터 접근 불가
admin_routes.py 1053줄 (FastAPI 권장 300줄 초과), 계층 분리 없음

해결 방안

1. FastAPI 계층 분리

구조: admin-dashboard/backend/

schemas/user.py, schemas/robeing.py: Pydantic 모델
state/user_repository.py, state/robeing_repository.py: main_db CRUD
services/user_service.py, services/robeing_service.py: 비즈니스 로직
routers/users.py, routers/robeings.py: API 엔드포인트

원칙 준수: router → service → repository, DB 접근은 repository에서만

2. main_db 연결

docker-compose.yml:19: DATABASE_URL=postgresql+asyncpg://robeings:robeings@172.17.0.1:5432/main_db state/user_repository.py:14: AsyncEngine 생성, asyncpg 사용

3. Frontend UI 추가

index.html:73-96: 사용자/팀, 로빙 네비게이션 메뉴 index.html:301-364: 사용자/팀, 로빙 섹션 (통계 카드 + 테이블) app.js:747-843: loadUsers(), loadRobeings() 함수 (asyncio 병렬 처리)

4. Gateway 프록시 수정

문제: 신규 API(/admin/api/users)와 기존 API(/admin/system) 경로 패턴 상이 해결: robeing-gateway/app/routers/admin.py:48-57 - 조건부 경로 처리

- users/robeings → /admin/api/* 유지
- 기타 → /admin/* 변환

5. 브라우저 캐시 문제

문제: app.js 수정했지만 브라우저가 오래된 캐시 사용 해결: index.html:20 - <script src="/admin/app.js?v=20251204">

구현 완료

커밋: admin-dashboard(0365162), robeing-gateway(8a682bd) 테스트: 14명 사용자, 2개 로빙 조회 성공

교훈

1. 작업 전 기존 구조 파악 필수

포트(8000), Gateway 프록시 구조를 docs 미확인하고 변경 시도 → 시간 낭비
AGENTS.md에 "구조 파악 필수" 원칙 추가

2. Gateway 프록시 경로 설계

신규/기존 API 경로 패턴 통일 필요
조건부 처리로 해결 가능하나 복잡도 증가

3. 브라우저 캐시 회피

JS/CSS 수정 시 버전 파라미터(?v=YYYYMMDD) 필수
Ctrl+F5도 안 되는 경우 있음 (nginx ETag)

2.6 KiB Raw Blame History