# 자동매매 활성화 가이드 (Deployment & Safety)

## 개요
이 문서는 MACD 알림 봇의 **자동매매 기능(auto_trade)**을 안전하게 활성화하고 운영하는 방법을 설명합니다.

---

## 1. 사전 준비 (필수)

### 1.1 Upbit API 키 생성
1. [Upbit 홈페이지](https://upbit.com) 로그인
2. 계정 설정 → API 관리 → "Open API" 클릭
3. "오픈 API 키 생성" 버튼 클릭
4. 접근 권한:
   - ✅ **조회**: 계좌, 자산, 주문내역 (필수)
   - ✅ **매매**: 매도 주문 (필수)
   - ✅ **출금**: 해제 권장 (자동매매에 불필요)
5. IP 화이트리스트: 봇이 실행되는 서버 IP 추가 (선택, 권장)
6. Access Key / Secret Key 메모 (비밀 유지!)

### 1.2 Telegram Bot 토큰 & Chat ID 확인
- 기존에 설정했다면 그대로 사용 가능
- 없다면 [BotFather로 새 봇 생성](https://core.telegram.org/bots#botfather) 후 Chat ID 확인

### 1.3 환경변수 설정 (`.env` 파일)
```bash
# Telegram 알림
TELEGRAM_BOT_TOKEN=your_bot_token
TELEGRAM_CHAT_ID=your_chat_id

# Upbit API (자동매매 시 필수)
UPBIT_ACCESS_KEY=your_access_key
UPBIT_SECRET_KEY=your_secret_key

# 선택: 자동매매 활성화 확인 (require_env_confirm=true일 때)
AUTO_TRADE_ENABLED=1

# 선택: 주문 모니터링 타임아웃 (초, 기본 120)
ORDER_MONITOR_TIMEOUT=120

# 선택: 주문 폴링 간격 (초, 기본 3)
ORDER_POLL_INTERVAL=3

# 선택: 재시도 횟수 (기본 1)
ORDER_MAX_RETRIES=1
```

⚠️ `.env` 파일을 `.gitignore`에 추가하여 비밀 정보를 저장소에 커밋하지 마세요.

---

## 2. config.json 설정

### 2.1 기본 설정 (신중하게)
```json
{
  "trading_mode": "signal_only",
  "auto_trade": {
    "enabled": false,
    "max_trade_krw": 1000000,
    "allowed_symbols": [],
    "require_env_confirm": true
  },
  "confirm": {
    "confirm_via_file": true,
    "confirm_timeout": 300
  },
  "monitor": {
    "enabled": true,
    "timeout": 120,
    "poll_interval": 3,
    "max_retries": 1
  },
  "notify": {
    "order_filled": true,
    "order_partial": true,
    "order_cancelled": true,
    "order_error": true
  },
  "dry_run": true
}
```

### 2.2 각 항목 설명

#### `trading_mode`
- `"signal_only"` (기본): Telegram 알림만 전송
- `"auto_trade"`: 자동매매 시도 (수동 확인 필수)
- `"mixed"`: 알림 + 거래 기록

#### `auto_trade`
- `enabled`: `false`로 유지 (기본값). 실제 자동매도 활성화하려면 명시적으로 `true`로 변경
- `buy_enabled`: `false`로 유지 (기본값). 실제 자동매수 활성화하려면 명시적으로 `true`로 변경
- `buy_amount_krw`: 매수 시 사용할 KRW 금액 (예: 10,000)
- `max_trade_krw`: 한 번에 매도할 최대 KRW 금액 (예: 1,000,000)
- `allowed_symbols`: 자동매매 허용 심볼 목록. 빈 배열이면 모든 심볼 허용
  - 예: `["KRW-BTC", "KRW-ETH"]` (이 심볼들만 자동매매)
- `require_env_confirm`: `true`이면 환경변수 `AUTO_TRADE_ENABLED=1` 필요 (권장)

#### `confirm`
- `confirm_via_file`: 파일 기반 확인 활성화 여부
- `confirm_timeout`: 확인 대기 시간(초). 이 시간 내에 확인이 없으면 주문 취소

#### `monitor`
- `enabled`: 주문 모니터링 활성화
- `timeout`: 주문 폴링 타임아웃(초)
- `poll_interval`: 주문 상태 확인 간격(초)
- `max_retries`: 타임아웃 시 재시도 횟수

#### `notify`
- `order_filled`: 완전체결 시 알림
- `order_partial`: 부분체결/타임아웃 시 알림
- `order_cancelled`: 주문 취소 시 알림
- `order_error`: 오류 발생 시 알림

---

## 3. 안전 체크리스트 (자동매매 활성화 전)

### ✅ 필수 확인 항목
- [ ] Upbit API 키가 올바르게 발급되었나? (테스트 계좌에서 실제 키 사용하기)
- [ ] `.env` 파일이 `.gitignore`에 있나?
- [ ] `config.json`의 `dry_run`이 `true`로 설정되어 있나? (테스트 단계)
- [ ] `auto_trade.enabled`가 `false`로 설정되어 있나? (테스트 단계)
- [ ] 로그 파일(`logs/macd_alarm.log`)을 확인할 수 있는 환경인가?

### ✅ 단계적 활성화 (점진적 위험 증가)

#### 3.1 단계 1: Signal-Only 모드 (알림만)
```json
{
  "trading_mode": "signal_only",
  "dry_run": true
}
```
- 실행: `python main.py`
- 기대 결과: 매도/매수 신호 감지 시 Telegram 알림 수신
- 확인: 로그에 오류 없고, Telegram 메시지가 제대로 도착하는가?

#### 3.2 단계 2: Mixed 모드 (알림 + 기록, dry-run)
```json
{
  "trading_mode": "mixed",
  "auto_trade": {
    "enabled": false,
    "buy_enabled": false
  },
  "dry_run": true
}
```
- 실행: `python main.py`
- 기대 결과: 매도 신호 시 Telegram + `trades.json` 기록
- 매수 신호는 `auto_trade.buy_enabled`가 true일 때만 `trades.json`에 기록됨
- 확인: `trades.json`에 매도 기록이 제대로 저장되는가? (매수 기록은 buy_enabled가 true일 때만 저장됨)

#### 3.3 단계 3: Auto-Trade 시뮬레이션 (dry-run, 실제 주문 아님)
```json
{
  "trading_mode": "auto_trade",
  "auto_trade": {
    "enabled": true,
    "max_trade_krw": 100000,
    "allowed_symbols": [],
    "require_env_confirm": true
  },
  "dry_run": true
}
```
- 환경변수 설정:
  ```bash
  $env:AUTO_TRADE_ENABLED = "1"
  ```
- 실행: `python main.py`
- 기대 결과:
  - 매도 신호 감지 시 Telegram으로 확인 토큰 수신
  - 토큰으로 파일 생성 후 주문 진행 (시뮬레이션)
  - `pending_orders.json` 및 `trades.json`에 기록
- 확인:
  - Telegram 확인 메시지 형식이 명확한가?
  - 파일 생성으로 확인 메커니즘이 동작하는가?
  - 거래 기록이 제대로 저장되는가?

#### 3.4 단계 4: **실제 자동매도 활성화** (최종 단계, 신중!)
```json
{
  "trading_mode": "auto_trade",
  "auto_trade": {
    "enabled": true,
    "buy_enabled": false,
    "max_trade_krw": 100000,
    "allowed_symbols": ["KRW-BTC"],
    "require_env_confirm": true
  },
  "dry_run": false
}
```
- 환경변수 설정:
  ```bash
  $env:AUTO_TRADE_ENABLED = "1"
  ```
- Upbit 테스트 계좌 또는 소액 계좌 사용 권장
- 실행: `python main.py`
- 확인:
  - Telegram에서 실제 매도 주문 확인 메시지 수신
  - 파일 생성으로 주문 실행
  - Upbit 계정에서 주문 이력 확인
  - 모니터링 후 체결 알림 수신

#### 3.5 단계 5: **실제 자동매수 활성화** (최종 단계, 매우 신중!)
```json
{
  "trading_mode": "auto_trade",
  "auto_trade": {
    "enabled": true,
    "buy_enabled": true,
    "buy_amount_krw": 10000,
    "max_trade_krw": 100000,
    "allowed_symbols": ["KRW-BTC"],
    "require_env_confirm": true
  },
  "dry_run": false
}
```
- 환경변수 설정:
  ```bash
  $env:AUTO_TRADE_ENABLED = "1"
  ```
- ⚠️ **중요**: 자동매수는 자본 손실 위험이 높습니다. 반드시 소액으로 시작하세요.
- Upbit 테스트 계좌 또는 소액 계좌 사용 필수
- 실행: `python main.py`
- 확인:
  - 매수 신호 감지 시 Telegram에서 매수 주문 확인 메시지 수신
  - 파일 생성으로 주문 실행
  - Upbit 계정에서 매수 주문 이력 확인
  - 모니터링 후 체결 알림 수신
  - `holdings.json`에 새로운 보유 정보 자동 기록

---

## 4. 주문 확인 프로세스

### 4.1 Telegram 기반 확인 (현재 구현)
1. 자동매매 신호 감지 → Telegram 알림 수신
   ```
   [확인필요] 자동매매 주문 대기
   토큰: a1b2c3d4
   심볼: KRW-BTC
   주문량: 0.00010000
   ```

2. 프로젝트 루트에서 파일 생성 (PowerShell 예):
   ```powershell
   New-Item "confirm_a1b2c3d4" -ItemType File
   ```
   또는 `confirmed_tokens.txt` 파일에 토큰 추가:
   ```
   a1b2c3d4
   ```

3. 코드가 자동으로 파일/토큰 감지 → 주문 실행

### 4.2 타임아웃
- 기본 300초(5분) 내에 확인이 없으면 자동 취소
- `config.json`의 `confirm.confirm_timeout`으로 조정 가능

---

## 5. 운영 (Troubleshooting)

### 주문이 실행되지 않는 경우
1. **환경변수 확인**:
   ```bash
   echo $env:AUTO_TRADE_ENABLED
   # 결과: 1이어야 함
   ```

2. **API 키 확인**:
   ```bash
   echo $env:UPBIT_ACCESS_KEY
   # 결과: 실제 키가 설정되어 있어야 함
   ```

3. **로그 파일 확인**:
   ```bash
   Get-Content "logs/macd_alarm.log" -Tail 20
   # "자동매매 비활성화" 또는 "Upbit API 키 없음" 오류 찾기
   ```

4. **config.json 문법 확인**:
   ```bash
   python -c "import json; json.load(open('config.json'))"
   # JSON 파싱 오류 있으면 출력됨
   ```

### 부분체결 처리
- 주문량이 크거나 시장 유동성이 낮으면 부분체결 발생 가능
- `ORDER_MAX_RETRIES` 환경변수로 재시도 횟수 조정 (기본 1회)
- 모니터링은 `ORDER_MONITOR_TIMEOUT` 시간(기본 120초) 동안 진행

### 긴급 중지
- 파일 생성하지 않으면 `confirm_timeout` 후 자동 취소
- 또는 `dry_run: true`로 되돌려서 봇 재시작

---

## 6. 성능/안정성 팁

1. **작은 규모로 시작**:
   - `max_trade_krw`: 처음엔 10만~100만 KRW 범위
   - `allowed_symbols`: 확실한 심볼 몇 개만 선택

2. **로그 모니터링**:
   - 실시간: `Get-Content "logs/macd_alarm.log" -Tail 10 -Wait`
   - 또는 별도 터미널에서: `tail -f logs/macd_alarm.log`

3. **야간/주말 고려**:
   - Upbit는 24/7 운영이지만, 유동성이 낮은 시간대 존재
   - 백테스트 후 적절한 시간대에만 매매 권장

4. **백업**:
   - `trades.json` 주기적 백업
   - 또는 SQLite로 마이그레이션 고려

---

## 7. FAQ

**Q: 실제로 주문이 체결되면 어떻게 되나?**  
A: Upbit 계정에서 직접 체결되며, `trades.json` + Telegram 알림으로 기록됩니다.

**Q: 파일 생성을 깜빡하면?**  
A: `confirm_timeout` 후 자동 취소되고, `trades.json`에 `user_not_confirmed` 기록됩니다.

**Q: 여러 심볼이 동시에 신호 나면?**  
A: 각 심볼마다 독립적인 토큰으로 확인 요청. 병렬 처리 가능.

**Q: 테스트 중 실제 주문을 방지하려면?**  
A: `dry_run: true` 또는 `auto_trade.enabled: false`, `auto_trade.buy_enabled: false` 유지.

**Q: 자동매수와 자동매도를 독립적으로 제어할 수 있나?**  
A: 네. `auto_trade.enabled`는 매도만, `auto_trade.buy_enabled`는 매수만 제어합니다. 각각 독립적으로 활성화/비활성화 가능합니다.

**Q: 매수 후 holdings.json은 자동으로 업데이트되나?**  
A: 네. 매수 체결 완료 시 자동으로 `holdings.json`에 매수가, 수량, 최고가, 매수시간이 기록됩니다.

**Q: 자동매수 금액을 어떻게 설정하나?**  
A: `config.json`의 `auto_trade.buy_amount_krw`에 매수할 KRW 금액을 설정하세요. (예: 10000 = 1만원)

---

## 8. 법적 공지

⚠️ **면책**: 이 봇은 교육 목적으로 제작되었습니다. 실제 투자/자동매매 시 발생하는 손실에 대해 개발자는 책임을 지지 않습니다. 충분한 테스트 후 자신의 책임 하에 사용하세요.