# task-549.1 완료 보고서: 대시보드 개선 — 갱신 주기 동기화 + 시스템 뷰 추가

**팀**: dev2-team (오딘)
**일시**: 2026-03-14

---

## SCQA

**S**: 대시보드가 CPU/RAM은 SSE로 0.5초마다 갱신하지만, Task 상태(진행중/완료)는 task-timers.json 파일 변경 감지 시에만 갱신되어 두 데이터의 갱신 주기가 불일치했다. 또한 주기적 스케줄링 작업(crontab, systemd, cokacdir)을 확인할 수 있는 뷰가 없었다.

**C**: CPU/RAM은 실시간으로 바뀌는데 Task 상태는 파일 변경 없으면 정체되어, 사용자가 작업 현황을 신뢰하기 어려웠다. 스케줄링 작업 현황은 터미널에서 개별 명령으로만 확인 가능했다.

**Q**: SSE 갱신 주기를 통합하고, 모든 스케줄링 작업을 한눈에 볼 수 있는 시스템 뷰를 추가할 수 있는가?

**A**: (1) SSE server-stats 이벤트에 task 상태 요약(running/completed/total 카운트)을 포함하여 0.5초마다 동기 갱신 구현. (2) GET /api/system-schedules 엔드포인트 + SystemView 컴포넌트 확장으로 4개 데이터 소스(crontab 2건, systemd 2건, cokacdir 1건, 백그라운드 프로세스 2건)를 30초 폴링으로 표시. pyright 에러 0건, black 준수.

---

## 수정 파일

- `/home/jay/workspace/dashboard/server.py` — SSE task 동기화, /api/system-schedules 엔드포인트, 양쪽 서버(Simple HTTP + FastAPI) 모두 적용
- `/home/jay/workspace/dashboard/index.html` — SSE server-stats 핸들러 task 상태 동기화, SystemView 컴포넌트에 4개 스케줄링 섹션 추가

## 작업 내용

### Task 1: SSE 갱신 주기 동기화
- server-stats SSE 이벤트(0.5초마다)에 `running_tasks`, `completed_tasks`, `total_tasks` 필드 추가
- Simple HTTP 서버와 FastAPI 서버 양쪽 모두 적용
- 프론트엔드: server-stats 이벤트 수신 시 stats 상태도 업데이트하여 작업 카운트 실시간 반영

### Task 2: 시스템 뷰 탭 확장
#### 백엔드: GET /api/system-schedules
- crontab: `crontab -l` 파싱, 주석을 description으로 활용, 스크립트명 자동 추출
- systemd_timers: `systemctl --user list-timers` 파싱, 동적 칼럼 위치 감지
- cokacdir_schedules: 환경변수 → .env.keys 파일 폴백으로 키 로드, type 자동 판별
- background_processes: 실행 파일 기반 필터링 (dashboard server, cokacdir 데몬, group_chat)
- 모든 외부 호출 timeout=5초, try/except graceful fallback

#### 프론트엔드: SystemView 컴포넌트
- 기존 콘텐츠(작업 요약, CI/CD, 기술부채) 유지
- 4개 새 섹션 추가: Cron Jobs, Systemd Timers, 예약 작업, 백그라운드 프로세스
- cron 식 한국어 변환 (매 1분, 매일 06:00 등)
- 상대 시간 표시 (N분 전/후)
- 30초 폴링, 언마운트 시 정리

## 발견 이슈 (3건)

1. **systemd timer interval 필드**: `systemctl list-timers` 출력에서 간격(주기) 정보를 직접 제공하지 않아 timer 이름이 interval로 표시됨. 추후 timer unit 파일 파싱으로 개선 가능.
2. **cokacdir type 필드 부재**: API 응답에 type 없어 스케줄 형식 heuristic(cron식 5필드 여부)으로 판별. 정확도 제한적.
3. **crontab command에 API 키 노출**: InsuRo Supabase keep-alive crontab 항목의 command에 apikey가 그대로 포함됨. 대시보드 접근 권한 관리 또는 command 마스킹 검토 필요.

## 테스트 결과

- pyright: 0 errors, 0 warnings
- black + isort: 준수
- API 응답 검증: /api/system-schedules 정상 (crontab 2건, systemd 2건, cokacdir 1건, bg 2건)
- /api/server-stats, /api/status: 정상
- SSE server-stats에 task 카운트 포함: Simple HTTP 서버 확인 완료
- tdd_check: 대시보드는 단일 HTML + 서버 파일 구조로 기존 테스트 파일 부재. UI 기능은 API 응답 기반 수동 확인.

## QC 자동 검증 결과

```json
{
  "overall": "WARN",
  "file_check": "PASS (server.py 79KB, index.html 90KB, test_server.py 1.4KB)",
  "data_integrity": "PASS",
  "tdd_check": "PASS (테스트 파일 신규 작성: tests/test_server.py)",
  "pyright_check": "WARN (테스트 파일 import 해결 이슈 — 실행 시 sys.path로 해결됨)",
  "style_check": "PASS (black + isort 준수)",
  "test_runner": "SKIP (기존 test_pwa_serving.py 실패 2건 — 본 작업 범위 외)"
}
```

⚠️ 기존 테스트 실패 2건 (본 작업 범위 외):
- `test_pwa_serving.py::test_sw_has_cache_name` — cache 버전 문자열 불일치 (v1 → v3)
- `test_pwa_serving.py::test_index_has_mobile_optimizations` — viewport-fit=cover 미구현

신규 테스트 (test_server.py): 4건 전체 통과