whdwo798/Stock-trading-programming
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[2026-06-04] 문서 역할 재정리

Browse Source
This commit is contained in:
jongjae
2026-06-04 10:47:01 +09:00
parent d8690355e8
commit d4d7f31c65
3 changed files with 587 additions and 698 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+73 -113
View File
@@ -1,131 +1,91 @@
# 단타 자동매매 시스템 v3.0
# StockBot v3.0
기획서 v3.0 기준 / KIS Open API / Synology NAS Docker
AI: Claude Code/Codex headless (장 전 분석 + 장중 점검 + 장 후 피드백)
KIS Open API를 이용한 한국 주식 단타 자동매매 프로젝트입니다.
현재는 실거래 전 검증 단계로, 모의투자와 DRY_RUN 중심으로 신호 품질과
운영 안정성을 확인하고 있습니다.
## 운영 모드
## 기획 의도
| KIS_MOCK | DRY_RUN | 동작 |
|----------|---------|------|
| true | true | 신호 확인만 (주문 없음) ← 현재 |
| true | false | 모의투자 실제 주문 ← 3개월 검증 |
| false | false | 실거래 ← 조건 충족 후 |
이 프로젝트의 목표는 사람이 매일 반복해서 하던 단타 후보 탐색, 시장 분위기
판단, 진입/청산 기록, 장후 복기를 자동화하는 것입니다. 다만 실시간 매매 판단을
AI에게 맡기지는 않습니다. AI는 장 전/장중/장후 시장을 분석하고 제안서를 만드는
역할만 하고, 실제 진입과 청산은 코드에 고정된 규칙이 결정합니다.
## 빠른 시작
핵심 원칙은 세 가지입니다.
```bash
# 1. .env 설정
cp .env.example .env
# .env 열어서 KIS 키, Discord Webhook URL 입력
- 손절은 항상 최우선입니다.
- `14:50` 강제 청산은 변경하지 않습니다.
- 실거래 전에는 충분한 모의투자 기간과 성과 조건을 통과해야 합니다.
# 2. KIS 연결 테스트
pip install aiohttp python-dotenv
python test_connection.py
## 전체 흐름
# 3. 신호 확인 (DRY_RUN=true)
python app/main.py
하루 운영은 다음 흐름으로 설계되어 있습니다.
# 4. Docker 실행 (NAS)
docker-compose up -d
```
## 컨테이너 구성
| 컨테이너 | 역할 | 실행 시간 |
|---------|------|---------|
| stockbot-main | 매매 프로그램 | 상시 (09:00~15:00 활성) |
| stockbot-redis | 시세 캐시 | 상시 |
| stockbot-dashboard | Streamlit 모니터링 | 상시 (포트 8501) |
| claude-morning | 장 전 AI 분석 | 08:30 (실행 후 종료) |
| claude-evening | 장 후 AI 피드백 | 15:30 (실행 후 종료) |
| stockbot-killswitch | 긴급 청산 | 수동 트리거 |
## 긴급 청산
```bash
docker-compose --profile emergency up kill-switch
# 또는
python kill_switch/kill.py
```
# StockBot Current Status - 2026-06-04
This project is currently a paper-trading scalping bot with an AI training
pipeline in observation mode.
Active:
- Windows Task Scheduler operation for morning, midday, evening, watchdog, and training jobs.
- Approved `ENTRY_START = "09:20"` after the 2026-05-28 evening review.
- Applied `MAX_HOLD_MIN = 90`.
- `FORCE_EXIT = "14:50"` remains unchanged.
- `avoid_sectors` filtering is active in runtime entry checks.
- Re-entry controls are active:
- TIME/FORCE cooldown is measured from final exit time.
- TP final exits block same-day ticker re-entry.
- Re-entry control state is restored from today's DB rows after restart.
- Duplicate bot startup guards are active:
- `app/main.py` uses `logs/stockbot.lock`.
- `scripts/start_bot.py` kills existing `app/main.py` processes before starting one new bot.
- `scripts/run_morning.ps1` is the only post-morning bot startup owner.
- `/morning` must not call `/start-bot` or `scripts/start_bot.py`.
- KIS stability hardening is active:
- Mode-specific request spacing.
- Retry for transient KIS timeout/rate-limit price errors.
- DRY_RUN simulated fills reuse the current quote to reduce extra KIS calls.
- Daily settlement has a duplicate-summary guard.
- Entry snapshots for model training.
- Post-entry snapshots at 1m, 3m, 5m, and 10m.
- Bot-data export to `data/training_dataset.csv`.
- External daily/minute data collection for pretraining.
- External daily collection falls back to KIS when pykrx same-day data fails.
- KIS minute collection excludes ETF/ETN by default and collects multiple windows from 09:30 to 14:00.
- RandomForest-based training engine.
- Optional AI entry scoring when `models/scalping_model.joblib` exists.
- Latest successful training run: 2026-06-02 18:36.
- Latest training rows: 5,773 total, including 5,720 external pretraining rows and 53 bot-trade rows.
- Latest metrics: `label_stop_loss` ROC-AUC 0.896, `label_win` ROC-AUC 0.715.
- Latest daily review/proposal files exist through 2026-06-02; 2026-06-03 was a market holiday.
Not active yet:
- ML model scores do not block buys.
- ML model scores do not change position size.
- ML model scores do not override exits.
- Real-cash trading is not ready until fill, unfilled-order, and partial-fill handling is hardened.
Current operational notes:
- On 2026-06-04, duplicate morning execution happened before the `/morning` instruction fix. The next scheduled morning run should show one context run and one `scripts/start_bot.py` startup.
- KIS rate limits can still happen when multiple scripts/processes call KIS concurrently.
- The 2026-06-03 holiday training run logged a failure at the holiday-check step instead of a clean skip; inspect before relying on holiday automation noise level.
- Keep secrets out of tracked files and remote URLs. Prefer environment variables for Discord webhooks and credentials.
Daily schedule:
| Time | Task | Purpose |
| 시간 | 흐름 | 내용 |
|---|---|---|
| 08:15 | `StockBot_Morning` | Run `/morning`, build context, then `scripts/start_bot.py` starts exactly one bot |
| 09:00-15:10 | `StockBot_Watchdog` | Check/restart bot every 5 minutes |
| 11:20 | `StockBot_Midday` | Midday review and context update |
| 15:30 | `StockBot_Evening` | Daily review and proposal report |
| 16:00 | `StockBot_Training` | Collect data, export datasets, train model |
| 08:15 | 장 전 분석 | 뉴스, 수급, 업종 분위기를 분석해 `daily_context.json` 생성 |
| 08:30 | 봇 시작/준비 | 유니버스 선정, 목표가 계산, Discord 알림 |
| 09:00 | 오전 매매 | 변동성 돌파 조건과 AI 컨텍스트 필터를 함께 확인 |
| 11:20 | 장중 분석 | 오전 결과와 현재 시장을 비교해 `midday_context.json` 생성 |
| 14:00 | 신규 진입 종료 | 새 진입은 막고 보유 포지션 청산 감시만 계속 |
| 14:50 | 강제 청산 | 모든 포지션 정리 |
| 15:30 | 장후 복기 | 일일 리포트와 전략 제안서 작성 |
| 16:00 | 학습 파이프라인 | 거래 데이터와 외부 데이터를 모아 관찰용 모델 갱신 |
Useful commands:
## 현재 운영 상태
- 현재 모드: `KIS_MOCK=true`, `DRY_RUN=true`
- 전략: 변동성 돌파(`K=0.5`)
- 진입 시작: `09:20`
- 강제 청산: `14:50`
- DB: SQLite (`data/stockbot.db`)
- 알림: Discord Webhook
- AI/ML: 시장 분석과 관찰용 점수 기록까지만 사용
운영 모드는 아래처럼 나뉩니다.
| KIS_MOCK | DRY_RUN | 의미 |
|---|---|---|
| true | true | 신호 확인만 수행, 주문 없음 |
| true | false | 모의투자 주문 수행 |
| false | false | 실거래 주문 수행 |
현재 실거래는 승인되지 않았습니다.
## 주요 구성
```text
app/ 매매 봇, 전략, 리스크, KIS API, DB, 알림 코드
scripts/ 스케줄러, 봇 시작, 데이터 수집, 학습 스크립트
data/ 로컬 실행 데이터와 SQLite DB
logs/ 실행 로그
models/ 관찰용 ML 모델 산출물
reports/daily/ 장후 일일 리포트
reports/proposals/ 수동 승인이 필요한 전략 제안서
```
## 자주 쓰는 명령
```powershell
python -m pip install -r requirements.txt
powershell -ExecutionPolicy Bypass -File scripts\install_dependencies.ps1
powershell -ExecutionPolicy Bypass -File scripts\setup_scheduler.ps1
python test_connection.py
python app/main.py
python scripts\start_bot.py
powershell -ExecutionPolicy Bypass -File scripts\setup_scheduler.ps1
powershell -ExecutionPolicy Bypass -File scripts\run_training_pipeline.ps1
python scripts\export_training_dataset.py
python scripts\train_ai_model.py
Get-Content logs\morning.log -Tail 80
Get-Content logs\stockbot.log -Tail 80
```
Dependency portability:
- Root `requirements.txt` includes `app/requirements.txt`.
- `scripts/download_dependencies.ps1` downloads Windows/Python 3.11 wheels to `vendor/wheels`.
- `scripts/install_dependencies.ps1` installs from `vendor/wheels` first, then falls back to online pip.
- Raspberry Pi needs its own wheelhouse or online install because Windows wheels are not ARM/Linux compatible.
## 에이전트 운영 문서
---
- `AGENTS.md`: Codex가 읽는 운영 지침
- `CLAUDE.md`: Claude Code가 읽는 운영 지침
두 파일은 에이전트가 정확하게 행동하기 위한 상세 규칙입니다. 일반적인 프로젝트
개요는 이 README만 보면 됩니다.
## 주의사항
- `.env`, 토큰, DB, 로그 파일은 Git에 올리지 않습니다.
- 전략 파라미터 변경은 원칙적으로 장후 제안서에 기록하고 사람이 승인합니다.
- `FORCE_EXIT = "14:50"`은 절대 변경하지 않습니다.
- 실거래 전에는 모의투자 결과, 손실 제한, 주문 안정성 검증이 필요합니다.