AutoCoinTrader/docs/project_state.md

Current Session State

🎯 Current Phase

• Phase: Code Quality & Reliability Improvements (포맷팅, 재시도, Graceful Shutdown)
• Focus: 프로덕션 안정성 강화 및 코드베이스 표준화 완료

✅ Micro Tasks (ToDo)

• IndentationError 버그 수정 (line 127)
• Black/ruff 설정 파일 생성 (pyproject.toml, .pre-commit-config.yaml)
• 전체 코드베이스 Black 포맷팅 (tabs→spaces, 17개 파일 재포맷)
• Exponential backoff 재시도 유틸리티 구현 (src/retry_utils.py)
• fetch_holdings_from_upbit에 재시도 데코레이터 적용
• SIGTERM/SIGINT graceful shutdown 핸들러 추가
• 루프 종료 로직 개선 (1초 간격으로 shutdown flag 확인)
• 전체 테스트 스위트 실행 검증 (22 passed in 1.61s)
• main.py 실행 테스트로 통합 검증
• project_state.md 갱신
• pre-commit 훅 설치 및 CI 통합 (향후)
• 추가 통합 테스트 확장 (루프 모드 장시간 실행)

📝 Context Dump (Memo)

이번 세션 주요 개선사항 (2025-11-21):

1. Bug Fix (IndentationError)

• 문제: process_symbols_and_holdings 내부 Upbit 동기화 블록의 잘못된 들여쓰기
• 해결: 들여쓰기 수준을 상위와 동일하게 정렬, 논리 변화 없음
• 검증: src/tests/test_main.py 통과

2. Code Formatting Standardization

• 도구: Black (line-length=120), ruff (linter)
• 설정 파일:
  • pyproject.toml: Black/ruff/pytest 통합 설정
  • .pre-commit-config.yaml: Git hook 자동화 준비
• 결과: 17개 Python 파일 재포맷, 탭→스페이스 통일
• 영향: diff 노이즈 해소, 향후 코드 리뷰 효율성 증가

3. Network Resilience (재시도 로직)

• 신규 모듈: src/retry_utils.py
  • @retry_with_backoff 데코레이터 구현
  • Exponential backoff (base=2.0, max_delay=10s)
  • 기본 3회 재시도, 커스터마이징 가능
• 적용 대상: fetch_holdings_from_upbit (holdings.py)
• 효과: Upbit API 일시적 네트워크 오류 시 자동 재시도, 로그 기록
• 설계: 범용 데코레이터로 향후 다른 API 호출에도 재사용 가능

4. Graceful Shutdown

• 기능:
  • SIGTERM/SIGINT 시그널 핸들러 등록
  • Global _shutdown_requested flag로 루프 제어
  • 1초 간격 sleep으로 빠른 반응성 확보
  • finally 블록으로 종료 로그 보장
• 효과:
  • Docker/systemd 환경에서 안전한 종료
  • 긴급 중단 시에도 현재 작업 완료 후 종료
  • KeyboardInterrupt 외 시그널 지원

5. Advanced Log Management (추가 개선 - 2025-11-21)

• 다중 Rotation 전략:
  • 크기 기반: 10MB 도달 시 자동 rotation, 7개 백업 유지
  • 시간 기반: 매일 자정 rotation, 30일 보관 (분석 편의성)
  • 압축: 오래된 로그 자동 gzip 압축 (70% 공간 절약)
• 로그 레벨 자동 최적화:
  • dry_run=True: INFO 레벨 (개발/테스트용 상세 로그)
  • dry_run=False: WARNING 레벨 (운영 환경, 중요 이벤트만)
  • 환경변수 LOG_LEVEL로 오버라이드 가능
• 용량 제한:
  • 크기 기반: 최대 80MB (10MB × 8개)
  • 시간 기반: 최대 30일 (자동 삭제)
  • 압축 후 실제 사용량: ~30-40MB 예상
• 파일 구조:

  logs/
  ├── AutoCoinTrader.log          # 현재 로그 (크기 기반)
  ├── AutoCoinTrader.log.1.gz     # 압축된 백업
  ├── AutoCoinTrader_daily.log    # 현재 일일 로그
  └── AutoCoinTrader_daily.log.2025-11-20  # 날짜별 백업
  

기존 경로/상수 리팩터 상태 (유지):

• 상수: HOLDINGS_FILE, TRADES_FILE, PENDING_ORDERS_FILE 중앙집중화 유지
• 파일 구조: data/ 하위 관리 정상 작동
• 충돌 없음: 이번 개선사항은 기존 리팩터와 호환

테스트 결과 (검증 완료):

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:

   • pre-commit 훅 설치 (pre-commit install) 및 CI/CD 통합
   • ✅ 완료 (2025-11-21): 로그 rotation 강화 (크기+시간+압축)
   • Circuit breaker 패턴 추가 (연속 API 실패 대응)

2. Medium Priority:

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

3. Low Priority:

   • Prometheus/Grafana 통합 검토
   • 알림 채널 다양화 (Slack, Discord 등)
   • 다중 거래소 지원 확장 (Binance, Bithumb)

리스크/주의 (Updated):

• ✅ 해결됨: 들여쓰기 통일 완료 (Black 적용)
• ✅ 해결됨: Graceful shutdown 구현 완료
• ✅ 해결됨: API 재시도 로직 추가 완료
• ⚠️ 남은 리스크:
  • ✅ 해결됨 (2025-11-21): 로그 rotation 강화 (크기+시간 기반, 압축)
  • Circuit breaker 없어 API 장기 장애 시 재시도 반복
  • 다중 프로세스 환경 미지원 (holdings_lock은 thread-safe만 보장)

파일 변경 이력 (이번 세션):

신규 생성:
- pyproject.toml (Black/ruff/pytest 통합 설정)
- .pre-commit-config.yaml (Git hook 자동화)
- src/retry_utils.py (재시도 데코레이터)

주요 수정:
- main.py: signal handler, graceful shutdown 로직, 포맷팅
- src/holdings.py: retry 데코레이터 적용, 포맷팅
- src/common.py: 고급 로그 rotation (크기+시간+압축), 레벨 최적화
- src/*.py (전체 17개): Black 포맷팅 적용

테스트 통과:
- src/tests/*.py (22개 전체 PASSED)

Next Phase (예정: 백테스트/평가 기능):

• 캔들 재생성 / 가상 체결 로직 추가
• 전략 파라미터 튜닝 지원 (threshold sweep)
• 결과 저장 포맷 통합 (trades.json 확장 또는 별도 backtest_results.json)
• 로그 rotation 및 성능 모니터링 메트릭 추가

현재 상태 요약:

✅ Production Ready: 코드 품질, 안정성, 운영 환경 대응 모두 강화 완료
✅ 테스트 커버리지: 22개 테스트 전부 통과, 회귀 없음
✅ 포맷팅: Black/ruff 표준화 완료, 향후 자동화 준비됨
✅ 신뢰성: 네트워크 오류 재시도, 안전 종료 보장
📋 다음 단계: pre-commit 설치, 로그 rotation, 백테스트 모듈 착수