auto-stock/docs/RISK_MANAGEMENT_API.md

# 🔥 리스크 관리 & 성과 평가 API 가이드

## 개요
자동매매 시스템의 안정성과 수익성을 높이기 위한 리스크 관리 기능입니다.

## 주요 기능

### 1. Maximum Drawdown (MDD) 추적
**엔드포인트**: `GET /api/v1/risk/risk-metrics?days=30`

계좌 최고점 대비 최저점 낙폭을 측정합니다.

**응답 예시**:
```json
{
  "max_drawdown": 150000,
  "max_drawdown_pct": 15.5,
  "current_equity": 850000,
  "peak_equity": 1000000,
  "trades_count": 45,
  "risk_level": "주의",
  "equity_curve": [...],
  "drawdown_curve": [...]
}
```

**위험 레벨**:
- `안전`: MDD < 10%
- `주의`: 10% ≤ MDD < 20%
- `경고`: 20% ≤ MDD < 30% (포지션 축소 권장)
- `위험`: MDD ≥ 30% (시스템 중지 권장)

---

### 2. Sharpe Ratio 계산
**엔드포인트**: `GET /api/v1/risk/sharpe-ratio?days=30`

수익률 대비 변동성(리스크)을 측정하여 전략의 질을 평가합니다.

**응답 예시**:
```json
{
  "sharpe_ratio": 1.85,
  "avg_return": 2.3,
  "std_return": 5.1,
  "annualized_return": 579.6,
  "interpretation": "Good (우수)",
  "trades_count": 42
}
```

**해석**:
- `> 2.0`: Excellent (매우 우수)
- `> 1.0`: Good (우수)
- `> 0`: Fair (보통)
- `< 0`: Poor (개선 필요)

---

### 3. 일일 트레이딩 세션 조회
**엔드포인트**: `GET /api/v1/risk/session/today`

오늘의 연속 손실, 일일 손익, 거래 중지 상태를 확인합니다.

**응답 예시**:
```json
{
  "session_date": "2026-02-11",
  "consecutive_losses": 2,
  "consecutive_wins": 0,
  "daily_profit_loss": -45000,
  "daily_trades_count": 5,
  "is_paused": false,
  "pause_reason": null,
  "starting_balance": 10000000,
  "ending_balance": 9955000,
  "peak_balance": 10050000
}
```

---

### 4. 주문 전 리스크 제한 확인
**엔드포인트**: `POST /api/v1/risk/check-risk-limits`

**파라미터**:
- `order_value`: 주문 금액
- `account_balance`: 계좌 잔고

**응답 예시 (통과)**:
```json
{
  "allowed": true,
  "risk_level": "OK",
  "warnings": [],
  "position_ratio": 15.5,
  "daily_loss_ratio": 1.2,
  "consecutive_losses": 1
}
```

**응답 예시 (거부)**:
```json
{
  "allowed": false,
  "reason": "연속 3회 손실 발생",
  "risk_level": "CRITICAL",
  "consecutive_losses": 3
}
```

**자동 차단 조건**:
1. **연속 3회 손실**: 3연패 시 자동 중지
2. **일일 손실 3% 초과**: 계좌 대비 3% 손실 시 중지
3. **포지션 사이즈 20% 초과**: 단일 포지션이 계좌의 20% 초과 시 거부

---

### 5. 거래 결과 업데이트
**엔드포인트**: `POST /api/v1/risk/update-session`

**파라미터**:
- `trade_result`: `win` 또는 `loss`
- `profit_loss`: 거래 손익

매도 체결 후 호출하여 세션 상태를 업데이트합니다.

---

### 6. 승률 및 손익 통계
**엔드포인트**: `GET /api/v1/risk/win-rate?days=30`

**응답 예시**:
```json
{
  "win_rate": 62.5,
  "total_trades": 40,
  "wins": 25,
  "losses": 15,
  "total_profit": 1250000,
  "total_loss": 450000,
  "net_profit": 800000,
  "profit_factor": 2.78,
  "avg_win": 50000,
  "avg_loss": 30000,
  "risk_reward_ratio": 1.67
}
```

**주요 지표**:
- **Profit Factor**: 총 이익 / 총 손실 (1.0 이상 권장, 2.0 이상 우수)
- **Risk/Reward Ratio**: 평균 승리 / 평균 손실 (1.5 이상 권장)

---

## 리스크 관리 설정

### 현재 기본값
```python
MAX_POSITION_SIZE_RATIO = 0.20    # 단일 포지션 20% 제한
MAX_DAILY_LOSS_RATIO = 0.03       # 일일 손실 3% 제한
MAX_CONSECUTIVE_LOSSES = 3        # 연속 3회 손실 제한

# 수수료 및 세금
COMMISSION_RATE = 0.00015         # 수수료 0.015%
TRADE_TAX_RATE = 0.0023           # 거래세 0.23% (매도만)
TOTAL_COST_RATE = 0.0026          # 왕복 약 0.26%
```

---

## 사용 예시

### 매수 전 체크
```python
# 주문 전 리스크 확인
response = requests.post(
    "/api/v1/risk/check-risk-limits",
    params={
        "order_value": 2000000,  # 200만원 주문
        "account_balance": 10000000  # 1000만원 잔고
    }
)

if response.json()["allowed"]:
    # 매수 실행
    execute_buy_order()
else:
    # 주문 거부
    logger.warning(f"Order rejected: {response.json()['reason']}")
```

### 매도 후 세션 업데이트
```python
# 매도 체결 후
sell_result = execute_sell_order()

# 손익에 따라 세션 업데이트
trade_result = "win" if sell_result["profit_loss"] > 0 else "loss"

requests.post(
    "/api/v1/risk/update-session",
    params={
        "trade_result": trade_result,
        "profit_loss": sell_result["profit_loss"]
    }
)
```

---

## 대시보드 표시 권장 사항

### 필수 표시 지표
1. **오늘의 상태**
   - 연속 손실 횟수
   - 일일 손익
   - 거래 중지 상태

2. **리스크 메트릭**
   - MDD %
   - Sharpe Ratio
   - 승률

3. **경고 알림**
   - 연속 2회 손실: 노란색 경고
   - 연속 3회 손실: 빨간색 차단
   - MDD 20% 초과: 주황색 경고
   - MDD 30% 초과: 빨간색 위험

---

## 주의사항

1. **백테스팅 후 실전 적용**: 새로운 전략은 반드시 백테스팅으로 검증
2. **리스크 한도 준수**: 설정된 한도를 절대 임의로 변경하지 않기
3. **정기 점검**: 매주 Sharpe Ratio와 MDD 확인
4. **감정 제어**: 시스템이 중지하면 하루 쉬기

---

## 다음 단계 (추가 개발 예정)

- [ ] 백테스팅 API
- [ ] Slack/Telegram 알림 연동
- [ ] 실시간 경고 대시보드
- [ ] 월간/분기별 성과 리포트
- [ ] ATR 기반 동적 손절 설정