전체 화면 / 위젯
대시보드 페이지 (web/src/pages/Dashboard.tsx)의 5개 위젯이 어떻게 동작하는지 정리합니다.
📸 대시보드 위젯 레이아웃 (추후 자동 캡처 예정)
StatsGrid (상단 카드)
사용자 봇의 실시간 KPI를 카드 그리드로 보여줍니다.
| 카드 | 의미 | 데이터 소스 |
|---|---|---|
| Equity | 현재 총 자산 (USD/USDT/KRW 환산) | summary.equity |
| Daily P&L | 당일 손익 (절대값 / %) | summary.daily_pnl, summary.daily_pnl_pct |
| Total P&L | 누적 P&L | summary.total_pnl, summary.total_pnl_pct |
| Open Positions | 현재 오픈 포지션 수 | summary.open_positions |
| Today's Trades | 당일 거래 수 | summary.total_trades_today |
| Win Rate | 승률 (%) | summary.win_rate |
| Sharpe | 샤프 비율 (초기 0) | summary.sharpe_ratio |
| Max DD | 최대 낙폭 | summary.max_drawdown |
값이 양수면 emerald(녹색), 음수면 rose(빨강) 컬러로 차이가 표시됩니다.
EquityChart (중앙 곡선)
TradingView Lightweight Charts 기반 시계열 자산 곡선입니다.
- X축: ISO timestamp
- Y축: USD 환산 자산
- 우상단의 1d / 1w / 1m 버튼으로 기간 변경 (현재 1d 기본)
- 데이터 소스:
GET /api/dashboard/equity?period=1d→EquityPoint[] - 비어있을 때: "No equity data yet — start the bot to begin tracking" 메시지
OpenPositions / RecentTrades (좌우 2열)
좌측은 현재 오픈 포지션 목록, 우측은 최근 5건의 거래 이력입니다.
- 좌측:
GET /api/positions?asset_class=...(1초 폴링) - 우측:
GET /api/trades?page=1&limit=5&asset_class=...(1초 폴링) - 자산군 배지(crypto=amber, us=blue, kr=rose)가 함께 표시됩니다.
- 상세 페이지로 이동: 행 클릭 → 각각
/positions,/trades
RegimeBadge (시장 레짐)
전략이 인식한 시장 상태를 컬러 배지로 표시합니다.
| Regime | 의미 | 색상 |
|---|---|---|
trending_up | 상승 추세 | emerald |
trending_down | 하락 추세 | rose |
ranging | 박스권 | amber |
volatile | 고변동성 | violet |
unknown | 봇 비활성/판단 불가 | zinc |
summary.regime 필드를 그대로 매핑합니다.
BotControl (봇 제어)
| 버튼 | 동작 | 호출 API |
|---|---|---|
| Start (Paper) | paper 모드로 봇 시작 | POST /api/bot/start body: {mode: "paper"} |
| Start (Live) | live 모드로 시작 (라이브 활성 필수) | POST /api/bot/start body: {mode: "live"} |
| Stop | 실행 중인 봇 중지 | POST /api/bot/stop |
| Status | 현재 상태 폴링 | GET /api/bot/status (1초 자동) |
절대 룰
페이퍼 트레이딩 최소 3개월 검증 후 실전 투입. Live 활성화는 별도의 토큰 기반 활성 절차를 거치며, Settings → Risk Rules와 Operations → paper-to-live 참고.
새로고침 주기
| 위젯 | 주기 | 트리거 |
|---|---|---|
| StatsGrid | 1s | TanStack Query refetchInterval |
| EquityChart | 1s | 동일 |
| OpenPositions | 1s | 동일 |
| RecentTrades | 1s | 동일 |
| BotControl status | 1s | 자체 useQuery |
WebSocket이 연결되면 폴링 결과는 캐시 무효화 트리거로만 작용하고, 실 데이터는 push 채널로 갱신됩니다 (참고: WebSockets).
API 호출 예시
curl -s -H "Authorization: Bearer $TOKEN" \
"http://localhost:8000/api/dashboard/summary?asset_class=all"
응답:
{
"equity": 10245.67,
"daily_pnl": 12.34,
"daily_pnl_pct": 0.12,
"total_pnl": 245.67,
"open_positions": 2,
"total_trades_today": 5,
"win_rate": 0.6,
"regime": "trending_up",
"bot_status": "running",
"current_price": 67890.12,
"strategy": "momentum",
"uptime_seconds": 3600
}
자주 묻는 질문
Q. Equity 값이 봇 시작 직후에는 0이에요.
A. equity history는 봇이 첫 tick을 처리한 뒤부터 적재됩니다. 1-2초 후 자동 채워집니다.
Q. 차트가 멈춰 있어요.
A. bot_status === "stopped"이면 새 데이터 입력이 없습니다. BotControl에서 다시 시작하세요.