executor/API_USAGE_GUIDE.md

# BAA 전략 API 사용 가이드

## 시작하기

### 1. 서버 실행

```bash
# 개발 서버 실행
python manage.py runserver

# 서버가 http://localhost:8000 에서 실행됩니다
```

### 2. 준비된 스크립트 사용

세 가지 편리한 스크립트가 제공됩니다:

#### A. 전체 예제 실행 (`baa_api_examples.sh`)
모든 주요 기능을 순차적으로 테스트합니다.

```bash
./baa_api_examples.sh
```

**실행 내용:**
1. 사용 가능한 전략 목록 조회
2. BAA-G12 시뮬레이션 모드 실행
3. BAA-G4 실제 데이터 모드 (현재 날짜)
4. BAA-G12 특정 날짜 기준 (2024-01-31)

#### B. 빠른 테스트 (`quick_baa_test.sh`)
단일 포트폴리오를 빠르게 생성하고 요약 정보를 표시합니다.

```bash
# 기본 실행 (BAA-G4, $50,000, 현재 날짜)
./quick_baa_test.sh

# 전략 변형 지정
./quick_baa_test.sh BAA-G12

# 전략 + 초기 자본 지정
./quick_baa_test.sh BAA-G4 100000

# 전략 + 초기 자본 + 특정 날짜
./quick_baa_test.sh BAA-G12 75000 2024-01-31
```

**출력 예시:**
```
====== 포트폴리오 요약 ======
기준일: 2025-10-04
모드: offensive
카나리아 bad 개수: 0
총 투자액: $49947.08
잔여 현금: $52.92

====== 포트폴리오 구성 ======
VEA: 818주 @ $61.06 = $49947.08

====== 카나리아 상태 ======
SPY: 모멘텀=8.55%, bad=false
VWO: 모멘텀=10.15%, bad=false
VEA: 모멘텀=8.63%, bad=false
BND: 모멘텀=1.32%, bad=false
```

#### C. 개별 curl 명령어 참조 (`BAA_CURL_EXAMPLES.md`)
다양한 curl 명령어 예제와 응답 샘플을 포함한 상세 가이드입니다.

---

## API 엔드포인트

### 1. 전략 구현체 목록 조회

**요청:**
```bash
GET /api/strategies/implementations/
```

**응답:**
```json
{
  "available_implementations": {
    "BoldAssetAllocation": {
      "name": "BoldAssetAllocation",
      "description": "상대 모멘텀과 절대 모멘텀을 결합한 공격적 전술적 자산배분 전략",
      "versions": [...]
    }
  }
}
```

### 2. 전략 실행

**요청:**
```bash
POST /api/strategies/execute/
Content-Type: application/json

{
  "strategy_name": "BoldAssetAllocation",
  "version": "1.0.0",
  "parameters": {
    "initial_capital": 50000,
    "variant": "BAA-G4",
    "use_real_data": true,
    "as_of_date": null
  }
}
```

**응답:**
```json
{
  "execution_id": 123,
  "status": "pending",
  "message": "Strategy execution started"
}
```

### 3. 실행 결과 조회

**요청:**
```bash
GET /api/executions/{execution_id}/
```

**응답 (완료 시):**
```json
{
  "execution_id": 123,
  "strategy": "BoldAssetAllocation",
  "version": "1.0.0",
  "status": "completed",
  "started_at": "2025-10-04T10:30:00Z",
  "completed_at": "2025-10-04T10:30:10Z",
  "result": {
    "mode": "offensive",
    "portfolio": [...],
    "canary_status": {...}
  }
}
```

---

## 주요 파라미터

| 파라미터 | 필수 | 기본값 | 설명 |
|---------|------|--------|------|
| `initial_capital` | ✓ | 100000 | 초기 자본 (달러) |
| `variant` | ✓ | "BAA-G12" | 전략 변형 (BAA-G12, BAA-G4, BAA-G12/T3, BAA-G4/T2, BAA-SPY) |
| `use_real_data` | ✓ | false | 실제 데이터 사용 여부 |
| `as_of_date` | ✗ | null | 기준일 (YYYY-MM-DD 형식, null이면 현재) |
| `offensive_top` | ✗ | 전략별 | 공격 유니버스에서 선택할 자산 수 |
| `defensive_top` | ✗ | 3 | 방어 유니버스에서 선택할 자산 수 |
| `breadth_param` | ✗ | 1 | 카나리아 임계값 |

---

## 전략 변형별 특징

### BAA-G12 (Balanced)
- **추천 대상**: 중위험 선호, 분산 투자
- **자산 수**: 12개 (주식 7 + 대체자산 3 + 채권 2)
- **선택**: Top 6
- **기대 CAGR**: ~14.6%
- **기대 MaxDD**: ~8.7%

```bash
./quick_baa_test.sh BAA-G12 100000
```

### BAA-G4 (Aggressive)
- **추천 대상**: 고위험 선호, 집중 투자
- **자산 수**: 4개 (QQQ, VWO, VEA, BND)
- **선택**: Top 1
- **기대 CAGR**: ~21.0%
- **기대 MaxDD**: ~14.6%

```bash
./quick_baa_test.sh BAA-G4 100000
```

### BAA-G12/T3
- **추천 대상**: BAA-G12와 G4의 중간
- **자산 수**: 12개
- **선택**: Top 3
- **기대 CAGR**: ~16.4%
- **기대 MaxDD**: ~11.4%

```bash
./quick_baa_test.sh BAA-G12/T3 100000
```

### BAA-G4/T2
- **추천 대상**: 적당한 공격성
- **자산 수**: 4개
- **선택**: Top 2
- **기대 CAGR**: ~17.7%
- **기대 MaxDD**: ~12.7%

```bash
./quick_baa_test.sh BAA-G4/T2 100000
```

### BAA-SPY
- **추천 대상**: 단순함 선호, SPY 기반
- **자산 수**: 1개 (SPY)
- **선택**: SPY만 사용
- **기대 CAGR**: ~11.4%
- **기대 MaxDD**: ~16.2%

```bash
./quick_baa_test.sh BAA-SPY 100000
```

---

## 실행 모드

### 시뮬레이션 모드 (`use_real_data: false`)
- **목적**: 백테스트 결과 확인
- **데이터**: 1970-2022년 통계 기반
- **실행 시간**: ~2초
- **결과**: CAGR, Sharpe Ratio, Max DD 등 성과 지표

```bash
curl -X POST http://localhost:8000/api/strategies/execute/ \
  -H "Content-Type: application/json" \
  -d '{
    "strategy_name": "BoldAssetAllocation",
    "parameters": {
      "variant": "BAA-G12",
      "use_real_data": false
    }
  }'
```

### 실제 데이터 모드 (`use_real_data: true`)
- **목적**: 실제 포트폴리오 제안
- **데이터**: yfinance API를 통한 실시간 가격
- **실행 시간**: ~5-15초 (데이터 다운로드 포함)
- **결과**: 티커별 매수 수량, 현재가, 배분액

```bash
curl -X POST http://localhost:8000/api/strategies/execute/ \
  -H "Content-Type: application/json" \
  -d '{
    "strategy_name": "BoldAssetAllocation",
    "parameters": {
      "variant": "BAA-G4",
      "initial_capital": 50000,
      "use_real_data": true
    }
  }'
```

---

## 포트폴리오 해석

### 공격 모드 (Offensive)
카나리아 자산이 모두 양호할 때 활성화됩니다.

**특징:**
- 주식 및 성장 자산에 투자
- 높은 수익 잠재력
- 선택된 자산에 동일 가중 배분

**예시:**
```json
{
  "mode": "offensive",
  "canary_bad_count": 0,
  "portfolio": [
    {"ticker": "VEA", "weight": 100.0, "shares": 818}
  ]
}
```

### 방어 모드 (Defensive)
카나리아 자산 중 1개 이상이 음수 모멘텀일 때 활성화됩니다.

**특징:**
- 채권 및 안전 자산으로 전환
- 크래시 보호
- Top 3 방어 자산 선택

**예시:**
```json
{
  "mode": "defensive",
  "canary_bad_count": 1,
  "portfolio": [
    {"ticker": "DBC", "weight": 33.33, "shares": 1555},
    {"ticker": "TLT", "weight": 33.33, "shares": 374},
    {"ticker": "LQD", "weight": 33.33, "shares": 327}
  ]
}
```

---

## 워크플로우 예시

### 월간 리밸런싱 워크플로우

```bash
#!/bin/bash
# monthly_rebalance.sh

# 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": 100000,
      "variant": "BAA-G12",
      "use_real_data": true
    }
  }' | jq -r '.execution_id')

# 2. 실행 완료 대기
sleep 10

# 3. 결과 조회 및 저장
DATE=$(date +%Y%m%d)
curl -s http://localhost:8000/api/executions/${EXEC_ID}/ \
  | jq '.result' > portfolio_${DATE}.json

# 4. 매수 주문 생성 (예시)
jq -r '.portfolio[] | "BUY \(.shares) \(.ticker) @ \(.current_price)"' \
  portfolio_${DATE}.json > orders_${DATE}.txt

echo "Portfolio saved to portfolio_${DATE}.json"
echo "Orders saved to orders_${DATE}.txt"
```

---

## 트러블슈팅

### 1. "execution_id": null
**원인**: 전략 이름 또는 파라미터 오류

**해결:**
```bash
# 사용 가능한 전략 확인
curl http://localhost:8000/api/strategies/implementations/
```

### 2. "status": "failed"
**원인**: 파라미터 검증 실패 또는 데이터 다운로드 오류

**확인:**
```bash
curl http://localhost:8000/api/executions/{execution_id}/ | jq '.error_message'
```

### 3. 데이터 다운로드 실패
**원인**: 네트워크 또는 yfinance API 문제

**해결:**
- 인터넷 연결 확인
- 잠시 후 재시도
- 다른 날짜로 시도

### 4. 서버 응답 없음
**확인:**
```bash
# 서버 상태 확인
curl http://localhost:8000/api/strategies/implementations/

# Django 서버 로그 확인
python manage.py runserver  # 콘솔 출력 확인
```

---

## 성능 최적화

### 1. 병렬 실행
여러 전략을 동시에 실행할 수 있습니다:

```bash
# 동시 실행
curl -X POST http://localhost:8000/api/strategies/execute/ \
  -d '{"strategy_name":"BoldAssetAllocation","parameters":{"variant":"BAA-G12","use_real_data":true}}' &

curl -X POST http://localhost:8000/api/strategies/execute/ \
  -d '{"strategy_name":"BoldAssetAllocation","parameters":{"variant":"BAA-G4","use_real_data":true}}' &

wait
```

### 2. 캐싱 (향후 구현 예정)
동일한 날짜의 반복 요청은 캐시된 데이터를 사용할 수 있습니다.

---

## 보안 고려사항

### 프로덕션 환경
- `@csrf_exempt` 제거 및 CSRF 토큰 사용
- API 키 인증 추가
- HTTPS 사용
- Rate limiting 적용

---

## 다음 단계

1. **자동화**: cron을 사용한 월간 자동 리밸런싱
2. **알림**: 이메일/슬랙 알림 설정
3. **대시보드**: 웹 UI 추가
4. **백테스트**: 과거 날짜 범위에 대한 성과 분석

---

## 지원

문제가 발생하면 다음을 확인하세요:
- Django 서버 로그
- `BAA_CURL_EXAMPLES.md` 예제
- `BAA_STRATEGY_README.md` 전략 설명