executor/STRATEGY_MODULES_README.md

# 전략 모듈 구조

## 📁 디렉토리 구조

```
strategies/
├── __init__.py
├── base.py                      # 기본 클래스 및 레지스트리
├── implementations.py            # 통합 임포트 모듈
├── models.py                    # Django 모델
├── views.py                     # Django 뷰
├── urls.py                      # URL 라우팅
└── impls/                       # 전략 구현체 모듈
    ├── __init__.py              # 모듈 통합
    ├── trend_following.py       # 추세 추종 전략
    ├── mean_reversion.py        # 평균 회귀 전략
    ├── volatility_breakout.py   # 변동성 돌파 전략
    └── asset_allocation.py      # 자산 배분 전략
```

---

## 📊 전략 분류

### 1. 추세 추종(Trend Following) 전략
**파일**: `strategies/impls/trend_following.py`

이동평균선, 모멘텀 등 추세를 따라가는 전략들

#### 포함된 전략:
- **MovingAverageCrossover** (v1.0.0)
  - 단기/장기 이동평균선 교차 전략
  - 골든크로스/데드크로스 기반
  - 파라미터: `short_window`, `long_window`

**사용 예시:**
```python
from strategies.impls.trend_following import MovingAverageCrossover

strategy = MovingAverageCrossover()
result = strategy.execute({
    "short_window": 20,
    "long_window": 50,
    "initial_capital": 100000
})
```

---

### 2. 평균 회귀(Mean Reversion) 전략
**파일**: `strategies/impls/mean_reversion.py`

RSI, 볼린저밴드 등 과매수/과매도 구간에서 반대 방향으로 거래

#### 포함된 전략:
- **RSIMeanReversion** (v1.0.0)
  - RSI 지표 기반 평균회귀
  - 과매수(70)/과매도(30) 구간 역방향 거래
  - 파라미터: `rsi_period`, `oversold_threshold`, `overbought_threshold`

**사용 예시:**
```python
from strategies.impls.mean_reversion import RSIMeanReversion

strategy = RSIMeanReversion()
result = strategy.execute({
    "rsi_period": 14,
    "oversold_threshold": 30,
    "overbought_threshold": 70,
    "initial_capital": 100000
})
```

---

### 3. 변동성 돌파(Volatility Breakout) 전략
**파일**: `strategies/impls/volatility_breakout.py`

볼린저 밴드, ATR 등 변동성 기반 돌파 전략들

#### 포함된 전략:
- **BollingerBandBreakout** (v2.0.0)
  - 볼린저 밴드 상한/하한 돌파 전략
  - 변동성 확장 구간 포착
  - 파라미터: `period`, `std_dev`, `stop_loss`

**사용 예시:**
```python
from strategies.impls.volatility_breakout import BollingerBandBreakout

strategy = BollingerBandBreakout()
result = strategy.execute({
    "period": 20,
    "std_dev": 2.0,
    "initial_capital": 100000
})
```

---

### 4. 자산 배분(Asset Allocation) 전략
**파일**: `strategies/impls/asset_allocation.py`

전술적 자산배분, 리스크 패리티 등 다양한 자산에 배분하는 전략들

#### 포함된 전략:
- **BoldAssetAllocation** (v1.0.0)
  - 상대/절대 모멘텀 결합 전략
  - 카나리아 유니버스 기반 크래시 보호
  - 5가지 변형: BAA-G12, BAA-G4, BAA-G12/T3, BAA-G4/T2, BAA-SPY
  - 실제 데이터 기반 포트폴리오 제안 기능

**사용 예시:**
```python
from strategies.impls.asset_allocation import BoldAssetAllocation

# 시뮬레이션 모드
strategy = BoldAssetAllocation()
result = strategy.execute({
    "variant": "BAA-G12",
    "initial_capital": 100000,
    "use_real_data": False
})

# 실제 데이터 모드
result = strategy.execute({
    "variant": "BAA-G4",
    "initial_capital": 50000,
    "use_real_data": True,
    "as_of_date": "2024-01-31"
})
```

---

## 🔧 모듈 사용 방법

### 통합 임포트 (권장)
```python
# 모든 전략을 한 번에 임포트
from strategies import implementations

# 또는 특정 전략만
from strategies.implementations import (
    MovingAverageCrossover,
    BoldAssetAllocation
)
```

### 개별 모듈 임포트
```python
# 특정 카테고리의 전략만 필요한 경우
from strategies.impls.trend_following import MovingAverageCrossover
from strategies.impls.asset_allocation import BoldAssetAllocation
```

### 레지스트리 사용
```python
from strategies.base import StrategyRegistry

# 등록된 전략 조회
available = StrategyRegistry.list_strategies()

# 전략 인스턴스 생성
strategy = StrategyRegistry.get_strategy(
    name="BoldAssetAllocation",
    version="1.0.0"
)
```

---

## ➕ 새 전략 추가하기

### 1. 적절한 카테고리 선택

전략 유형에 따라 해당 파일 선택:
- 추세 추종 → `trend_following.py`
- 평균 회귀 → `mean_reversion.py`
- 변동성 돌파 → `volatility_breakout.py`
- 자산 배분 → `asset_allocation.py`

새 카테고리가 필요하면 새 파일 생성 (예: `arbitrage.py`)

### 2. 전략 클래스 작성

```python
# strategies/impls/your_category.py

from typing import Dict, Any
from ..base import BaseQuantStrategy, strategy

@strategy
class YourStrategy(BaseQuantStrategy):
    """전략 설명"""

    @property
    def name(self) -> str:
        return "YourStrategy"

    @property
    def description(self) -> str:
        return "전략에 대한 상세 설명"

    @property
    def version(self) -> str:
        return "1.0.0"

    @property
    def default_parameters(self) -> Dict[str, Any]:
        return {
            "param1": "value1",
            "param2": "value2"
        }

    def validate_parameters(self, parameters: Dict[str, Any]) -> bool:
        # 파라미터 검증 로직
        return True

    def execute(self, parameters: Dict[str, Any] = None) -> Dict[str, Any]:
        # 전략 실행 로직
        return {
            "strategy": self.name,
            "result": "..."
        }
```

### 3. 임포트 경로 추가

#### `strategies/impls/__init__.py`에 추가:
```python
from .your_category import YourStrategy

__all__ = [
    # ... 기존 전략들
    'YourStrategy',
]
```

#### `strategies/implementations.py`에 추가:
```python
from .impls.your_category import YourStrategy

__all__ = [
    # ... 기존 전략들
    'YourStrategy',
]
```

### 4. 자동 등록 확인

`@strategy` 데코레이터를 사용하면 자동으로 레지스트리에 등록됩니다.

```python
# 확인
python manage.py shell

>>> from strategies.base import StrategyRegistry
>>> StrategyRegistry.list_strategies()
# YourStrategy가 포함되어 있는지 확인
```

---

## 📝 모범 사례

### 1. 파일 조직
- 한 파일에 너무 많은 전략을 넣지 마세요 (최대 5개 권장)
- 유사한 특성의 전략끼리 그룹화

### 2. 명명 규칙
- 클래스명: PascalCase (예: `MovingAverageCrossover`)
- 파일명: snake_case (예: `trend_following.py`)
- 전략 이름(name): 클래스명과 동일

### 3. 문서화
- 각 파일 상단에 독스트링으로 카테고리 설명
- 각 전략 클래스에 독스트링으로 전략 설명
- 파라미터 의미를 주석으로 명시

### 4. 의존성 관리
- 공통 의존성: 파일 상단에 import
- 선택적 의존성: 함수/메서드 내부에서 import

```python
# 좋은 예
import time
import random
from typing import Dict, Any
from ..base import BaseQuantStrategy, strategy

@strategy
class MyStrategy(BaseQuantStrategy):
    def execute(self, parameters):
        # 여기서만 필요한 라이브러리
        import some_optional_lib
        ...
```

---

## 🔄 마이그레이션 가이드

### 기존 `implementations.py`에서 분리된 코드 사용하기

#### Before (기존):
```python
from strategies.implementations import BoldAssetAllocation
```

#### After (현재):
```python
# 방법 1: 기존과 동일하게 사용 (권장)
from strategies.implementations import BoldAssetAllocation

# 방법 2: 직접 모듈에서 임포트
from strategies.impls.asset_allocation import BoldAssetAllocation
```

**👍 호환성**: 기존 코드 수정 불필요!

---

## 🧪 테스트

### 개별 모듈 테스트
```python
# test_trend_following.py
from strategies.impls.trend_following import MovingAverageCrossover

def test_moving_average():
    strategy = MovingAverageCrossover()
    result = strategy.execute()
    assert result["strategy"] == "MovingAverageCrossover"
```

### 통합 테스트
```python
# test_all_strategies.py
from strategies.implementations import (
    MovingAverageCrossover,
    RSIMeanReversion,
    BollingerBandBreakout,
    BoldAssetAllocation
)

strategies = [
    MovingAverageCrossover(),
    RSIMeanReversion(),
    BollingerBandBreakout(),
    BoldAssetAllocation()
]

for strategy in strategies:
    result = strategy.execute()
    assert "strategy" in result
```

---

## 🎯 장점

### 1. 코드 구조화
- 관련 전략끼리 그룹화
- 파일 크기 감소 (가독성 향상)
- 명확한 책임 분리

### 2. 유지보수성
- 특정 카테고리만 수정 가능
- 머지 충돌 감소
- 버그 추적 용이

### 3. 확장성
- 새 카테고리 쉽게 추가
- 독립적인 개발 가능
- 팀 협업 용이

### 4. 성능
- 필요한 모듈만 로드
- 메모리 사용 최적화
- 빠른 개발 서버 재시작

---

## 📚 참고

- **기본 클래스**: `strategies/base.py`
- **레지스트리**: `strategies/base.py - StrategyRegistry`
- **API 가이드**: `API_USAGE_GUIDE.md`
- **BAA 전략**: `BAA_STRATEGY_README.md`

---

## ❓ FAQ

### Q: 기존 코드가 작동하지 않나요?
**A:** 아니요! `implementations.py`가 자동으로 모든 모듈을 임포트하므로 기존 코드는 그대로 작동합니다.

### Q: 새 카테고리를 추가하려면?
**A:**
1. `strategies/impls/new_category.py` 생성
2. `strategies/impls/__init__.py`에 임포트 추가
3. `strategies/implementations.py`에 임포트 추가

### Q: 전략을 다른 카테고리로 옮기려면?
**A:**
1. 전략 클래스를 새 파일로 복사
2. 두 `__init__.py` 파일의 임포트 경로 수정
3. 기존 파일에서 전략 삭제

### Q: 한 전략이 여러 카테고리에 속한다면?
**A:** 가장 주요한 특성에 맞는 카테고리에 배치하세요. 또는 `hybrid.py` 같은 새 카테고리를 만드세요.