diff --git a/API_USAGE_GUIDE.md b/API_USAGE_GUIDE.md index 5b211ae..6e3d2be 100644 --- a/API_USAGE_GUIDE.md +++ b/API_USAGE_GUIDE.md @@ -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` 구현하여 백테스트 지원 ---