pyqqq-script 0.0.1__py3-none-any.whl

pyqqq3/infra/broker/kis.py

@@ -0,0 +1,134 @@
+"""KISDomesticBroker — 한국투자증권 REST/Websocket 어댑터 (스켈레톤).
+
+실제 API 연동은 추후 작성한다. 이 파일은 Broker 계약 형태와
+이벤트 발행 헬퍼만 제공해 LiveTrading 이 Backtest 와 동일한 구조로
+조립될 수 있음을 보여준다.
+
+외부로 나가는 것 (이 어댑터의 책임):
+    buy/sell/cancel → KIS REST 주문 API
+    set_stop_loss/set_take_profit/set_trailing_stop → 로컬 상태
+
+외부에서 들어오는 것 (Account 에 반영될 이벤트):
+    OrderSubmitted  — 주문 접수 응답
+    OrderRejected   — 주문 거부 응답
+    FillExecuted    — 체결 통보 (websocket)
+    CashDeposited   — 초기 잔고 조회 응답
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+import logging
+from decimal import Decimal
+from typing import TYPE_CHECKING, Callable
+
+from pyqqq3.model.types import Bar, OrderSide, Position
+
+if TYPE_CHECKING:
+    from pyqqq3.model.execution.events import ExecutionEvent
+    from pyqqq3.model.symbol import Symbol
+
+_log = logging.getLogger("pyqqq3.broker.kis")
+
+
+class KISDomesticBroker:
+    """한국투자증권 브로커 어댑터 (스켈레톤 / 미구현).
+
+    Attributes:
+        symbol: 단일 종목 전용 (향후 멀티심볼 확장 여지).
+    """
+
+    def __init__(
+        self,
+        symbol: "Symbol",
+        event_sink: "Callable[[ExecutionEvent], None]",
+        account_no: str = "",
+    ) -> None:
+        self._symbol = symbol
+        self._emit: Callable[[ExecutionEvent], None] = event_sink
+        self._account_no = account_no
+        self._seq = 0
+        self._stop_loss_pct: float | None = None
+        self._take_profit_pct: float | None = None
+        self._trailing_pct: float | None = None
+
+    # ------------------------------------------------------------------ Broker interface
+
+    def process(self, bar: Bar) -> None:
+        """실시간 모드에서는 no-op. 체결은 외부 이벤트로 들어온다."""
+        # 향후: 봉 단위 리스크 체크가 필요하면 여기에. 단, 실제 손절/익절 주문은
+        # 거래소에 미리 걸어두거나(OCO), websocket 에서 판단.
+
+    def buy(
+        self,
+        current_price: Decimal,
+        qty: int | None = None,
+        amount: int | None = None,
+        pct: float | None = None,
+    ) -> None:
+        raise NotImplementedError("KIS 주문 API 연동 필요")
+
+    def sell(
+        self,
+        current_price: Decimal,
+        qty: int | None = None,
+        pct: float | None = None,
+    ) -> None:
+        raise NotImplementedError("KIS 주문 API 연동 필요")
+
+    def set_stop_loss(self, pct: float) -> None:
+        self._stop_loss_pct = float(pct)
+
+    def set_take_profit(self, pct: float) -> None:
+        self._take_profit_pct = float(pct)
+
+    def set_trailing_stop(self, pct: float) -> None:
+        self._trailing_pct = float(pct)
+
+    def get_position(self, current_price: Decimal) -> Position:
+        raise NotImplementedError("Account 애그리게이트 조회로 위임 예정")
+
+    # ------------------------------------------------------------------ event emission helpers
+
+    def _next_seq(self) -> int:
+        self._seq += 1
+        return self._seq
+
+    def emit_cash_deposited(self, amount: Decimal) -> None:
+        """초기 잔고 조회 결과를 이벤트로 발행 (run 시작 시 1회)."""
+        from pyqqq3.model.execution.events import CashDeposited
+
+        self._emit(
+            CashDeposited(
+                occurred_at=dt.datetime.now(),
+                bar_index=0,
+                seq=self._next_seq(),
+                amount=amount,
+            )
+        )
+
+    def emit_fill(
+        self,
+        order_id: str,
+        side: OrderSide,
+        price: Decimal,
+        quantity: int,
+        commission: Decimal,
+        occurred_at: dt.datetime,
+        bar_index: int = 0,
+    ) -> None:
+        """체결 통보 (websocket callback) → 이벤트로 변환."""
+        from pyqqq3.model.execution.events import FillExecuted
+
+        self._emit(
+            FillExecuted(
+                occurred_at=occurred_at,
+                bar_index=bar_index,
+                seq=self._next_seq(),
+                order_id=order_id,
+                side=side,
+                price=price,
+                quantity=quantity,
+                commission=commission,
+            )
+        )