auto-stock/backend/app/realtime/README.md

Realtime Module

WebSocket 기반 실시간 시세 수신 및 이벤트 처리 모듈

모듈 구조

realtime/
├── __init__.py              # 모듈 내보내기
├── websocket_client.py     # KIS WebSocket 클라이언트
├── event_handler.py        # 이벤트 핸들러 관리자
├── market_scheduler.py     # 장 스케줄 관리
├── examples.py             # 사용 예시
└── README.md

사용 방법

1. 기본 WebSocket 연결

from app.realtime import KISWebSocketClient, event_handler, EventType
from app.realtime.websocket_client import create_websocket_client

# 핸들러 등록
async def on_price_update(event_data):
    print(f"{event_data['stock_code']}: {event_data['current_price']}원")

event_handler.register(EventType.PRICE_UPDATE, on_price_update)

# WebSocket 연결
ws_client = create_websocket_client()
await ws_client.connect()

# 종목 구독
await ws_client.subscribe_price("005930")  # 삼성전자

# 메시지 수신 시작
await ws_client.listen()

2. 이벤트 핸들러

from app.realtime import event_handler, EventType

# 특정 이벤트 핸들러
async def handle_price_update(event_data):
    stock_code = event_data['stock_code']
    price = event_data['current_price']
    print(f"{stock_code}: {price}원")

event_handler.register(EventType.PRICE_UPDATE, handle_price_update)

# 글로벌 핸들러 (모든 이벤트 수신)
async def global_handler(event_type, event_data):
    print(f"[이벤트] {event_type.value}: {event_data}")

event_handler.register_global(global_handler)

# 핸들러 해제
event_handler.unregister(EventType.PRICE_UPDATE, handle_price_update)

3. 장 스케줄러

from app.realtime import market_scheduler, MarketStatus

# 현재 장 상태 확인
status = market_scheduler.get_current_status()
print(f"현재 장 상태: {status}")

# 장 개장 여부
if market_scheduler.is_market_open():
    print("장 개장 중")

# 다음 장 시작까지 남은 시간
seconds = market_scheduler.get_seconds_until_market_open()
print(f"장 시작까지 {seconds}초 남음")

# 콜백 등록
async def on_market_open():
    print("🔔 장 시작!")
    # WebSocket 연결, 구독 등

async def on_market_close():
    print("🔕 장 종료!")
    # WebSocket 연결 해제

market_scheduler.register_callbacks(
    on_open=on_market_open,
    on_close=on_market_close
)

# 스케줄러 실행
await market_scheduler.run()

4. 실시간 전략 실행

from app.realtime import event_handler, EventType
from app.strategy import strategy_manager
from app.trading import order_manager, market_data_provider

# 핸들러: 실시간 시세 → 전략 실행 → 주문
async def on_price_update(event_data):
    stock_code = event_data['stock_code']
    current_price = event_data['current_price']
    
    # 시장 데이터 구성
    market_data = {
        "current_price": current_price,
        "minute_chart": await market_data_provider.get_minute_chart(stock_code),
    }
    
    # 전략 실행
    signal = await strategy_manager.run_strategy(
        "DayTrading",
        stock_code=stock_code,
        market_data=market_data
    )
    
    # 신호 발생 시 주문
    if signal:
        await order_manager.place_order(
            stock_code=signal.stock_code,
            order_type=signal.signal_type.value,
            quantity=10,
            price=signal.price
        )

event_handler.register(EventType.PRICE_UPDATE, on_price_update)

5. 전체 시스템 통합

import asyncio
from app.realtime import event_handler, EventType, market_scheduler
from app.realtime.websocket_client import create_websocket_client
from app.strategy import strategy_manager
from app.strategy.strategies import DayTradingStrategy
from app.trading import order_manager, market_data_provider

# 1. 전략 등록
strategy = DayTradingStrategy()
strategy_manager.register_strategy(strategy)

# 2. 이벤트 핸들러
async def on_price_update(event_data):
    # ... 전략 실행 로직
    pass

event_handler.register(EventType.PRICE_UPDATE, on_price_update)

# 3. 장 스케줄러
ws_client = None

async def on_market_open():
    global ws_client
    ws_client = create_websocket_client()
    await ws_client.connect()
    
    # 관심 종목 구독
    for code in ["005930", "000660"]:
        await ws_client.subscribe_price(code)
    
    asyncio.create_task(ws_client.listen())

async def on_market_close():
    if ws_client:
        await ws_client.disconnect()

market_scheduler.register_callbacks(
    on_open=on_market_open,
    on_close=on_market_close
)

# 4. 실행
await market_scheduler.run()

주요 기능

KISWebSocketClient

• ✅ KIS API WebSocket 연결
• ✅ 실시간 현재가/호가 수신
• ✅ 체결 데이터 수신
• ✅ 종목 구독/구독해제
• ✅ 자동 재연결
• ✅ 이벤트 기반 데이터 전달

EventHandler

• ✅ 7가지 이벤트 타입
  • PRICE_UPDATE: 현재가 업데이트
  • ORDERBOOK_UPDATE: 호가 업데이트
  • EXECUTION: 체결 발생
  • ORDER_CONFIRM: 주문 확인
  • ERROR: 에러
  • CONNECTED: 연결
  • DISCONNECTED: 연결 해제
• ✅ 타입별 핸들러 등록
• ✅ 글로벌 핸들러 (모든 이벤트)
• ✅ 비동기 핸들러 실행
• ✅ 에러 핸들링

MarketScheduler

• ✅ 4가지 장 상태
  • PRE_MARKET: 장 전 (08:00~09:00)
  • MARKET_OPEN: 정규장 (09:00~15:30)
  • AFTER_MARKET: 장 후 (15:30~18:00)
  • MARKET_CLOSED: 휴장
• ✅ 장 시작/종료 콜백
• ✅ 남은 시간 계산
• ✅ 자동 상태 감지

이벤트 데이터 구조

PRICE_UPDATE

{
    "stock_code": "005930",
    "stock_name": "삼성전자",
    "current_price": 75000,
    "change_rate": 1.5,
    "volume": 1000000,
    "timestamp": datetime(...)
}

EXECUTION

{
    "order_id": "0000123456",
    "stock_code": "005930",
    "executed_price": 75000,
    "executed_quantity": 10,
    "timestamp": datetime(...)
}

설치 요구사항

pip install websockets

사용 예시 파일

상세한 예시는 examples.py 참고:

• 기본 실시간 시세 수신
• 실시간 전략 실행
• 장 스케줄러 활용
• 전체 시스템 통합

Phase 3 완료 체크리스트

• realtime/websocket_client.py 생성
• realtime/event_handler.py 생성
• realtime/market_scheduler.py 생성
• realtime/examples.py 생성
• README 문서 작성

다음 단계

• 기존 WebSocket 코드 마이그레이션
• API 엔드포인트 통합
• 프론트엔드 WebSocket 연결

---

작성일: 2026-03-06
작성자: 서영우