kis_bot/remove/legacy_root/MAIN_PY_STRUCTURE.md

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) - 전체 시스템 라이프사이클 기동

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

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

---

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

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

1. kiwoom_rest_api/cli/main.py:
   • 키움 REST API 래퍼의 CLI 엔트리포인트 (uvicorn으로 로컬 서버 실행)
2. 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 안전 정지 및 마감 알림 전송