diff --git a/CLAUDE.md b/CLAUDE.md index 5247fb2..6c15dca 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -94,6 +94,7 @@ Smart Scanner runs in `TRADE_MODE=realtime` only. Daily mode uses static watchli - **[Testing](docs/testing.md)** — Test structure, coverage requirements, writing tests - **[Agent Policies](docs/agents.md)** — Prime directives, constraints, prohibited actions - **[Requirements Log](docs/requirements-log.md)** — User requirements and feedback tracking +- **[Live Trading Checklist](docs/live-trading-checklist.md)** — 모의→실전 전환 체크리스트 ## Core Principles diff --git a/docs/live-trading-checklist.md b/docs/live-trading-checklist.md new file mode 100644 index 0000000..912b2fc --- /dev/null +++ b/docs/live-trading-checklist.md @@ -0,0 +1,131 @@ +# 실전 전환 체크리스트 + +모의 거래(paper)에서 실전(live)으로 전환하기 전에 아래 항목을 **순서대로** 모두 확인하세요. + +--- + +## 1. 사전 조건 + +### 1-1. KIS OpenAPI 실전 계좌 준비 +- [ ] 한국투자증권 계좌 개설 완료 (일반 위탁 계좌) +- [ ] OpenAPI 실전 사용 신청 (KIS 홈페이지 → Open API → 서비스 신청) +- [ ] 실전용 APP_KEY / APP_SECRET 발급 완료 +- [ ] KIS_ACCOUNT_NO 형식 확인: `XXXXXXXX-XX` (8자리-2자리) + +### 1-2. 리스크 파라미터 검토 +- [ ] `CIRCUIT_BREAKER_PCT` 확인: 기본값 -3.0% (더 엄격하게 조정 권장) +- [ ] `FAT_FINGER_PCT` 확인: 기본값 30.0% (1회 주문 최대 잔고 대비 %) +- [ ] `CONFIDENCE_THRESHOLD` 확인: BEARISH ≥ 90, NEUTRAL ≥ 80, BULLISH ≥ 75 +- [ ] 초기 투자금 결정 및 해외 주식 운용 한도 설정 + +### 1-3. 시스템 요건 +- [ ] 커버리지 80% 이상 유지 확인: `pytest --cov=src` +- [ ] 타입 체크 통과: `mypy src/ --strict` +- [ ] Lint 통과: `ruff check src/ tests/` + +--- + +## 2. 환경 설정 + +### 2-1. `.env` 파일 수정 + +```bash +# 1. KIS 실전 URL로 변경 (모의: openapivts 포트 29443) +KIS_BASE_URL=https://openapi.koreainvestment.com:9443 + +# 2. 실전 APP_KEY / APP_SECRET으로 교체 +KIS_APP_KEY=<실전_APP_KEY> +KIS_APP_SECRET=<실전_APP_SECRET> +KIS_ACCOUNT_NO=<실전_계좌번호> + +# 3. 모드를 live로 변경 +MODE=live + +# 4. PAPER_OVERSEAS_CASH 비활성화 (live 모드에선 무시되지만 명시적으로 0 설정) +PAPER_OVERSEAS_CASH=0 +``` + +> ⚠️ `KIS_BASE_URL` 포트 주의: +> - **모의(VTS)**: `https://openapivts.koreainvestment.com:29443` +> - **실전**: `https://openapi.koreainvestment.com:9443` + +### 2-2. TR_ID 자동 분기 확인 + +아래 TR_ID는 `MODE` 값에 따라 코드에서 **자동으로 선택**됩니다. +별도 설정 불필요하나, 문제 발생 시 아래 표를 참조하세요. + +| 구분 | 모의 TR_ID | 실전 TR_ID | +|------|-----------|-----------| +| 국내 잔고 조회 | `VTTC8434R` | `TTTC8434R` | +| 국내 현금 매수 | `VTTC0012U` | `TTTC0012U` | +| 국내 현금 매도 | `VTTC0011U` | `TTTC0011U` | +| 해외 잔고 조회 | `VTTS3012R` | `TTTS3012R` | +| 해외 매수 | `VTTT1002U` | `TTTT1002U` | +| 해외 매도 | `VTTT1001U` | `TTTT1006U` | + +> **출처**: `docs/한국투자증권_오픈API_전체문서_20260221_030000.xlsx` (공식 문서 기준) + +--- + +## 3. 최종 확인 + +### 3-1. 실전 시작 전 점검 +- [ ] DB 백업 완료: `data/trade_logs.db` → `data/backups/` +- [ ] Telegram 알림 설정 확인 (실전에서는 알림이 더욱 중요) +- [ ] 소액으로 첫 거래 진행 후 TR_ID/계좌 정상 동작 확인 + +### 3-2. 실행 명령 + +```bash +# 실전 모드로 실행 +python -m src.main --mode=live + +# 대시보드 함께 실행 (별도 터미널에서 모니터링) +python -m src.main --mode=live --dashboard +``` + +### 3-3. 실전 시작 직후 확인 사항 +- [ ] 로그에 `MODE=live` 출력 확인 +- [ ] 첫 잔고 조회 성공 (ConnectionError 없음) +- [ ] Telegram 알림 수신 확인 ("System started") +- [ ] 첫 주문 후 KIS 앱에서 체결 내역 확인 + +--- + +## 4. 비상 정지 방법 + +### 즉각 정지 +```bash +# 터미널에서 Ctrl+C (정상 종료 트리거) +# 또는 Telegram 봇 명령: +/stop +``` + +### Circuit Breaker 발동 시 +- CB가 발동되면 자동으로 거래 중단 및 Telegram 알림 전송 +- CB 임계값: `CIRCUIT_BREAKER_PCT` (기본 -3.0%) +- **임계값은 엄격하게만 조정 가능** (더 낮은 음수 값으로만 변경) + +--- + +## 5. 롤백 절차 + +실전 전환 후 문제 발생 시: + +```bash +# 1. 즉시 .env에서 MODE=paper로 복원 +# 2. 재시작 +python -m src.main --mode=paper + +# 3. DB에서 최근 거래 확인 +sqlite3 data/trade_logs.db "SELECT * FROM trades ORDER BY id DESC LIMIT 20;" +``` + +--- + +## 관련 문서 + +- [시스템 아키텍처](architecture.md) +- [워크플로우 가이드](workflow.md) +- [재해 복구](disaster_recovery.md) +- [Agent 제약 조건](agents.md)