kis_trader/main.py 파일 구조 및 구동 메커니즘 분석

kis_trader/main.py 파일은 kis_bot 프로젝트의 메인 실행 엔트리포인트이자, 전체 자동매매 시스템의 공유 인프라 및 다중 전략 쓰레드를 총괄하는 통합 오케스트레이터(TradingOrchestrator) 역할을 담당합니다.

1. 개요 및 역할 (Overview)

파일 위치: kis_trader/main.py
실행 방식: python -m kis_trader.main
주요 역할:
1. 공유 인프라 관리: KIS API 클라이언트, 데이터베이스, 웹소켓(WS), 주문 관리자, 예수금 장부, 조건검색/랭킹 매니저, 서킷브레이커(MarketGuard) 초기화
2. 다중 전략 쓰레드 기동/감시: 전략별 독립 Thread 생성, 헬스체크, 비정상 종료 시 자동 재기동
3. 유니버스 동적 스위칭: 전략별 유니버스 소스(ranking, condition, kiwoom_condition, ls_condition) 매핑 및 런타임 제어
4. 자산 및 손익 추적: TTL 2초 캐시 기반 KIS 계좌 잔고 조회, 당일 시작 자산 baseline 기록, 봇 실현손익 및 평가손익 계산
5. 리포팅 및 알림: Mattermost/Telegram 연동 (기동, 09:00 장시작, 15:15 장마감 전, 15:35 최종 마감, 종료 알림)
6. 고아 잔고 복구 및 리스크 관리: 장마감 전/후 REST 잔고 ↔ DB 대조 복구 및 일일 익절/손절 가드 주입

2. 모듈 구성 및 의존성 (Module Structure)

graph TD
    Main[main.py: main / TradingOrchestrator] --> DB[database.db_manager: get_db]
    Main --> KIS[execution.kis_client: KISClient]
    Main --> Order[execution.order_manager: OrderManager]
    Main --> Ledger[execution.account_cash: AccountCashLedger]
    Main --> WS[network.ws_manager: WSManager]
    Main --> Condition[network.condition_manager / kiwoom / ls]
    Main --> Ranking[network.ranking_manager: VolumeRankManager]
    Main --> Guard[network.market_guard: MarketGuard]
    Main --> ProfitHalt[engine.daily_profit_halt: DailyProfitHaltGuard]
    Main --> Strategies[strategies: Scalping, TailCatch, Momentum, US_Momentum, Breakout, etc.]

3. 핵심 클래스: `TradingOrchestrator` 상세 분석

3.1 `init(self)` - 객체 생성 및 인프라 바인딩

클라이언트 분리 정책 (Market Data vs Trade):
- self.client: 주문 및 계좌 전용 (KIS_MOCK 환경변수 적용)
- self.market_client: 시세 및 조건검색/분봉 조회 전용 (모의 서버 500 에러 방지를 위해 실전 키 KIS_APP_KEY_REAL 우선 사용)
인프라 객체 생성:
- AccountCashLedger & OrderManager (실시간 예수금 추적 및 주문 집행)
- WSManager (국내 KIS 웹소켓)
- 해외(US) 실시간 웹소켓, 키움/LS 조건검색 및 시세 WS 검증기 핸들 선언
- OrderManager에 자산 요약(_asset_line_for_notify), 전략 손익(_strategy_daily_pnl_for_notify), 호가창 조회 프로바이더 주입

3.2 `start(self)` - 전체 시스템 라이프사이클 기동

WS 및 시세 망 기동: WSManager, 해외(US) WS, LS/키움 WS 기동
유니버스 매니저 기동: _start_universe_managers() 호출
시장 급락 가드 기동: MarketGuard 기동 및 bootstrap_sync() 실행 (서킷브레이커 동기화)
예수금 API 선동기화: _fetch_asset_snapshot(force=True)로 기동 직후 stale 데이터 차단
전략 쓰레드 등록 및 시작: _register_strategies()로 전략 인스턴스 생성 후 strat.start() (Thread 실행)
시작 자산 기록: 09:00 이후 최초 총자산을 DB kv_store에 저장하여 당일 baseline 확정
시작 알림 발송: Mattermost (sys_channel + stock) 및 Telegram으로 기동 메시지 전송
시그널 등록 및 메인 루프 진입: SIGINT, SIGTERM 핸들러 등록 후 _heartbeat_loop() 호출

3.3 `_register_strategies()` & `_setup_daily_profit_halt()` - 전략 등록 및 일일 익절 가드

STRATEGY_{SID}_ENABLED 환경변수에 따라 대상 전략 등록:
- SCALP (ScalpingStrategy)
- SHORT (TailCatchStrategy)
- MOMENTUM (MomentumStrategy)
- US_MOMENTUM (UsMomentumStrategy)
- BREAKOUT (BreakoutStrategy)
- RANGE_BREAK (RangeBreakStrategy)
- UPDOW (UpdowStrategy)
- DBBAND (DbBandStrategy)
- DART (DartStrategy)
DailyProfitHaltGuard 생성 후 모든 전략 쓰레드에 주입하여 일일 목표 수익 달성 시 자동 청산 및 신규 매수 중단 처리

3.4 `_heartbeat_loop(self)` - 메인 대기 및 주기적 모니터링

60초 주기 (Heartbeat & Thread Recovery):
- 모든 전략 쓰레드의 is_alive() 확인
- 비정상 종료된 전략 감지 시 _restart_dead()를 통해 새 인스턴스로 자동 재기동 및 알림
10초 주기 (Pending Fill Poll):
- order_mgr.poll_pending_fills()로 체결 대기 중인 미체결 주문 재조회
20초 주기 (Daily Report Tick):
- _daily_report_tick() 호출

3.5 `_daily_report_tick(self)` - 자산/시간 기반 자동 리포트 및 고아 복구

09:00 (장 시작 알림): 당일 1회 계좌 예수금, 주문 가능 금액, 활성 전략 리포트 발송
15:15 (장마감 전 현황): 당일 실현손익, 계좌 평가손익, 보유 종목 수 발송
15:35 (장마감 최종 보고): 당일 매매 건수, 입금 대비 누적 손익 리포트 발송
Pre-EOD & 15:36~16:00 (고아 잔고 복구):
- reconcile_orphan_positions()를 실행하여 REST 실잔고와 DB active_trades 불일치 자동 정합화 및 유령 데이터 정리

3.6 `_fetch_asset_snapshot()`, `_bot_daily_realized_pnl()` - 자산 연산

_fetch_asset_snapshot():
- inquire-balance 및 inquire-psbl-order API 호출
- 2초 TTL 캐시로 호출 폭주 방지
- ACCOUNT_CASH_BASIS (dnca, d2, ord_psbl, min) 설정에 따라 사용 가능 예수금 산출
_bot_daily_realized_pnl():
- DB trade_history에서 강제정리/외부매도를 제외한 당일 순실현손익 및 청산 건수 합산

3.7 `stop(self)` & `_on_signal()` - 안전 종료 (Graceful Shutdown)

모든 전략 쓰레드의 stop_loop() 호출 후 join(timeout=5) 수행
조건검색 매니저, 랭킹 매니저, 시세 WS, 키움/LS WS 정지
_build_shutdown_report()를 통해 최종 계좌/자산 상태를 정리하여 Mattermost/Telegram으로 발송 후 안전하게 프로세스 종료

4. 기타 프로젝트 내 `main.py` 파일 참고

본 프로젝트에는 kis_trader/main.py 외에 아래의 main.py 파일들이 존재합니다:

kiwoom_rest_api/cli/main.py:
- 키움 REST API 래퍼의 CLI 엔트리포인트 (uvicorn으로 로컬 서버 실행)
sample_python/main.py:
- LS증권 샘플 파이썬 연동 코드

5. 요약 (Summary Table)

주요 메서드	주기 / 실행 시점	역할 및 비고
`TradingOrchestrator.start()`	기동 시	WS, 매니저, 가드, 전략 쓰레드 초기화 및 실행
`_register_strategies()`	기동 시	active 전략 스위치 확인 후 전략 인스턴스 등록
`_heartbeat_loop()`	상시 (1s sleep)	쓰레드 헬스체크(60s), 미체결 폴링(10s), 리포트 틱(20s)
`_restart_dead()`	전략 죽었을 때	동일 전략 객체 re-instantiate 및 자동 재기동
`_daily_report_tick()`	20s 주기 검사	09:00 장시작 / 15:15 장마감전 / 15:35 마감 최종 / 고아복구
`_fetch_asset_snapshot()`	필요 시 (TTL 2s)	KIS 잔고/주문가능 금액 조회 및 캐싱
`stop()`	종료 신호 수신 시	쓰레드/WS 안전 정지 및 마감 알림 전송

7.8 KiB Raw Blame History

kis_trader/main.py 파일 구조 및 구동 메커니즘 분석

1. 개요 및 역할 (Overview)

2. 모듈 구성 및 의존성 (Module Structure)

3. 핵심 클래스: TradingOrchestrator 상세 분석

3.1 __init__(self) - 객체 생성 및 인프라 바인딩

3.2 start(self) - 전체 시스템 라이프사이클 기동

3.3 _register_strategies() & _setup_daily_profit_halt() - 전략 등록 및 일일 익절 가드

3.4 _heartbeat_loop(self) - 메인 대기 및 주기적 모니터링

3.5 _daily_report_tick(self) - 자산/시간 기반 자동 리포트 및 고아 복구

3.6 _fetch_asset_snapshot(), _bot_daily_realized_pnl() - 자산 연산

3.7 stop(self) & _on_signal() - 안전 종료 (Graceful Shutdown)

4. 기타 프로젝트 내 main.py 파일 참고