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

사용 예시:

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

사용 예시:

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

사용 예시:

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
  • 실제 데이터 기반 포트폴리오 제안 기능

사용 예시:

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"
})

---

🔧 모듈 사용 방법

통합 임포트 (권장)

# 모든 전략을 한 번에 임포트
from strategies import implementations

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

개별 모듈 임포트

# 특정 카테고리의 전략만 필요한 경우
from strategies.impls.trend_following import MovingAverageCrossover
from strategies.impls.asset_allocation import BoldAssetAllocation

레지스트리 사용

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. 전략 클래스 작성

# 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에 추가:

from .your_category import YourStrategy

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

strategies/implementations.py에 추가:

from .impls.your_category import YourStrategy

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

4. 자동 등록 확인

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

# 확인
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

# 좋은 예
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 (기존):

from strategies.implementations import BoldAssetAllocation

After (현재):

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

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

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

---

🧪 테스트

개별 모듈 테스트

# test_trend_following.py
from strategies.impls.trend_following import MovingAverageCrossover

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

통합 테스트

# 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 같은 새 카테고리를 만드세요.