# task-1816.1 완료 보고서 — 대시보드 인프라 개선 Lv.4: 코드 변경 즉시 반영 시스템

## SCQA

**S**: 대시보드(server.py, *.js)를 수정할 때마다 수동 서버 재시작 + 브라우저 강제 새로고침이 필요하여 개발 효율이 저하되고 있다.

**C**: (1) server.py 수정 시 수동 재시작 필수, (2) JS 수정 시 SW 캐시로 구버전 표시, (3) 두 문제가 반복되어 작업 속도가 저하됨. 특히 SW의 프리캐시가 JS 파일을 캐시하여 코드 수정이 반영되지 않는 것이 핵심 원인.

**Q**: 수동 개입 없이 서버 코드와 프론트엔드 변경을 즉시 반영할 수 있는가?

**A**: 3가지 조치를 구현하여 해결: (1) SW 제거 + ETag 기반 캐시 검증으로 JS 즉시 반영, (2) watchdog 기반 auto_reload로 .py 변경 시 자동 재시작, (3) systemd 서비스로 상시 감시. ETag 304 응답 확인, auto_reload 재시작 PID 변경 확인, data/ 제외 확인 완료.

---

## 구현 내역

### Step 1: SW 제거 + ETag 캐시 검증

**index.html 변경**:
- SW 등록(`navigator.serviceWorker.register`) → unregister 코드로 교체
- 기존 사용자의 SW 캐시 자동 삭제: `caches.keys().forEach(delete)`
- PWA 메타 태그 제거: `manifest.json` 링크, `apple-mobile-web-app-*`
- `theme-color` 유지 (브라우저 테마용)

**server.py 변경**:
- `Cache-Control: no-cache, no-store, must-revalidate` → `Cache-Control: no-cache`로 변경
- `Pragma`, `Expires` 헤더 제거 (불필요)
- 정적 파일(.js, .json, .html, .css)에 ETag 헤더 추가 (`mtime_size` 기반)
- `If-None-Match` 헤더 처리: ETag 일치 시 304 Not Modified 응답
- 304 응답 시 `_no_cache_static` 플래그 해제로 중복 헤더 방지

### Step 2: auto_reload 파일감시 + systemd 서비스

**auto_reload.py (신규)**:
- watchdog `FileSystemEventHandler` 기반 dashboard/ 디렉토리 감시
- `.py` 파일 변경/생성 시 `systemctl --user restart dashboard.service` 실행
- 디바운스: 2초 Timer로 연속 변경 시 마지막 1회만 재시작
- 제외: `data/`, `__pycache__/`, `.git/` 디렉토리 + `.pyc`, `.db`, `.json`, `.log`, `.pem` 확장자
- 로깅: 변경 파일명 + 재시작 시각 기록

**dashboard-watcher.service (신규)**:
- auto_reload.py를 systemd user 서비스로 등록
- `After=dashboard.service`, `Restart=always`
- 로그를 server.log에 통합

---

## 테스트 결과

### ETag 캐시 검증
- `curl -sv http://localhost:8000/dashboard/components/App.js` → 200 OK + `ETag: "1776166964_71671"` + `Cache-Control: no-cache` 확인
- `curl -H 'If-None-Match: "..."'` → 304 Not Modified + 단일 Cache-Control 헤더 확인
- API 엔드포인트(`/api/status`, `/api/org`) → 200 OK 정상 (회귀 없음)

### auto_reload 자동 재시작
- helpers.py에 주석 추가 → PID 697298 → 697950 변경 확인 (자동 재시작 성공)
- data/wiki-statuses.json 수정 → PID 변경 없음 (data/ 제외 정상)
- dashboard-watcher.service → `active (running)`, 메모리 9.4M

### 테스트 스위트
- `tests/test_pwa_serving.py`: 9/9 PASS (SW unregister, PWA 메타 제거 검증)
- `test_server.py`: 18 passed, 1 warning (pytest) — 기존 실패 제외

---

## 발견 이슈 및 해결

### 자체 해결 (3건)
1. **304 응답 시 Cache-Control 중복** — `_no_cache_static` 플래그 미해제로 end_headers()에서 중복 전송. 304 경로에서 플래그 해제 추가 (server.py:3900)
2. **auto_reload.py pyright 타입 에러** — `event.src_path`가 `bytes | str` 타입. `str()` 변환 + `FileSystemEvent` 타입 힌트 추가
3. **test_pwa_serving.py 테스트 실패** — SW 제거로 기존 `test_index_has_pwa_meta` 실패. `test_index_sw_unregister` + `test_index_no_pwa_meta`로 교체

### 범위 외 미해결 (2건)
1. **server.py pyright "too complex" 에러 2건** (do_GET:1612, do_POST:5261) — 범위 외 사유: 기존 7200줄 핸들러 구조적 문제. 리팩토링은 별도 작업 필요
2. **test_server.py 기존 실패 10건** (GPU 모듈 임포트 7건, bot detection 3건) — 범위 외 사유: 이번 작업 이전부터 존재하는 실패

---

## 산출물 파일

### 신규 생성
- `/home/jay/workspace/dashboard/auto_reload.py`
- `/home/jay/.config/systemd/user/dashboard-watcher.service`

### 수정
- `/home/jay/workspace/dashboard/server.py` (end_headers ETag + 정적파일 304 처리)
- `/home/jay/workspace/dashboard/index.html` (SW register → unregister + PWA 메타 제거)
- `/home/jay/workspace/dashboard/tests/test_pwa_serving.py` (PWA 테스트 → SW unregister 테스트)

### 기존 유지 (삭제하지 않음)
- `/home/jay/workspace/dashboard/sw.js` (기존 사용자 SW 정리 기간 후 삭제 예정)
- `/home/jay/workspace/dashboard/manifest.json` (참조 제거 완료, 파일은 유지)

---

## 모델 사용 기록

- 이리스 / index.html SW 제거 + unregister 교체 / sonnet / -
- 불칸 / server.py ETag + auto_reload.py + systemd 서비스 / sonnet / -
- 아르고스 / test_pwa_serving.py 테스트 업데이트 / sonnet / -

---

## QC 결과

- test_runner: PASS (18 passed)
- pyright_check: FAIL (기존 복잡도 에러 2건 — 이번 작업 무관)
- style_check: WARN → black/isort 적용 완료
- tdd_check: WARN (인프라 작업 특성상 구현 선행)
- data_integrity: PASS
- file_check: PASS (보고서 + .done 생성 후)

## 세션 통계
- 총 도구 호출: 0회