커밋 1 — 실매 가격 TTL 구멍 (본체)

왜: 체결이 없어도 마지막가는 유지인데, TTL로 None 만들고 매도/EOD를 건너뛰어 8/5 돌파·금요일 leftover가 남음. 호가필터 TTL 구멍과 같은 병.

넣을 파일

신규: kis_trader/engine/live_sell_price.py
kis_trader/strategies/base.py (_ws_last_quote, _resolve_sell_price)
전략: momentum.py scalping.py tail_catch.py breakout.py range_break.py dart_strategy.py updow_strategy.py updown_feed.py us_momentum.py
WS: ws_manager.py kis_ws.py kiwoom_ws.py ls_ws.py kis_ws_overseas.py
kis_trader/web/live_config_schema.py (WS_PRICE_MAX_AGE_SEC 기본 0)
database.py (키 주석 + legacy/ sys.path)
kis_trader/execution/order_manager.py (잔고 있는데 40240000 ghost_purge 금지 — 같은 EOD 사고)
EOD가 min_hold에 안 막히게 손본 momentum_hts_logic.py / scalping_engine.py / tail_engine.py (이 대화에서 손본 부분만 확인 후)
문서: docs/like_mcp.md/db_erd.md code_architecture.md (가격 TTL 문구)
메시지 초안

fix: 매수·매도 현재가를 TTL로 버리지 않음 (마지막 RAM)
횡보·체결 공백을 죽은 캐시로 오인해 None 처리하면 손절·EOD가 스킵된다.
호가필터와 같이 나이는 무시하고 마지막 체결가를 유지한다. EOD는 매수가 폴백.
영향: 실매 O / 백테·옵투나 봉 경로 거의 무관 (엔진 식 변경 아님)

커밋 2 — 루트 정리 (remove/ vs legacy/)
왜: 루트 단독봇·테스트는 지울 보관함으로. 웹·알람이 아직 쓰는 모듈은 remove에 두면 나중에 폴더째 삭제 때 깨짐.

넣을 파일

이동: 미사용 → remove/legacy_root/ (래퍼, ETF/키움 옛봇, 테스트, kiwoom_rest_api 등)
이동: 사용 중 → legacy/ (holding_bot kis_holding_ver1 news_analyzer kis_long_ver1/2)
신규: kis_trader/utils/legacy_root.py legacy/README.md remove/README.md
import 경로: backtest_web.py mm_butler.py mm_remote.py updow_holding_cfg.py dbband_stock_cfg.py param_search_updow*.py dbband_param_search.py param_search_apply_snapshot.py verify_three_paths.py
docs/like_mcp.md/code_architecture.md 수동 노트
메시지 초안

chore: 미사용 루트는 remove/, 웹·알람 구모듈은 legacy/
remove는 나중에 통째 삭제 예정. holding_bot·news_analyzer·kis_long은
ensure_legacy_root로 legacy/만 본다.
빼기: scratch/set_ws_price_max_age_zero.py (일회성)

remove/legacy_root/MAIN_PY_STRUCTURE.md

@@ -0,0 +1,126 @@
+# 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 안전 정지 및 마감 알림 전송 |