# task-938.2 완료 보고서: 대시보드 토큰 사용량 시각화

## SCQA

**S**: 조직 대시보드(http://100.76.130.39:8000/dashboard/)가 8개 탭으로 운영 중이나, 토큰 사용량 모니터링 기능이 없어 비용 추적이 불가능했다.

**C**: 제이회장님이 "이상하게 토큰이 많이 소모된 작업이 있는지 한눈에 보여야 해"라고 요구. task-938.1의 토큰 추적 API가 미완성 상태에서도 시각화가 가능해야 한다.

**Q**: API 미완성 시에도 토큰 사용량을 실시간 시각화하고 이상치를 한눈에 파악할 수 있는가?

**A**: task-timers.json(818개 작업)에서 duration 기반 토큰 추정 엔진 + `/api/token-usage` API + Chart.js 시각화 뷰를 구현. 총 84.8M 토큰, $2,446 비용, 40건 이상치를 식별. 이상치 상위 5건은 평균(104K)의 31~80배. token-ledger.json이 생성되면 자동 전환.

## 산출물

### 신규 생성 (1건)
- `/home/jay/workspace/dashboard/components/TokenView.js` (467줄) — 토큰 시각화 React 컴포넌트

### 수정 (3건)
- `/home/jay/workspace/dashboard/server.py` — `get_token_usage()` 메서드 + `/api/token-usage` 엔드포인트 추가
- `/home/jay/workspace/dashboard/components/App.js` — tabs 배열에 '토큰' 탭 + TokenView 렌더링 추가
- `/home/jay/workspace/dashboard/index.html` — Chart.js CDN + TokenView.js 스크립트 로드 추가

## 구현 상세

### 1. 서버 API (`/api/token-usage`)
- `DataLoader.get_token_usage()` 메서드: token-ledger.json(우선) 또는 task-timers.json(fallback) 기반
- 추정 로직: `duration_seconds * 50 = input_tokens`, `input * 0.3 = output_tokens`
- Opus 기준 가격: `(input * 15 + output * 75) / 1M`
- 반환: tasks(최근 30건), summary(전체), anomalies(평균×2 이상), source

### 2. 프론트엔드 뷰
- **요약 카드 4개**: 총 토큰(84.8M), 총 비용($2,446.17), 평균 토큰(104K), 이상치(40건 빨간 배지)
- **바 차트**: Chart.js 가로 막대, 평균선 + 이상치(빨간색) 강조, X축 max = avg×4, tooltip에 상세 정보
- **이상치 알림**: 기본 5건 + 더보기 토글, 카드 형태 (task_id/설명/팀배지/토큰/ratio)
- **팀별 도넛 차트**: 팀 색상 구분, 중앙에 총 토큰 표시, 우측 비율 바
- **fallback**: API 실패 시 정적 데이터로 렌더링

### 3. 디자인
- 기존 대시보드 Tailwind 톤 유지
- 모바일 반응형 (grid-cols-1 sm:grid-cols-2 lg:grid-cols-4)
- CDN: Chart.js@4 (1개 추가)

## 테스트 결과

- **API 테스트**: `get_token_usage()` — Tasks: 30건, Summary: 818 작업 집계, Anomalies: 40건, Source: estimated — PASS
- **pyright**: 0 errors, 0 warnings, 0 informations — PASS
- **Bracket balance**: Braces 0, Parens 0, Brackets 0 — PASS
- **Playwright 브라우저 테스트**: Token tab 클릭 → 요약 카드 visible, 이상치 섹션 visible, 팀 차트 visible, 콘솔 에러 0건 — PASS

## 발견 이슈 및 해결

### 자체 해결 (3건)
1. **바 차트 스케일 왜곡** — 극단적 이상치(task-252.1: 8.3M)가 다른 막대를 압축. X축 max를 avg×4로 제한하여 해결.
2. **이상치 목록 과다** — 40건이 페이지를 지배. 기본 5건 표시 + "더보기 (+35건)" 토글로 해결.
3. **서버 재시작 필요** — API 추가 후 기존 서버에 반영되려면 재시작 필요. 서버 재시작 확인 완료.

### 범위 외 미해결 (1건)
1. **팀 카드에 토큰 정보 추가** — 작업 지시의 선택 사항 (항목 5). task-938.1 완료 후 token_usage 필드가 tasks API에 추가되면 기존 TeamCard에 자연스럽게 통합 가능. 현재는 추정 데이터이므로 별도 탭에서 확인하는 것이 적절.

## QC 자동 검증

- **overall**: PASS
- **file_check**: PASS (TokenView.js 23,410 bytes, server.py 114,026 bytes, report 3,782 bytes)
- **data_integrity**: PASS
- **test_runner**: PASS (pytest 6 passed in 0.24s)
- **pyright_check**: PASS (0 errors, 0 warnings)
- **style_check**: PASS (black OK, isort OK)
- **critical_gap**: PASS
- **spec_compliance**: PASS
- **duplicate_check**: PASS (최대 유사도 7.7%)
- **summary**: 8 PASS, 4 SKIP