# StockBot v3.0 종합기획서

> 최종 수정: 2026-05-27  
> 현재 인프라: 로컬 Windows 작업 스케줄러  
> 이전 예정 인프라: Synology NAS Docker  
> 현재 운영 모드: 모의투자 / DRY_RUN 중심  
> 언어: Python 3.11  
> API: KIS Open API  
> DB: SQLite  
> 알림: Discord Webhook  
> AI: Claude/Codex headless 자동 분석

---

## 0. 핵심 원칙

1. 진입과 청산은 코드가 결정하고, AI는 시장 리뷰와 제안만 담당한다.
2. 손절은 AI 판단과 무관하게 항상 우선한다.
3. `FORCE_EXIT = "14:50"`은 절대 변경하지 않는다.
4. 실거래 전환은 모의투자/드라이런 검증 후 수동 승인한다.
5. 전략 파라미터 변경은 근거를 남기고 승인 후 반영한다.
6. `.env`는 Git에 올리지 않는다.

---

## 1. 현재 구현 상태

| 항목 | 현재 상태 |
|------|-----------|
| 운영 방식 | 로컬 Windows 작업 스케줄러 |
| 봇 실행 | `app/main.py` |
| 전략 | 변동성 돌파 `K=0.5` |
| 시세 수집 | KIS REST 폴링 중심 |
| WebSocket | 차기 과제 |
| Redis | 차기/NAS Docker 과제 |
| DB | `data/stockbot.db` SQLite |
| 학습 데이터 | `entry_snapshots`, `post_entry_snapshots` |
| ML 모델 | 관찰 모드, 진입 차단/수량 조절에는 미사용 |
| 복구 설치 | `Restore_StockBot.bat` |

---

## 2. 현재 전략 파라미터

현재 기준 파일: `app/config.py`

```python
STRATEGY_K    = 0.5
ENTRY_START   = "09:15"
ENTRY_END     = "14:30"
FORCE_EXIT    = "14:50"

TP1_PCT       = 0.020
TP1_RATIO     = 0.70
TP2_PCT       = 0.025
SL_PCT        = 0.020
MAX_HOLD_MIN  = 120

TICKER_REENTRY_COOLDOWN_MIN = 60

POS_SIZE_PCT  = 0.20
MAX_POSITIONS = 2
DAILY_SL_PCT  = 0.03
CONSEC_LOSS   = 3

ENTRY_LIMIT_ENFORCE = False
MAX_DAILY_ENTRIES = 30
MAX_HOURLY_STOP_LOSS = 4
ENTRY_PAUSE_WINDOWS = (
    ("11:00", "11:20"),
    ("14:00", "15:30"),
)

AI_CONTEXT_PATH = "data/daily_context.json"
AI_MIN_SCORE    = 40
AI_BOOST_MULTI  = 1.5
```

### 원 기획 대비 변경된 전략

| 항목 | 원 기획 | 현재 구현 | 상태 |
|------|---------|-----------|------|
| 진입 시작 | 09:00 | 09:15 | 2026-05-27 승인 적용 |
| TP1 | +2%, 50% 매도 | +2%, 70% 매도 | 변경됨 |
| TP2 | +3% 전량 | +2.5% 전량 | 변경됨 |
| SL | -1.5% | -2.0% | 변경됨 |
| L3 | 3연속 손절 시 당일 중단 | L3-B 포지션 축소 | 변경됨 |
| 동일 종목 재진입 | 없음 | 60분 쿨다운 | 추가됨 |
| 신규 진입 차단 | 14:30 | 14:00 이후 차단 | 구현상 강화 |
| 강제청산 | 14:50 | 14:50 | 유지 |

---

## 3. 리스크 관리

### L1-L5

| 레벨 | 조건 | 현재 동작 |
|------|------|-----------|
| L1 | 개별 포지션 손절 | 즉시 손절 |
| L2 | 일일 손실 -3% | 신규 매매 중단 |
| L3-B | 연속 손절 | 포지션 크기 단계 축소 |
| L4 | 주간 손실 -7% | 중단 |
| L5 | 월간 손실 -15% | 전략 폐기 및 재검토 |

### L3-B 포지션 배율

| 연속 손절 | 포지션 배율 |
|-----------|-------------|
| 0회 | 1.0 |
| 1회 | 0.7 |
| 2회 | 0.5 |
| 3회 이상 | 0.3 |

익절 시 연속 손절 카운트는 한 단계만 회복한다.

---

## 4. AI 역할

AI는 두 종류로 나뉜다.

### 4.1 일일 AI 컨텍스트

`data/daily_context.json`은 실제 진입 필터에 사용된다.

적용 항목:

- `trade_allowed=false`면 신규 진입 차단
- `blacklist_tickers`는 진입 차단
- `avoid_sectors`는 섹터 회피
- `boosted_tickers`는 포지션 배율 가산
- `position_size_multiplier`는 수량 계산에 반영

### 4.2 ML 모델

`models/scalping_model.joblib`이 있으면 진입 시점의 점수를 계산하고 저장한다.

현재 동작:

- `entry_snapshots.ai_win_score` 저장
- `entry_snapshots.ai_stop_loss_score` 저장
- `entry_snapshots.ai_model_version` 저장
- 로그에 `AI_SCORE` 출력
- 매매 차단이나 수량 조절에는 사용하지 않음

즉, ML은 현재 관찰 모드다.

---

## 5. 하루 자동화 흐름

| 시간 | 작업 | 설명 |
|------|------|------|
| 08:15 | `StockBot_Morning` | `/morning`, 뉴스/시장 분석, `daily_context.json` 생성 |
| 08:30 | 봇 컨텍스트 로드 | AI 컨텍스트 로드, 유니버스 갱신 |
| 08:50 | 목표가 계산 | 전일 고저와 당일 시가 기반 |
| 09:00 | 매매 루프 시작 | 실제 신규 진입은 `ENTRY_START=09:20` 이후 |
| 09:00-15:05 | `StockBot_Watchdog` | 5분마다 봇 생존 감시, 15:10 결산 직후 재시작 금지 |
| 11:00 | 점심 컨텍스트 대기 | `midday_context.json` 전까지 신규 진입 중지 |
| 11:20 | `StockBot_Midday` | `/midday`, 점심 세션 조건 생성 |
| 14:00 | 신규 진입 중단 | 보유 포지션 청산 체크는 계속 |
| 14:50 | 강제 전량 청산 | 절대 불변 |
| 15:10 | 일일 결산 | DB 저장 및 Discord 알림 |
| 15:30 | `StockBot_Evening` | `/evening`, 분석 및 제안서/리포트 생성 |
| 16:00 | `StockBot_Training` | 학습 데이터 수집 및 모델 학습 |

---

## 6. 작업 스케줄러

등록 스크립트: `scripts/setup_scheduler.ps1`

| 작업명 | 시간 | 스크립트 |
|--------|------|----------|
| `StockBot_Morning` | 08:15 | `scripts/run_morning.ps1` |
| `StockBot_Midday` | 11:20 | `scripts/run_midday.ps1` |
| `StockBot_Evening` | 15:30 | `scripts/run_evening.ps1` |
| `StockBot_Training` | 16:00 | `scripts/run_training_pipeline.ps1` |
| `StockBot_Watchdog` | 09:00-15:05, 5분마다 | `scripts/run_watchdog.ps1` |

모든 실행 스크립트는 프로젝트 내부 `.venv`의 Python을 우선 사용한다.
08:50 이후 재시작 시 봇은 목표가를 즉시 재계산하며, KIS 시가가 `0`이면 목표가 계산에서 제외한다.

---

## 7. 데이터와 학습

### 주요 테이블

| 테이블 | 목적 |
|--------|------|
| `trades` | 매매 이력 |
| `daily_summary` | 일일 결산 |
| `positions` | 보유 포지션 복구 |
| `ai_context_log` | 일일 AI 컨텍스트 기록 |
| `entry_snapshots` | 진입 시점 특징과 AI/ML 점수 |
| `post_entry_snapshots` | 진입 후 60/180/300/600초 샘플 |

### 학습 파이프라인

| 스크립트 | 목적 |
|----------|------|
| `scripts/collect_daily_features.py` | 일별 시장 특징 수집 |
| `scripts/collect_minute_data.py` | KIS 분봉 데이터 수집 |
| `scripts/export_training_dataset.py` | 실제 봇 거래 데이터셋 export |
| `scripts/build_external_training_dataset.py` | 외부 분봉 기반 사전학습 데이터셋 생성 |
| `scripts/train_ai_model.py` | 모델 학습 |

출력:

- `models/scalping_model.joblib`
- `models/scalping_model.metrics.json`

---

## 8. Discord 알림

| 이벤트 | 알림 |
|--------|------|
| Morning 분석 | 시장 분위기, 섹터, boosted/blacklist |
| 매수 | 종목, 수량, 가격, AI boosted 여부 |
| TP1 | 1차 익절 |
| TP2 | 2차 익절 |
| SL | 손절 |
| Force exit | 14:50 강제청산 |
| Daily summary | 15:10 결산 |
| Evening 분석 | 일일 분석과 제안 |
| Risk | L2/L4/L5 경고 |

Discord 요청에는 `User-Agent: DiscordBot (stockbot, 1.0)` 헤더를 포함한다.

---

## 9. 복구 설치

포맷 후 복구용 실행 파일:

```text
Restore_StockBot.bat
```

복구 절차:

1. `stockbot_v3` 전체 폴더를 압축해 보관한다.
2. 포맷 후 압축을 푼다.
3. `Restore_StockBot.bat`를 관리자 권한으로 실행한다.

복구 스크립트가 수행하는 작업:

- Git 설치 확인/설치
- Node.js 설치 확인/설치
- Python 3.11 설치 확인/설치
- `.venv` 생성
- `vendor/wheels` 기반 Python 라이브러리 설치
- wheelhouse가 없거나 `-OnlinePip` 사용 시 온라인 pip 설치
- Claude CLI/Codex CLI 설치 시도
- 스케줄러 재등록
- 기본 Python 의존성 import 확인

반드시 별도 보관해야 할 민감 파일:

- `.env`
- `data/stockbot.db`
- 필요한 경우 `models/`

`.env`는 Git에 올리지 않는다.

---

## 10. 현재 운영 리스크

1. KIS minute-bar endpoint는 실응답 로그 검증이 더 필요하다.
2. KIS REST 요청 제한 초과와 타임아웃이 장초반에 발생할 수 있다.
3. WebSocket/Redis 기반 실시간 구조는 아직 미완성이다.
4. 실거래 전환 전에는 체결, 부분체결, 미체결, 취소/정정, 재시작 복구 로직이 더 필요하다.
5. 초반 09:20 이후에도 손실 집중이 반복되는지 추가 검증이 필요하다.
6. `AI_RISK_SL_MAP`의 한글 키 인코딩은 점검이 필요하다. 정상 risk level과 매핑되지 않으면 리스크별 SL 조정이 무력화될 수 있다.
7. 기존 로그와 일부 문서는 인코딩 깨짐이 남아 있어 장기적으로 정리해야 한다.

---

## 11. 최근 제안과 상태

파일: `reports/proposals/2026-05-27_strategy_proposal.md`

| 제안 | 상태 |
|------|------|
| `ENTRY_START` 09:05 -> 09:15 | 승인 및 적용 |
| `ENTRY_START` 09:15 -> 09:20 | 승인 및 적용 |
| 장초반 포지션 축소 | 보류 |
| 시간대별 SL 강화 | 보류 |

`ENTRY_START=09:20` 변경 후 최소 5거래 이상 관찰한 뒤 다음 조정을 판단한다.

---

## 12. 실거래 전환 조건

전부 충족해야 한다.

| 조건 | 기준 |
|------|------|
| 누적 운영 | 30거래일 이상 |
| 승률 | 최근 30일 > 48% |
| MDD | 최근 30일 < -10% |
| 샤프지수 | 최근 30일 > 1.0 |
| L3-B 최소배율 도달 | 월 2회 이하 |

전환 방법:

```text
KIS_MOCK=false
DRY_RUN=false
```

단, 현재는 실거래 승인 상태가 아니다.

---

## 13. 다음 개발 과제

우선순위:

1. `AI_RISK_SL_MAP` 인코딩/키 매핑 점검
2. KIS API rate-limit 완화
3. KIS minute-bar 실응답 검증
4. 장초반 09:20 이후 손익 데이터 축적
5. WebSocket 시세 구조 도입
6. 실거래용 주문 복구/부분체결/미체결 처리 강화
7. NAS Docker 이전

---

## 14. 절대 금지

- `FORCE_EXIT = "14:50"` 변경 금지
- 손절 우선순위 하향 금지
- `.env` Git 커밋 금지
- AI/ML 모델이 검증 없이 실시간 청산을 방해하는 구조 금지
- 실거래 모드 임의 전환 금지