# AutoCoinTrader 사용 가이드

## 개요
AutoCoinTrader는 Upbit 시세 데이터를 기반으로 MACD, SMA, ADX 지표를 활용해 매수/매도 신호를 분석하고(`dry_run` 모드), 설정에 따라 자동 주문까지 수행할 수 있는 트레이딩 보조/자동화 도구입니다. 모든 주요 상태 파일(`holdings.json`, `trades.json`, `pending_orders.json`)은 `data/` 디렉터리 하위에서 관리됩니다.

## 1. 사전 준비
### 1.1 필수 요구사항
1. Python 3.11 이상
2. 가상환경 권장 (venv, pyenv, Conda 등)
3. Upbit API 키 (자동매매 사용 시)
4. Telegram Bot Token & Chat ID (알림 사용 시)

### 1.2 설치
```powershell
python -m venv .venv; .\.venv\Scripts\activate
pip install -r requirements.txt
```

### 1.3 환경변수 설정 (`.env`)
`.env` 파일에 아래 항목을 필요 시 추가:
```bash
TELEGRAM_BOT_TOKEN=123456789:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
TELEGRAM_CHAT_ID=123456789
UPBIT_ACCESS_KEY=YOUR_UPBIT_ACCESS
UPBIT_SECRET_KEY=YOUR_UPBIT_SECRET

# 선택 기능
AGGREGATE_ALERTS=false
TELEGRAM_TEST=0
AUTO_TRADE_ENABLED=0   # require_env_confirm 활성화 시 1로 설정해야 자동매매 진행
ORDER_MONITOR_TIMEOUT=120
ORDER_POLL_INTERVAL=3
ORDER_MAX_RETRIES=1
ORDER_MAX_CONSECUTIVE_ERRORS=5
```
`UPBIT_*` 키는 실거래(dry_run=False) + 자동매매(trading_mode=auto_trade/mixed)에서 필수.
`.env`는 반드시 `.gitignore`에 포함시키십시오.

## 2. 설정 파일 (`config/config.json`)
미존재 시 기본값이 내부 로직에서 자동 로드됩니다. 핵심 항목:
| 키 | 설명 | 기본값 |
|----|------|--------|
| candle_count | 각 심볼 지표 계산에 사용하는 캔들 개수 | 200 |
| buy_check_interval_minutes | 매수 조건 검사 주기 | 240 |
| stop_loss_check_interval_minutes | 손절 검사 주기 | 60 |
| profit_taking_check_interval_minutes | 익절 검사 주기 | 240 |
| loop | True면 주기적 루프 실행 | True |
| dry_run | True면 시뮬레이션 기록만 | True |
| max_threads | 병렬 스레드 수 | 3 |
| trading_mode | signal_only / auto_trade / mixed | signal_only |
| auto_trade.buy_enabled | 자동 매수 허용 여부 | False |
| auto_trade.buy_amount_krw | 1회 매수 금액 | 10000 |
| auto_trade.min_order_value_krw | 최소 주문 허용 KRW | 5000 |
| auto_trade.loss_threshold | 손절 기준(%) | -5.0 |
| auto_trade.profit_threshold_1 | 부분 익절 시작 수익률(%) | 10.0 |
| auto_trade.profit_threshold_2 | 전량 익절 고수익 기준(%) | 30.0 |
| auto_trade.drawdown_1 | 중간 구간 트레일링 하락률(%) | 5.0 |
| auto_trade.drawdown_2 | 고수익 구간 트레일링 하락률(%) | 15.0 |

## 3. 주요 데이터 파일 (data/)
| 파일 | 용도 |
|------|------|
| holdings.json | 현재 보유 코인 상태 (매수 평균가, 수량, max_price 등) |
| trades.json | 매수/매도 기록 (원자적 저장) |
| pending_orders.json | 사용자 확인 대기 중인 주문 토큰 목록 |

모든 경로는 코드 내부에서 `src.common`의 상수를 통해 관리되므로 재배치 시 해당 상수만 수정하면 됩니다.

## 4. 실행 방법
### 4.1 기본 실행 (드라이런)
```powershell
python main.py
```
루프 모드, 설정 주기에 따라 매수/손절/익절 검사 수행. `data/` 하위에 기록 생성.

### 4.2 벤치마크 실행
```powershell
python main.py --benchmark
```
순차/병렬 처리 시간 비교 후 로그 출력.

### 4.3 실거래 모드 전환
1. `config.json`에서 `dry_run`을 `false`, `trading_mode`를 `auto_trade` 또는 `mixed`로 설정.
2. `.env`에 `UPBIT_ACCESS_KEY`, `UPBIT_SECRET_KEY` 추가.
3. (선택) `AUTO_TRADE_ENABLED=1` 설정 (require_env_confirm일 경우 필수).
4. 소액으로 먼저 검증 후 확장.

### 4.4 Telegram 알림 테스트
`.env`에 `TELEGRAM_TEST=1` 설정 후 최초 실행 시 시작 메시지 전송.

## 5. 매수/매도 로직 개요
1. 매수 조건: MACD 교차, SMA 단기>장기, ADX 임계 초과 조합 (3가지 패턴)
2. 매도 조건: 손절(초기 하락), 부분 익절 후 수익 보호, 트레일링 익절 (구간별 다른 하락률 적용)
3. 부분 익절 1회 후 `partial_sell_done` 플래그로 중복 익절 방지.

## 6. 수동 확인 기반 주문 흐름
자동매매 모드에서 주문은 `pending_orders.json`에 기록 → 사용자가 `confirm_<토큰>` 파일 생성 → 타임아웃 내 확인되면 주문 실행.

## 7. 로그
`logs/AutoCoinTrader.log` 회전 로그(최대 10MB, 백업 7개). `LOG_DIR`, `LOG_LEVEL` 환경변수로 조정 가능.

## 8. Troubleshooting
| 증상 | 원인 | 해결 |
|------|------|------|
| 실거래 안 됨 | API 키 미설정 | `.env` 키 추가 및 dry_run False |
| 텔레그램 알림 없음 | 토큰/채팅ID 누락 | `.env` 값 확인 |
| 부분 체결 후 holdings 미반영 | 네트워크 지연 | 로그에서 monitor 결과 확인 후 수동 조정 |
| trades.json 손상 | 비정상 종료 | 자동 백업(`.corrupted.<ts>`) 후 재생성됨 |

## 9. 성능 & 안정성 팁
1. 스레드 수(`max_threads`)를 심볼 수 대비 과도하게 늘리지 말 것 (IO 포화 발생 가능).
2. 캔들 개수(`candle_count`)는 필요 이상 크게 하면 지표 계산 비용 증가.
3. 네트워크 오류 다발 시 `ORDER_MAX_CONSECUTIVE_ERRORS` 조정.

## 10. 백테스트 확장 (향후 계획)
`data/` 구조 유지 + 별도 `backtest/` 모듈에서 동일 지표 계산 후 결과 비교, `trades.json` 포맷 재사용. (구현 예정)

## 11. FAQ
**Q: dry_run과 auto_trade 차이?**  
A: dry_run은 모든 거래를 기록만 하고 실제 주문을 보내지 않음. auto_trade는 조건 충족 시 주문 API 호출.

**Q: 부분 익절 후 재매도는 어떻게?**  
A: `partial_sell_done` 플래그 True 후 트레일링 조건 또는 수익 보호 조건 충족 시 전량 매도.

**Q: trades.json 손상 시?**  
A: 자동으로 `.corrupted.<timestamp>` 백업 후 새로 시작. 백업 파일 검토 가능.

**Q: 설정 변경 반영 시점?**  
A: 프로세스 재시작 필요. 장기 실행 중에는 실시간 반영 안 함.

**Q: 최소 주문 금액 미만 상황?**  
A: 매도/매수 모두 안전하게 건너뛰고 로그와 텔레그램 알림(선택)으로 통지.