docs: Admin Dashboard 캐시 문제 및 Nginx 상태 카드 제거 트러블슈팅 문서 추가

journey/troubleshooting/260116_admin_dashboard_cache_and_nginx_card_fix.md

@@ -0,0 +1,70 @@
+# Admin Dashboard 캐시 문제 및 Nginx 상태 카드 제거
+
+**날짜**: 2026-01-16
+**작성자**: admin
+**관련 파일**:
+- `admin-dashboard/backend/routers/admin_static.py`
+- `admin-dashboard/frontend/index.html`
+- `admin-dashboard/frontend/modules/system.js`
+- `admin-dashboard/backend/services/system_service.py`
+
+---
+
+## 문제 상황
+
+### 1. 브라우저 캐시로 인한 반영 실패
+- 15일 구축한 카드/테이블 형식이 브라우저에 반영되지 않음
+- `index.html` 자체에 캐시 방지 헤더가 없어 브라우저가 오래된 HTML을 로드
+- `styles.css`에 버전 파라미터가 없어 CSS 캐시 문제 발생
+
+### 2. Nginx 상태 카드 불필요
+- 사용자 요청으로 Nginx 상태 카드 제거 필요
+
+### 3. Git 충돌 마커로 인한 앱 시작 실패
+- `system_service.py:389`에 Git 충돌 마커(`>>>>>>>`) 잔존하여 SyntaxError 발생
+
+---
+
+## 해결 방안
+
+### 1. 캐시 방지 헤더 강제 적용
+- `admin_static.py:13-19`: `/admin` 루트 경로 응답에 캐시 방지 헤더 추가
+- `admin_static.py:40-47`: 모든 정적 파일 응답에 `Cache-Control: no-cache, no-store, must-revalidate` 적용
+
+### 2. 버전 파라미터 갱신
+- `index.html:10`: `styles.css?v=20260116` 버전 파라미터 추가
+- `index.html:21-25`: 모든 JS 파일 버전 파라미터 `v=20260116`으로 통일
+
+### 3. Nginx 상태 카드 제거
+- `index.html:233-247`: `systemSection` 내 Nginx 상태 카드 제거
+- `index.html:303-320`: `system-servicesSection` 내 Nginx 상태 카드 제거
+- `system.js:96-120`: `loadNginxStatus()` 함수에 null 체크 추가
+- `system.js:465-470`: `loadServices()` 함수 내 nginxStatus 처리에 null 체크 추가
+
+### 4. Git 충돌 마커 제거
+- `system_service.py:389`: 충돌 마커 제거
+
+---
+
+## 구현 완료
+
+- 커밋: `6dcc781` - 캐시 방지 헤더 및 버전 파라미터 적용
+- 커밋: `b6f6718` - Git 충돌 마커 제거
+- 커밋: `7c21179`, `ca02693` - Nginx 상태 카드 제거
+- 배포: Gitea Actions 자동 배포 완료, 컨테이너 수동 재시작으로 즉시 반영 확인
+
+---
+
+## 교훈
+
+### 캐시 문제 반복 발생 원인
+- **수동 버전 관리의 한계**: JS만 갱신하고 CSS 누락하는 습관적 작업 방식
+- **시스템적 캐시 제어 부재**: HTML 자체에 캐시 방지 헤더가 없어 브라우저가 로컬 캐시 우선 사용
+
+### 재발 방지책
+- **시스템적 강제 적용**: `admin_static.py`에서 모든 정적 파일 응답에 캐시 방지 헤더를 강제로 적용 (휴먼 에러 방지)
+- **원칙 문서 강화**: `AGENTS.md`에 "정적 자산 수정 시 CSS/JS 버전 파라미터 동시 갱신" 최우선 체크리스트 명시
+- **배포 후 검증**: `curl -I` 명령으로 서버 응답 헤더의 최신화 여부를 사실 기반으로 직접 검증
+
+### Git 충돌 마커 관리
+- 배포 전 `grep` 명령으로 충돌 마커(`<<<<<<<`, `=======`, `>>>>>>>`) 검색 필수