✍️ 필사 모드: ETF 리밸런싱 자동화 가이드: 규칙 기반 투자 운영

# portfolio_config.yaml
# 최종 수정: 2026-03-04
# 변경 사유: 2026년 자산배분 비중 조정 (채권 비중 확대)

portfolio:
  name: '2026 장기 성장형'
  owner: 'youngjukim'
  base_currency: 'KRW'
  broker: '한국투자증권' # 또는 키움, 미래에셋 등

  # 목표 자산 배분
  allocation:
    core:
      weight: 0.70
      assets:
        - ticker: 'TIGER 미국S&P500'
          code: '360750'
          target: 0.35
          min: 0.30
          max: 0.40
        - ticker: 'KODEX 200'
          code: '069500'
          target: 0.15
          min: 0.10
          max: 0.20
        - ticker: 'TIGER 미국채10년선물'
          code: '305080'
          target: 0.15
          min: 0.10
          max: 0.20
        - ticker: 'KODEX 종합채권(AA-이상)액티브'
          code: '443160'
          target: 0.05
          min: 0.02
          max: 0.08

    satellite:
      weight: 0.30
      assets:
        - ticker: 'TIGER 반도체'
          code: '091230'
          target: 0.10
          min: 0.05
          max: 0.15
        - ticker: 'KODEX 2차전지산업'
          code: '305720'
          target: 0.10
          min: 0.05
          max: 0.15
        - ticker: 'TIGER 금은선물(H)'
          code: '319640'
          target: 0.10
          min: 0.05
          max: 0.15

  # 리밸런싱 규칙
  rebalancing:
    strategy: 'hybrid'
    scheduled:
      frequency: 'quarterly'
      months: [1, 4, 7, 10] # 1월, 4월, 7월, 10월 첫 영업일
      day: 'first_business_day'
    drift_trigger:
      threshold: 0.05 # ±5% 이탈 시 긴급 리밸런싱
      check_frequency: 'weekly' # 매주 월요일 확인
    constraints:
      min_trade_amount: 100000 # 최소 거래 금액 10만원
      avoid_ex_dividend_dates: true # 배당 기준일 전후 매매 회피
      tax_loss_harvesting: false # 한국에서는 실효성 낮음

  # 비용 설정
  costs:
    etf_commission_rate: 0.00015 # 0.015% (온라인 증권사 기준)
    etf_tax_rate: 0.0 # 국내 ETF 매매차익 비과세 (2025 기준)
    overseas_etf_tax_rate: 0.22 # 해외 ETF 양도소득세 22%
    slippage_estimate: 0.001 # 0.1% 슬리피지 추정

"""
ETF 리밸런싱 엔진
- 포트폴리오 설정 파일을 읽어 현재 비중과 목표 비중의 차이를 계산
- 리밸런싱이 필요한 자산에 대해 매매 주문을 생성
"""
import yaml
from dataclasses import dataclass
from typing import Optional


@dataclass
class TradeOrder:
    """매매 주문 데이터."""
    ticker: str
    code: str
    action: str          # "BUY" or "SELL"
    amount_krw: int      # 매매 금액 (원)
    reason: str          # 리밸런싱 사유

    def __str__(self):
        return (
            f"[{self.action}] {self.ticker} ({self.code}) "
            f"₩{self.amount_krw:,} - {self.reason}"
        )


def load_config(path: str = "portfolio_config.yaml") -> dict:
    """포트폴리오 설정 파일을 로드한다."""
    with open(path, "r", encoding="utf-8") as f:
        return yaml.safe_load(f)


def get_current_holdings(broker_api) -> dict:
    """증권사 API에서 현재 보유 자산 정보를 조회한다.

    Returns:
        {종목코드: {"value_krw": 금액, "quantity": 수량}}
    """
    # 실제 구현 시 한국투자증권 OpenAPI, 키움 Open API+ 등 사용
    # 여기서는 예시 데이터 반환
    return {
        "360750": {"value_krw": 4_200_000, "quantity": 250},
        "069500": {"value_krw": 1_600_000, "quantity": 45},
        "305080": {"value_krw": 1_400_000, "quantity": 140},
        "443160": {"value_krw": 500_000, "quantity": 50},
        "091230": {"value_krw": 1_500_000, "quantity": 30},
        "305720": {"value_krw": 800_000, "quantity": 25},
        "319640": {"value_krw": 1_000_000, "quantity": 80},
    }


def calculate_drift(config: dict, holdings: dict) -> list[dict]:
    """각 자산의 목표 비중 대비 현재 편차를 계산한다."""
    total_value = sum(h["value_krw"] for h in holdings.values())
    if total_value == 0:
        return []

    results = []
    for section in ["core", "satellite"]:
        for asset in config["portfolio"]["allocation"][section]["assets"]:
            code = asset["code"]
            holding = holdings.get(code, {"value_krw": 0})
            current_weight = holding["value_krw"] / total_value
            target_weight = asset["target"]
            drift = current_weight - target_weight

            results.append({
                "ticker": asset["ticker"],
                "code": code,
                "target_weight": target_weight,
                "current_weight": round(current_weight, 4),
                "drift": round(drift, 4),
                "drift_pct": round(drift * 100, 2),
                "value_krw": holding["value_krw"],
                "section": section,
            })

    return results


def needs_rebalancing(
    drift_data: list[dict],
    threshold: float = 0.05,
) -> bool:
    """편차 임계치를 초과한 자산이 있는지 확인한다."""
    return any(abs(d["drift"]) > threshold for d in drift_data)


def generate_orders(
    config: dict,
    drift_data: list[dict],
    total_value: int,
    min_trade: int = 100_000,
) -> list[TradeOrder]:
    """리밸런싱에 필요한 매매 주문 목록을 생성한다."""
    orders = []

    for asset in drift_data:
        target_value = int(total_value * asset["target_weight"])
        diff = target_value - asset["value_krw"]

        # 최소 거래 금액 미만이면 스킵
        if abs(diff) < min_trade:
            continue

        action = "BUY" if diff > 0 else "SELL"
        reason = (
            f"목표 {asset['target_weight']*100:.1f}% vs "
            f"현재 {asset['current_weight']*100:.1f}% "
            f"(편차 {asset['drift_pct']:+.2f}%p)"
        )

        orders.append(TradeOrder(
            ticker=asset["ticker"],
            code=asset["code"],
            action=action,
            amount_krw=abs(diff),
            reason=reason,
        ))

    return orders


def run_rebalancing(
    config_path: str = "portfolio_config.yaml",
    dry_run: bool = True,
) -> None:
    """리밸런싱 전체 프로세스를 실행한다."""
    config = load_config(config_path)
    holdings = get_current_holdings(broker_api=None)
    total_value = sum(h["value_krw"] for h in holdings.values())

    print(f"총 자산: ₩{total_value:,}")
    print(f"리밸런싱 전략: {config['portfolio']['rebalancing']['strategy']}")
    print()

    # 편차 계산
    drift_data = calculate_drift(config, holdings)

    print("=== 현재 포트폴리오 편차 ===")
    for d in drift_data:
        flag = " ⚠" if abs(d["drift"]) > 0.05 else ""
        print(
            f"  {d['ticker']}: "
            f"목표 {d['target_weight']*100:.1f}% | "
            f"현재 {d['current_weight']*100:.1f}% | "
            f"편차 {d['drift_pct']:+.2f}%p{flag}"
        )
    print()

    # 리밸런싱 필요 여부 판단
    threshold = config["portfolio"]["rebalancing"]["drift_trigger"]["threshold"]
    if not needs_rebalancing(drift_data, threshold):
        print("리밸런싱 불필요: 모든 자산이 임계치 내에 있음")
        return

    # 매매 주문 생성
    min_trade = config["portfolio"]["rebalancing"]["constraints"]["min_trade_amount"]
    orders = generate_orders(config, drift_data, total_value, min_trade)

    print(f"=== 매매 주문 ({len(orders)}건) ===")
    for order in orders:
        print(f"  {order}")
    print()

    # 비용 추정
    commission_rate = config["portfolio"]["costs"]["etf_commission_rate"]
    total_trade = sum(o.amount_krw for o in orders)
    estimated_cost = int(total_trade * commission_rate)
    print(f"총 매매 금액: ₩{total_trade:,}")
    print(f"예상 수수료: ₩{estimated_cost:,}")

    if dry_run:
        print("\n[DRY RUN] 실제 주문은 실행되지 않았습니다.")
    else:
        print("\n[LIVE] 주문을 실행합니다...")
        # 실제 구현 시 증권사 API 호출


if __name__ == "__main__":
    run_rebalancing(dry_run=True)

총 자산: ₩11,000,000
리밸런싱 전략: hybrid

=== 현재 포트폴리오 편차 ===
  TIGER 미국S&P500: 목표 35.0% | 현재 38.2% | 편차 +3.18%p
  KODEX 200: 목표 15.0% | 현재 14.5% | 편차 -0.45%p
  TIGER 미국채10년선물: 목표 15.0% | 현재 12.7% | 편차 -2.27%p
  KODEX 종합채권(AA-이상)액티브: 목표 5.0% | 현재 4.5% | 편차 -0.45%p
  TIGER 반도체: 목표 10.0% | 현재 13.6% | 편차 +3.64%p
  KODEX 2차전지산업: 목표 10.0% | 현재 7.3% | 편차 -2.73%p
  TIGER 금은선물(H): 목표 10.0% | 현재 9.1% | 편차 -0.91%p

=== 매매 주문 (4건) ===
  [SELL] TIGER 미국S&P500 (360750) ₩350,000 - 목표 35.0% vs 현재 38.2% (편차 +3.18%p)
  [BUY] TIGER 미국채10년선물 (305080) ₩250,000 - 목표 15.0% vs 현재 12.7% (편차 -2.27%p)
  [SELL] TIGER 반도체 (091230) ₩400,000 - 목표 10.0% vs 현재 13.6% (편차 +3.64%p)
  [BUY] KODEX 2차전지산업 (305720) ₩300,000 - 목표 10.0% vs 현재 7.3% (편차 -2.73%p)

총 매매 금액: ₩1,300,000
예상 수수료: ₩195

[DRY RUN] 실제 주문은 실행되지 않았습니다.

# .github/workflows/rebalance-check.yml
name: ETF 리밸런싱 점검

on:
  schedule:
    # 매주 월요일 한국시간 09:00 (UTC 00:00)
    - cron: '0 0 * * 1'
  workflow_dispatch: # 수동 실행 가능

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Python 환경 설정
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'

      - name: 의존성 설치
        run: pip install pyyaml requests

      - name: 리밸런싱 점검 (Dry Run)
        run: python rebalance.py --dry-run
        env:
          BROKER_APP_KEY: ${{ secrets.BROKER_APP_KEY }}
          BROKER_APP_SECRET: ${{ secrets.BROKER_APP_SECRET }}

      - name: 결과 알림 (Slack)
        if: always()
        run: |
          python notify.py --channel "#investment" \
            --message "주간 리밸런싱 점검 완료. 상세 내용은 GitHub Actions 로그 참조."
        env:
          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}

"""리밸런싱 점검 결과를 Slack으로 전송한다."""
import json
import os
import urllib.request


def send_slack_notification(
    webhook_url: str,
    channel: str,
    message: str,
    orders: list[dict] | None = None,
) -> None:
    """Slack Incoming Webhook으로 알림을 전송한다."""
    blocks = [
        {
            "type": "header",
            "text": {
                "type": "plain_text",
                "text": "ETF 리밸런싱 점검 결과",
            },
        },
        {
            "type": "section",
            "text": {
                "type": "mrkdwn",
                "text": message,
            },
        },
    ]

    if orders:
        order_text = "\n".join(
            f"- {'매수' if o['action'] == 'BUY' else '매도'} "
            f"{o['ticker']} ₩{o['amount']:,}"
            for o in orders
        )
        blocks.append({
            "type": "section",
            "text": {
                "type": "mrkdwn",
                "text": f"*필요 매매 주문:*\n{order_text}",
            },
        })

    payload = json.dumps({
        "channel": channel,
        "blocks": blocks,
    }).encode("utf-8")

    req = urllib.request.Request(
        webhook_url,
        data=payload,
        headers={"Content-Type": "application/json"},
    )
    urllib.request.urlopen(req)


if __name__ == "__main__":
    send_slack_notification(
        webhook_url=os.environ["SLACK_WEBHOOK_URL"],
        channel="#investment",
        message="모든 자산이 목표 비중 ±5% 이내입니다. 리밸런싱 불필요.",
    )

"""리밸런싱 거래 로그를 JSON 파일로 관리한다."""
import json
from datetime import datetime
from dataclasses import dataclass, asdict


@dataclass
class RebalanceLog:
    """리밸런싱 실행 기록."""
    date: str
    trigger: str  # "scheduled" | "drift" | "manual"
    total_portfolio_value: int
    trades: list[dict]
    total_trade_amount: int
    total_commission: int
    pre_drift: dict   # 리밸런싱 전 편차
    post_drift: dict  # 리밸런싱 후 편차
    notes: str = ""


def save_log(log: RebalanceLog, path: str = "rebalance_log.json"):
    """거래 로그를 파일에 추가한다."""
    try:
        with open(path, "r") as f:
            logs = json.load(f)
    except FileNotFoundError:
        logs = []

    logs.append(asdict(log))

    with open(path, "w", encoding="utf-8") as f:
        json.dump(logs, f, indent=2, ensure_ascii=False)


# 사용 예시
log = RebalanceLog(
    date="2026-03-04",
    trigger="scheduled",
    total_portfolio_value=11_000_000,
    trades=[
        {"ticker": "TIGER 미국S&P500", "action": "SELL", "amount": 350_000},
        {"ticker": "TIGER 미국채10년선물", "action": "BUY", "amount": 250_000},
    ],
    total_trade_amount=600_000,
    total_commission=90,
    pre_drift={"TIGER 미국S&P500": 3.18, "TIGER 미국채10년선물": -2.27},
    post_drift={"TIGER 미국S&P500": 0.12, "TIGER 미국채10년선물": -0.08},
    notes="2026년 Q1 정기 리밸런싱. S&P500 비중 과다로 채권으로 이전.",
)
save_log(log)