shuim
1b9257c4d2
## 배경 "전략이 혼란스럽고 현재와 맞지 않는다"를 조사한 결과, 전략 설계가 아니라 전략을 검증했다는 도구와 파라미터 소스가 어긋나 있었다. ## 파라미터 소스 단일화 - 우선순위가 adaptive > strategy_cfg(DB) > config.py 인데 문서는 맨 마지막인 config.py 를 기술하고 있었다. 11곳이 불일치(BULL RSI 46 vs DB 30, SL -7% vs -6%). - DEFAULT_PARAMS 를 config.py 에 정합 + alembic 0012 로 기존 DB 행 갱신 (운영자가 UI 로 바꾼 값은 보존, 옛 기본값과 같은 행만 갱신, 테이블 가드·멱등) ## 백테스트를 실전 로직에 정합 - calculate_adx_simple 이 정확히 period 배(14.0×) 발산 → Aggressive 게이트 `ADX>25` 가 전 레짐 100% 통과. 전환 빈도 5.6%→2.0%(-65%), 성과 상방 편향 - 백테스트 RSI 는 SMA, 실전은 Wilder → 진입 판정 10~11% 불일치 - us_backtest_engine RSI 1봉 지연 제거 (룩어헤드 없음을 절단 테스트로 증명) - backend/backtest_results/ 25건은 폐기 대상 (§8.4) ## 리스크 가드 복원 - 4% 절대 상한이 try 블록 안에 있어 예외 시 적응형 6~7% 가 통과 → try 밖으로 - 청산을 매수보다 먼저 평가 (보유 종목이 추천에 들면 손절 대신 물타기가 나갔다) - 리스크 가드 4개를 매수 전용화 → MDD -10%·보유한도 도달 시에도 손절 작동 - MDD 갱신 5회 연속 실패 시 신규 진입 차단 fail-safe (청산은 계속 허용) - 스윙 청산이 DT 보유분까지 매도하던 문제, sell_pct 기준 혼재 정정 ## 죽은 코드 제거 (2,695줄) - short_term_strategy, kosdaq_scanner, app/strategy/ 패키지 - app/trading/ + korea_investment_api_adapter (real_market_api 정본은 korea_investment_api.py:1482, adapter 는 import 0건) ## 지표·사이징 단일화 (수치 무변경 증명) - indicators_core.py: 3,274건 비교 최대 오차 0.000e+00 - sizing_core.py: 42,105건 비교 불일치 0 - 미국 전략 상수 13개 config 편입 (hex 까지 동일, 3,168 케이스 전수 비교) ## 테스트 안전 (실 KIS 호출 차단) - 유닛 테스트가 실제 KIS 에 매도 주문을 2회 전송하고 있었다. 리팩터링이 close_stale_positions 의 대상을 _execute_exit → _execute_exit_stale 로 바꿨는데 목이 전자에 걸려 빗나갔다. test_api_endpoints 도 캡처된 싱글톤 참조 누수로 실제 잔고 조회를 타 141초를 소비했다. - backend/tests/conftest.py 신설: 주문·토큰·시세·잔고를 호출 즉시 예외로 차단. 예외는 BaseException 파생(프로덕션 except Exception 폴백에 삼켜지지 않게), 클래스 메서드에 적용(캡처된 참조까지 덮음), DATABASE_URL `_test` 가드 강제 - 전체 유닛 스위트: 365초/6 failed → 11.8초/0 failed (소켓 차단 하 559 passed) ## 신규 (둘 다 플래그 OFF, 백테스트 미검증) - range_trading_strategy.py — SIDEWAYS 담당 전략이 없던 빈 칸. 미배선 - check_bear_buy_signal_v2 — BEAR 4중 AND(발화율 2.3%) → 점수제(12.4%) ## 문서 - CLAUDE.md 를 실제 코드 기준으로 재작성. §0 파라미터 우선순위, §4.1 테스트 규약, §6.4 문서화되지 않았던 진입 차단 게이트 9종, §8.4 백테스트 폐기 근거, §8.5 미해결 19항목 - 루트 md 6개 → 2개(docs/ 이동), 중복 배치 문서 병합, 스테일 worktree 제거 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
88 lines
3.0 KiB
Markdown
88 lines
3.0 KiB
Markdown
# Auto Stock Trading System with MCP
|
|
|
|
Claude AI와 MCP(Model Context Protocol)를 활용한 한국 주식 자동매매 시스템
|
|
|
|
## 시스템 아키텍처
|
|
|
|
- **Frontend**: React + TypeScript + Vite
|
|
- **Backend**: Python FastAPI + WebSocket
|
|
- **MCP Server**: Claude AI 통합
|
|
- **Database**: PostgreSQL
|
|
- **Cache**: Redis
|
|
- **Message Queue**: RabbitMQ
|
|
- **API**: 한국투자증권 API
|
|
|
|
## 주요 기능
|
|
|
|
1. **실시간 시장 데이터 수집**
|
|
2. **Claude AI 기반 규칙 검증**
|
|
3. **자동 매매 실행**
|
|
4. **포트폴리오 관리**
|
|
5. **실시간 모니터링**
|
|
|
|
## 프로젝트 구조
|
|
|
|
```
|
|
auto-stock/
|
|
├── frontend/ # React 프론트엔드
|
|
├── backend/ # FastAPI 백엔드
|
|
├── mcp-server/ # MCP 서버
|
|
├── docker/ # Docker 설정
|
|
├── deploy/ # NAS 배포
|
|
├── docs/ # 문서 (아래 목록)
|
|
└── scripts/ # 배포 스크립트
|
|
```
|
|
|
|
## 문서
|
|
|
|
작업 규칙과 전략 명세는 **`CLAUDE.md`** 가 정본이다. 파라미터 값을 확인할 때는 §0(파라미터 우선순위)을 먼저 읽을 것.
|
|
|
|
| 문서 | 내용 |
|
|
|------|------|
|
|
| [CLAUDE.md](./CLAUDE.md) | **작업 규칙·전략 명세·미해결 항목 (정본)** |
|
|
| [docs/INSTALLATION.md](docs/INSTALLATION.md) | 설치 |
|
|
| [docs/USER_GUIDE.md](docs/USER_GUIDE.md) | 사용법 |
|
|
| [docs/PROJECT_STRUCTURE.md](docs/PROJECT_STRUCTURE.md) | 코드 구조 |
|
|
| [docs/backend_guide.md](docs/backend_guide.md) | 백엔드 가이드 |
|
|
| [docs/API_DOCS.md](docs/API_DOCS.md) | API 명세 |
|
|
| [docs/API_SAFE_OPERATION.md](docs/API_SAFE_OPERATION.md) | API 안전 운영 |
|
|
| [docs/RISK_MANAGEMENT_API.md](docs/RISK_MANAGEMENT_API.md) | 리스크 API |
|
|
| [docs/BATCH_GUIDE.md](docs/BATCH_GUIDE.md) | 배치 분석 (cron 3개 잡) |
|
|
| [deploy/NAS-SETUP-GUIDE.md](deploy/NAS-SETUP-GUIDE.md) | NAS 배포 |
|
|
| [docs/multi_tenant_design.md](docs/multi_tenant_design.md) | 멀티테넌트 설계 |
|
|
| [docs/multi_tenant_phase1_review.md](docs/multi_tenant_phase1_review.md) | 멀티테넌트 1단계 검수 |
|
|
|
|
이력 참고용(현행 아님): [docs/REFACTORING_PLAN.md](docs/REFACTORING_PLAN.md)(폐기), [docs/AUTOTRADE_DIAGNOSIS.md](docs/AUTOTRADE_DIAGNOSIS.md), [docs/SPEED_OPTIMIZATION.md](docs/SPEED_OPTIMIZATION.md)
|
|
|
|
## 빠른 시작
|
|
|
|
```bash
|
|
# 환경 변수 설정
|
|
cp .env.example .env
|
|
|
|
# 기본값
|
|
# - `DATABASE_URL`은 `.env.example`에 이미 도커 컨테이너(127.0.0.1:5432)를
|
|
# 가리키도록 설정되어 있습니다. 로컬 개발 시 별도 수정이 필요 없습니다.
|
|
# 원격 DB를 사용하려면 여기에 URL을 덮어쓰십시오.
|
|
|
|
# Docker로 전체 시스템 시작
|
|
./scripts/deploy.sh
|
|
|
|
# 개발 모드
|
|
./scripts/dev.sh
|
|
```
|
|
|
|
## 환경 변수
|
|
|
|
`.env` 파일에 다음 설정 필요:
|
|
|
|
- `KOREA_INVESTMENT_APP_KEY`: 한국투자증권 앱키
|
|
- `KOREA_INVESTMENT_APP_SECRET`: 한국투자증권 시크릿
|
|
- `ANTHROPIC_API_KEY`: Claude API 키
|
|
- `DATABASE_URL`: PostgreSQL 연결 URL (기본값은 도커 컨테이너)
|
|
- `REDIS_URL`: Redis 연결 URL
|
|
|
|
## 라이센스
|
|
|
|
MIT
|