refactor: enhance Optuna backtesting framework, optimize orderbook filtering, and update database management utilities.
This commit is contained in:
Your Name
313
docs/like_mcp.md/MODIFICATION_GUIDE.md
Normal file
313
docs/like_mcp.md/MODIFICATION_GUIDE.md
Normal file
@@ -0,0 +1,313 @@
|
||||
# kis_bot 코드 수정 가이드 — AI 에이전트 필수 체크리스트
|
||||
|
||||
> **이 문서의 목적**: 코드 수정 시 사이드 이펙트를 빠짐없이 잡기 위한 절차 정의.
|
||||
> 두 참조 문서와 함께 사용하세요.
|
||||
> - 📦 [code_architecture.md](./code_architecture.md) — 파일 간 import 의존성 맵
|
||||
> - 🗄️ [db_erd.md](./db_erd.md) — DB 테이블 스키마 & ERD
|
||||
|
||||
---
|
||||
|
||||
## ⚡ 핵심 원칙
|
||||
|
||||
```
|
||||
코드를 수정하기 전에,
|
||||
반드시 아래 섹션에 해당하는 grep을 먼저 실행하고
|
||||
결과를 확인한 뒤 수정 범위를 확정한다.
|
||||
```
|
||||
|
||||
**grep을 생략해도 되는 유일한 경우**: 주석/docstring 텍스트만 바꾸는 경우.
|
||||
|
||||
---
|
||||
|
||||
## 🔍 수정 유형별 필수 grep 목록
|
||||
|
||||
### 0. 조건검색 유니버스 (LS / 키움) — 시드·재시도
|
||||
|
||||
> LS 공백·ALIGN·job 이벤트 수정 시. 상세: [code_architecture.md 수동 노트](./code_architecture.md)
|
||||
|
||||
```bash
|
||||
grep -rn "LS_T1859_EMPTY_RETRY\|t1859\|_refresh_empty\|STALE_RESYNC\|rows_prefer" /home/hoon/kis_bot/kis_trader/network --include="*.py"
|
||||
grep -rn "condition_common\|condition_job_events\|LIVE_UNIVERSE_SLOT_ALIGN\|CAND_LIMIT" /home/hoon/kis_bot --include="*.py" -l
|
||||
```
|
||||
|
||||
**체크리스트**:
|
||||
- [ ] LS: AFR≠풀덤프 → RAM0 재시드(`LS_T1859_EMPTY_RETRY_SEC`, 기본 **1**·TR_GAP≥1.1). **0=OFF** (무한 REST 아님)
|
||||
- [ ] 키움 CNSRREQ / LS t1859 시드 경로 **합치지 말 것** (공통은 `condition_common` JOB 플래그만)
|
||||
- [ ] 빈 t1859 → history INSERT 금지
|
||||
- [ ] `database.py` ENV 키 목록 + `env_config_ext` 저장 검증
|
||||
- [ ] 웹 조건 이벤트/정합 탭 API (해당 시)
|
||||
|
||||
---
|
||||
|
||||
### 1. ENV 파라미터 추가/변경/삭제
|
||||
|
||||
> 예: `MOMENTUM_E_MIN_CHG_PCT`, `SCALP_STOP_LOSS_PCT` 등
|
||||
|
||||
```bash
|
||||
# ① env 키 이름 직접 참조
|
||||
grep -r "MOMENTUM_E_MIN_CHG_PCT" /home/hoon/kis_bot --include="*.py" -l
|
||||
|
||||
# ② params dict snake_case 키
|
||||
grep -r "e_min_chg_pct" /home/hoon/kis_bot --include="*.py" -l
|
||||
|
||||
# ③ database.py CREATE TABLE 컬럼 정의
|
||||
grep -n "MOMENTUM_E_MIN_CHG_PCT" /home/hoon/kis_bot/database.py
|
||||
|
||||
# ④ env_keys.py 등록 여부
|
||||
grep -r "E_MIN_CHG_PCT" /home/hoon/kis_bot/kis_trader/engine/momentum_env_keys.py
|
||||
```
|
||||
|
||||
**확인 후 수정해야 할 곳 체크리스트**:
|
||||
- [ ] `database.py` — CREATE TABLE에 컬럼 추가
|
||||
- [ ] `kis_trader/engine/momentum_env_keys.py` — `MOMENTUM_CONFIG_KEYS` 등록
|
||||
- [ ] `kis_trader/engine/momentum_engine.py` — `get_momentum_defaults()` 로드 및 return dict
|
||||
- [ ] `kis_trader/engine/momentum_hts_logic.py` — 실제 로직에서 사용
|
||||
- [ ] `kis_trader/backtest/param_search_momentum.py` — 그리드/텀 탐색 범위
|
||||
- [ ] `kis_trader/backtest/param_search_apply_snapshot.py` — 스냅샷 적용 매핑
|
||||
- [ ] `kis_trader/backtest/optuna_search_space.py` — Optuna 탐색 공간 (해당 시)
|
||||
|
||||
---
|
||||
|
||||
### 2. DB 테이블 컬럼 추가/변경/삭제
|
||||
|
||||
```bash
|
||||
# ① 해당 테이블 참조 파일 목록
|
||||
grep -r "active_trades" /home/hoon/kis_bot --include="*.py" -l
|
||||
|
||||
# ② 컬럼명 직접 참조
|
||||
grep -rn "avg_buy_price" /home/hoon/kis_bot --include="*.py"
|
||||
|
||||
# ③ INSERT/UPDATE 구문 (컬럼 순서에 민감)
|
||||
grep -rn "INSERT INTO active_trades" /home/hoon/kis_bot --include="*.py"
|
||||
grep -rn "UPDATE active_trades" /home/hoon/kis_bot --include="*.py"
|
||||
```
|
||||
|
||||
**확인 후 수정해야 할 곳 체크리스트**:
|
||||
- [ ] `database.py` — `CREATE TABLE`, `ALTER TABLE`
|
||||
- [ ] `database.py` — INSERT/UPDATE 쿼리 전부
|
||||
- [ ] 해당 테이블 참조 파일들 — SELECT 컬럼 파싱 로직
|
||||
|
||||
---
|
||||
|
||||
### 3. 함수/메서드 시그니처 변경
|
||||
|
||||
```bash
|
||||
# ① 함수 정의 위치
|
||||
grep -rn "def eval_momentum_hts_buy_at_index" /home/hoon/kis_bot --include="*.py"
|
||||
|
||||
# ② 함수 호출 위치 전부
|
||||
grep -rn "eval_momentum_hts_buy_at_index" /home/hoon/kis_bot --include="*.py"
|
||||
|
||||
# ③ import 위치
|
||||
grep -rn "from.*import.*eval_momentum_hts_buy_at_index" /home/hoon/kis_bot --include="*.py"
|
||||
```
|
||||
|
||||
**확인 후 수정해야 할 곳 체크리스트**:
|
||||
- [ ] 함수 정의 파일
|
||||
- [ ] 함수를 import하는 모든 파일
|
||||
- [ ] 함수를 호출하는 모든 파일
|
||||
|
||||
---
|
||||
|
||||
### 4. 전략 params dict 키 추가/변경
|
||||
|
||||
> 예: `mom_vol_mult`, `e_min_chg_pct` 같은 params 딕셔너리 키
|
||||
|
||||
```bash
|
||||
# ① params에서 꺼내는 곳
|
||||
grep -rn '"e_min_chg_pct"' /home/hoon/kis_bot --include="*.py"
|
||||
|
||||
# ② params에 넣는 곳 (파일 목록)
|
||||
grep -rn "e_min_chg_pct" /home/hoon/kis_bot --include="*.py" -l
|
||||
```
|
||||
|
||||
**확인 후 수정해야 할 곳 체크리스트**:
|
||||
- [ ] 엔진 `get_*_defaults()` 함수 — params 생성
|
||||
- [ ] 엔진 로직 파일 — `params.get("key", default)`
|
||||
- [ ] 파라미터 서치 — 그리드 정의, 스냅샷 적용, `_to_env` 매핑
|
||||
- [ ] Optuna 탐색 공간 — `_suggest_from_grid` 대상 그리드
|
||||
|
||||
---
|
||||
|
||||
### 5. 클래스/모듈 이름 변경 또는 파일 이동
|
||||
|
||||
```bash
|
||||
# ① import 참조 전부
|
||||
grep -rn "from kis_trader.engine.momentum_hts_logic import" /home/hoon/kis_bot --include="*.py"
|
||||
|
||||
# ② 문자열로 언급되는 곳 (동적 import, 로그 등)
|
||||
grep -rn "momentum_hts_logic" /home/hoon/kis_bot --include="*.py"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 6. 웜업(Warmup) 로직 변경
|
||||
|
||||
```bash
|
||||
# ① 웜업 관련 함수 목록
|
||||
grep -rn "candle_warmup" /home/hoon/kis_bot --include="*.py" -l
|
||||
grep -rn "REST_WARMUP" /home/hoon/kis_bot --include="*.py" -l
|
||||
|
||||
# ② 웜업 bars env 키
|
||||
grep -rn "BACKTEST_CANDLE_WARMUP_BARS" /home/hoon/kis_bot --include="*.py"
|
||||
grep -rn "BACKTEST_REST_WARMUP_BARS" /home/hoon/kis_bot --include="*.py"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 7. HTS 조건식 로직 변경
|
||||
|
||||
```bash
|
||||
# ① skip_hts_scan_dupes 관련
|
||||
grep -rn "skip_hts" /home/hoon/kis_bot --include="*.py" -l
|
||||
|
||||
# ② hts_trigger 설정
|
||||
grep -rn "hts_trigger_defaults" /home/hoon/kis_bot --include="*.py"
|
||||
grep -rn "trigger_e_confirm" /home/hoon/kis_bot --include="*.py"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📋 수정 전 표준 워크플로우
|
||||
|
||||
```
|
||||
1. 수정 요청 파악
|
||||
└─ 어떤 유형의 변경인가? (ENV / DB / 함수 / 파라미터 / 파일이동 ...)
|
||||
|
||||
2. code_architecture.md 에서 연관 파일 1차 파악
|
||||
└─ 허브 파일 Top 20 체크
|
||||
└─ 전략별 파일 분류에서 관련 전략 파일 확인
|
||||
└─ DB 테이블 ↔ 코드 파일 연관 맵 확인
|
||||
|
||||
3. 위 섹션의 grep 명령어 실행 (반드시)
|
||||
└─ 발견된 파일 목록 확정
|
||||
|
||||
4. db_erd.md 에서 DB 스키마 확인 (DB 관련 변경 시)
|
||||
└─ 컬럼 타입, PK, 인덱스 확인
|
||||
|
||||
5. 수정 범위 확정 후 코드 수정
|
||||
|
||||
6. 문법 검사
|
||||
└─ python3 -m py_compile <수정한 파일>
|
||||
|
||||
7. (필수) docs/ 문서 갱신 — 아래 조건 중 하나라도 해당하면
|
||||
└─ 파일 추가/삭제/이동이 있었다면 → code_architecture.md 재생성
|
||||
└─ DB 테이블/컬럼이 변경됐으면 → db_erd.md 재생성
|
||||
└─ ENV 키/params 키가 추가됐으면 → MODIFICATION_GUIDE.md 체크리스트 갱신
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚨 이 프로젝트 특이 사항 (절대 무시 금지)
|
||||
|
||||
### SKIP_HTS_SCAN_DUPES 규칙
|
||||
```
|
||||
`*_SKIP_HTS_SCAN_DUPES` 는 사용자가 언급하기 전까지 false 유지.
|
||||
임의로 true로 바꾸지 말 것.
|
||||
```
|
||||
|
||||
### HTS 조건식과 코드 분리
|
||||
```
|
||||
HTS는 후보 유니버스 참고용.
|
||||
그리드를 HTS 밴드에 맞추라고 강제하지 말 것.
|
||||
```
|
||||
|
||||
### 백테스트 웜업 전략별 분리
|
||||
```
|
||||
모멘텀 웜업 변경이 스캘핑/꼬리잡기 웜업에 영향을 주지 않는다.
|
||||
각 전략 웜업 함수는 독립적이다:
|
||||
- momentum_backtest_candle_warmup_bars() ← momentum_backtest_common.py
|
||||
- scalp_backtest_candle_warmup_bars() ← scalping_backtest_common.py
|
||||
- tail_backtest_candle_warmup_bars() ← tail_backtest_common.py
|
||||
```
|
||||
|
||||
### env 키 저장 경로
|
||||
```
|
||||
database.py의 CREATE TABLE 컬럼에 있는 키 → 해당 config_* 테이블 컬럼
|
||||
database.py의 CREATE TABLE에 없는 키 → env_config_ext (key-value 테이블)
|
||||
새 env 키 추가 시 두 경로 중 어디에 저장될지 확인 필요.
|
||||
```
|
||||
|
||||
### e_min_chg_pct 단위
|
||||
```
|
||||
e_min_chg_pct 는 퍼센트 단위 (0.5 = 0.5%).
|
||||
코드 내부에서 / 100.0 변환 후 사용.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ 자주 쓰는 grep 원라이너 모음
|
||||
|
||||
```bash
|
||||
# ENV 키 전체 참조 추적
|
||||
grep -rn "ENV_KEY_NAME" /home/hoon/kis_bot --include="*.py"
|
||||
|
||||
# DB 테이블 참조 파일 목록
|
||||
grep -rl "table_name" /home/hoon/kis_bot --include="*.py"
|
||||
|
||||
# params dict 특정 키 추적
|
||||
grep -rn '"param_key"' /home/hoon/kis_bot --include="*.py"
|
||||
|
||||
# 함수 호출 추적
|
||||
grep -rn "function_name(" /home/hoon/kis_bot --include="*.py"
|
||||
|
||||
# import 경로 추적
|
||||
grep -rn "from module.path import" /home/hoon/kis_bot --include="*.py"
|
||||
|
||||
# 특정 전략 파일만 검색
|
||||
grep -rn "keyword" /home/hoon/kis_bot/kis_trader/engine --include="*momentum*"
|
||||
|
||||
# SQL 쿼리 내 테이블 참조
|
||||
grep -rn "FROM table_name\|INTO table_name\|UPDATE table_name" /home/hoon/kis_bot --include="*.py"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ✅ 이 가이드 + 두 MD 파일이면 충분한가?
|
||||
|
||||
| 상황 | 충분 여부 |
|
||||
|------|----------|
|
||||
| ENV 파라미터 추가/변경 | ✅ 충분 (위 체크리스트 따르면) |
|
||||
| DB 컬럼 추가/변경 | ✅ 충분 (grep 필수 실행 시) |
|
||||
| 함수 시그니처 변경 | ✅ 충분 |
|
||||
| 전략 간 공유 유틸 변경 | ✅ `code_architecture.md` 허브 파일 + grep |
|
||||
| 동적 import 패턴 변경 | ⚠️ grep으로만 확인 가능 (MD로 탐지 불가) |
|
||||
| 런타임에만 나타나는 의존 | ❌ 실제 실행해봐야 함 |
|
||||
|
||||
> **결론**: grep을 반드시 실행한다는 전제 하에,
|
||||
> 이 세 파일(MODIFICATION_GUIDE.md + code_architecture.md + db_erd.md)이면
|
||||
> 런타임 의존성을 제외한 대부분의 케이스에서 누락 없이 수정 가능합니다.
|
||||
|
||||
---
|
||||
|
||||
## 🔄 docs/ 문서 갱신 규칙 (필수)
|
||||
|
||||
### 갱신 트리거 조건
|
||||
|
||||
| 변경 유형 | 갱신할 문서 |
|
||||
|-----------|------------|
|
||||
| .py 파일 추가/삭제/이동 | `code_architecture.md` |
|
||||
| import 구조 변경 | `code_architecture.md` |
|
||||
| DB 테이블/컬럼 변경 | `db_erd.md` |
|
||||
| ENV 키/params dict 키 추가 | `MODIFICATION_GUIDE.md` 체크리스트 |
|
||||
| 전략 추가/삭제 | `code_architecture.md` + `MODIFICATION_GUIDE.md` |
|
||||
|
||||
### 갱신 방법
|
||||
|
||||
```bash
|
||||
# code_architecture.md 재생성 (AST 분석 스크립트)
|
||||
cd /home/hoon/kis_bot && python3 /tmp/gen_arch_md.py
|
||||
|
||||
# db_erd.md 재생성 (DB DDL 추출 → MD 변환)
|
||||
cd /home/hoon/kis_bot && python3 /tmp/gen_erd_md.py
|
||||
```
|
||||
|
||||
### 동적 import 안전성 (2026-08-01 감사 결과)
|
||||
|
||||
이 프로젝트의 동적 import는 **총 7건**이며, 전부 무해한 패턴입니다:
|
||||
- 표준 라이브러리 인라인 호출: `__import__("json")`, `__import__("time")` — 3건
|
||||
- 테스트 모듈 로딩: `importlib.import_module("_test_...")` — 2건
|
||||
- 레거시 (remove/ 폴더, 비활성) — 2건
|
||||
|
||||
**핵심 매매/엔진/백테 코드에서 동적 import로 전략을 분기하는 패턴은 없습니다.**
|
||||
코드 수정 불필요.
|
||||
Reference in New Issue
Block a user