Merge pull request #437 from easygap/feat/deposit-twr

feat: 적립 입금 + 시간가중수익률(TWR) — 소액 적립 트랙 선행 구현

Author: easygap

core/basket_evaluation.py

@@ -250,6 +250,31 @@ def build_daily_report_extras(
     return extras
 
 
+def time_weighted_capital(
+    initial_capital: float,
+    flows: list,
+    operation_start: Any,
+    today: Any,
+) -> float:
+    """기간 시간가중 평균 자본 (Modified Dietz 분모) — 비용 드래그 연환산의 공정한 분모.
+
+    flows: [(occurred_at, amount)...]. 각 유입은 '남은 기간 비율'만큼만 자본에 기여한다 —
+    말기 입금이 전 기간 분모를 부풀려 비용 게이트를 느슨하게 만드는 것을 막는다
+    (예: 59일차 3M 입금이 60일치 비용의 분모가 되면 안 된다).
+    """
+    def _d(v):
+        return v.date() if hasattr(v, "date") and callable(getattr(v, "date")) else v
+
+    start_d, end_d = _d(operation_start), _d(today)
+    period_days = max(1, (end_d - start_d).days)
+    weighted = float(initial_capital)
+    for occurred_at, amount in flows or []:
+        remain = (end_d - _d(occurred_at)).days
+        frac = min(1.0, max(0.0, remain / period_days))
+        weighted += float(amount) * frac
+    return max(weighted, 1.0)
+
+
 def decompose_return_gap(
     nav_return_pct: float | None,
     design_return_pct: float | None,
@@ -418,9 +443,23 @@ def _d(v):
         )
     )
 
+    # 적립식 계정(외부 현금 흐름 존재): 총평가/초기자본은 입금을 수익으로 오표기하므로
+    # 스냅샷의 TWR 누적수익률을 쓰고, 비용 분모는 시간가중 평균 자본(Modified Dietz)으로
+    # 바꾼다 — 말기 입금이 전 기간 비용의 분모를 부풀려 게이트를 느슨하게 만들지 않게.
+    # 흐름 0건이면 아래 두 값은 기존과 완전히 동일하다(하위 호환).
+    from database.repositories import get_cash_flows, has_cash_flows
+    account_has_flows = has_cash_flows(account_key=basket_key)
+    if account_has_flows:
+        initial_capital = time_weighted_capital(
+            initial_capital, get_cash_flows(account_key=basket_key), operation_start, today,
+        )
+
     nav_return_pct = None
     if snaps:
-        nav_return_pct = (float(snaps[-1].total_value) / initial_capital - 1.0) * 100
+        if account_has_flows:
+            nav_return_pct = float(snaps[-1].cumulative_return or 0.0)
+        else:
+            nav_return_pct = (float(snaps[-1].total_value) / initial_capital - 1.0) * 100
 
     # NAV는 마지막 스냅샷 시점의 값이다 — 벤치마크·설계 조회도 같은 종료일로 맞춰야
     # 세 값을 비교할 때 하루치 시장 변동이 실행 격차로 오귀속되지 않는다(적대적 리뷰 medium).

core/notifier.py

@@ -314,6 +314,14 @@ def send_daily_report(self, report: dict) -> None:
             {"name": "📋 보유 종목", "value": f"{report.get('position_count', 0)}개", "inline": True},
             {"name": "🔄 당일 매매", "value": f"{report.get('total_trades', 0)}건", "inline": True},
         ]
+        # 적립식 계정: 누적 원금(초기+입금)을 평가액과 분리 표기(있을 때만) —
+        # '내가 넣은 돈 대비 얼마'가 한눈에 보이게.
+        if report.get("principal") is not None:
+            fields.insert(1, {
+                "name": "💳 누적 원금",
+                "value": f"{report.get('principal', 0):,.0f}원",
+                "inline": True,
+            })
         # 리포트 v2 부가 필드(있을 때만) — 시장/설계/일정 대비 판단용.
         # 값은 core.basket_evaluation.build_daily_report_extras가 만든 문자열이다.
         for key, label, inline in (

core/portfolio_manager.py

@@ -14,9 +14,26 @@
     save_portfolio_snapshot,
     get_latest_peak_value,
     get_strategy_performance_summary,
+    get_cash_flow_total,
+    get_cash_flow_total_between,
+    get_max_cumulative_return,
+    get_latest_snapshot_summary,
+    has_cash_flows,
 )
 
 
+def twr_period_return(v_prev: float, v_now: float, flow: float = 0.0) -> float:
+    """구간 시간가중수익률(소수). 외부 현금 흐름(flow, +입금)은 구간 시작에 유입으로 간주.
+
+    r = v_now / (v_prev + flow) - 1  — 입금은 수익이 아니므로 분모에 더해 중화한다.
+    분모가 0 이하이면 판정 불가로 0을 반환한다(신규 계정 초기 상태 등).
+    """
+    base = float(v_prev) + float(flow)
+    if base <= 0:
+        return 0.0
+    return float(v_now) / base - 1.0
+
+
 class LiveBrokerBalanceUnavailable(RuntimeError):
     """live 주문 판단에 필요한 KIS 잔고를 확인하지 못한 상태."""
 
@@ -102,9 +119,12 @@ def _get_db_financials(self, invested: float, current_value: float, mode: str) -
             mode=mode,
             account_key=self.account_key if self.account_key else None,
         )
-        cash = self.initial_capital + cash_summary["cash_delta"]
+        # 외부 현금 흐름(입금/출금)은 현금에 더하되 손익에서는 제외한다 —
+        # 입금은 수익이 아니다(적립식 지원, docs/POCKET_TRACK_PLAN.md §4).
+        deposits = get_cash_flow_total(account_key=self.account_key)
+        cash = self.initial_capital + deposits + cash_summary["cash_delta"]
         total_value = cash + current_value
-        realized_pnl = cash + invested - self.initial_capital
+        realized_pnl = cash + invested - self.initial_capital - deposits
         unrealized_pnl = current_value - invested
         return {
             "cash": cash,
@@ -154,6 +174,8 @@ def get_portfolio_summary(self, current_prices: dict = None) -> dict:
                 broker_balance_error = str(e)
                 logger.warning("KIS 잔고 조회 실패 — DB 기준으로 대체: {}", e)
 
+        deposits_total = get_cash_flow_total(account_key=self.account_key)
+
         if cash is None or total_value is None:
             financials = self._get_db_financials(
                 invested,
@@ -166,13 +188,47 @@ def get_portfolio_summary(self, current_prices: dict = None) -> dict:
             unrealized_pnl = financials["unrealized_pnl"]
         else:
             unrealized_pnl = current_value - invested
-            realized_pnl = total_value - self.initial_capital - unrealized_pnl
+            realized_pnl = total_value - self.initial_capital - deposits_total - unrealized_pnl
+
+        # 분기는 순합이 아니라 '흐름 존재 여부'로 — 순합 0(+100/-100)이어도 구간
+        # 수익률은 이미 흐름의 영향을 받았으므로 TWR 경로를 유지해야 한다.
+        account_has_flows = deposits_total != 0 or has_cash_flows(self.account_key)
 
-        total_return = ((total_value / self.initial_capital) - 1) * 100 if self.initial_capital > 0 else 0
+        if not account_has_flows:
+            # 무입금 계정: 기존 산식 그대로 (하위 호환 — 결과 불변)
+            total_return = ((total_value / self.initial_capital) - 1) * 100 if self.initial_capital > 0 else 0
 
-        if total_value > self._peak_value:
-            self._peak_value = total_value
-        mdd = ((self._peak_value - total_value) / self._peak_value) * 100 if self._peak_value > 0 else 0
+            if total_value > self._peak_value:
+                self._peak_value = total_value
+            mdd = ((self._peak_value - total_value) / self._peak_value) * 100 if self._peak_value > 0 else 0
+        else:
+            # 적립식 계정: 시간가중수익률(TWR) — 입금은 수익이 아니다.
+            # 직전 스냅샷과 이번 측정 사이 유입(flow)을 분모에 더해 중화하고,
+            # 누적은 직전 스냅샷의 누적수익률에 구간 수익률을 연결한다.
+            from datetime import datetime as _dt
+            prev = get_latest_snapshot_summary(account_key=self.account_key)
+            if prev is None:
+                # 첫 측정: 초기자본이 첫 유입, 그간의 입금 전액이 구간 유입
+                r = twr_period_return(self.initial_capital, total_value, deposits_total)
+                total_return = r * 100
+            else:
+                # 경계는 실제 측정 시각(created_at) — date(자정 귀속)를 쓰면 스냅샷
+                # 이전의 같은 날 입금이 이중 산입된다.
+                boundary = prev.get("created_at") or prev.get("date")
+                flow_since = get_cash_flow_total_between(
+                    self.account_key, boundary, _dt.now(),
+                )
+                r = twr_period_return(prev["total_value"], total_value, flow_since)
+                total_return = ((1 + prev["cumulative_return"] / 100) * (1 + r) - 1) * 100
+
+            # MDD도 TWR 지수 기준 — 원화 피크로 재면 입금이 낙폭을 가짜 회복시킨다.
+            index_now = 1 + total_return / 100
+            hist_max = get_max_cumulative_return(account_key=self.account_key)
+            peak_index = max(1.0, index_now, 1 + (hist_max or 0.0) / 100)
+            mdd = ((peak_index - index_now) / peak_index) * 100 if peak_index > 0 else 0
+            # 원화 피크(peak_value 컬럼)는 스냅샷 연속성 위해 기존대로 계속 기록
+            if total_value > self._peak_value:
+                self._peak_value = total_value
 
         return {
             "total_value": round(total_value, 0),
@@ -184,6 +240,8 @@ def get_portfolio_summary(self, current_prices: dict = None) -> dict:
             "position_count": len(positions),
             "realized_pnl": round(realized_pnl, 0),
             "unrealized_pnl": round(unrealized_pnl, 0),
+            "deposits_total": round(deposits_total, 0),
+            "principal": round(self.initial_capital + deposits_total, 0),
             "positions": position_details,
             "broker_balance_ok": broker_balance_ok,
             "broker_balance_source": broker_balance_source,

database/models.py

@@ -223,6 +223,29 @@ def __repr__(self):
         return f"<FailedOrder({self.symbol} {self.action} {self.quantity}주 @{self.price}, status={self.status})>"
 
 
+class CashFlow(Base):
+    """
+    외부 현금 흐름(입금/출금) 테이블 — 적립식 운영 지원.
+
+    수익률 계산에서 입금은 수익이 아니다: 시간가중수익률(TWR) 계산이 이 기록으로
+    입금 구간을 분리한다(docs/POCKET_TRACK_PLAN.md §4). paper는
+    tools/record_deposit.py로 기록하고, live도 실제 입금 후 같은 도구로 기록해야
+    TWR이 맞는다(증권사 잔고는 현금만 알지, 언제 얼마가 외부에서 왔는지는 모른다).
+    """
+    __tablename__ = "cash_flows"
+
+    id = Column(Integer, primary_key=True, autoincrement=True)
+    account_key = Column(String(64), default="", nullable=False, index=True)
+    amount = Column(Float, nullable=False)                       # +입금 / -출금 (원)
+    occurred_at = Column(DateTime, nullable=False, index=True)   # 발생 시각(귀속 기준)
+    note = Column(String(200), default="")                       # 메모 (예: 7월 적립)
+    mode = Column(String(20), default="paper")
+    created_at = Column(DateTime, default=datetime.now)
+
+    def __repr__(self):
+        return f"<CashFlow({self.account_key}, {self.amount:+,.0f}, {self.occurred_at})>"
+
+
 class OperationEvent(Base):
     """
     운영 이벤트 로그 테이블.