docs: update README/ARCHITECTURE with per-symbol strategy params

- Add per-symbol env var override examples to README strategy section
- Add per-symbol env vars to environment variable reference table
- Update ARCHITECTURE multi-symbol section with SymbolStrategyParams
- Update CLAUDE.md configuration section
- Update test counts to 138

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
21in7
2026-03-17 17:31:47 +09:00
parent 55c20012a3
commit ab032691d4
3 changed files with 37 additions and 12 deletions

View File

@@ -44,9 +44,10 @@ main.py
) )
``` ```
- **독립**: 각 봇은 자체 `Exchange`, `MLFilter`, `DataStream` 소유 - **독립**: 각 봇은 자체 `Exchange`, `MLFilter`, `DataStream`, `SymbolStrategyParams` 소유
- **공유**: `RiskManager`만 싱글턴으로 글로벌 리스크(일일 손실 한도, 동일 방향 제한) 관리 - **공유**: `RiskManager`만 싱글턴으로 글로벌 리스크(일일 손실 한도, 동일 방향 제한) 관리
- **병렬**: `asyncio.gather()`로 동시 실행, 서로 간섭 없음 - **병렬**: `asyncio.gather()`로 동시 실행, 서로 간섭 없음
- **심볼별 전략**: `config.get_symbol_params(symbol)`로 SL/TP/ADX 등을 심볼별 독립 설정 (`ATR_SL_MULT_XRPUSDT` 등 환경변수)
### 1.3 기술 스택 ### 1.3 기술 스택
@@ -248,7 +249,7 @@ Binance Combined WebSocket 단일 연결로 주 거래 심볼 + 상관관계 심
SL = 진입가 - ATR × ATR_SL_MULT (기본 2.0) SL = 진입가 - ATR × ATR_SL_MULT (기본 2.0)
TP = 진입가 + ATR × ATR_TP_MULT (기본 2.0) TP = 진입가 + ATR × ATR_TP_MULT (기본 2.0)
※ SL/TP/신호임계값/ADX/거래량배수 모두 환경변수로 설정 가능 ※ SL/TP/신호임계값/ADX/거래량배수 모두 환경변수로 설정 가능 (심볼별 오버라이드 지원)
``` ```
숏 신호는 롱의 대칭 조건으로 계산됩니다. 숏 신호는 롱의 대칭 조건으로 계산됩니다.
@@ -660,7 +661,7 @@ pytest tests/ -v # 전체 실행
bash scripts/run_tests.sh # 래퍼 스크립트 실행 bash scripts/run_tests.sh # 래퍼 스크립트 실행
``` ```
`tests/` 폴더에 15개 테스트 파일, 총 **136개의 테스트 케이스**가 작성되어 있습니다. `tests/` 폴더에 15개 테스트 파일, 총 **138개의 테스트 케이스**가 작성되어 있습니다.
### 6.2 모듈별 테스트 현황 ### 6.2 모듈별 테스트 현황
@@ -720,7 +721,7 @@ bash scripts/run_tests.sh # 래퍼 스크립트 실행
|------|--------|------| |------|--------|------|
| `main.py` | — | 진입점. 심볼별 `TradingBot` 생성 + 공유 `RiskManager` + `asyncio.gather()` | | `main.py` | — | 진입점. 심볼별 `TradingBot` 생성 + 공유 `RiskManager` + `asyncio.gather()` |
| `src/bot.py` | 오케스트레이터 | 심볼별 독립 트레이딩 루프 | | `src/bot.py` | 오케스트레이터 | 심볼별 독립 트레이딩 루프 |
| `src/config.py` | — | 환경변수 기반 설정 (`symbols` 리스트, `correlation_symbols`) | | `src/config.py` | — | 환경변수 기반 설정 (`symbols` 리스트, `correlation_symbols`, 심볼별 `SymbolStrategyParams`) |
| `src/data_stream.py` | Data | Combined WebSocket 캔들 수신·버퍼 관리 | | `src/data_stream.py` | Data | Combined WebSocket 캔들 수신·버퍼 관리 |
| `src/indicators.py` | Signal | 기술 지표 계산 및 복합 신호 생성 | | `src/indicators.py` | Signal | 기술 지표 계산 및 복합 신호 생성 |
| `src/ml_features.py` | ML Filter | 26개 ML 피처 추출 | | `src/ml_features.py` | ML Filter | 26개 ML 피처 추출 |

View File

@@ -90,7 +90,7 @@ bash scripts/deploy_model.sh --symbol XRPUSDT
Environment variables via `.env` file (see `.env.example`). Key vars: `BINANCE_API_KEY`, `BINANCE_API_SECRET`, `SYMBOLS` (comma-separated, e.g. `XRPUSDT,TRXUSDT`), `CORRELATION_SYMBOLS` (default `BTCUSDT,ETHUSDT`), `LEVERAGE`, `DISCORD_WEBHOOK_URL`, `MARGIN_MAX_RATIO`, `MARGIN_MIN_RATIO`, `MAX_SAME_DIRECTION` (default 2), `NO_ML_FILTER`. Environment variables via `.env` file (see `.env.example`). Key vars: `BINANCE_API_KEY`, `BINANCE_API_SECRET`, `SYMBOLS` (comma-separated, e.g. `XRPUSDT,TRXUSDT`), `CORRELATION_SYMBOLS` (default `BTCUSDT,ETHUSDT`), `LEVERAGE`, `DISCORD_WEBHOOK_URL`, `MARGIN_MAX_RATIO`, `MARGIN_MIN_RATIO`, `MAX_SAME_DIRECTION` (default 2), `NO_ML_FILTER`.
`src/config.py` uses `@dataclass` with `__post_init__` to load and validate all env vars. `src/config.py` uses `@dataclass` with `__post_init__` to load and validate all env vars. Per-symbol strategy params supported via `SymbolStrategyParams` — override with `ATR_SL_MULT_{SYMBOL}`, `ATR_TP_MULT_{SYMBOL}`, `SIGNAL_THRESHOLD_{SYMBOL}`, `ADX_THRESHOLD_{SYMBOL}`, `VOL_MULTIPLIER_{SYMBOL}`. Access via `config.get_symbol_params(symbol)`.
## Deployment ## Deployment

View File

@@ -110,6 +110,8 @@ Discord 웹훅을 설정했다면 진입/청산 시 실시간 알림을 받게
환경변수로 전략 파라미터를 조절할 수 있습니다. 기본값은 Walk-Forward 백테스트 스윕 결과에서 선정된 값입니다. 환경변수로 전략 파라미터를 조절할 수 있습니다. 기본값은 Walk-Forward 백테스트 스윕 결과에서 선정된 값입니다.
**전역 기본값** (심볼별 오버라이드 없을 때 적용):
| 환경변수 | 기본값 | 설명 | | 환경변수 | 기본값 | 설명 |
|---------|--------|------| |---------|--------|------|
| `ATR_SL_MULT` | `2.0` | 손절 ATR 배수 | | `ATR_SL_MULT` | `2.0` | 손절 ATR 배수 |
@@ -118,6 +120,23 @@ Discord 웹훅을 설정했다면 진입/청산 시 실시간 알림을 받게
| `ADX_THRESHOLD` | `25` | ADX 횡보장 필터 (0=비활성) | | `ADX_THRESHOLD` | `25` | ADX 횡보장 필터 (0=비활성) |
| `VOL_MULTIPLIER` | `2.5` | 거래량 급증 감지 배수 | | `VOL_MULTIPLIER` | `2.5` | 거래량 급증 감지 배수 |
**심볼별 오버라이드**: `{환경변수}_{심볼}` 형태로 심볼마다 독립 설정 가능. 미설정 시 전역 기본값 사용.
```env
# 예시: 2026-03-17 스윕 최적화 결과
ATR_SL_MULT_XRPUSDT=1.5
ATR_TP_MULT_XRPUSDT=4.0
ADX_THRESHOLD_XRPUSDT=30
ATR_SL_MULT_TRXUSDT=1.0
ATR_TP_MULT_TRXUSDT=4.0
ADX_THRESHOLD_TRXUSDT=30
ATR_SL_MULT_DOGEUSDT=2.0
ATR_TP_MULT_DOGEUSDT=2.0
ADX_THRESHOLD_DOGEUSDT=30
```
### ML 필터 ### ML 필터
ML 필터는 기술 지표 신호를 한 번 더 검증하여 오진입을 차단합니다. 기본적으로 **비활성화** 상태입니다. ML 필터는 기술 지표 신호를 한 번 더 검증하여 오진입을 차단합니다. 기본적으로 **비활성화** 상태입니다.
@@ -189,11 +208,16 @@ docker compose up -d
| `MARGIN_DECAY_RATE` | `0.0006` | | 잔고 증가 시 감소 속도 | | `MARGIN_DECAY_RATE` | `0.0006` | | 잔고 증가 시 감소 속도 |
| `NO_ML_FILTER` | `true` | | ML 필터 비활성화 | | `NO_ML_FILTER` | `true` | | ML 필터 비활성화 |
| `ML_THRESHOLD` | `0.55` | | ML 예측 확률 임계값 | | `ML_THRESHOLD` | `0.55` | | ML 예측 확률 임계값 |
| `ATR_SL_MULT` | `2.0` | | 손절 ATR 배수 | | `ATR_SL_MULT` | `2.0` | | 손절 ATR 배수 (전역 기본값) |
| `ATR_TP_MULT` | `2.0` | | 익절 ATR 배수 | | `ATR_TP_MULT` | `2.0` | | 익절 ATR 배수 (전역 기본값) |
| `SIGNAL_THRESHOLD` | `3` | | 최소 가중치 점수 | | `SIGNAL_THRESHOLD` | `3` | | 최소 가중치 점수 (전역 기본값) |
| `ADX_THRESHOLD` | `25` | | ADX 횡보장 필터 (0=비활성) | | `ADX_THRESHOLD` | `25` | | ADX 횡보장 필터 (전역 기본값, 0=비활성) |
| `VOL_MULTIPLIER` | `2.5` | | 거래량 급증 배수 | | `VOL_MULTIPLIER` | `2.5` | | 거래량 급증 배수 (전역 기본값) |
| `ATR_SL_MULT_{SYMBOL}` | — | | 심볼별 손절 ATR 배수 오버라이드 |
| `ATR_TP_MULT_{SYMBOL}` | — | | 심볼별 익절 ATR 배수 오버라이드 |
| `SIGNAL_THRESHOLD_{SYMBOL}` | — | | 심볼별 최소 가중치 점수 오버라이드 |
| `ADX_THRESHOLD_{SYMBOL}` | — | | 심볼별 ADX 필터 오버라이드 |
| `VOL_MULTIPLIER_{SYMBOL}` | — | | 심볼별 거래량 배수 오버라이드 |
| `DASHBOARD_API_URL` | `http://10.1.10.24:8000` | | 대시보드 API 주소 (주간 리포트용) | | `DASHBOARD_API_URL` | `http://10.1.10.24:8000` | | 대시보드 API 주소 (주간 리포트용) |
| `BINANCE_TESTNET_API_KEY` | — | | Testnet API 키 | | `BINANCE_TESTNET_API_KEY` | — | | Testnet API 키 |
| `BINANCE_TESTNET_API_SECRET` | — | | Testnet API 시크릿 | | `BINANCE_TESTNET_API_SECRET` | — | | Testnet API 시크릿 |
@@ -246,7 +270,7 @@ cointrader/
│ └── weekly/ # 주간 리포트 JSON 저장 │ └── weekly/ # 주간 리포트 JSON 저장
├── logs/ # 로그 파일 ├── logs/ # 로그 파일
├── docs/plans/ # 설계 문서 및 구현 플랜 ├── docs/plans/ # 설계 문서 및 구현 플랜
├── tests/ # 테스트 코드 (15파일, 136개 케이스) ├── tests/ # 테스트 코드 (15파일, 138개 케이스)
├── Dockerfile ├── Dockerfile
├── docker-compose.yml ├── docker-compose.yml
├── Jenkinsfile ├── Jenkinsfile
@@ -270,7 +294,7 @@ cp .env.example .env
## 테스트 ## 테스트
```bash ```bash
# 전체 테스트 (136개) # 전체 테스트 (138개)
bash scripts/run_tests.sh bash scripts/run_tests.sh
# 특정 키워드 필터 # 특정 키워드 필터