[Lap 4] [모듈 3: Portfolio] 2008·2022 금융위기를 견디는 회계 장부

# 순진한 백테스트의 위험한 잔고 계산
cash = 100_000
for date, trade in trades.items():
    if trade.side == "BUY":
        cash -= trade.amount # 💥 현금이 0원 아래로 내려가는지 검사하지 않음!
        positions[trade.ticker] += trade.qty

# tests/test_portfolio_account.py
import pytest
from datetime import date
from quant_backtester.engine.portfolio import PortfolioAccount
from quant_backtester.engine.order import Trade, OrderSide
from quant_backtester.errors import InsufficientCashError

def test_insufficient_cash_raises_error_when_buying():
    """
    초기 자본 $10,000인 계좌에서 수수료 포함 $12,000어치 매수를 시도하면
    반드시 InsufficientCashError가 발생해야 한다 (유령 현금 원천 차단).
    """
    account = PortfolioAccount(initial_cash=10000.0)
    
    over_budget_trade = Trade(
        ticker="AAPL",
        side=OrderSide.BUY,
        quantity=60,
        fill_price=200.0,      # 총 60 * 200 = $12,000
        commission=5.0,
        execution_date=date(2024, 3, 15)
    )

    with pytest.raises(InsufficientCashError) as exc_info:
        account.process_trade(over_budget_trade)
    
    assert "Insufficient cash balance" in str(exc_info.value)
    assert account.cash == 10000.0  # 잔고는 단 1센트도 깎이지 않아야 함

def test_accurate_mtm_valuation_during_2008_crash():
    """
    2008년 리먼 파산일 주가가 -20% 폭락했을 때
    Mark-to-Market 시가평가로 NAV가 정확히 반영되는지 검증.
    """
    account = PortfolioAccount(initial_cash=100000.0)
    
    # 1. SPY 400주를 $140에 매수 ($56,000 소진, 수수료 $2)
    buy_trade = Trade(
        ticker="SPY",
        side=OrderSide.BUY,
        quantity=400,
        fill_price=140.0,
        commission=2.0,
        execution_date=date(2008, 9, 12)
    )
    account.process_trade(buy_trade)
    
    assert account.cash == 100000.0 - 56002.0 # $43,998.0
    
    # 2. 리먼 파산 후 SPY가 $112로 폭락 (-20%)
    current_prices = {"SPY": 112.0}
    account.update_daily_nav(as_of_date=date(2008, 9, 15), current_prices=current_prices)

    # 포지션 가치: 400주 * 112 = $44,800
    # 현금: $43,998
    # 총 순자산(NAV): $88,798 (초기 10만 달러 대비 -$11,202 손실)
    assert account.total_equity == 88798.0
    assert account.unrealized_pnl == -11200.0 # (112 - 140) * 400

$ pytest tests/test_portfolio_account.py
============================= FAILURES =============================
ImportError: cannot import name 'PortfolioAccount' from 'quant_backtester.engine.portfolio'
========================= 2 failed in 0.05s =========================

# quant_backtester/engine/portfolio.py
from datetime import date
from typing import Dict
from dataclasses import dataclass
from quant_backtester.engine.order import Trade, OrderSide
from quant_backtester.errors import InsufficientCashError

@dataclass
class Position:
    ticker: str
    quantity: int = 0
    average_cost: float = 0.0
    current_price: float = 0.0

    @property
    def market_value(self) -> float:
        return self.quantity * self.current_price

    @property
    def unrealized_pnl(self) -> float:
        return self.quantity * (self.current_price - self.average_cost)

class PortfolioAccount:
    """
    단 1달러의 유령 돈도 허용하지 않는 복식부기 포트폴리오 회계 계정.
    """
    def __init__(self, initial_cash: float):
        self._initial_cash = initial_cash
        self._cash = initial_cash
        self._positions: Dict[str, Position] = {}
        self._realized_pnl: float = 0.0
        self._total_commission: float = 0.0

    @property
    def cash(self) -> float:
        return self._cash

    @property
    def total_equity(self) -> float:
        # NAV = 현금 + 모든 보유 종목의 시가평가액
        return self._cash + sum(p.market_value for p in self._positions.values())

    @property
    def unrealized_pnl(self) -> float:
        return sum(p.unrealized_pnl for p in self._positions.values())

    def process_trade(self, trade: Trade) -> None:
        trade_amount = trade.quantity * trade.fill_price
        total_cost = trade_amount + trade.commission

        if trade.side == OrderSide.BUY:
            # 1. 엄격한 현금 부족 검증 (Hard Gate)
            if self._cash < total_cost:
                raise InsufficientCashError(
                    f"💥 Insufficient cash balance! Required: ${total_cost:,.2f}, Available: ${self._cash:,.2f}."
                )

            self._cash -= total_cost
            self._total_commission += trade.commission

            pos = self._positions.setdefault(trade.ticker, Position(ticker=trade.ticker, current_price=trade.fill_price))
            new_qty = pos.quantity + trade.quantity
            pos.average_cost = ((pos.quantity * pos.average_cost) + trade_amount) / new_qty
            pos.quantity = new_qty
            pos.current_price = trade.fill_price

        elif trade.side == OrderSide.SELL:
            pos = self._positions.get(trade.ticker)
            if not pos or pos.quantity < trade.quantity:
                raise ValueError(f"Cannot sell more shares than currently held for {trade.ticker}")

            proceeds = trade_amount - trade.commission
            self._cash += proceeds
            self._total_commission += trade.commission
            
            # 실현 손익 계산
            trade_realized_pnl = trade.quantity * (trade.fill_price - pos.average_cost) - trade.commission
            self._realized_pnl += trade_realized_pnl
            pos.quantity -= trade.quantity
            pos.current_price = trade.fill_price
            
            if pos.quantity == 0:
                del self._positions[trade.ticker]

    def update_daily_nav(self, as_of_date: date, current_prices: Dict[str, float]) -> None:
        """
        당일 종가로 모든 포지션 MTM 시가평가 및 NAV 확정
        """
        for ticker, pos in self._positions.items():
            if ticker in current_prices:
                pos.current_price = current_prices[ticker]

$ pytest tests/test_portfolio_account.py -v
tests/test_portfolio_account.py::test_insufficient_cash_raises_error_when_buying PASSED [ 50%]
tests/test_portfolio_account.py::test_accurate_mtm_valuation_during_2008_crash PASSED [100%]

========================= 2 passed in 0.08s =========================