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