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

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

---

## 1. 개요 및 역할 (Overview)

* **파일 위치**: [kis_trader/main.py](file:///home/hoon/kis_bot/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)

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