🚀 KORStockScan V13.0 - 완전 자동화 멀티 엔진 퀀트 스나이퍼

KORStockScan은 키움증권 REST API와 머신러닝(Stacking Ensemble), 그리고 **생성형 AI(Gemini 2.5 Flash)**를 결합하여 주식 시장을 스캐닝하고, 실시간 웹소켓을 통해 최적의 타점을 잡아내어 완전 자동매매를 수행하는 지능형 퀀트 트레이딩 봇입니다.

최신 업데이트를 통해 기존 코스피 우량주 스윙 매매를 넘어, 코스닥 주도주(하이브리드)와 초단타 스캘핑까지 동시에 감시하는 **'3-Way 멀티 스레드 아키텍처'**로 진화했습니다.

특히, 시스템의 전두엽 역할을 하는 **'Gemini-Brain(ai_engine.py)'**이 도입되어, 단순한 조건 검색을 넘어 호가창의 뎁스(Depth)와 틱 체결 흐름을 AI가 실시간으로 판독합니다. 수급강도(VPW)라는 기계적 기준에 AI의 직관(Score)을 더한 동적 타점 제어(Dynamic Pullback Matrix) 시스템을 통해, 시장 상황에 맞춰 매수 그물의 깊이를 스스로 조절하는 진정한 의미의 무호흡 무인 매매를 집행합니다.

---

🛰️ 스캐너 엔진 비교 (Scanner Comparison)

시스템은 SniperRadar 모듈을 공유하지만, 시장의 특성과 매매 호흡에 따라 3가지의 독립적인 AI 스캐닝 엔진을 가동합니다. 모든 엔진은 **Gemini 2.5 Flash 기반의 AI 두뇌(ai_engine.py)**와 결합되어 있습니다.

구분	⚡ 초단타 스캘핑 + AI (Scalping)	🏢 코스피 AI 앙상블 (KOSPI)	🚀 코스닥 AI 하이브리드 (KOSDAQ)
감시 대상	시장 전체 (000: 코스피 + 코스닥)	코스피 대형/우량주 중심 (001)	코스닥 중소형/테마주 중심 (101)
스캔 주기	1분 주기 (초고속 틱/호가 탐색)	15분 주기 (추세 및 패턴 분석)	15분 주기 (수급 및 테마 분석)
분석 깊이	실시간 수급(VPW) + Gemini-Brain 틱 흐름 분석	기술적 지표(MACD/RSI) + AI 펀더멘털 판독	외국인/기관 수급 및 신용잔고 + AI 테마 판독
매수 타점	[스마트 눌림목] AI 점수 + 지수 연동 가변 타점 (-0.35% 등)	[스윙 타점] 1차 스캔 통과 + AI 확신도 80점 이상	[스윙 타점] 1차 스캔 통과 + AI 확신도 80점 이상
전략 태그	SCALPING_AI (지능형 초단타)	KOSPI_ML (안정형 스윙 전술)	KOSDAQ_ML (탄력형 스윙 전술)
매매 목표	+2.0% 익절 / -2.5% 칼손절	전략별 가변 익절 및 트레일링 스탑 적용	전략별 가변 익절 및 트레일링 스탑 적용
핵심 모듈	scalping_scanner.py	final_ensemble_scanner.py	kosdaq_scanner.py

※ Scalping 3.0: 지능형 타점 제어 시스템 (Dynamic Pullback Matrix) 스캘핑 모듈은 단순히 지정된 퍼센트(-0.5%)에서 기계적으로 대기하지 않습니다. 실시간 체결강도(VPW)와 Gemini-Brain이 산정한 **AI 확신도(0~100점)**를 융합하여, AI가 강하게 추천하는 종목은 얕은 눌림목(-0.1%)에서 공격적으로 낚아채고, 위험 요소가 감지된 종목(DROP)은 심해(-1.5%)로 그물을 내려 방어적으로 대응합니다.

---

✨ 핵심 기능 (Key Features)

1. SniperRadar (통합 정보국)

• 7개 API 입체 분석: 거래량 급증(ka10023), 프로그램 순매수(ka90008), 체결강도 추이(ka10046) 등 7개 API를 조합하여 세력의 진입 조짐을 포착합니다.
• 투망 & 현미경 전략: 시장 전체를 넓게 훑는 '투망' 단계와 개별 종목의 수급을 정밀 검증하는 '현미경' 단계를 거쳐 고확신 타점만 추출합니다.

2. AI 앙상블 판독 (KOSPI/KOSDAQ 스윙)

• Stacking Ensemble: XGBoost, LightGBM 등 4개 모델의 예측치를 메타 모델이 최종 통합하여 당일 상승 확률을 산출합니다.
• 데이터 통합: 실시간 일봉(OHLCV), 투자자별 순매수, 신용 잔고율 데이터를 결합하여 입체적인 차트 분석을 수행합니다.

3. 실시간 매매 엔진 (Sniper V2)

• 멀티 전략 대응: DB에 기록된 strategy 태그에 따라 초단타, 코스피 스윙, 코스닥 스윙 등 각기 다른 매매 룰을 적용합니다.
• 눌림목 자동 진입: 스캘핑 포착 시 현재가 대비 정확한 호가 단위를 계산하여 2호가 아래에 매수 대기 주문을 넣어 안전한 진입을 도모합니다.
• 성과 추적: 매수/매도가, 매매 시간, 수익률을 DB에 영구 기록하여 전략별 승률과 성과를 관리합니다.

🚀 주요 기능 (New Updates!)

🤖 AI 트레이딩 엔진 고도화

• Gemini 2.5 Flash 모델 탑재: 시장 상황에 대한 초고속 판단 및 종목 분석 수행.
• AI 섀도우 모드: 실매매 전 AI의 판단을 기록하고 검증하는 로직 안정화.

🧠 Gemini-Brain: 하이브리드 의사결정 및 리스크 관리 시스템

본 시스템의 가장 큰 특징은 단순한 지표 조건부 매매를 넘어, 생성형 AI(Gemini 2.5 Flash)가 호가창 뎁스(Depth)와 1분봉(Micro-VWAP 등)을 실시간으로 읽고 최종 매매 승인권을 행사한다는 점입니다. AI는 스나이퍼 엔진 내에서 두 가지 핵심 역할을 수행합니다.

• 🚫 AI 거부권 (Veto Power) 발동

  • 기존 퀀트 스캐너가 "수급 폭발"을 외치며 매수 사인을 내더라도, AI가 1분봉의 윗꼬리나 VWAP 이탈을 감지하여 하방 리스크가 크다고 판단(Score 40점 이하)하면 **즉각 매수 프로세스를 강제 종료(Veto)**합니다.
  • 세력의 '가짜 돌파(Bull Trap)' 및 '설거지 패턴'에 당하는 뇌동매매를 원천 차단하고 3분(180초)의 쿨타임을 부여합니다.

• 🎯 동적 타점 제어 (Dynamic Pullback Matrix)

  • 무사히 AI의 거부권을 통과한 종목에 대해서는, AI의 확신도(Score 0~100)와 실시간 체결강도(VPW)를 융합하여 매수 그물의 깊이를 스스로 조절합니다.

  • 강한 확신(BUY): 얕은 눌림목(-0.1%)에서 공격적으로 물량 확보

  • 보통 수급(WAIT): 기본 눌림목(-0.5%)에서 보수적으로 대기

  • 🏃‍♂️ 지능형 조기 청산 및 방어 (Smart Exit & Risk-Cut)

  • 매수 이후에도 AI 엔진은 15초 주기로 보유 종목의 1분봉 흐름과 실시간 체결강도를 감시합니다.

  • 조기 익절 (Take-Profit 조기화): 기계적 목표 수익률(+2.0%)에 도달하기 전이라도, 매수세가 둔화되고 고점 징후가 보이면(Score < 50) 수익권(+0.5% 이상)에서 욕심내지 않고 즉시 물량을 넘깁니다.

  • 지능형 칼손절 (Smart Stop-Loss): 기계적 손절선(-2.5%)을 터치하기 전이라도, 세력의 이탈이나 투매 징후가 포착되면(Score <= 35) 즉시 뼈를 깎아내는 손절을 감행하여 계좌를 방어합니다.

• 🛡️ 무결점 자동 전환 (Zero-Code Fallback System)

  • 구글 API 서버 장애나 일일 쿼터 소진으로 인해 AI가 응답하지 못할 경우, 시스템은 에러를 뿜으며 멈추지 않습니다.
  • AI가 기본값(50점)을 반환하면 시스템은 이를 "AI 판단 보류"로 인식하여 스마트 청산(Smart Exit) 로직을 부드럽게 우회(Bypass)합니다. 이후 봇은 즉각 감정을 배제한 '기계적 퀀트 매도 룰(시간/가격 타임아웃)'로 돌아가 매매를 무사히 마무리합니다.

🧠 AI 지능형 조기 청산 및 방어 시스템 (Smart Exit & Fallback)

KORStockScan의 Gemini-Brain은 단순히 진입(Buy) 타점만 잡는 것을 넘어, 주식을 보유한 순간부터 매도(Sell)할 때까지 전 구간에 걸쳐 실시간으로 개입하며 계좌를 방어합니다.

🩺 1. 실시간 모니터링 (15초 건강 검진)

• 스나이퍼 엔진이 주식을 매수(HOLDING 상태)하면, AI 엔진은 15초 주기로 최근 1분봉 흐름과 실시간 호가창 매물대를 다시 분석합니다.
• 현재 주가의 추가 상승 여력과 하방 리스크를 0~100점(Score)의 점수로 지속해서 재평가합니다.

🏃‍♂️ 2. 지능형 조기 익절 (Smart Take-Profit)

• 발동 조건: 현재 수익 중(+0.5% 이상) & AI 점수 50점 미만
• 동작 원리: 기계적 목표가(+2.0%)에 도달하지 않았더라도, AI가 호가창의 매수세 둔화나 차트상의 고점 징후(긴 윗꼬리 등)를 포착하면 욕심을 버리고 즉시 시장가로 익절하여 수익을 안전하게 확정 짓습니다.

🔪 3. 지능형 칼손절 (Smart Stop-Loss)

• 발동 조건: 현재 손실 중 & AI 점수 35점 이하 (DROP)
• 동작 원리: 기계적 손절선(-2.5%)까지 끌려가며 계좌가 녹아내리는 것을 방지합니다. 단순한 눌림목이 아닌 세력의 투매나 설거지 패턴으로 판단되면, 손실이 커지기 전에 뼈를 깎아내는 즉각적인 손절을 감행하여 치명상을 피합니다.

🛡️ 4. 무결점 안전장치 (Zero-Code Fallback Mechanism)

• 장애 대응: 구글 Gemini API의 일일 쿼터가 소진되거나 일시적인 통신 장애가 발생할 경우, 시스템이 멈추거나 오작동하지 않도록 완벽한 Fallback 구조가 설계되어 있습니다.
• 동작 원리: 통신 불가 시 AI 엔진은 기본값인 **50점**을 반환합니다. 50점은 조기 익절(< 50)과 조기 손절(<= 35) 조건을 모두 빗겨가는 '투명망토' 점수입니다.
• 결과: AI 개입 로직이 자연스럽게 우회(Bypass)되며, 스나이퍼는 즉각 감정을 배제한 기계적 퀀트 룰(목표가 도달, 손절가 터치, 장 마감 시간 초과 등)로 자동 전환되어 안전하게 매매를 마무리합니다.

⚡ 스마트 스캘핑 시스템 (Scalping 2.0)

• 수급강도(VPW) 연동: 거래량과 체결 강도에 따라 매수 눌림목 깊이를 자동으로 조절.
• 호가 단위(Tick) 최적화: 종목의 가격대별 호가 규격을 계산하여 최적의 체결 가격 산출.

🏄‍♂️ 5. 수익 극대화: AI 가변 트레일링 익절 (Dynamic Trailing Stop)

• 기계적 족쇄 해제 (Let it Run): 주가가 설정된 기본 목표 수익률(+2.0%)에 도달하더라도 무조건 매도하지 않습니다.
• 지능형 홀딩 (Smart Holding): AI가 실시간 호가창의 강력한 매수 벽 돌파와 1분봉의 상승 에너지를 감지하여 높은 확신도(Score >= 75)를 유지한다면, 매도를 보류하고 수익이 +3%, +5% 이상으로 극대화될 때까지 추세를 끝까지 추적합니다.
• 타점 최적화 익절: 상승 모멘텀이 꺾이거나 매도세가 출회되어 점수가 하락하는 순간, 가장 유리한 고점에서 즉각 시장가로 던져 수익을 최종 확정 짓습니다.
• 쿼터 안전장치 연동: AI 한도 초과 시(Score 50 반환) 트레일링 조건에서 자연스럽게 탈락하므로, 주식을 쥔 채 멈추지 않고 즉시 '기계적 2.0% 익절'로 부드럽게 복귀(Fallback)합니다.

---

🛠️ 시스템 안정성 개선

• DB 동기화 무결성: 매도 체결 영수증 처리 로직 개선으로 실시간 잔고와 DB 상태 불일치 해결.
• 권한별 알림 시스템: Admin 및 VIP 등급에 따른 차등 텔레그램 알림 발송.

---

📂 프로젝트 구조 (Project Structure)

/KORStockScan
├── src/
│   ├── bot_main.py             # 🤖 메인 컨트롤러 (시스템 가동 및 텔레그램 인터페이스)
│   ├── signal_radar.py         # 📡 SniperRadar (전체 스캐닝 스케줄 및 데이터 흐름 제어)
│   │
│   ├── ai_engine.py            # 🧠 [NEW] AI core (Gemini 2.5 Flash API 통신 및 프롬프트 관리)
│   ├── final_ensemble_scanner.py # 🔍 KOSPI 스윙 분석 (ai_engine 호출 및 기술적 지표 결합)
│   ├── kosdaq_scanner.py       # 🔍 KOSDAQ 하이브리드 AI 스캐너
│   ├── scalping_scanner.py     # 🔍 SCALPING 수급 급등주 추출 엔진
│   │
│   ├── kiwoom_sniper_v2.py     # 🔫 매매 집행 엔진 (Scalping 2.0: 수급 연동 스마트 매매)
│   ├── kiwoom_websocket.py     # 🔌 실시간 데이터 센터 (호가 수신 & '00' TR 체결 감시)
│   ├── kiwoom_orders.py        # 🛒 주문 통신 모듈 (REST API 기반 매수/매도 집행)
│   ├── kiwoom_utils.py         # 🛠️ 유틸리티 (get_smart_target_price: 호가/수급 최적화)
│   ├── db_manager.py           # 🗄️ SQLite 통합 관리 (상태 동기화 및 VIP 권한 관리)
│   └── constants.py            # 📏 시스템 상수 (매매 규칙 및 전략 파라미터 정의)
│
├── data/
│   ├── config_prod.json        # ⚙️ 설정 파일 (API 키, ADMIN_ID, 모델 설정)
│   ├── user_data.db            # 👤 사용자 DB (VIP 권한 및 텔레그램 유저 관리)
│   └── kospi_stock_data.db     # 📊 매매 DB (추천 히스토리, 수익률, 체결 기록)
│
├── README.md                   # 📝 프로젝트 문서 (AI 모델 사양 및 매매 로직 가이드)
└── .gitignore                  # 🙈 보안 파일 및 DB 캐시 제외 설정

---

⚙️ 설치 및 설정 (Installation & Setup)

1. 환경 준비

• OS: Windows 또는 Linux (키움증권 REST API 기반으로 OS 제약이 적습니다.)
• Python: 3.13 버전 이상 권장
• 데이터베이스: SQLite3 (기본 내장)

2. 패키지 설치

저장소를 복제하고 필요한 라이브러리를 설치합니다.

git clone [https://github.com/your-username/KORStockScan.git](https://github.com/your-username/KORStockScan.git)
cd KORStockScan
pip install -r requirements.txt

3. 시스템 가동

설정 파일(config_prod.json) 세팅 후, 전체 시스템 제어 센터인 bot_main.py를 실행하면 멀티 스캐너와 매매 엔진이 스레드 방식으로 동시에 가동됩니다.

1. 설정 파일 작성: data/config_prod.json 파일에 키움 API 앱키, 시크릿키, 텔레그램 토큰 등을 올바르게 입력합니다.
2. 통합 엔진 실행: 터미널에서 아래 명령어를 입력하여 시스템을 시작합니다.

   python src/bot_main.py

3. 가동 확인: 터미널에 [시스템] 정상거래일 - 스나이퍼 매매 엔진 가동 완료 등의 메시지가 뜨는지 확인합니다.

---

📊 데이터베이스 및 성과 관리

시스템은 모든 추천 이력과 매매 성과를 투명하게 관리하며, 전략별 승률 분석이 가능하도록 설계되었습니다.

• 통합 DB 관리: data/kospi_stock_data.db를 통해 모든 추천 이력, 매수/매도가, 수익률을 통합 관리합니다.
• 자동 스키마 최적화: 시스템 가동 시 strategy(전략 태그), sell_price(매도가), profit_rate(수익률) 등 필수 컬럼을 자동으로 검사하고 생성하여 DB 에러를 원천 차단합니다.
• 실시간 성적표: 매매 체결 시 수익률을 영구 기록하며, 텔레그램을 통해 성적표 리포트를 즉시 보고합니다.
• 중복 추천 방지: 동일 종목이 당일 여러 번 포착되더라도 already_picked 로직을 통해 중복 알림과 뇌동매매를 방지합니다.

---

🚀 Future Roadmap (Upcoming Features)

• 보조지표 앙상블 추가: 현재 VWAP 및 5-MA 중심의 스캘핑 타점에 RSI(14), MACD 하락 다이버전스 필터 추가 (1분봉 수집 한도 확장 필요)
• AI 동적 청산(Tightening): HOLDING 상태에서 AI 스코어 감쇠에 따른 가변적 익절/손절선 적용

---

⚠️ 면책 조항 (Disclaimer)

본 소프트웨어는 개인적인 투자 참고 및 알고리즘 트레이딩 학습 목적으로 제작되었습니다.

1. 투자 책임: 모든 투자 결정에 대한 최종 책임은 사용자 본인에게 있습니다. 제작자는 이 프로그램을 사용하여 발생한 어떠한 경제적 손실에 대해서도 법적 책임을 지지 않습니다.
2. 시스템 리스크: 주식 거래는 원금 손실의 위험이 매우 크며, 자동 매매 시스템의 예기치 못한 오류, 네트워크 장애, 또는 API 통신 지연으로 인해 손실이 발생할 수 있습니다.
3. 사전 테스트: 실투자 전에는 반드시 모의투자 환경에서 충분한 테스트를 거친 후 운용하시기 바랍니다.