# task-553.1 완료 보고서: 대시보드 GPU 모니터링 추가

## SCQA

**S**: 서버에 NVIDIA GTX 1060 6GB GPU가 CUDA 12.2로 정상 작동 중이나, 대시보드는 CPU/RAM만 표시하고 있다.

**C**: GPU 사용률, VRAM, 온도 등 핵심 자원 정보가 대시보드에서 누락되어 서버 모니터링이 불완전하다.

**Q**: 기존 SSE server-stats에 GPU 데이터를 통합하고 UI에 표시할 수 있는가?

**A**: nvidia-smi 기반 GPU 데이터 수집 함수를 추가하고 server-stats의 4곳(HTTP API, HTTP SSE, FastAPI API, FastAPI SSE)에 통합 완료. 프론트엔드에 GPU 사용률/VRAM/온도/전력 배지를 CPU/RAM과 동일한 디자인으로 추가. GPU 없는 환경에서는 gpu 키가 응답에서 제외되어 graceful degradation 보장. pyright 에러 0건, 실제 API 테스트에서 GPU 데이터 정상 반환 확인.

## 작업 내용

### 백엔드 (server.py)
1. `DashboardHandler._get_gpu_stats()` 정적 메서드 추가
   - nvidia-smi CLI로 GPU 이름, 온도, 사용률, VRAM 사용/총량, 전력 수집
   - nvidia-smi 실패 시(GPU 없는 환경) `None` 반환 → 응답에 gpu 키 미포함
   - subprocess timeout 5초 설정
2. HTTP API `/api/server-stats` 응답에 `gpu` 필드 추가
3. HTTP SSE `handle_stream` server-stats 이벤트에 `gpu` 필드 추가
4. FastAPI GET `/api/server-stats` 응답에 `gpu` 필드 추가
5. FastAPI SSE `event_generator` server-stats 이벤트에 `gpu` 필드 추가

### 프론트엔드 (index.html)
1. CPU/RAM 배지 영역에 GPU 배지 블록 추가 (조건부 렌더링)
   - GPU 사용률: 60/80% 기준 green/amber/red
   - VRAM: 사용/총용량 MiB, 점유율 기반 색상
   - 온도: 60/80°C 기준 green/amber/red
   - 전력: 회색 고정 배지
2. `serverStats.gpu`가 없으면 GPU 영역 전체 미렌더링
3. `|` 구분자로 CPU/RAM과 GPU 시각적 분리

## 생성/수정 파일 목록
- `/home/jay/workspace/dashboard/server.py` — GPU 데이터 수집 함수 + 4곳 통합
- `/home/jay/workspace/dashboard/index.html` — GPU 모니터링 UI 배지 추가
- `/home/jay/workspace/dashboard/test_server.py` — GPU 테스트 6건 추가

## 테스트 결과
- pyright (server.py): 0 errors, 0 warnings
- GPU 단위 테스트: 6 passed (TestGetGpuStats)
  - dict/None 반환, 필수 필드 검증, 값 범위 검증, nvidia-smi 실패/미설치/타임아웃 처리
- 실제 API: `curl http://127.0.0.1:8000/api/server-stats` → gpu 필드 포함 확인
  - gpu_name: "NVIDIA GeForce GTX 1060 6GB", gpu_temp: 35, gpu_util: 0, vram_used_mib: 2, vram_total_mib: 6144, power_draw_w: 9.2
- 기존 pytest: 11 passed, 12 failed (모두 본 작업 범위 외 기존 회귀)

## 발견된 이슈 (3건)
1. **기존 테스트 회귀 12건**: `_classify_task_project`, `get_project_classified_tasks`, `get_system_status` 등 server.py에서 삭제된 메서드를 참조하는 테스트가 12건 실패 중. 본 작업 범위 외.
2. **GPU SSE 주기 차이**: HTTP SSE는 0.5초마다, FastAPI SSE는 10초(20사이클)마다 server-stats 전송. GPU 데이터도 동일 주기를 따르므로 FastAPI 모드에서는 GPU 업데이트가 덜 빈번함.
3. **VRAM 표시 단위**: MiB 단위로 표시되어 GPU가 6GB이면 "2M/6144M"으로 나옴. GB 단위 변환이 필요할 수 있으나, 정밀도 유지를 위해 현재 MiB 유지.

⚠️ 기존 테스트 실패 12건 (본 작업 범위 외): TestClassifyTaskProject, TestGetProjectClassifiedTasks, TestGetSystemStatus, TestGetSystemStatusStaleFiltering, TestProjectIdClassification, TestMemberStatusTimezone

## 완료 기준 체크
- [x] nvidia-smi로 GPU 데이터 수집 → SSE에 포함
- [x] 대시보드 UI에 GPU 사용률/VRAM/온도 표시
- [x] GPU 없는 환경에서 에러 없이 graceful 처리
- [x] 기존 CPU/RAM 표시와 시각적 일관성

## QC 자동 검증 결과
- overall: **WARN** (Gate PASS)
- file_check: PASS (3/3)
- data_integrity: PASS
- tdd_check: PASS (테스트 + 구현 파일 모두 존재)
- pyright_check: WARN (13건 — 기존 테스트 파일의 import 경로 문제, 본 작업 범위 외)
- style_check: PASS (black + isort 준수)
- .done 생성: /home/jay/workspace/memory/events/task-553.1.done