From 1610103c46d47809f369b6538185cdb734473f3b Mon Sep 17 00:00:00 2001
From: happybell80 <happybell80@naver.com>
Date: Mon, 17 Nov 2025 18:12:58 +0900
Subject: [PATCH] docs: Add admin dashboard standard deployment refactoring
 (2025-11-17)

---
 ...shboard_standard_deployment_refactoring.md | 120 ++++++++++++++++++
 1 file changed, 120 insertions(+)
 create mode 100644 journey/troubleshooting/251117_admin_dashboard_standard_deployment_refactoring.md

diff --git a/journey/troubleshooting/251117_admin_dashboard_standard_deployment_refactoring.md b/journey/troubleshooting/251117_admin_dashboard_standard_deployment_refactoring.md
new file mode 100644
index 0000000..bb9a8e0
--- /dev/null
+++ b/journey/troubleshooting/251117_admin_dashboard_standard_deployment_refactoring.md
@@ -0,0 +1,120 @@
+# 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 간 토큰 키 불일치 방지
+