최초 프로젝트 업로드 (Script Auto Commit)

2025-12-03 22:37:46 +09:00
commit ed7084dd8f
30 changed files with 3254 additions and 0 deletions
--- a/docs/DEPLOYMENT.md
+++ b/docs/DEPLOYMENT.md
@@ -0,0 +1,354 @@
+# 자동매매 활성화 가이드 (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. 법적 공지
+
+⚠️ **면책**: 이 봇은 교육 목적으로 제작되었습니다. 실제 투자/자동매매 시 발생하는 손실에 대해 개발자는 책임을 지지 않습니다. 충분한 테스트 후 자신의 책임 하에 사용하세요.
+