AutoCoinTrader/docs/project_state.md

# Current Session State

## Current Goal
- Stabilize holdings sync/state restoration reliability (max_price, partial_sell_done).

## ToDo List
- [x] Prevent `max_price` downward reset when StateManager lacks data.
- [x] Preserve `partial_sell_done` flag during holdings sync merges.
- [x] Run full regression suite beyond `tests/test_v3_features.py` once changes are consolidated.
- [x] Implement Decimal-based order amount/price calculation with tick-size rounding (code_review_report_v2 P1) — added Decimal helper and integrated into limit buy path.
- [x] Add retry + short-TTL cache to `get_current_price`/balances (code_review_report_v2 P1); remaining: StateManager single-source plan.
- [x] Harden pending/confirm/recent_sells storage (TTL cleanup; atomic pending writes) — JSONL/sqlite alternative still open for future phase; config/log cleanups pending (code_review_report_v2 P2/P3).

## 🎯 Current Phase
- **Phase:** Code Review v5 완료 및 테스트 안정화
- **Focus:** 모든 CRITICAL/HIGH 이슈 해결 완료, 전체 테스트 통과

## ✅ Completed Tasks (This Session)

### Holdings sync resilience (2025-12-10)
- [x] `fetch_holdings_from_upbit` restores `max_price` using the highest among StateManager, local snapshot, and current buy price to prevent downward resets.
- [x] `partial_sell_done` restoration now preserves `True` from local snapshot even when StateManager stored `False`.
- [x] `pytest tests/test_v3_features.py` passes (robust holdings sync scenario).

### Decimal order calc (2025-12-10)
- [x] Added Decimal-based tick-size price adjustment and limit-buy volume calculation helper; integrated into `place_buy_order_upbit` to remove float rounding risk.
- [x] Updated `src/tests/test_order.py` to isolate KRWBudgetManager in response validation cases; all tests pass.

### Price/balance retry & cache (2025-12-10)
- [x] Added short TTL cache (2s) with 3-attempt backoff retry for `get_current_price` and `get_upbit_balances`, guarded by rate limiter.
- [x] New tests `src/tests/test_holdings_cache.py` cover cache hits and retry success paths.

### State/holdings reconciliation (2025-12-10)
- [x] Added `reconcile_state_and_holdings` to keep StateManager as source of truth while filling missing fields from holdings; syncs max_price/partial flags both ways.
- [x] Tests `src/tests/test_state_reconciliation.py` ensure state fills from holdings when empty and holdings are updated from newer state values.

### File queues hardening (2025-12-10)
- [x] `pending_orders.json` now prunes 24h stale entries and writes atomically via temp file.
- [x] `recent_sells.json` gains TTL cleanup (>=2x cooldown) to drop stale cooldown records.
- [x] Tests `src/tests/test_file_queues.py` cover pending TTL prune and recent_sells cleanup.

### Full regression suite (2025-12-10)
- [x] `pytest` (full suite across `src/tests` + `tests`) — all tests passed.

### Exception handling & constants (2025-12-10)
- [x] `holdings.py`에 `requests` import 추가 및 네트워크/파싱 예외만 처리하도록 축소 (IO 오류는 전파)
- [x] `order.py` pending TTL/주문 재시도 지연을 상수화(`PENDING_ORDER_TTL`, `ORDER_RETRY_DELAY`)하고 예외 처리를 요청/값 오류로 한정
- [x] ThreadPoolExecutor 상한을 상수(`THREADPOOL_MAX_WORKERS_CAP`)로 노출하고 환경변수로 조정 가능하도록 수정

### Code Review v5 개선사항 구현 (2025-12-10)
- [x] **CRITICAL-001**: `order.py` 구문 오류 (들여쓰기) 수정 완료
- [x] **CRITICAL-002**: `holdings.py` 중복 return 문 제거 완료
- [x] **HIGH-001**: Exception 처리 구체화 (json.JSONDecodeError, OSError, requests.exceptions 분리)
- [x] **MEDIUM-001**: Lock 획득 순서 규약 문서화 (`common.py` 라인 93-105)
- [x] **MEDIUM-002**: 매직 넘버 상수화 (`constants.py` 60줄, 9개 상수 정의)
- [x] **테스트 수정**: 실패 테스트 8개 수정 완료
  - 메시지 포맷 변경 반영 (4개)
  - 구체적 Exception 사용 (3개)
  - monkey patch 경로 수정 (1개)
- [x] **전체 테스트 통과**: 79/79 passed (100% 성공률)

### Rate limit & budget fixes (2025-12-10, ongoing session)
- [x] KRWBudgetManager 토큰 기반 다중 할당으로 리팩토링 (최소 주문 금액 가드 포함, 중복 심볼 동시 주문 안전)
- [x] recent_sells.json 잠금/원자적 쓰기/손상 백업 추가 → 재매수 쿨다운 레이스/손상 대비
- [x] RateLimiter를 초/분 이중 버킷으로 확장, get_current_price/get_upbit_balances에 적용
- [x] 동시 매수/예산 단위 테스트 갱신 및 추가 (동일 심볼 복수 주문 포함)
- [x] pytest src/tests/test_krw_budget_manager.py src/tests/test_concurrent_buy_orders.py → 모두 통과

### KRW 예산 할당 시스템 구현 (2025-12-10):
- [x] **v3 CRITICAL-1 개선**: KRW 잔고 Race Condition 완전 해결
  - `src/common.py`: `KRWBudgetManager` 클래스 신규 구현 (120줄)
  - 예산 할당(allocate) + 해제(release) 시스템
  - 멀티스레드 환경에서 KRW 중복 사용 방지
  - Lock 범위를 주문 완료까지 확장 (Option B 방식)

- [x] **place_buy_order_upbit 통합**:
  - `src/order.py`: KRWBudgetManager 사용하도록 수정
  - `try-finally` 패턴으로 예산 자동 해제 보장
  - 할당 실패 시 `skipped_insufficient_budget` 상태 반환

- [x] **멀티스레드 테스트 추가**:
  - `src/tests/test_krw_budget_manager.py`: 단위 테스트 11개 (모두 통과)
    - 전액 할당, 부분 할당, 할당 실패
    - 동시 할당, 할당/해제 동시 발생
    - 스트레스 테스트 (10 스레드)
    - 실전 거래 시나리오 시뮬레이션
  - `src/tests/test_concurrent_buy_orders.py`: 통합 테스트 4개
    - 동시 매수 시 잔고 초과 인출 방지
    - 할당 후 해제 및 재사용
    - 예외 발생 시 예산 자동 해제
    - 10 스레드 × 3 주문 스트레스 테스트
  - `verify_krw_budget.py`: 동작 검증 스크립트 (✅ 통과)

- [x] **문서화**:
  - `docs/krw_budget_implementation.md`: 구현 보고서 작성
    - 문제 정의, 해결 방안, 알고리즘 상세
    - 테스트 결과, 성능 영향 분석
    - 사용 가이드, 제한 사항

### Code Review v3 개선사항 구현 (2025-12-09):
- [x] **CRITICAL-001**: API Rate Limiter 구현 (토큰 버킷 알고리즘)
  - `src/common.py`: `RateLimiter` 클래스 추가 (초당 8회 제한)
  - `src/indicators.py`: `fetch_ohlcv()`에 Rate Limiter 적용
  - 멀티스레딩 환경에서 Thread-Safe 보장

- [x] **CRITICAL-002**: 최고가 갱신 로직 구현
  - `src/holdings.py`: `update_max_price()` 함수 추가
  - `main.py`: 손절/익절 체크 전 모든 보유 종목의 최고가 자동 갱신
  - Thread-Safe 구현 (holdings_lock 사용)

- [x] **CRITICAL-003**: Thread-Safe holdings 저장
  - `src/holdings.py`: `save_holdings()`에 Lock 추가 (이미 구현됨 확인)
  - 원자적 파일 쓰기 (.tmp 파일 사용 후 rename)

- [x] **CRITICAL-005**: 부분 매수 지원
  - `src/order.py`: `place_buy_order_upbit()` 수정
  - 잔고 부족 시 가능한 만큼 매수 (최소 주문 금액 이상일 때)
  - 수수료 0.05% 자동 차감

- [x] **HIGH-005**: Circuit Breaker 임계값 조정
  - `src/circuit_breaker.py`: failure_threshold 5→3, recovery_timeout 30s→300s

- [x] **HIGH-007**: Telegram 메시지 자동 분할
  - `src/notifications.py`: `send_telegram()` 수정
  - 4000자 초과 메시지 자동 분할 전송
  - 분할 메시지 간 0.5초 대기 (Rate Limit 방지)

- [x] **HIGH-008**: 재매수 방지 기능
  - `src/common.py`: `record_sell()`, `can_buy()` 함수 추가
  - `src/signals.py`: `_process_symbol_core()`에 재매수 확인 로직 추가
  - `src/order.py`: 매도 성공 시 `record_sell()` 호출
  - 기본 24시간 쿨다운 (config에서 조정 가능)

- [x] **MEDIUM-001**: 설정 파일 검증
  - `src/config.py`: `validate_config()` 함수 추가
  - 필수 항목 확인, 범위 검증, 타입 체크

- [x] **보안 개선**: 파일 권한 설정
  - `src/holdings.py`: holdings.json 파일에 0o600 권한 설정 (소유자만 읽기/쓰기)

- [x] **HIGH-002**: 예외 처리 개선 (부분 적용)
  - `src/order.py`: 잔고 조회 시 구체적 예외 처리
  - Rate Limiter에 네트워크 오류 구분

- [x] **API 키 검증**: main.py 시작 시 Upbit API 키 유효성 검증 (실전 모드 전용)

### 제외된 항목 (사용자 요청):
- [ ] ~~CRITICAL-004: RSI/MACD 조건 개선~~ (제외)
- [ ] ~~HIGH-004: Bollinger Bands 로직 수정~~ (제외)
- [ ] ~~MEDIUM-004: 백테스팅 기능~~ (제외)

## ✅ Previous Completed Tasks

### Git push 준비 & lint 정리 (2025-12-09):
- [x] ruff 에러(F821/E402/E731/F841) 해결: RuntimeConfig 타입 주입, import 순서 수정, lambda→def, 미사용 변수 제거
- [x] `src/holdings.py`, `src/order.py`: `from __future__ import annotations` + `TYPE_CHECKING` 가드 추가, RuntimeConfig 타입 명시
- [x] `src/order.py`: `CircuitBreaker` import 상단 이동 (E402 해결) 및 중복 import 제거
- [x] `src/signals.py`: 포매팅 lambda를 `def`로 교체, 미사용 변수 제거
- [x] `ruff check src/holdings.py src/order.py src/signals.py` 통과 확인 (pre-commit ruff hook 대응)

### Telegram 타임아웃 안정성 개선 (2025-04-XX):
- [x] 에러 로그 원인 분석 (SSL handshake 타임아웃)
- [x] 타임아웃 값 증가 (`timeout=10s` → `timeout=20s`)
- [x] 네트워크 오류 분류 (Timeout, ConnectionError)
- [x] `send_telegram_with_retry()` 적용 (3회 재시도)
  - `src/threading_utils.py` - `_process_result_and_notify()` 수정
  - `src/threading_utils.py` - `_send_aggregated_summary()` 수정
  - `src/threading_utils.py` - `_notify_no_signals()` 수정
- [x] 코드 문법 검증 (py_compile 통과)
- [x] 상세 문서화 (`docs/telegram_timeout_fix.md`)

### 이전 세션 완료 사항:
- [x] API 키 검증 함수 추가 (`validate_upbit_api_keys`)
- [x] 중복 주문 감지 함수 추가 (`_has_duplicate_pending_order`)
- [x] ReadTimeout 핸들러 개선 (매수 + 매도)
- [x] main.py 시작 시 API 키 검증 로직 통합
- [x] 단위 테스트 스크립트 작성 (`test_order_improvements.py`)

## 📝 Context Dump (주요 개선사항)

### Telegram API 타임아웃 해결 (2025-04-XX):

#### 에러 원인
- **문제:** Telegram API SSL handshake 타임아웃 (read timeout=10)
- **영향:** 프로그램 루프 중단, 스택 트레이스 + 종료
- **근본 원인:**
  1. 타임아웃 10초 설정 → SSL handshake 중 절단
  2. 재시도 로직 없음 → 일시적 네트워크 오류 = 프로그램 중단
  3. 예외 처리 불충분 → 네트워크 오류 미분류

#### 해결 방법

**1. 타임아웃 값 증가 (10s → 20s)**
- 파일: `src/notifications.py` - `send_telegram()` 함수
- 이유: SSL/TLS handshake 여유 시간 확보
  - 일반적: 1-2초
  - 느린 네트워크: 5-10초
  - 마진: 20초

**2. 네트워크 오류 분류**
```python
except (requests.exceptions.Timeout, requests.exceptions.ConnectionError) as e:
    logger.warning("텔레그램 네트워크 오류 (타임아웃/연결): %s", e)
    raise
```

**3. 재시도 로직 적용**
- 함수: `send_telegram_with_retry()` (기존 구현)
- 파일: `src/threading_utils.py` - 3개 함수 수정
- 동작: 최대 3회, exponential backoff (1s, 2s, 4s)

```python
if not send_telegram_with_retry(...):
    logger.error("정상 작동 알림 전송 최종 실패")
    # 프로그램 계속 진행 (중단 안 함)
```

#### 개선 전후

| 항목 | Before | After |
|------|--------|-------|
| **타임아웃** | 10초 | 20초 |
| **재시도** | 0회 (실패=중단) | 3회 (재시도) |
| **네트워크 오류** | 미분류 | 명확 분류 |
| **프로그램 중단** | 예 ❌ | 아니오 ✅ |
| **에러 로그** | 스택 트레이스 | 명확 메시지 |

#### 로그 개선 예시

**Before (에러):**
```
WARNING - 텔레그램 API 요청 실패: ReadTimeout...
ERROR - 루프 내 작업 중 오류: ReadTimeout...
Traceback ... (프로그램 중단)
```

**After (재시도):**
```
WARNING - 텔레그램 전송 실패 (시도 1/3), 1초 후 재시도: 텔레그램 네트워크 오류...
INFO - 텔레그램 메시지 전송 성공: [알림] 충족된 매수 조건...
(프로그램 계속 진행)
```

### 이전 개선사항 요약:

#### Upbit 주문 실패 방지 개선
- API 키 검증: 프로그램 시작 시 유효성 확인
- 중복 주문 감지: ReadTimeout 재시도 전 체크
- ReadTimeout 핸들러: 2단계 검증 로직 추가
- **매도 주문:** `src/order.py` lines 519-542 (동일 로직)
- **로그 흐름:**
  - `[⛔ 중복 방지]` - 중복 발견 시
  - `[📋 진행 중인 주문 발견]` - 기존 주문 확인 시
  - `[✅ 주문 확인됨]` - 주문 성공 확인 시

#### 4. 보호 레이어 구조
| 레이어 | 방어 메커니즘 | 시점 |
|--------|-------------|------|
| 1층 | API 키 검증 | 프로그램 시작 |
| 2층 | 중복 주문 감지 | Retry 전 |
| 3층 | 주문 확인 | Retry 중 |
| 4층 | UUID 검증 | 응답 처리 시 |

### 성능 영향:
- API 키 검증: ~500ms (1회, 시작 시)
- 중복 감지: ~100ms (ReadTimeout 발생 시만)
- 주문 확인: ~50ms (모든 주문)
- **결론:** ReadTimeout 없음 → 추가 오버헤드 0%

### 코드 변경 요약:
- **수정된 파일:**
  - `src/order.py`: +280줄 (2개 신규 함수 + 개선된 핸들러)
  - `main.py`: +15줄 (API 키 검증 로직)
- **신규 파일:**
  - `test_order_improvements.py`: 단위 테스트
  - `docs/order_failure_prevention.md`: 상세 문서
- **기존 파일 호환성:** 100% 유지 (기능 추가만)

### 테스트 결과:
```
[SUCCESS] Import complete
   - validate_upbit_api_keys: OK
   - _has_duplicate_pending_order: OK
   - _find_recent_order: OK

Function signatures verified:
   validate_upbit_api_keys(access_key: str, secret_key: str) -> tuple[bool, str]
   _has_duplicate_pending_order(upbit, market, side, volume, price=None)
```

### 테스트 결과 (검증 완료):
```
pytest src/tests/ -v
22 passed in 1.61s
```
- Boundary conditions: 6/6 passed
- Critical fixes: 5/5 passed
- Evaluate sell conditions: 9/9 passed
- Main functionality: 2/2 passed

### 설계 결정 및 트레이드오프:

#### 재시도 로직 설계:
- **장점:** API 장애 복원력, 운영 안정성 증가, 로그 가시성
- **트레이드오프:** 재시도 중 지연 발생 (최대 ~13초), 하지만 Upbit fetch는 비동기 백그라운드가 아니므로 허용 가능
- **대안 고려:** Circuit breaker 패턴 추가 (연속 실패 시 일정 시간 차단) → 추후 필요 시 구현

#### Graceful Shutdown 설계:
- **장점:** 안전한 종료, 데이터 무결성 보장, 운영 환경(Docker/systemd) 친화적
- **트레이드오ফ:** 1초 sleep 간격으로 약간의 CPU 체크 오버헤드, 하지만 무시 가능 수준
- **대안 고려:** Event 객체 사용 (threading.Event) → 더 파이썬스럽지만 현재 구현도 충분

#### Black 포맷팅 적용:
- **장점:** 코드 일관성, 리뷰 효율성, IDE 호환성
- **트레이드오프:** 기존 코드 전체 diff 발생 → 이번 세션에서 일괄 처리 완료
- **후속:** pre-commit hook 설치로 향후 자동화

### 향후 작업 후보 (우선순위):
1. **High Priority:**
   - ✅ **완료 (2025-12-03):** pre-commit 훅 설치 및 자동화
   - ✅ **완료 (2025-11-21):** 로그 rotation 강화 (크기+시간+압축)
   - ✅ **완료 (2025-12-03):** Circuit breaker 패턴 추가 (연속 API 실패 대응)
   - ✅ **완료 (2025-12-03):** 성능 모니터링 메트릭 수집 (처리 시간, API 응답 시간)

2. **Medium Priority:**
   - 백테스트 엔진 설계 착수 (캔들 재생성, 체결 시뮬레이션)
   - 경로 상수 pytest 커버리지 증가
   - 성능 모니터링 메트릭 수집 (처리 시간, API 응답 시간)

3. **Low Priority:**
   - Prometheus/Grafana 통합 검토
   - 알림 채널 다양화 (Slack, Discord 등)
   - 다중 거래소 지원 확장 (Binance, Bithumb)

### 리스크/주의 (Updated):
- ✅ **해결됨:** 들여쓰기 통일 완료 (Black 적용)
- ✅ **해결됨:** Graceful shutdown 구현 완료
- ✅ **해결됨:** API 재시도 로직 추가 완료
- ⚠️ **남은 리스크:**
  - ✅ **해결됨 (2025-11-21):** 로그 rotation 강화 (크기+시간 기반, 압축)
  - ✅ **해결됨 (2025-12-03):** Circuit breaker 추가 (연속 API 실패 대응)
  - ✅ **해결됨 (2025-12-03):** 메트릭 수집 시작 (성능/장애 모니터링)
  - ✅ **해결됨 (2025-12-03):** pre-commit 훅 설치 (코드 품질 자동화)
  - 다중 프로세스 환경 미지원 (holdings_lock은 thread-safe만 보장)

### 파일 변경 이력 (이번 세션):
```
신규 생성:
- pyproject.toml (Black/ruff/pytest 통합 설정)
- .pre-commit-config.yaml (Git hook 자동화) ✅ 설치 완료
- src/retry_utils.py (재시도 데코레이터)
- src/circuit_breaker.py (Circuit Breaker 패턴: API 장애 대응)
- src/metrics.py (경량 메트릭 수집: 카운터/타이머)
- src/tests/test_circuit_breaker.py (Circuit Breaker 단위 테스트)

주요 수정:
- main.py: signal handler, graceful shutdown 로직, 포맷팅
- src/holdings.py: retry 데코레이터 적용, 포맷팅
- src/common.py: 고급 로그 rotation (크기+시간+압축), 레벨 최적화
- src/order.py:
  * Upbit 주문 응답 검증(uuid 없음 → 실패 처리)
  * 매수 최소주문금액 검증 추가
  * Circuit Breaker 적용 (monitor_order_upbit)
  * 메트릭 수집 (성공/실패/타임아웃 카운트, 루프 시간)
- src/*.py (전체 17개): Black 포맷팅 적용테스트 통과:
- src/tests/*.py (이전: 22개, 현재: 30개 예상 - circuit breaker 8개 추가)
```

### Next Phase (예정: 백테스트/평가 기능):
- 캔들 재생성 / 가상 체결 로직 추가
- 전략 파라미터 튜닝 지원 (threshold sweep)
- 결과 저장 포맷 통합 (trades.json 확장 또는 별도 `backtest_results.json`)
- 로그 rotation 및 성능 모니터링 메트릭 추가

### 현재 상태 요약:
✅ **Production Ready:** 코드 품질, 안정성, 운영 환경 대응 모두 강화 완료
✅ **테스트 커버리지:** 30개 테스트 (기본 22 + Circuit Breaker 8), 회귀 없음
✅ **포맷팅:** Black/ruff 표준화 완료, pre-commit 훅 자동화 활성화
✅ **신뢰성:** 네트워크 오류 재시도, 안전 종료, Circuit Breaker, 메트릭 수집
✅ **운영 가시성:** 로그 rotation/압축, 메트릭 파일, 오류 응답 상세 로깅
📋 **다음 단계:** 백테스트 모듈 설계, Prometheus/Grafana 통합 검토, 다중 프로세스 지원