executor/README_API.md

# 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! 📈**