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

README.md

@@ -0,0 +1,162 @@
+# MACD 알림 봇 (Upbit 기반)
+
+이 프로젝트는 Upbit의 OHLCV 데이터를 `pyupbit`로 가져와 MACD, SMA, ADX를 계산하고, 설정된 매수/매도 조건에 따라 Telegram으로 알림을 보내는 봇입니다.
+
+---
+
+## 프로젝트 구조
+
+최근 프로젝트가 모듈화되어 다음과 같은 구조를 갖습니다:
+
+```
+macd_alarm/
+├── main.py                # 프로그램의 진입점
+├── src/                  # 모듈화된 코드
+│   ├── __init__.py       # 패키지 초기화
+│   ├── common.py         # 로깅 설정
+│   ├── config.py         # 설정 및 심볼 로드, RuntimeConfig
+│   ├── indicators.py     # MACD 및 지표 계산
+│   ├── holdings.py       # 보유 자산 관리
+│   ├── order.py          # 주문 및 확인
+│   ├── signals.py        # 매수/매도 신호 처리
+│   ├── notifications.py  # Telegram 알림
+│   ├── threading_utils.py # 멀티스레딩 유틸리티
+│   └── tests/            # 테스트 코드
+│       ├── test_helpers.py
+│       ├── test_main.py
+│       └── test_evaluate_sell_conditions.py
+└── pytest.ini            # pytest 설정
+```
+
+---
+
+## 주요 기능
+
+- **config.py**: 설정 파일(`config.json`) 로드, 심볼 목록 읽기, `RuntimeConfig` 데이터클래스로 실행 컨텍스트 관리.
+- **indicators.py**: OHLCV 데이터를 가져오고 MACD, SMA, ADX 계산.
+- **holdings.py**: 보유 자산 로드, 저장 및 현재 가격 확인.
+- **order.py**: 주문 실행 및 결과 확인.
+- **signals.py**: 매수/매도 조건 확인 및 기록.
+- **notifications.py**: Telegram 알림 전송.
+- **threading_utils.py**: 멀티스레딩 실행 지원.
+
+### RuntimeConfig
+
+프로젝트는 `RuntimeConfig` 데이터클래스를 사용하여 설정과 환경 변수를 단일 컨텍스트로 관리합니다. 이를 통해 함수 간 파라미터 전달이 간소화되고, 새로운 설정 옵션을 쉽게 추가할 수 있습니다.
+
+```python
+from src.config import build_runtime_config
+
+# config.json 로드 후
+cfg = build_runtime_config(config_dict)
+
+# cfg는 다음을 포함:
+# - timeframe, indicator_timeframe, limit
+# - telegram_bot_token, telegram_chat_id
+# - upbit_access_key, upbit_secret_key
+# - dry_run, max_threads, trading_mode 등
+```
+
+---
+
+## 매도 로직 및 경계값 처리 정책
+
+### 핵심 매도 조건
+
+1. **손절 (조건1)**: 수익률 ≤ -5% → 전량 매도
+2. **부분 익절 (조건3)**: 수익률 ≥ 10% 첫 도달 시 → 50% 매도 (1회만)
+3. **트레일링 익절 (조건2/4/5)**: 최고점 대비 일정 하락률 초과 시 → 전량 매도
+4. **수익률 보호 (조건4-2/5-2)**: 최고 수익률이 임계선(10%/30%)을 넘긴 후 다시 임계선 이하로 하락 시 → 전량 매도
+
+### 경계값(Equality) 처리 규칙
+
+**중요**: 수익률이 임계선(10%/30%)과 **정확히 일치(==)**하는 경우, 상황에 따라 다르게 처리됩니다:
+
+#### 상승 중 경계선 도달 (부분익절)
+- **조건**: `profit_rate >= 10%` (첫 도달)
+- **동작**: 절반 매도 (50%)
+- **논리**: 상승 추세에서 경계선 도달은 부분 익절 기회
+
+#### 하락 중 경계선 도달 (수익률 보호)
+- **조건**: 최고 수익률이 임계선을 초과한 뒤 `profit_rate <= threshold`로 하락
+- **동작**: 전량 매도 (100%, stop_loss)
+- **논리**: 최고점을 찍고 내려오는 중 경계선 도달은 하락 신호로 간주하여 수익 보호
+
+**예시**:
+```python
+# 시나리오 1: 상승 중 10% 도달 (첫 진입)
+# max_profit_rate: 10%, profit_rate: 10% → 부분익절 50% 매도
+
+# 시나리오 2: 하락 중 10% 도달 (중간 구간 보호)
+# max_profit_rate: 20%, profit_rate: 10% → 수익률 보호 100% 매도 (조건4-2)
+
+# 시나리오 3: 하락 중 30% 도달 (고수익 구간 보호)
+# max_profit_rate: 35%, profit_rate: 30% → 수익률 보호 100% 매도 (조건5-2)
+```
+
+**구현 상세** (`src/signals.py::evaluate_sell_conditions`):
+- 부분익절: `if profit_rate >= profit_threshold_1:` (>= 사용)
+- 중구간 보호: `if profit_rate <= profit_threshold_1:` (<= 사용)
+- 고구간 보호: `if profit_rate <= profit_threshold_2:` (<= 사용)
+
+---
+
+## 실행 방법
+
+1. **의존성 설치**:
+
+   ```bash
+   python -m pip install -r requirements.txt
+   ```
+
+2. **환경 변수 설정** (Telegram 및 Upbit API 키):
+
+   PowerShell:
+   ```powershell
+   $env:TELEGRAM_BOT_TOKEN = "YOUR_BOT_TOKEN"
+   $env:TELEGRAM_CHAT_ID = "YOUR_CHAT_ID"
+   $env:UPBIT_ACCESS_KEY = "YOUR_UPBIT_ACCESS_KEY"
+   $env:UPBIT_SECRET_KEY = "YOUR_UPBIT_SECRET_KEY"
+   ```
+
+   또는 `.env` 파일 생성:
+   ```
+   TELEGRAM_BOT_TOKEN=YOUR_BOT_TOKEN
+   TELEGRAM_CHAT_ID=YOUR_CHAT_ID
+   UPBIT_ACCESS_KEY=YOUR_UPBIT_ACCESS_KEY
+   UPBIT_SECRET_KEY=YOUR_UPBIT_SECRET_KEY
+   ```
+
+3. **설정 파일 준비**:
+
+   ```bash
+   copy config.example.json config.json
+   ```
+
+   `config.json` 파일을 필요에 따라 수정합니다.
+
+4. **프로그램 실행**:
+
+   ```bash
+   python main.py
+   ```
+
+---
+
+## 테스트 실행
+
+1. **pytest 설치**:
+
+   ```bash
+   python -m pip install pytest
+   ```
+
+2. **테스트 실행**:
+
+   ```bash
+   pytest
+   ```
+
+---
+
+이 문서는 프로젝트의 최신 구조와 실행 방법을 반영하도록 업데이트되었습니다.