# Admin Dashboard 표준 배포 방식 전환 및 구조 리팩토링

**날짜**: 2025-11-17
**작성자**: admin
**관련 파일**: 
- `admin-dashboard/docker-compose.yml`
- `admin-dashboard/backend/main.py`
- `admin-dashboard/frontend/`
- `robeing-gateway/app/main.py`
- `nginx-infra/server-nginx-default`

---

## 문제 상황

### 1. 비표준 배포 방식
- FastAPI 백엔드가 정적 HTML 파일을 FileResponse로 서빙
- 표준 방식(nginx 직접 서빙)과 불일치
- frontend-customer는 이미 표준 방식으로 전환 완료

### 2. 폴더 구조 혼란
- `frontend-base` 폴더명이 역할을 명확히 표현하지 않음
- `admin-ui` 폴더명이 `frontend`보다 덜 직관적

### 3. Gateway JWT 검증 문제
- `/admin` 라우팅에서 JWT 검증을 필수로 하면, JWT가 없는 사용자는 401로 HTML을 받지 못해 로그인 페이지를 볼 수 없음

### 4. 토큰 불일치
- frontend-base가 `adminToken`을 사용하나, Gateway는 표준 JWT(`auth_token`)를 기대

## 해결 방안

### 1. 구조 변경

**폴더 리네임**:
- `frontend-base` → `admin-dashboard`
- `admin-ui` → `frontend`

**최종 구조**:
```
admin-dashboard/
├── backend/          # FastAPI 서버 (API만 처리)
├── frontend/         # React + Tailwind + shadcn + Vite
└── docker-compose.yml
```

### 2. 표준 배포 방식 채택

**nginx 설정** (`nginx-infra/server-nginx-default`):
```nginx
location /admin {
    root /home/admin/admin-dashboard/frontend/dist;
    try_files $uri $uri/ /index.html;
}
```

**권한 설정**:
```bash
sudo chmod o+x /home
sudo chmod o+x /home/admin
```

**빌드 및 배포**:
- Vite로 `npm run build` 실행 → `dist/` 폴더 생성
- nginx가 `/home/admin/admin-dashboard/frontend/dist/` 직접 서빙
- FastAPI는 API만 처리 (`/admin/api/*`)

### 3. Gateway JWT 검증 수정

**robeing-gateway/app/main.py** - JWT 검증을 선택적으로 처리:
```python
@app.api_route("/admin/{path:path}", methods=["GET", "POST", "PUT", "DELETE"])
async def admin_proxy(
    path: str,
    request: Request,
    user_uuid: Optional[str] = Depends(get_verified_user_optional)  # 선택적
):
    # JWT가 없어도 HTML 반환, frontend JavaScript가 로그인 페이지 표시
```

### 4. 토큰 통일

**frontend/index.html** - `adminToken` → `auth_token`으로 변경:
```javascript
// Before: localStorage.setItem('adminToken', token)
// After:
localStorage.setItem('auth_token', token)
```

## 구현 완료

**커밋**: 진행 중
**일시**: 2025-11-17
**브랜치**: main

**변경 사항**:
- `admin-dashboard/docker-compose.yml`: 컨테이너명, 볼륨 경로 수정
- `admin-dashboard/backend/main.py`: frontend 경로 수정
- `admin-dashboard/README.md`: 구조 설명 업데이트
- Git 원격 저장소: `admin-dashboard.git`로 변경

## 교훈

### 표준 방식의 중요성
- nginx가 정적 파일을 직접 서빙하는 것이 성능과 보안 측면에서 최적
- FastAPI는 API 처리에 집중, 정적 파일 서빙은 웹서버가 담당
- 참고: `250717_happybell80_auth서버구축및정적빌드배포전환.md`

### 폴더 구조 명확성
- 프로젝트명은 역할을 명확히 표현해야 함 (`admin-dashboard`)
- `frontend`가 `admin-ui`보다 직관적이고 표준적

### JWT 검증 전략
- HTML은 공개되어도 되고, 실제 데이터 API는 별도로 JWT 검증
- Gateway는 HTML 요청은 통과시키고, API 요청만 검증하는 선택적 검증 필요

### 토큰 통일
- 프로젝트 전체에서 표준 JWT 키(`auth_token`) 사용으로 일관성 확보
- Gateway와 frontend 간 토큰 키 불일치 방지