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 +**작성자**: 서영우