docs: add KJB strategy design doc, implementation plan, and quant notes

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs/plans/2026-02-19-kjb-strategy-design.md

@@ -0,0 +1,122 @@
+# Kim Jong-bong (KJB) Strategy - Full System Design
+
+**Date**: 2026-02-19
+**Status**: Approved
+
+## Overview
+
+Implement the Kim Jong-bong short-term trading strategy from `quant.md` as a full system:
+backtesting, daily signal generation, portfolio management, and frontend dashboard.
+
+This strategy is fundamentally different from existing strategies (Quality, MultiFactor,
+ValueMomentum) which are periodic-rebalancing based. KJB is signal-based daily trading
+with individual position management, stop-losses, and trailing stops.
+
+## Trading Rules (from quant.md)
+
+### Universe
+- Market cap rank: 1-30 (large caps)
+- Daily trading value >= 200 billion KRW
+
+### Entry Signals (all must be true)
+- Relative Strength vs KOSPI > 100 (stock outperforming market over 10 trading days)
+- AND at least one of:
+  - Box breakout (close > 20-day high)
+  - Large bullish candle (daily return >= 5% AND volume >= 1.5x 20-day average)
+
+### Exit Rules
+- Stop-loss: -3% from entry price
+- Take-profit 1: +5% → sell 50% of position
+- Take-profit 2: +10% → sell remaining
+- Trailing stop: when +5%, move stop to entry price; when +10%, move stop to +5%
+
+### Portfolio Rules
+- Cash reserve: 30% (investable = total capital x 0.7)
+- Max positions: 10
+- Position size: equal weight (investable / max_positions)
+
+## Architecture
+
+### 1. Strategy Layer
+
+**`KJBStrategy(BaseStrategy)`** - `services/strategy/kjb.py`
+- Compatible with existing strategy pattern (returns `StrategyResult`)
+- Used for stock ranking by KJB criteria
+- Scores based on: relative strength, breakout proximity, volume trend
+
+**`KJBSignalGenerator`** - `services/strategy/kjb.py`
+- Separate class for daily signal generation
+- Input: stock ticker + price data
+- Output: buy/sell signals with entry, target, stop-loss prices
+- Used by: DailyBacktestEngine, daily scheduler job
+
+### 2. Daily Backtest Engine
+
+**`DailyBacktestEngine`** - `services/backtest/daily_engine.py`
+- New engine alongside existing `BacktestEngine`
+- Daily simulation loop (not rebalance-based)
+- Each day: check entry signals for universe, check exit conditions for positions
+- Uses `TradingPortfolio` for position management
+
+**`TradingPortfolio`** - `services/backtest/trading_portfolio.py`
+- Separate class from existing `VirtualPortfolio`
+- Supports: `enter_position()`, `exit_position()`, `partial_exit()`
+- Per-position tracking: stop_loss, target_price, trailing_stop
+- Cash reserve enforcement (30%)
+- Transaction recording with reasons
+
+### 3. Signal System
+
+**DB Model: `Signal`** - `models/signal.py`
+- Fields: date, ticker, signal_type (buy/sell/partial_sell), entry_price,
+  target_price, stop_loss_price, reason, status (active/executed/expired)
+
+**Scheduler Job: `kjb_daily_signal_job`** - `jobs/kjb_signal_job.py`
+- Runs daily at 18:00 KST (after price data collection)
+- Generates signals for all universe stocks
+- Saves to DB
+
+### 4. API Endpoints
+
+**Signal API** - `api/signal.py`
+- `GET /api/signal/kjb/today` - today's buy/sell signals
+- `GET /api/signal/kjb/history` - historical signals
+- `GET /api/signal/kjb/positions` - active positions with P&L
+
+**Strategy API additions:**
+- `POST /api/strategy/kjb` - run KJB ranking
+
+**Backtest additions:**
+- Existing backtest API works with strategy_type="kjb"
+
+### 5. Frontend
+
+- KJB signal dashboard page
+- Today's signals cards (buy/sell recommendations)
+- Active positions table (entry price, current price, P&L, stop-loss level)
+- Portfolio value chart
+
+## Files to Create
+
+| File | Purpose |
+|------|---------|
+| `services/strategy/kjb.py` | KJBStrategy + KJBSignalGenerator |
+| `services/backtest/daily_engine.py` | DailyBacktestEngine |
+| `services/backtest/trading_portfolio.py` | TradingPortfolio |
+| `models/signal.py` | Signal DB model |
+| `schemas/signal.py` | Signal Pydantic schemas |
+| `api/signal.py` | Signal API endpoints |
+| `jobs/kjb_signal_job.py` | Daily signal scheduler job |
+| Alembic migration | signals table |
+| Frontend pages | KJB dashboard |
+
+## Files to Modify
+
+| File | Change |
+|------|--------|
+| `services/backtest/engine.py` | Add "kjb" to `_create_strategy()` |
+| `models/__init__.py` | Register Signal model |
+| `api/__init__.py` | Register signal router |
+| `schemas/backtest.py` | Add "kjb" to strategy_type enum |
+| `jobs/scheduler.py` | Register KJB signal job |
+| `api/strategy.py` | Add KJB strategy endpoint |

quant.md

@@ -0,0 +1,439 @@
+# 김종봉 주식 전략 퀀트 구현 상세 가이드
+
+## 📌 전략 개요
+
+### 출처
+- **영상 1**: "이 방법만 알고 있으면 종잣돈 천만원으로 금방 1억 법니다" (GZw3wTgMTwE, 2023-08-09)
+- **영상 2**: "이 방법만 알고 있다면 종잣돈 천만원으로 금방 1억 법니다" (Ps9tzVhHpu0, 2024-01-30)
+- **채널**: 월급쟁이부자들TV
+- **전략가**: 김종봉
+
+### 핵심 철학
+- **목표 수익률**: 월 10% (연 약 120%)
+- **자금 증대 목표**: 1,000만원 → 1억원 (1년 내)
+- **투자 기간**: 단기~중기 (보유 기간 수일~수주)
+- **핵심 원칙**: "시장(코스피)을 이기는 종목"에만 투자
+
+---
+
+## 🎯 구체적 매매 규칙
+
+### 1. 초기 자금 및 포트폴리오 구성
+
+| 항목 | 기준 |
+|------|------|
+| **시드 머니** | 1,000만원 (초보자는 100만원 연습 추천) |
+| **분산 종목 수** | 5~10개 |
+| **종목당 투자금** | 100만원 (1,000만원 기준) 또는 5~10만원 (100만원 기준) |
+| **현금 비중** | 약 30% (하락장 대비) |
+| **리밸런싱 주기** | 3개월 (분기별 성과 검증) |
+
+### 2. 종목 선정 기준 (필수 필터)
+
+#### A. 유동성 필터
+```
+✅ 일 거래대금 >= 2,000억원 (2조 아님, 2천억)
+```
+
+**대상 종목 예시**:
+- 삼성전자
+- SK하이닉스
+- LG전자
+- LG이노텍
+- 네이버
+- 카카오
+- LG에너지솔루션
+
+#### B. 시가총액 필터
+```
+✅ 시가총액 순위: 1~30위 (대형주 중심)
+```
+
+#### C. 상대강도 필터 (핵심)
+```
+✅ 종목 수익률 > 코스피 수익률 (최근 2주~1개월)
+✅ 특히 삼성전자 > 코스피 일 때 시장 강세 신호
+```
+
+**구현 방법**:
+```python
+# 상대강도 지수 (Relative Strength Index vs Market)
+RS = (종목 수익률 / 코스피 수익률) * 100
+# RS > 100이면 시장 대비 강함
+```
+
+#### D. 차트 패턴 필터
+```
+✅ 장대양봉 출현 (전일 대비 5% 이상 상승 + 거래량 폭증)
+✅ 박스권 돌파 (직전 고점 갱신)
+✅ 상승 추세 중 조정 후 지지선 터치
+```
+
+**장대양봉 정의**:
+- 종가 >= 시가 + (고가 - 저가) × 0.7
+- 거래대금 >= 직전 20일 평균 × 1.5
+
+### 3. 진입 규칙
+
+#### 시나리오 작성 (필수)
+매매 전 반드시 기록:
+```
+1. 진입가: [예시] 삼성전자 72,000원
+2. 목표가: [예시] 75,600원 (+5%)
+3. 손절가: [예시] 69,840원 (-3%)
+4. 근거: 코스피 지지선 반등 + 삼성전자 박스권 상단 돌파
+```
+
+#### 진입 타이밍
+| 조건 | 설명 |
+|------|------|
+| **조건 1** | 코스피 3선(지지·저항·추세) 차트에서 지지선 근처 |
+| **조건 2** | 박스권 상단 돌파 후 재진입 (돌파 확인 1~2일 후) |
+| **조건 3** | 장대양봉 발생 다음날 시초가 근처 |
+| **진입 방식** | 지정가 주문 (고점 근처에서 대기) |
+
+### 4. 청산 규칙
+
+#### A. 익절 (Profit Taking)
+```
+✅ 1차 익절: +5% 도달 시 50% 물량 청산
+✅ 2차 익절: +10% 도달 시 나머지 50% 청산
+✅ 목표: 주당 5% 수익 (주 1~2회 매매)
+```
+
+#### B. 손절 (Stop Loss)
+```
+❌ 손절 기준: -3% ~ -10%
+❌ 원칙: 시나리오 이탈 시 즉시 손절
+❌ 예시: 진입가 72,000원 → 손절가 69,840원 (-3%)
+```
+
+#### C. 트레일링 스톱
+```
+- 5% 이상 수익 발생 시 손절선을 진입가(본전)로 상향
+- 10% 이상 수익 시 손절선을 +5% 지점으로 상향
+```
+
+### 5. 리스크 관리
+
+| 항목 | 기준 |
+|------|------|
+| **종목당 최대 손실** | -3% (초기 자본의 0.3%) |
+| **포트폴리오 최대 손실** | -10% (초기 자본 기준) |
+| **승률 목표** | 60% 이상 |
+| **손익비** | 1:1.5 이상 (손실 3% vs 수익 5%) |
+| **월간 목표 수익률** | 10% |
+| **연간 목표 수익률** | 120% (복리 고려 시 약 113%) |
+
+---
+
+## 🔧 퀀트 구현 상세
+
+### 필요 데이터
+
+#### 1. 시장 데이터
+- **코스피 지수**: 일봉 OHLCV (최소 1년 이상)
+- **삼성전자**: 일봉 OHLCV (선행지표로 활용)
+
+#### 2. 종목 데이터
+```python
+필수 컬럼:
+- 날짜 (Date)
+- 시가 (Open)
+- 고가 (High)
+- 저가 (Low)
+- 종가 (Close)
+- 거래량 (Volume)
+- 거래대금 (Value = Close × Volume)
+- 시가총액 (Market Cap)
+```
+
+#### 3. 데이터 소스
+- **한국거래소 API** (공식, 실시간)
+- **FinanceDataReader** (무료, Python 라이브러리)
+- **증권사 API** (키움, 이베스트 등, 실전 매매 시)
+- **야후 파이낸스** (yfinance, 해외 주식 포함)
+
+### 구현 단계
+
+#### Phase 1: 데이터 수집 및 전처리
+```python
+import pandas as pd
+import FinanceDataReader as fdr
+
+# 1. 코스피 지수
+kospi = fdr.DataReader('KS11', '2020-01-01')
+
+# 2. 시가총액 상위 30개 종목
+krx = fdr.StockListing('KRX')
+top30 = krx.nlargest(30, 'Marcap')
+
+# 3. 개별 종목 데이터
+stocks = {}
+for code in top30['Code']:
+    stocks[code] = fdr.DataReader(code, '2020-01-01')
+```
+
+#### Phase 2: 필터링 로직
+```python
+def filter_liquidity(df, threshold=200_000_000_000):
+    """거래대금 2000억 이상 필터"""
+    df['Value'] = df['Close'] * df['Volume']
+    return df[df['Value'] >= threshold]
+
+def relative_strength(stock_return, market_return):
+    """상대강도 계산"""
+    return (stock_return / market_return) * 100
+
+def detect_breakout(df, lookback=20):
+    """박스권 돌파 감지"""
+    df['Highest'] = df['High'].rolling(lookback).max()
+    df['Breakout'] = df['Close'] > df['Highest'].shift(1)
+    return df
+
+def detect_large_candle(df, threshold=0.05):
+    """장대양봉 감지 (5% 이상)"""
+    df['Daily_Return'] = df['Close'].pct_change()
+    df['Volume_Ratio'] = df['Volume'] / df['Volume'].rolling(20).mean()
+    df['Large_Candle'] = (df['Daily_Return'] >= threshold) & (df['Volume_Ratio'] >= 1.5)
+    return df
+```
+
+#### Phase 3: 신호 생성
+```python
+def generate_signals(stock_df, kospi_df):
+    """매수/매도 신호 생성"""
+    signals = pd.DataFrame(index=stock_df.index)
+    
+    # 상대강도
+    stock_ret = stock_df['Close'].pct_change(10)  # 2주
+    market_ret = kospi_df['Close'].pct_change(10)
+    signals['RS'] = (stock_ret / market_ret) * 100
+    
+    # 매수 신호
+    signals['Buy'] = (
+        (signals['RS'] > 100) &  # 시장 대비 강함
+        (stock_df['Breakout']) &  # 박스권 돌파
+        (stock_df['Large_Candle'])  # 장대양봉
+    )
+    
+    return signals
+```
+
+#### Phase 4: 백테스팅 엔진
+```python
+class KimJongBongStrategy:
+    def __init__(self, initial_capital=10_000_000):
+        self.capital = initial_capital
+        self.cash = initial_capital * 0.7  # 30% 현금 보유
+        self.positions = {}
+        self.max_stocks = 10
+        self.position_size = initial_capital / self.max_stocks
+        
+    def enter_position(self, code, price, date):
+        """진입"""
+        shares = int(self.position_size / price)
+        cost = shares * price
+        if cost <= self.cash:
+            self.positions[code] = {
+                'shares': shares,
+                'entry_price': price,
+                'entry_date': date,
+                'stop_loss': price * 0.97,  # -3%
+                'target': price * 1.05  # +5%
+            }
+            self.cash -= cost
+            return True
+        return False
+    
+    def exit_position(self, code, price, date, reason):
+        """청산"""
+        if code in self.positions:
+            pos = self.positions[code]
+            proceeds = pos['shares'] * price
+            self.cash += proceeds
+            profit = (price / pos['entry_price'] - 1) * 100
+            del self.positions[code]
+            return profit
+        return 0
+    
+    def check_exits(self, date, prices):
+        """익절/손절 체크"""
+        for code in list(self.positions.keys()):
+            pos = self.positions[code]
+            current_price = prices[code]
+            
+            # 손절
+            if current_price <= pos['stop_loss']:
+                self.exit_position(code, current_price, date, 'stop_loss')
+            
+            # 익절
+            elif current_price >= pos['target']:
+                self.exit_position(code, current_price, date, 'take_profit')
+```
+
+#### Phase 5: 성과 평가
+```python
+def calculate_metrics(returns):
+    """성과 지표"""
+    total_return = (returns + 1).prod() - 1
+    sharpe = returns.mean() / returns.std() * (252 ** 0.5)
+    max_dd = (returns.cumsum() - returns.cumsum().cummax()).min()
+    
+    return {
+        'Total Return': f"{total_return:.2%}",
+        'Sharpe Ratio': f"{sharpe:.2f}",
+        'Max Drawdown': f"{max_dd:.2%}",
+        'Win Rate': f"{(returns > 0).sum() / len(returns):.2%}"
+    }
+```
+
+---
+
+## 📊 백테스팅 파라미터
+
+### 권장 설정
+| 파라미터 | 값 | 설명 |
+|----------|-----|------|
+| **백테스팅 기간** | 2020-01-01 ~ 2024-12-31 | 최소 3년 이상 |
+| **초기 자본** | 10,000,000원 | 영상 기준 |
+| **리밸런싱** | 분기별 (3개월) | 성과 검증 및 종목 교체 |
+| **수수료** | 0.015% (매수) + 0.25% (매도, 세금 포함) | 실전 반영 |
+| **슬리피지** | 0.1% | 체결가 불리함 |
+| **벤치마크** | 코스피 지수 (KS11) | 비교 대상 |
+
+### 최적화 대상
+1. **상대강도 기간**: 10일 (2주) vs 20일 (1개월) vs 60일 (3개월)
+2. **손절 비율**: -3% vs -5% vs -10%
+3. **익절 비율**: +5% vs +7% vs +10%
+4. **종목 수**: 5개 vs 10개 vs 15개
+5. **현금 비중**: 20% vs 30% vs 50%
+
+---
+
+## 🚀 실전 적용 로드맵
+
+### Step 1: 백테스팅 (1~2주)
+- 과거 데이터로 전략 검증
+- 연평균 수익률, 최대 낙폭, 승률 확인
+- 벤치마크 대비 초과 수익 여부 평가
+
+### Step 2: 페이퍼 트레이딩 (1개월)
+- 실시간 데이터로 모의 투자
+- 신호 발생 빈도 및 정확도 체크
+- 감정 개입 없이 기계적 실행 연습
+
+### Step 3: 소액 실전 (3개월)
+- 100만원으로 시작
+- 5~10개 종목, 종목당 10~20만원
+- 매매 일지 기록 (진입/청산 근거, 수익률)
+
+### Step 4: 본격 운용 (6개월 이후)
+- 1,000만원 투입
+- 분기별 성과 리뷰
+- 전략 개선 (필터 추가, 파라미터 최적화)
+
+---
+
+## ⚠️ 주의사항
+
+### 전략의 한계
+1. **백테스팅 없음**: 영상은 실제 통계 검증 없이 경험 기반
+2. **생존 편향**: 성공 사례 중심, 실패 사례 미공개
+3. **시장 환경 의존**: 상승장에서 유리, 하락장에서 취약
+4. **거래 비용**: 잦은 매매 시 수수료+세금 누적
+
+### 리스크 관리 필수
+- **과최적화 주의**: 과거 데이터에만 맞춘 전략은 미래 실패
+- **레버리지 금지**: 신용/미수 사용 시 손실 확대
+- **분산 투자**: 한 종목에 30% 이상 투자 금지
+- **감정 통제**: 손절/익절 원칙 엄수
+
+---
+
+## 📦 필요 기술 스택
+
+### Python 라이브러리
+```bash
+pip install pandas numpy yfinance FinanceDataReader
+pip install backtrader vectorbt ta-lib
+pip install matplotlib seaborn plotly
+```
+
+### 개발 환경
+- **로컬**: Jupyter Notebook / VS Code
+- **클라우드**: Google Colab (무료) / AWS SageMaker
+- **데이터베이스**: SQLite (소규모) / PostgreSQL (대규모)
+
+### 자동매매 연동 (선택)
+- **증권사 API**: 키움증권 Open API, 이베스트투자증권 xingAPI
+- **프레임워크**: PyQt5 (키움), gRPC (이베스트)
+
+---
+
+## 📚 참고 자료
+
+### 추가 학습
+1. **책**: "퀀트 투자 무작정 따라하기", "파이썬을 이용한 금융 데이터 분석"
+2. **강의**: 패스트캠퍼스 퀀트 트레이딩, 인프런 주식 자동매매
+3. **커뮤니티**: 네이버 카페 "시스템트레이딩", GitHub quant 저장소
+
+### 관련 전략
+- **모멘텀 전략**: 과거 수익률 상위 종목 매수
+- **브레이크아웃**: 52주 신고가 돌파
+- **평균회귀**: 과매도 구간 매수
+
+---
+
+## ✅ 체크리스트
+
+### 구현 전 확인사항
+- [ ] 데이터 소스 확보 (최소 3년 일봉)
+- [ ] 백테스팅 환경 구축 (Python + 라이브러리)
+- [ ] 초기 자본 및 목표 수익률 설정
+- [ ] 리스크 허용 범위 결정 (최대 손실 -10%?)
+- [ ] 매매 일지 양식 작성
+
+### 실전 전 확인사항
+- [ ] 백테스팅 결과 만족 (연 10% 이상, 샤프 1 이상)
+- [ ] 페이퍼 트레이딩 1개월 이상
+- [ ] 손절 원칙 테스트 (감정 개입 없이 실행 가능?)
+- [ ] 증권사 계좌 개설 (API 사용 가능 여부 확인)
+- [ ] 세금 및 수수료 계산 완료
+
+---
+
+## 🎯 최종 목표
+
+| 기간 | 시드 | 목표 | 월 수익률 | 비고 |
+|------|------|------|-----------|------|
+| **0개월** | 1,000만원 | - | - | 시작 |
+| **3개월** | 1,000만원 | 1,300만원 | 10% | 1분기 |
+| **6개월** | 1,300만원 | 1,700만원 | 10% | 2분기 |
+| **9개월** | 1,700만원 | 2,200만원 | 10% | 3분기 |
+| **12개월** | 2,200만원 | **1억원** | 10% | 목표 달성 |
+
+**복리 효과 시뮬레이션**:
+```
+월 10% × 12개월 = 약 213% (단리)
+월 10% 복리 = (1.1)^12 - 1 = 약 213.8%
+1,000만원 × 3.138 = 3,138만원 (현실적 목표)
+```
+
+---
+
+## 💬 추가 문의사항
+
+구현 과정에서 필요한 사항을 알려주시면:
+1. **전체 Python 코드** (백테스팅 시스템)
+2. **단계별 모듈** (데이터 수집 → 신호 생성 → 백테스팅)
+3. **Jupyter Notebook** (인터랙티브 실습)
+4. **자동매매 연동** (증권사 API 통합)
+
+맞춤형으로 제공해 드리겠습니다.
+
+---
+
+**작성일**: 2026-02-19  
+**버전**: 1.0  
+**출처**: 김종봉 전략 유튜브 영상 (월급쟁이부자들TV)