# 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` 명령으로 충돌 마커(`<<<<<<<`, `=======`, `>>>>>>>`) 검색 필수
