feat: 프로젝트 기본 구조 구축
This commit is contained in:
287
README_API.md
Normal file
287
README_API.md
Normal file
@@ -0,0 +1,287 @@
|
||||
# BAA 전략 API - 빠른 시작 가이드
|
||||
|
||||
## 📁 제공된 파일
|
||||
|
||||
### 실행 스크립트
|
||||
1. **`baa_api_examples.sh`** - 전체 기능 테스트 스크립트
|
||||
2. **`quick_baa_test.sh`** - 빠른 단일 포트폴리오 생성 스크립트
|
||||
|
||||
### 문서
|
||||
3. **`BAA_CURL_EXAMPLES.md`** - 상세한 curl 명령어 예제 모음
|
||||
4. **`API_USAGE_GUIDE.md`** - 완전한 API 사용 가이드
|
||||
5. **`BAA_STRATEGY_README.md`** - BAA 전략 설명 및 이론
|
||||
|
||||
---
|
||||
|
||||
## 🚀 5분 안에 시작하기
|
||||
|
||||
### 1단계: 서버 실행
|
||||
```bash
|
||||
python manage.py runserver
|
||||
```
|
||||
|
||||
### 2단계: 포트폴리오 생성
|
||||
```bash
|
||||
# 스크립트 실행 권한 부여 (최초 1회)
|
||||
chmod +x quick_baa_test.sh
|
||||
|
||||
# BAA-G4 전략으로 $50,000 포트폴리오 생성
|
||||
./quick_baa_test.sh
|
||||
```
|
||||
|
||||
**출력 예시:**
|
||||
```
|
||||
====== 포트폴리오 요약 ======
|
||||
기준일: 2025-10-04
|
||||
모드: offensive
|
||||
총 투자액: $49947.08
|
||||
잔여 현금: $52.92
|
||||
|
||||
====== 포트폴리오 구성 ======
|
||||
VEA: 818주 @ $61.06 = $49947.08
|
||||
```
|
||||
|
||||
완료! 🎉
|
||||
|
||||
---
|
||||
|
||||
## 📋 주요 사용 사례
|
||||
|
||||
### 사례 1: 다양한 전략 비교
|
||||
```bash
|
||||
./quick_baa_test.sh BAA-G12 # 균형형
|
||||
./quick_baa_test.sh BAA-G4 # 공격형
|
||||
./quick_baa_test.sh BAA-SPY # 단순형
|
||||
```
|
||||
|
||||
### 사례 2: 예산별 포트폴리오
|
||||
```bash
|
||||
./quick_baa_test.sh BAA-G4 25000 # $25,000
|
||||
./quick_baa_test.sh BAA-G4 100000 # $100,000
|
||||
./quick_baa_test.sh BAA-G4 250000 # $250,000
|
||||
```
|
||||
|
||||
### 사례 3: 과거 날짜 기준 분석
|
||||
```bash
|
||||
./quick_baa_test.sh BAA-G12 100000 2024-01-31
|
||||
./quick_baa_test.sh BAA-G12 100000 2024-06-30
|
||||
./quick_baa_test.sh BAA-G12 100000 2024-09-30
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 전략 선택 가이드
|
||||
|
||||
| 전략 | 위험도 | 자산 수 | CAGR | Max DD | 추천 대상 |
|
||||
|------|--------|---------|------|--------|-----------|
|
||||
| **BAA-G12** | 중 | 12개, Top6 선택 | 14.6% | 8.7% | 균형 잡힌 포트폴리오 |
|
||||
| **BAA-G4** | 고 | 4개, Top1 선택 | 21.0% | 14.6% | 높은 수익 추구 |
|
||||
| **BAA-G12/T3** | 중상 | 12개, Top3 선택 | 16.4% | 11.4% | 적당한 분산 |
|
||||
| **BAA-G4/T2** | 상 | 4개, Top2 선택 | 17.7% | 12.7% | 적당한 집중 |
|
||||
| **BAA-SPY** | 중하 | 1개 (SPY) | 11.4% | 16.2% | 단순함 선호 |
|
||||
|
||||
---
|
||||
|
||||
## 🔧 고급 사용법
|
||||
|
||||
### curl 명령어로 직접 호출
|
||||
```bash
|
||||
# 1. 전략 실행
|
||||
EXEC_ID=$(curl -s -X POST http://localhost:8000/api/strategies/execute/ \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"strategy_name": "BoldAssetAllocation",
|
||||
"parameters": {
|
||||
"initial_capital": 50000,
|
||||
"variant": "BAA-G4",
|
||||
"use_real_data": true
|
||||
}
|
||||
}' | jq -r '.execution_id')
|
||||
|
||||
# 2. 결과 조회
|
||||
sleep 10
|
||||
curl http://localhost:8000/api/executions/${EXEC_ID}/ | jq '.result'
|
||||
```
|
||||
|
||||
### 모든 예제 한번에 실행
|
||||
```bash
|
||||
chmod +x baa_api_examples.sh
|
||||
./baa_api_examples.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📚 더 알아보기
|
||||
|
||||
### 전략 이해하기
|
||||
👉 **`BAA_STRATEGY_README.md`** 읽기
|
||||
- BAA 전략의 원리와 메커니즘
|
||||
- 모멘텀 계산 방식
|
||||
- 카나리아 유니버스의 역할
|
||||
|
||||
### API 완전 가이드
|
||||
👉 **`API_USAGE_GUIDE.md`** 읽기
|
||||
- 모든 API 엔드포인트 설명
|
||||
- 워크플로우 예시
|
||||
- 트러블슈팅 가이드
|
||||
|
||||
### curl 명령어 레퍼런스
|
||||
👉 **`BAA_CURL_EXAMPLES.md`** 읽기
|
||||
- 다양한 curl 명령어 예제
|
||||
- 응답 샘플
|
||||
- 에러 처리 예시
|
||||
|
||||
---
|
||||
|
||||
## ❓ 자주 묻는 질문
|
||||
|
||||
### Q1: 어떤 전략을 선택해야 하나요?
|
||||
**A:**
|
||||
- 처음 시작: **BAA-G12** (균형형)
|
||||
- 높은 수익 추구: **BAA-G4** (공격형)
|
||||
- 단순함 선호: **BAA-SPY**
|
||||
|
||||
### Q2: 얼마나 자주 리밸런싱해야 하나요?
|
||||
**A:** 월말 (마지막 거래일)에 리밸런싱을 권장합니다.
|
||||
|
||||
### Q3: 최소 투자 금액은?
|
||||
**A:** 제한 없지만, $10,000 이상을 권장합니다 (적절한 분산을 위해).
|
||||
|
||||
### Q4: 실행 시간은 얼마나 걸리나요?
|
||||
**A:**
|
||||
- 시뮬레이션 모드: ~2초
|
||||
- 실제 데이터 모드: ~5-15초 (데이터 다운로드 포함)
|
||||
|
||||
### Q5: 공격/방어 모드는 무엇인가요?
|
||||
**A:**
|
||||
- **공격 모드**: 시장이 좋을 때, 주식 중심 포트폴리오
|
||||
- **방어 모드**: 시장 위험 감지 시, 채권 중심 포트폴리오
|
||||
- 카나리아 자산(SPY, VWO, VEA, BND)의 모멘텀으로 자동 전환
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ 의존성
|
||||
|
||||
### 필수
|
||||
- Python 3.13+
|
||||
- Django 5.2.7
|
||||
- yfinance
|
||||
- pandas, numpy
|
||||
|
||||
### 선택 (추천)
|
||||
- `jq`: JSON 포맷팅을 위해 설치 권장
|
||||
```bash
|
||||
# macOS
|
||||
brew install jq
|
||||
|
||||
# Ubuntu/Debian
|
||||
sudo apt-get install jq
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎬 실행 예제 영상
|
||||
|
||||
### 1. 기본 실행
|
||||
```bash
|
||||
$ ./quick_baa_test.sh
|
||||
|
||||
==================================
|
||||
BAA 전략 빠른 실행
|
||||
==================================
|
||||
변형: BAA-G4
|
||||
초기 자본: $50000
|
||||
기준일: null
|
||||
|
||||
전략 실행 중...
|
||||
실행 ID: 1
|
||||
|
||||
데이터 다운로드 및 계산 중..........
|
||||
|
||||
✓ 실행 완료!
|
||||
|
||||
====== 포트폴리오 요약 ======
|
||||
기준일: 2025-10-04
|
||||
모드: offensive
|
||||
총 투자액: $49947.08
|
||||
잔여 현금: $52.92
|
||||
|
||||
====== 포트폴리오 구성 ======
|
||||
VEA: 818주 @ $61.06 = $49947.08
|
||||
```
|
||||
|
||||
### 2. 전략 비교
|
||||
```bash
|
||||
# 세 가지 전략 비교
|
||||
for variant in BAA-G12 BAA-G4 BAA-SPY; do
|
||||
echo "=== $variant ==="
|
||||
./quick_baa_test.sh $variant 100000
|
||||
sleep 2
|
||||
done
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 포트폴리오 예시
|
||||
|
||||
### 공격 모드 예시 (2025-10-04)
|
||||
```json
|
||||
{
|
||||
"mode": "offensive",
|
||||
"portfolio": [
|
||||
{
|
||||
"ticker": "VEA",
|
||||
"weight": 100.0,
|
||||
"shares": 818,
|
||||
"current_price": 61.06,
|
||||
"actual_amount": 49947.08
|
||||
}
|
||||
],
|
||||
"canary_status": {
|
||||
"SPY": {"momentum": 0.0854, "is_bad": false},
|
||||
"VWO": {"momentum": 0.1015, "is_bad": false},
|
||||
"VEA": {"momentum": 0.0863, "is_bad": false},
|
||||
"BND": {"momentum": 0.0132, "is_bad": false}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 방어 모드 예시 (2024-01-31)
|
||||
```json
|
||||
{
|
||||
"mode": "defensive",
|
||||
"portfolio": [
|
||||
{"ticker": "DBC", "weight": 33.33, "shares": 1555},
|
||||
{"ticker": "TLT", "weight": 33.33, "shares": 374},
|
||||
{"ticker": "LQD", "weight": 33.33, "shares": 327}
|
||||
],
|
||||
"canary_status": {
|
||||
"VWO": {"momentum": -0.0110, "is_bad": true}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔗 관련 링크
|
||||
|
||||
- **전략 논문**: [SSRN 4166845](https://ssrn.com/abstract=4166845)
|
||||
- **Django 공식 문서**: https://docs.djangoproject.com/
|
||||
- **yfinance 문서**: https://github.com/ranaroussi/yfinance
|
||||
|
||||
---
|
||||
|
||||
## 📝 라이선스
|
||||
|
||||
교육 및 연구 목적으로만 사용하세요.
|
||||
|
||||
---
|
||||
|
||||
## 🆘 도움말
|
||||
|
||||
문제가 발생하면:
|
||||
1. 서버가 실행 중인지 확인
|
||||
2. `BAA_CURL_EXAMPLES.md`의 예제 참조
|
||||
3. Django 서버 로그 확인
|
||||
|
||||
**Happy Trading! 📈**
|
||||
Reference in New Issue
Block a user