docs: add detailed API usage guide for strategy backtesting

- Added documentation for `/api/strategies/backtest/` endpoint.
- Included request/response examples, parameter details, and performance metrics explanation.
- Clarified backtesting workflow, data sources, and rebalancing logic.
This commit is contained in:
2026-02-08 14:13:02 +09:00
parent b64a76a8b9
commit 0d7574e3c9

View File

@@ -119,7 +119,114 @@ Content-Type: application/json
}
```
### 3. 실행 결과 조회
### 3. 전략 백테스트
과거 데이터를 기반으로 월별 리밸런싱을 반복 수행하며 포트폴리오 성과를 추적합니다.
**요청:**
```bash
POST /api/strategies/backtest/
Content-Type: application/json
{
"strategy_name": "BoldAssetAllocation",
"parameters": {
"backtest_start_date": "2020-01-01",
"backtest_end_date": "2024-12-31",
"initial_capital": 100000,
"variant": "BAA-G12",
"transaction_cost": 0.001
}
}
```
**응답:**
```json
{
"execution_id": 456,
"status": "pending",
"message": "Backtest execution started"
}
```
실행은 비동기로 처리됩니다. 아래 `실행 결과 조회` 엔드포인트로 폴링하세요.
**백테스트 결과 (폴링 응답):**
```json
{
"execution_id": 456,
"status": "completed",
"result": {
"strategy": "BoldAssetAllocation",
"variant": "BAA-G12",
"backtest_start_date": "2020-01-01",
"backtest_end_date": "2024-12-31",
"initial_capital": 100000,
"final_capital": 138742.31,
"metrics": {
"cagr": 6.78,
"total_return": 38.74,
"annual_volatility": 7.52,
"max_drawdown": 8.12,
"sharpe_ratio": 0.90,
"sortino_ratio": 1.42,
"calmar_ratio": 0.83,
"win_rate": 65.0,
"best_month": 4.23,
"worst_month": -3.87
},
"daily_equity_curve": [
{"date": "2020-01-02", "value": 100050.0},
...
],
"monthly_returns": [
{"date": "2020-01-31", "return": 0.0023},
...
],
"allocation_history": [
{
"date": "2020-01-31",
"mode": "offensive",
"weights": {"SPY": 0.1667, "QQQ": 0.1667, ...},
"turnover": 1.0,
"cost": 100.0
},
...
],
"drawdown_series": [
{"date": "2020-01-02", "drawdown": -0.05},
...
]
}
}
```
**백테스트 파라미터:**
| 파라미터 | 필수 | 기본값 | 설명 |
|---------|------|--------|------|
| `backtest_start_date` | ✓ | - | 백테스트 시작일 (YYYY-MM-DD) |
| `backtest_end_date` | ✓ | - | 백테스트 종료일 (YYYY-MM-DD) |
| `initial_capital` | ✗ | 100000 | 초기 자본 (달러) |
| `variant` | ✗ | "BAA-G12" | 전략 변형 |
| `transaction_cost` | ✗ | 0.001 | 거래비용 비율 (0.1%) |
**성과 지표 설명:**
| 지표 | 설명 |
|------|------|
| `cagr` | 연평균 복리 수익률 (%) |
| `total_return` | 총 수익률 (%) |
| `annual_volatility` | 연율화 변동성 (%) |
| `max_drawdown` | 최대 낙폭 (%) |
| `sharpe_ratio` | 샤프 비율 (무위험 수익률 0% 가정) |
| `sortino_ratio` | 소르티노 비율 |
| `calmar_ratio` | 칼마 비율 (CAGR / MDD) |
| `win_rate` | 월간 승률 (%) |
| `best_month` | 최고 월 수익률 (%) |
| `worst_month` | 최저 월 수익률 (%) |
### 4. 실행 결과 조회
**요청:**
```bash
@@ -238,6 +345,27 @@ curl -X POST http://localhost:8000/api/strategies/execute/ \
}'
```
### 백테스트 모드 (`/api/strategies/backtest/`)
- **목적**: 과거 데이터 기반 전략 성과 검증
- **데이터**: yfinance API를 통한 과거 가격 (전체 기간 일괄 다운로드)
- **실행 시간**: ~30초-2분 (기간 및 자산 수에 따라)
- **결과**: 일별 equity curve, 월별 수익률, 배분 이력, 성과 지표 (CAGR, MDD, Sharpe 등)
- **리밸런싱**: 월말 영업일 기준
```bash
curl -X POST http://localhost:8000/api/strategies/backtest/ \
-H "Content-Type: application/json" \
-d '{
"strategy_name": "BoldAssetAllocation",
"parameters": {
"backtest_start_date": "2020-01-01",
"backtest_end_date": "2024-12-31",
"initial_capital": 100000,
"variant": "BAA-G12"
}
}'
```
### 실제 데이터 모드 (`use_real_data: true`)
- **목적**: 실제 포트폴리오 제안
- **데이터**: yfinance API를 통한 실시간 가격
@@ -416,7 +544,7 @@ wait
1. **자동화**: cron을 사용한 월간 자동 리밸런싱
2. **알림**: 이메일/슬랙 알림 설정
3. **대시보드**: 웹 UI 추가
4. **백테스트**: 과거 날짜 범위에 대한 성과 분석
4. **추가 전략 백테스트**: 다른 전략에도 `BacktestMixin` 구현하여 백테스트 지원
---