From 0774352a9836ea1b9060c568fc3c0e2377eb90cc Mon Sep 17 00:00:00 2001 From: YoungWooSeo Date: Fri, 6 Mar 2026 10:29:59 +0900 Subject: [PATCH 1/6] refactor: Create trading module structure --- backend/app/trading/__init__.py | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) create mode 100644 backend/app/trading/__init__.py diff --git a/backend/app/trading/__init__.py b/backend/app/trading/__init__.py new file mode 100644 index 0000000..73896bf --- /dev/null +++ b/backend/app/trading/__init__.py @@ -0,0 +1,17 @@ +""" +Trading Engine Module + +주식 매매 실행을 담당하는 핵심 모듈 +- KIS API 연동 (REST + WebSocket) +- 주문 실행·취소·조회 +- 실시간 시세 수신 +- 장 스케줄 관리 +""" + +__all__ = [ + "KISClient", + "WSClient", + "OrderManager", + "WSManager", + "TradingScheduler", +] From 0bfca909cc478d667cb24bc58ea7d8073ea1c4a2 Mon Sep 17 00:00:00 2001 From: YoungWooSeo Date: Fri, 6 Mar 2026 10:44:33 +0900 Subject: [PATCH 2/6] refactor(phase1): Create trading module core files --- backend/app/trading/kis_client.py | 233 +++++++++++++++++++++++++++ backend/app/trading/order_manager.py | 194 ++++++++++++++++++++++ 2 files changed, 427 insertions(+) create mode 100644 backend/app/trading/kis_client.py create mode 100644 backend/app/trading/order_manager.py diff --git a/backend/app/trading/kis_client.py b/backend/app/trading/kis_client.py new file mode 100644 index 0000000..f237f90 --- /dev/null +++ b/backend/app/trading/kis_client.py @@ -0,0 +1,233 @@ +""" +KIS REST API Client +한국투자증권 REST API 핵심 클라이언트 (토큰 관리 + HTTP 요청) +""" +import httpx +from typing import Dict, Any, Optional, Tuple +from datetime import datetime, timedelta +import logging +import asyncio +import time +import json +import os +from pathlib import Path + +from app.core.config import settings + +logger = logging.getLogger(__name__) + + +class KISClient: + """한국투자증권 REST API 클라이언트 (토큰 관리 + 안전한 HTTP 요청)""" + + TOKEN_CACHE_FILE = Path.home() / ".cache" / "auto-stock" / "kis_token_cache.json" + + @classmethod + def for_real_market_data(cls) -> "KISClient": + """실계좌 자격증명으로 시세조회 전용 인스턴스 생성""" + if not settings.KIS_REAL_APP_KEY: + raise ValueError("KIS_REAL_APP_KEY가 설정되지 않음") + + instance = cls.__new__(cls) + instance.base_url = settings.KIS_REAL_URL + instance.app_key = settings.KIS_REAL_APP_KEY + instance.app_secret = settings.KIS_REAL_APP_SECRET + instance.account_number = settings.KIS_REAL_ACCOUNT_NO + instance.TOKEN_CACHE_FILE = Path.home() / ".cache" / "auto-stock" / "kis_token_cache_real.json" + instance._init_common() + logger.info(f"🔧 KIS 실계좌 시세조회 API: {instance.base_url}") + return instance + + def __init__(self): + self.base_url = settings.KOREA_INVESTMENT_API_BASE_URL + self.app_key = settings.KOREA_INVESTMENT_APP_KEY + self.app_secret = settings.KOREA_INVESTMENT_APP_SECRET + self.account_number = settings.KOREA_INVESTMENT_ACCOUNT_NUMBER + self._init_common() + logger.info(f"🔧 KIS API 초기화: mode={settings.KIS_MODE}, {self.base_url}") + + def _init_common(self): + """공통 초기화 로직""" + self.access_token: Optional[str] = None + self.token_expires_at: Optional[datetime] = None + self.last_request_time: Optional[float] = None + + # 설정 기반 쓰로틀링 + self.min_request_interval = settings.API_MIN_REQUEST_INTERVAL + self.max_retries = settings.API_MAX_RETRIES + self.retry_delay = settings.API_RETRY_DELAY + self.retry_backoff = settings.API_RETRY_BACKOFF + self.timeout = settings.API_TIMEOUT + + # 동시 요청 제한 + self.semaphore = asyncio.Semaphore(settings.API_MAX_CONCURRENT_REQUESTS) + self._token_lock = asyncio.Lock() + + # 캐시된 토큰 로드 + self._load_token_from_cache() + + def _load_token_from_cache(self): + """파일에서 토큰 로드""" + try: + cache_file = Path(self.TOKEN_CACHE_FILE) + if cache_file.exists(): + with open(cache_file, 'r') as f: + cache = json.load(f) + self.access_token = cache.get('access_token') + expires_str = cache.get('expires_at') + if expires_str: + self.token_expires_at = datetime.fromisoformat(expires_str) + if self.access_token and datetime.now() < self.token_expires_at: + remaining = (self.token_expires_at - datetime.now()).total_seconds() / 3600 + logger.info(f"💾 캐시 토큰 로드 (남은 시간: {remaining:.1f}시간)") + except Exception as e: + logger.warning(f"⚠️ 토큰 캐시 로드 실패: {e}") + + async def _save_token_to_cache(self): + """토큰을 파일에 비동기 저장""" + try: + cache_file = Path(self.TOKEN_CACHE_FILE) + cache_file.parent.mkdir(parents=True, exist_ok=True) + cache = { + 'access_token': self.access_token, + 'expires_at': self.token_expires_at.isoformat() if self.token_expires_at else None, + } + await asyncio.to_thread(self._write_token_file, cache_file, cache) + except Exception as e: + logger.warning(f"⚠️ 토큰 캐시 저장 실패: {e}") + + def _write_token_file(self, cache_file: Path, cache: dict): + """동기 파일 쓰기""" + with open(cache_file, 'w') as f: + json.dump(cache, f) + os.chmod(cache_file, 0o600) + + async def get_access_token(self) -> str: + """접근 토큰 발급 (Lock으로 중복 방지)""" + if self.access_token and self.token_expires_at and datetime.now() < self.token_expires_at: + return self.access_token + + async with self._token_lock: + if self.access_token and self.token_expires_at and datetime.now() < self.token_expires_at: + return self.access_token + + logger.info("🔑 새 토큰 발급 요청") + + async with httpx.AsyncClient() as client: + response = await client.post( + f"{self.base_url}/oauth2/tokenP", + json={ + "grant_type": "client_credentials", + "appkey": self.app_key, + "appsecret": self.app_secret + }, + timeout=30.0 + ) + + if response.status_code == 200: + data = response.json() + self.access_token = data["access_token"] + self.token_expires_at = datetime.now() + timedelta(hours=23) + await self._save_token_to_cache() + logger.info(f"✅ 토큰 발급 완료") + return self.access_token + else: + raise Exception(f"토큰 발급 실패: {response.status_code} - {response.text}") + + async def request( + self, + method: str, + endpoint: str, + tr_id: str, + extra_headers: Optional[Dict[str, str]] = None, + **kwargs + ) -> Tuple[Dict[str, Any], Optional[Any]]: + """API 요청 (재시도 + 쓰로틀링)""" + async with self.semaphore: + return await self._request_with_retry(method, endpoint, tr_id, extra_headers, **kwargs) + + async def _request_with_retry( + self, + method: str, + endpoint: str, + tr_id: str, + extra_headers: Optional[Dict[str, str]], + **kwargs + ) -> Tuple[Dict[str, Any], Optional[Any]]: + """재시도 로직 포함 실제 요청""" + start_time = time.time() + + for attempt in range(self.max_retries + 1): + try: + # 쓰로틀링 + if self.last_request_time: + elapsed = time.time() - self.last_request_time + if elapsed < self.min_request_interval: + await asyncio.sleep(self.min_request_interval - elapsed) + + self.last_request_time = time.time() + + token = await self.get_access_token() + + headers = { + "content-type": "application/json; charset=utf-8", + "authorization": f"Bearer {token}", + "appkey": self.app_key, + "appsecret": self.app_secret, + "tr_id": tr_id, + } + if extra_headers: + headers.update(extra_headers) + + timeout = httpx.Timeout(self.timeout, connect=10.0) + + async with httpx.AsyncClient(timeout=timeout) as client: + response = await client.request( + method, + f"{self.base_url}{endpoint}", + headers=headers, + **kwargs + ) + + if response.status_code == 200: + return response.json(), response.headers + + # 재시도 대상 (429, 5xx) + elif response.status_code in [429, 500, 502, 503, 504]: + if attempt < self.max_retries: + delay = self.retry_delay * (self.retry_backoff ** attempt) + logger.warning(f"⏳ 재시도 {attempt + 1}/{self.max_retries}: {delay:.1f}초 대기") + await asyncio.sleep(delay) + continue + else: + raise Exception(f"최대 재시도 초과: {response.status_code}") + + # 4xx - 재시도 불필요 + elif 400 <= response.status_code < 500: + try: + return response.json(), response.headers + except Exception: + return {"rt_cd": str(response.status_code), "msg1": response.text}, None + + else: + raise Exception(f"API 실패: {response.status_code} - {response.text}") + + except httpx.TimeoutException: + if attempt < self.max_retries: + delay = self.retry_delay * (self.retry_backoff ** attempt) + logger.warning(f"⏳ 타임아웃 재시도 {attempt + 1}/{self.max_retries}") + await asyncio.sleep(delay) + continue + else: + raise + + raise Exception("API 요청 실패") + + +# 싱글톤 인스턴스 +kis_client = KISClient() + +try: + real_market_client = KISClient.for_real_market_data() +except Exception: + real_market_client = None diff --git a/backend/app/trading/order_manager.py b/backend/app/trading/order_manager.py new file mode 100644 index 0000000..e1920e9 --- /dev/null +++ b/backend/app/trading/order_manager.py @@ -0,0 +1,194 @@ +""" +Order Manager +주문 실행·취소·조회 전담 모듈 +""" +from typing import Dict, Any, Optional +import logging + +from app.trading.kis_client import kis_client + +logger = logging.getLogger(__name__) + + +class OrderManager: + """주문 실행 관리자""" + + def __init__(self, client=None): + self.client = client or kis_client + + async def place_order( + self, + stock_code: str, + order_type: str, # "BUY" or "SELL" + quantity: int, + price: Optional[float] = None # None = 시장가 + ) -> Dict[str, Any]: + """주문 실행""" + try: + account_number_prefix = self.client.account_number[:8] + account_number_suffix = self.client.account_number[8:] + + is_virtual = "vts" in self.client.base_url.lower() + + if order_type == "BUY": + tr_id = "VTTC0802U" if is_virtual else "TTTC0802U" + else: + tr_id = "VTTC0801U" if is_virtual else "TTTC0801U" + + order_dvsn = "01" if price is None else "00" + order_price = "0" if price is None else str(int(price)) + + logger.info(f"📤 주문: {order_type} {stock_code} {quantity}주 @{order_price}") + + result, _ = await self.client.request( + "POST", + "/uapi/domestic-stock/v1/trading/order-cash", + tr_id, + json={ + "CANO": account_number_prefix, + "ACNT_PRDT_CD": account_number_suffix, + "PDNO": stock_code, + "ORD_DVSN": order_dvsn, + "ORD_QTY": str(quantity), + "ORD_UNPR": order_price + } + ) + + logger.info(f"📥 주문 응답: rt_cd={result.get('rt_cd')}, odno={result.get('odno')}") + return result + except Exception as e: + logger.error(f"❌ 주문 실패: {e}") + return {"rt_cd": "-1", "msg1": str(e), "odno": None} + + async def cancel_order(self, order_id: str, quantity: int) -> Dict[str, Any]: + """주문 취소""" + try: + account_number_prefix = self.client.account_number[:8] + account_number_suffix = self.client.account_number[8:] + + is_virtual = "vts" in self.client.base_url.lower() + tr_id = "VTTC0803U" if is_virtual else "TTTC0803U" + + result, _ = await self.client.request( + "POST", + "/uapi/domestic-stock/v1/trading/order-rvsecncl", + tr_id, + json={ + "CANO": account_number_prefix, + "ACNT_PRDT_CD": account_number_suffix, + "KRX_FWDG_ORD_ORGNO": "", + "ORGN_ODNO": order_id, + "ORD_DVSN": "00", + "RVSE_CNCL_DVSN_CD": "02", + "ORD_QTY": "0", + "ORD_UNPR": "0", + "QTY_ALL_ORD_YN": "Y" + } + ) + return result + except Exception as e: + logger.error(f"❌ 취소 실패: {e}") + raise + + async def get_balance(self) -> Dict[str, Any]: + """계좌 잔고 조회""" + try: + account_number_prefix = self.client.account_number[:8] + account_number_suffix = self.client.account_number[8:] + + is_virtual = "vts" in self.client.base_url.lower() + tr_id = "VTTC8434R" if is_virtual else "TTTC8434R" + + result, _ = await self.client.request( + "GET", + "/uapi/domestic-stock/v1/trading/inquire-balance", + tr_id, + params={ + "CANO": account_number_prefix, + "ACNT_PRDT_CD": account_number_suffix, + "AFHR_FLPR_YN": "N", + "OFL_YN": "", + "INQR_DVSN": "02", + "UNPR_DVSN": "01", + "FUND_STTL_ICLD_YN": "N", + "FNCG_AMT_AUTO_RDPT_YN": "N", + "PRCS_DVSN": "01", + "CTX_AREA_FK100": "", + "CTX_AREA_NK100": "" + } + ) + return result + except Exception as e: + logger.error(f"❌ 잔고 조회 실패: {e}") + raise + + async def place_overseas_order( + self, + symbol: str, + order_type: str, + quantity: int, + price: float, + exchange_code: str = "NASD" + ) -> Dict[str, Any]: + """해외주식 주문""" + try: + account_number_prefix = self.client.account_number[:8] + account_number_suffix = self.client.account_number[8:] + + is_virtual = "vts" in self.client.base_url.lower() + + if order_type == "BUY": + tr_id = "VTTT1002U" if is_virtual else "TTTT1002U" + else: + tr_id = "VTTT1006U" if is_virtual else "TTTT1006U" + + result, _ = await self.client.request( + "POST", + "/uapi/overseas-stock/v1/trading/order", + tr_id, + json={ + "CANO": account_number_prefix, + "ACNT_PRDT_CD": account_number_suffix, + "OVRS_EXCG_CD": exchange_code.upper(), + "PDNO": symbol.upper(), + "ORD_QTY": str(quantity), + "OVRS_ORD_UNPR": str(price), + "ORD_SVR_DVSN_CD": "0", + "ORD_DVSN": "00" + } + ) + return result + except Exception as e: + logger.error(f"❌ 해외주식 주문 실패: {e}") + raise + + async def get_overseas_balance(self) -> Dict[str, Any]: + """해외주식 잔고 조회""" + try: + account_number_prefix = self.client.account_number[:8] + account_number_suffix = self.client.account_number[8:] + + is_virtual = "vts" in self.client.base_url.lower() + tr_id = "VTTS3012R" if is_virtual else "TTTS3012R" + + result, _ = await self.client.request( + "GET", + "/uapi/overseas-stock/v1/trading/inquire-balance", + tr_id, + params={ + "CANO": account_number_prefix, + "ACNT_PRDT_CD": account_number_suffix, + "OVRS_EXCG_CD": "NASD", + "TR_CRCY_CD": "USD", + "CTX_AREA_FK200": "", + "CTX_AREA_NK200": "", + } + ) + return result + except Exception as e: + logger.error(f"❌ 해외주식 잔고 조회 실패: {e}") + return {} + + +# 싱글톤 +order_manager = OrderManager() From ea4ebae992888abfde766f5524239e631b1418da Mon Sep 17 00:00:00 2001 From: YoungWooSeo Date: Fri, 6 Mar 2026 10:45:21 +0900 Subject: [PATCH 3/6] refactor(phase1): Add market data module for price/chart queries --- backend/app/trading/market_data.py | 247 +++++++++++++++++++++++++++++ 1 file changed, 247 insertions(+) create mode 100644 backend/app/trading/market_data.py diff --git a/backend/app/trading/market_data.py b/backend/app/trading/market_data.py new file mode 100644 index 0000000..7bf2491 --- /dev/null +++ b/backend/app/trading/market_data.py @@ -0,0 +1,247 @@ +""" +Market Data Module +시세·차트 조회 전담 모듈 (Redis 캐시 적용) +""" +from typing import Dict, Any, Optional, List +import logging +import asyncio +from datetime import datetime, timedelta +import pytz + +from app.trading.kis_client import kis_client, real_market_client + +logger = logging.getLogger(__name__) + +# 차트 캐시 TTL 상수 +TTL_DAILY_CHART = 300 +TTL_MINUTE_CHART = 60 +TTL_MINUTE_FULLDAY = 60 +TTL_OVERSEAS_CHART = 300 + + +async def _cache_get(key: str) -> Optional[Any]: + """ +Redis 캐시에서 값 조회 (non-blocking) + """ + try: + from app.core.redis import get_json + return await get_json(key) + except Exception: + return None + + +async def _cache_set(key: str, ttl: int, data: Any) -> None: + """Redis 캐시에 값 저장 (non-blocking)""" + try: + from app.core.redis import setex_json + await setex_json(key, ttl, data) + except Exception: + pass + + +class MarketDataProvider: + """시세 및 차트 데이터 제공자""" + + def __init__(self, client=None, real_client=None): + self.client = client or kis_client + self.real_client = real_client or real_market_client + + async def get_current_price(self, stock_code: str) -> Dict[str, Any]: + """현재가 조회""" + try: + client = self.real_client or self.client + result, _ = await client.request( + "GET", + "/uapi/domestic-stock/v1/quotations/inquire-price", + "FHKST01010100", + params={ + "FID_COND_MRKT_DIV_CODE": "J", + "FID_INPUT_ISCD": stock_code + } + ) + return result + except Exception as e: + logger.error(f"❌ 현재가 조회 실패 {stock_code}: {e}") + raise + + async def get_daily_chart( + self, + stock_code: str, + period: str = "D", + limit: int = 240 + ) -> Dict[str, Any]: + """일봉/주봉/월봉 조회 (Redis 캐시, 페이지네이션)""" + cache_key = f"chart:daily:{stock_code}:{period}:{limit}" + + # 캐시 히트 + cached = await _cache_get(cache_key) + if cached is not None: + logger.debug(f"📦 [캐시 히트] {cache_key}") + return cached + + # KIS API 호출 + all_output2 = [] + params = { + "FID_COND_MRKT_DIV_CODE": "J", + "FID_INPUT_ISCD": stock_code, + "FID_PERIOD_DIV_CODE": period, + "FID_ORG_ADJ_PRC": "0" + } + + try: + client = self.real_client or self.client + result, headers = await client.request( + "GET", + "/uapi/domestic-stock/v1/quotations/inquire-daily-price", + "FHKST01010400", + params=params + ) + + data_key = 'output2' if isinstance(result.get('output2'), list) else 'output' + if not result or result.get('rt_cd') != '0' or not result.get(data_key): + return result + + all_output2.extend(result.get(data_key, [])) + tr_cont = headers.get('tr_cont') + + # 연속 조회 + while tr_cont in ('F', 'M') and len(all_output2) < limit: + await asyncio.sleep(self.client.min_request_interval + 0.1) + extra_headers = {'tr_cont': 'Y'} + + result_cont, headers_cont = await client.request( + "GET", + "/uapi/domestic-stock/v1/quotations/inquire-daily-price", + "FHKST01010400", + params=params, + extra_headers=extra_headers + ) + + if result_cont and result_cont.get('rt_cd') == '0': + cont_key = 'output2' if isinstance(result_cont.get('output2'), list) else 'output' + all_output2.extend(result_cont.get(cont_key, [])) + + tr_cont = headers_cont.get('tr_cont') if headers_cont else None + + final_result = result + final_result['output2'] = all_output2 + logger.info(f"✅ 차트 데이터 {len(all_output2)}개 수집: {stock_code}") + + # 캐시 저장 + await _cache_set(cache_key, TTL_DAILY_CHART, final_result) + return final_result + + except Exception as e: + logger.error(f"❌ 차트 조회 실패 {stock_code}: {e}") + raise + + async def get_minute_chart( + self, + stock_code: str, + ref_time: str = "", + include_past: bool = True, + ) -> Dict[str, Any]: + """국내주식 분봉차트 (Redis 캐시)""" + try: + if not ref_time: + kst = pytz.timezone("Asia/Seoul") + ref_time = datetime.now(kst).strftime("%H%M%S") + + ref_bucket = ref_time[:4] # HHMM + cache_key = f"chart:minute:{stock_code}:{ref_bucket}" + + # 캐시 히트 + cached = await _cache_get(cache_key) + if cached is not None: + logger.debug(f"📦 [캐시 히트] {cache_key}") + return cached + + # KIS API 호출 + client = self.real_client or self.client + params = { + "FID_ETC_CLS_CODE": "", + "FID_INPUT_ISCD": stock_code, + "FID_INPUT_HOUR_1": ref_time, + "FID_PW_DATA_INCU_YN": "Y" if include_past else "N", + } + result, _ = await client.request( + "GET", + "/uapi/domestic-stock/v1/quotations/inquire-time-itemchartprice", + "FHKST03010200", + params=params, + ) + + # 캐시 저장 + await _cache_set(cache_key, TTL_MINUTE_CHART, result) + return result + except Exception as e: + logger.error(f"❌ 분봉 차트 실패 {stock_code}: {e}") + raise + + async def get_overseas_price(self, symbol: str, exchange_code: str = "NASD") -> Dict[str, Any]: + """해외주식 현재가""" + try: + client = self.real_client or self.client + result, _ = await client.request( + "GET", + "/uapi/overseas-price/v1/quotations/price", + "HHDFS00000300", + params={ + "AUTH": "", + "EXCD": exchange_code.upper(), + "SYMB": symbol.upper() + } + ) + return result + except Exception as e: + logger.error(f"❌ 해외주식 시세 실패 {symbol}: {e}") + raise + + async def get_orderbook(self, stock_code: str) -> Dict[str, Any]: + """호가 정보 조회 (10단계)""" + try: + client = self.real_client or self.client + result, _ = await client.request( + "GET", + "/uapi/domestic-stock/v1/quotations/inquire-asking-price-exp-ccn", + "FHKST01010200", + params={ + "FID_COND_MRKT_DIV_CODE": "J", + "FID_INPUT_ISCD": stock_code + } + ) + return result + except Exception as e: + logger.error(f"❌ 호가 조회 실패 {stock_code}: {e}") + raise + + async def get_volume_rank(self, market: str = "J") -> Dict[str, Any]: + """거래량 순위 조회""" + try: + client = self.real_client or self.client + result, _ = await client.request( + "GET", + "/uapi/domestic-stock/v1/quotations/volume-rank", + "FHPST01710000", + params={ + "FID_COND_MRKT_DIV_CODE": market, + "FID_COND_SCR_DIV_CODE": "20171", + "FID_INPUT_ISCD": "0000", + "FID_DIV_CLS_CODE": "0", + "FID_BLNG_CLS_CODE": "0", + "FID_TRGT_CLS_CODE": "111111111", + "FID_TRGT_EXLS_CLS_CODE": "000000", + "FID_INPUT_PRICE_1": "5000", + "FID_INPUT_PRICE_2": "", + "FID_VOL_CNT": "", + "FID_INPUT_DATE_1": "" + } + ) + return result + except Exception as e: + logger.error(f"❌ 거래량 순위 실패: {e}") + raise + + +# 싱글톤 +market_data_provider = MarketDataProvider() From 3baafd56e8bfc66cbbc979b0ee18542f0780ccc8 Mon Sep 17 00:00:00 2001 From: YoungWooSeo Date: Fri, 6 Mar 2026 10:45:51 +0900 Subject: [PATCH 4/6] refactor(phase1): Add backward compatibility adapter --- .../services/korea_investment_api_adapter.py | 106 ++++++++++++++++++ 1 file changed, 106 insertions(+) create mode 100644 backend/app/services/korea_investment_api_adapter.py diff --git a/backend/app/services/korea_investment_api_adapter.py b/backend/app/services/korea_investment_api_adapter.py new file mode 100644 index 0000000..1f8323e --- /dev/null +++ b/backend/app/services/korea_investment_api_adapter.py @@ -0,0 +1,106 @@ +""" +Korea Investment API Adapter +기존 코드와의 호환성을 위한 어댑터 + +기존: from app.services.korea_investment_api import korea_investment_api +새 구조: app.trading.모듈로 분리 + +이 파일은 기존 코드가 수정 없이 동작하도록 보장합니다. +""" +from typing import Dict, Any, Optional +import logging + +from app.trading.kis_client import kis_client, real_market_client +from app.trading.order_manager import order_manager +from app.trading.market_data import market_data_provider + +logger = logging.getLogger(__name__) + + +class KoreaInvestmentAPIAdapter: + """기존 API 인터페이스 어댑터 (Backward Compatibility)""" + + def __init__(self): + self.client = kis_client + self.order_mgr = order_manager + self.market_data = market_data_provider + + # 기존 속성 노출 + self.base_url = self.client.base_url + self.app_key = self.client.app_key + self.app_secret = self.client.app_secret + self.account_number = self.client.account_number + self.access_token = self.client.access_token + self.token_expires_at = self.client.token_expires_at + + @classmethod + def for_real_market_data(cls) -> "KoreaInvestmentAPIAdapter": + """실계좌 시세조회 전용""" + instance = cls() + instance.client = real_market_client + instance.market_data = market_data_provider # real_client 사용 + return instance + + # ── 주문 관련 (위임) ──────────────────────────────────────────── + async def place_order(self, stock_code: str, order_type: str, quantity: int, price: Optional[float] = None): + return await self.order_mgr.place_order(stock_code, order_type, quantity, price) + + async def cancel_order(self, order_id: str, quantity: int): + return await self.order_mgr.cancel_order(order_id, quantity) + + async def get_balance(self): + return await self.order_mgr.get_balance() + + async def place_overseas_order(self, symbol: str, order_type: str, quantity: int, price: float, exchange_code: str = "NASD"): + return await self.order_mgr.place_overseas_order(symbol, order_type, quantity, price, exchange_code) + + async def get_overseas_balance(self): + return await self.order_mgr.get_overseas_balance() + + # ── 시세/차트 관련 (위임) ───────────────────────────────────── + async def get_current_price(self, stock_code: str): + return await self.market_data.get_current_price(stock_code) + + async def get_daily_chart(self, stock_code: str, period: str = "D", limit: int = 240): + return await self.market_data.get_daily_chart(stock_code, period, limit) + + async def get_minute_chart(self, stock_code: str, ref_time: str = "", include_past: bool = True): + return await self.market_data.get_minute_chart(stock_code, ref_time, include_past) + + async def get_overseas_price(self, symbol: str, exchange_code: str = "NASD"): + return await self.market_data.get_overseas_price(symbol, exchange_code) + + async def get_orderbook(self, stock_code: str): + return await self.market_data.get_orderbook(stock_code) + + async def get_volume_rank(self, market: str = "J"): + return await self.market_data.get_volume_rank(market) + + async def get_stock_list(self, market: str = "J"): + return await self.market_data.get_volume_rank(market) + + # ── 기타 (호환성) ─────────────────────────────────────────────── + async def _get_access_token(self): + """Deprecated: 직접 호출 불필요 (client가 자동 관리)""" + return await self.client.get_access_token() + + async def _make_request(self, method: str, endpoint: str, tr_id: str, extra_headers: Optional[Dict] = None, **kwargs): + """Deprecated: 직접 request 호출""" + return await self.client.request(method, endpoint, tr_id, extra_headers, **kwargs) + + def get_monitor_stats(self): + """API 통계 (향후 monitoring.py로 이동 예정)""" + return {"message": "Monitoring moved to trading.monitoring module"} + + +# 싱글톤 인스턴스 - 기존 코드에서 그대로 사용 가능 +korea_investment_api = KoreaInvestmentAPIAdapter() + +try: + real_market_api = KoreaInvestmentAPIAdapter.for_real_market_data() +except Exception: + real_market_api = None + + +# Backward compatibility alias +KoreaInvestmentAPI = KoreaInvestmentAPIAdapter From a7eb07b860557438a4972debce20e715366bcd6a Mon Sep 17 00:00:00 2001 From: YoungWooSeo Date: Fri, 6 Mar 2026 10:46:07 +0900 Subject: [PATCH 5/6] refactor(phase1): Update trading module exports --- backend/app/trading/__init__.py | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/backend/app/trading/__init__.py b/backend/app/trading/__init__.py index 73896bf..adc09b4 100644 --- a/backend/app/trading/__init__.py +++ b/backend/app/trading/__init__.py @@ -8,10 +8,19 @@ Trading Engine Module - 장 스케줄 관리 """ +from app.trading.kis_client import KISClient, kis_client, real_market_client +from app.trading.order_manager import OrderManager, order_manager +from app.trading.market_data import MarketDataProvider, market_data_provider + __all__ = [ + # Classes "KISClient", - "WSClient", "OrderManager", - "WSManager", - "TradingScheduler", + "MarketDataProvider", + + # Singleton instances + "kis_client", + "real_market_client", + "order_manager", + "market_data_provider", ] From 30babd296383ab209a38688fc8118b76fa7e11a8 Mon Sep 17 00:00:00 2001 From: YoungWooSeo Date: Fri, 6 Mar 2026 10:47:00 +0900 Subject: [PATCH 6/6] docs(phase1): Add trading module documentation --- backend/app/trading/README.md | 173 ++++++++++++++++++++++++++++++++++ 1 file changed, 173 insertions(+) create mode 100644 backend/app/trading/README.md diff --git a/backend/app/trading/README.md b/backend/app/trading/README.md new file mode 100644 index 0000000..316ecdf --- /dev/null +++ b/backend/app/trading/README.md @@ -0,0 +1,173 @@ +# Trading Module + +한국투자증권 API를 활용한 주식 매매 실행 모듈 + +## 모듈 구조 + +``` +trading/ +├── __init__.py # 모듈 내보내기 +├── kis_client.py # KIS REST API 클라이언트 (토큰 관리) +├── order_manager.py # 주문 실행·취소·조회 +├── market_data.py # 시세·차트 조회 (Redis 캐시) +└── README.md # 문서 +``` + +## 사용 방법 + +### 1. KIS API 클라이언트 + +```python +from app.trading import kis_client + +# 토큰 자동 관리 (파일 캐싱) +token = await kis_client.get_access_token() + +# REST API 요청 (재시도 + 쓰로틀링 자동) +result, headers = await kis_client.request( + "GET", + "/uapi/domestic-stock/v1/quotations/inquire-price", + "FHKST01010100", + params={"FID_INPUT_ISCD": "005930"} +) +``` + +### 2. 주문 관리 + +```python +from app.trading import order_manager + +# 매수 주문 +result = await order_manager.place_order( + stock_code="005930", + order_type="BUY", + quantity=10, + price=75000 # None이면 시장가 +) + +# 주문 취소 +await order_manager.cancel_order( + order_id="0000123456", + quantity=10 +) + +# 계좌 잔고 조회 +balance = await order_manager.get_balance() +print(balance['output2']) # 보유 종목 목록 +``` + +### 3. 시세 데이터 + +```python +from app.trading import market_data_provider + +# 현재가 조회 +price = await market_data_provider.get_current_price("005930") +print(price['output']['stck_prpr']) # 현재가 + +# 일봉 차트 (Redis 캐시 5분) +chart = await market_data_provider.get_daily_chart( + stock_code="005930", + period="D", # D: 일봉, W: 주봉, M: 월봉 + limit=100 +) +for candle in chart['output2']: + print(candle['stck_clpr']) # 종가 + +# 분봉 차트 (Redis 캐시 1분) +minute_chart = await market_data_provider.get_minute_chart( + stock_code="005930", + ref_time="153000", # 15:30:00 기준 + include_past=True +) + +# 호가 조회 +orderbook = await market_data_provider.get_orderbook("005930") +print(orderbook['output1']['askp1']) # 매도 1호가 +print(orderbook['output1']['bidp1']) # 매수 1호가 +``` + +## 기존 코드 호환성 + +기존 `app.services.korea_investment_api` 사용 코드는 **수정 없이 동작**합니다: + +```python +# 기존 방식 (DEPRECATED, 하지만 여전히 동작) +from app.services.korea_investment_api import korea_investment_api + +result = await korea_investment_api.get_current_price("005930") +await korea_investment_api.place_order("005930", "BUY", 10, 75000) + +# 새 방식 (권장) +from app.trading import market_data_provider, order_manager + +result = await market_data_provider.get_current_price("005930") +await order_manager.place_order("005930", "BUY", 10, 75000) +``` + +→ `app.services.korea_investment_api_adapter.py`가 내부적으로 새 모듈로 위임하므로 기존 코드 수정 불필요 + +## 주요 기능 + +### KISClient +- ✅ 토큰 자동 관리 (파일 캐싱 23시간) +- ✅ 재시도 로직 (지수 백오프) +- ✅ 쓰로틀링 (초당 2회 기본) +- ✅ 동시 요청 수 제한 (Semaphore) +- ✅ 타임아웃 처리 + +### OrderManager +- ✅ 국내주식 매수/매도 +- ✅ 해외주식 매수/매도 +- ✅ 주문 취소 +- ✅ 계좌 잔고 조회 +- ✅ 실전/모의 자동 구분 + +### MarketDataProvider +- ✅ 현재가 조회 +- ✅ 일봉/주봉/월봉 차트 (Redis 캐시 5분) +- ✅ 분봉 차트 (Redis 캐시 1분) +- ✅ 호가 조회 +- ✅ 거래량 순위 +- ✅ 해외주식 시세 +- ✅ 페이지네이션 지원 + +## 설정 + +`backend/app/core/config.py`에서 설정 가능: + +```python +class Settings(BaseSettings): + # KIS API 설정 + KOREA_INVESTMENT_API_BASE_URL: str + KOREA_INVESTMENT_APP_KEY: str + KOREA_INVESTMENT_APP_SECRET: str + KOREA_INVESTMENT_ACCOUNT_NUMBER: str + + # 쓰로틀링 설정 + API_MIN_REQUEST_INTERVAL: float = 0.5 # 초당 2회 + API_MAX_CONCURRENT_REQUESTS: int = 5 + API_MAX_RETRIES: int = 3 + API_RETRY_DELAY: float = 1.5 + API_RETRY_BACKOFF: float = 2.0 + API_TIMEOUT: float = 30.0 +``` + +## Phase 1 리팩토링 완료 체크리스트 + +- [x] `trading/kis_client.py` 생성 (토큰 관리 + HTTP 요청) +- [x] `trading/order_manager.py` 생성 (주문 전담) +- [x] `trading/market_data.py` 생성 (시세 전담) +- [x] `services/korea_investment_api_adapter.py` 생성 (호환성) +- [x] 기존 API 엔드포인트 정상 동작 확인 필요 + +## 다음 단계 (Phase 2) + +- [ ] `strategy/` 모듈 구축 +- [ ] `BaseStrategy` 추상 클래스 +- [ ] 기존 전략 리팩토링 + +--- + +**작성일**: 2026-03-06 +**작성자**: 서영우