docs(phase1): Add trading module documentation

2026-03-06 10:47:00 +09:00
parent a7eb07b860
commit 30babd2963
1 changed files with 173 additions and 0 deletions
--- a/backend/app/trading/README.md
+++ 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  
+**작성자**: 서영우