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

docs/IMPROVEMENTS_REPORT.md

@@ -0,0 +1,101 @@
+# 권장 작업 완료 리포트 (2025-11-21)
+
+## ✅ 완료된 작업
+
+### 1. 코드 포맷팅 표준화
+- **Black & ruff 설정 완료**
+  - `pyproject.toml`: Black/ruff/pytest 통합 설정 (line-length=120, Python 3.11)
+  - `.pre-commit-config.yaml`: Git hook 자동화 준비
+  - 17개 Python 파일 포맷팅 완료 (tabs → spaces)
+
+### 2. 네트워크 복원력 강화
+- **재시도 유틸리티 구현**
+  - `src/retry_utils.py`: Exponential backoff 데코레이터
+  - 최대 3회 재시도, 2초 → 4초 → 8초 (최대 10초)
+  - `fetch_holdings_from_upbit`에 적용: Upbit API 일시 장애 자동 복구
+
+### 3. Graceful Shutdown 구현
+- **안전한 종료 처리**
+  - SIGTERM/SIGINT 시그널 핸들러 등록
+  - 1초 간격으로 shutdown flag 확인 (빠른 반응성)
+  - 현재 작업 완료 후 안전 종료 보장
+  - Docker/systemd 환경 친화적
+
+### 4. 테스트 검증
+- **전체 테스트 통과**
+  - 22개 테스트 모두 PASSED (1.61초)
+  - Boundary conditions, Critical fixes, Sell conditions, Main functionality
+  - 회귀 없음 확인
+
+### 5. 문서화
+- `project_state.md` 업데이트: 상세 컨텍스트 및 설계 결정 기록
+- `requirements.txt` 정리: 의존성 분류 및 코멘트 추가
+
+## 📊 통계
+
+```
+포맷팅된 파일: 17개
+신규 파일: 3개 (pyproject.toml, .pre-commit-config.yaml, src/retry_utils.py)
+테스트 통과: 22/22 (100%)
+코드 커버리지: Boundary(6), Critical(5), Sell(9), Main(2)
+```
+
+## 🎯 다음 단계 권장사항
+
+### High Priority
+1. **pre-commit 훅 설치**
+   ```powershell
+   pre-commit install
+   ```
+2. **로그 rotation 설정**
+   - `RotatingFileHandler` 적용 (10MB, 5개 백업)
+3. **Circuit breaker 패턴**
+   - 연속 API 실패 시 일정 시간 차단
+
+### Medium Priority
+1. 백테스트 엔진 설계
+2. 성능 모니터링 메트릭
+3. 경로 상수 테스트 커버리지
+
+## 🔧 사용 방법
+
+### 포맷팅 자동화
+```powershell
+# 전체 프로젝트 포맷팅
+python -m black .
+
+# Lint 체크
+python -m ruff check .
+
+# Lint 자동 수정
+python -m ruff check --fix .
+```
+
+### Graceful Shutdown 테스트
+```powershell
+# 루프 모드 실행
+python main.py
+
+# 다른 터미널에서
+Stop-Process -Name python -Signal SIGTERM  # 또는 Ctrl+C
+```
+
+### 재시도 로직 모니터링
+로그에서 `[RETRY]` 키워드로 재시도 이벤트 추적:
+```
+[RETRY] fetch_holdings_from_upbit 실패 (1/3): ConnectionError | 2.0초 후 재시도
+[RETRY] fetch_holdings_from_upbit 최종 실패 (3/3): TimeoutError
+```
+
+## ✨ 핵심 개선 효과
+
+1. **안정성 ↑**: API 장애 자동 복구, 안전한 종료
+2. **유지보수성 ↑**: 일관된 코드 스타일, 명확한 구조
+3. **운영 편의성 ↑**: Docker/systemd 친화적, 로그 가시성
+4. **개발 생산성 ↑**: 포맷팅 자동화, CI/CD 준비 완료
+
+---
+
+**Status:** ✅ Production Ready  
+**Last Updated:** 2025-11-21  
+**Test Coverage:** 22/22 PASSED

docs/implementation_plan.md

@@ -0,0 +1,35 @@
+<!--
+단계별 구현 체크리스트
+implementation_plan.md
+-->
+
+# Implementation Plan
+
+이 문서는 프로젝트의 개발 진행 상황을 추적합니다. AI는 이 문서를 참조하여 현재 단계(Context)를 파악하고 작업을 수행해야 합니다.
+
+## Phase 1: 환경 설정 및 기반 구축 (Setup) [ ]
+- [ ] 프로젝트 폴더 구조 생성 및 Git 초기화
+- [ ] `copilot-instructions.md` 및 `.env` 환경 변수 템플릿 설정
+- [ ] 언어별 패키지 매니저 설정 (requirements.txt, package.json, go.mod 등)
+- [ ] 기본 로깅(Logging) 및 설정(Config) 모듈 구현
+
+## Phase 2: 코어 비즈니스 로직 (Core Domain) [ ]
+- [ ] `project_requirements.md`의 핵심 기능을 담당하는 도메인 모델 설계
+- [ ] 데이터 처리 및 비즈니스 로직 구현 (순수 함수 위주)
+- [ ] 핵심 로직에 대한 단위 테스트(Unit Test) 작성 및 통과 확인
+
+## Phase 3: 인터페이스 및 데이터 연동 (Integration) [ ]
+- [ ] 외부 API 연동 또는 데이터베이스 연결 모듈 구현
+- [ ] 사용자 인터페이스(UI) 또는 API 엔드포인트 구현
+- [ ] 예외 처리(Exception Handling) 및 에러 응답 표준화
+
+## Phase 4: 시스템 통합 및 실행 (System Interface) [ ]
+- [ ] 메인 진입점(Entry Point) 구현 (main.py, index.js 등)
+- [ ] 전체 프로세스 통합 테스트 (Integration Test)
+- [ ] 로컬 환경에서의 End-to-End 실행 검증
+
+## Phase 5: 최적화 및 리팩토링 (Refinement) [ ]
+- [ ] 성능 병목 구간 분석 및 비동기/캐싱 적용
+- [ ] `review_prompt.md` 기반 자가 점검 및 코드 품질 개선
+- [ ] 최종 문서화 (README.md 작성)
+- [ ] 프로그램 사용법 작성 (user_guide.md)

docs/project_requirements.md

@@ -0,0 +1,45 @@
+<!--
+기획 및 로직 설계서
+project_requirements.md
+-->
+
+# Product Requirements Document (PRD)
+
+## 1. Project Overview
+- **프로젝트명:** [프로젝트 이름 입력]
+- **해결하려는 문제:** [이 프로젝트가 해결하고자 하는 핵심 문제 정의]
+- **목표:** [프로젝트의 최종 성공 기준]
+- **주요 타겟 유저:** [사용자 페르소나 정의]
+
+## 2. Core Features (User Stories)
+*(우선순위가 높은 순서대로 작성)*
+1.  **[핵심 기능 1]:** [사용자는 ~할 수 있다. 이를 통해 ~를 얻는다.]
+2.  **[핵심 기능 2]:** [상세 설명]
+3.  **[핵심 기능 3]:** [상세 설명]
+4.  **[부가 기능]:** [상세 설명]
+
+## 3. Tech Stack & Architecture
+- **Frontend:** [예: React, Tailwind CSS]
+- **Backend:** [예: Python FastAPI, Node.js]
+- **Database:** [예: PostgreSQL, Redis]
+- **Infra:** [예: AWS Lambda, Docker]
+
+## 4. Data Flow & Logic
+- **Input:** [데이터 입력 소스]
+- **Process:**
+    1. [단계 1: 데이터 수집/수신]
+    2. [단계 2: 핵심 비즈니스 로직 처리]
+    3. [단계 3: 데이터 저장 또는 가공]
+- **Output:** [최종 결과물 형태]
+
+## 5. File Structure Plan (Suggested)
+*(AI가 제안하거나 개발자가 미리 지정)*
+- `/src/core/` : 핵심 비즈니스 로직
+- `/src/api/` : 외부 인터페이스 및 API 핸들러
+- `/src/utils/` : 공통 유틸리티
+- `/tests/` : 단위 및 통합 테스트
+
+## 6. Non-Functional Requirements
+- **성능:** [예: 응답 속도 200ms 이내, 동시 접속 1000명 처리]
+- **보안:** [예: 모든 데이터 전송은 HTTPS, 민감 정보 암호화]
+- **안정성:** [예: 외부 API 실패 시 재시도(Retry) 로직 구현]

docs/project_state.md

@@ -0,0 +1,166 @@
+
+# Current Session State
+
+## 🎯 Current Phase
+- **Phase:** Code Quality & Reliability Improvements (포맷팅, 재시도, Graceful Shutdown)
+- **Focus:** 프로덕션 안정성 강화 및 코드베이스 표준화 완료
+
+## ✅ Micro Tasks (ToDo)
+- [x] IndentationError 버그 수정 (line 127)
+- [x] Black/ruff 설정 파일 생성 (`pyproject.toml`, `.pre-commit-config.yaml`)
+- [x] 전체 코드베이스 Black 포맷팅 (tabs→spaces, 17개 파일 재포맷)
+- [x] Exponential backoff 재시도 유틸리티 구현 (`src/retry_utils.py`)
+- [x] `fetch_holdings_from_upbit`에 재시도 데코레이터 적용
+- [x] SIGTERM/SIGINT graceful shutdown 핸들러 추가
+- [x] 루프 종료 로직 개선 (1초 간격으로 shutdown flag 확인)
+- [x] 전체 테스트 스위트 실행 검증 (22 passed in 1.61s)
+- [x] main.py 실행 테스트로 통합 검증
+- [x] 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, 백테스트 모듈 착수

docs/review_prompt.md

@@ -0,0 +1,108 @@
+<!--
+AI 코드 리뷰 지침
+review_prompt.md
+-->
+
+<!-- 코드 리뷰 프롬프트(실무용, 핵심 위주) -->
+
+<!--
+
+# 코드 리뷰 프롬프트
+다음 지침에 따라 코드를 검토하고 코드 리뷰 레포트(code_review_report.md)를 작성해주세요.
+
+## [1. 분석 컨텍스트]
+언어/환경: (예: Python 3.11, AWS Lambda)
+코드 목적: (예: 결제 로직 처리)
+핵심 요구: (예: 동시성 문제 해결, 성능 최적화)
+
+## [2. 역할 및 원칙]
+당신은 가장 까다로운 시니어 개발자입니다. 칭찬은 생략하고, 오직 **결함(Bug)**과 **위험 요소(Risk)**만 찾아내십시오.
+- 원칙: 코드가 "문제없다"고 가정하지 마십시오. 숨겨진 논리적 오류, 예외 처리 누락, 보안 취약점을 집요하게 파고드십시오.
+- 금지: 코드에 없는 내용을 추측하여 지적하지 마십시오(No Hallucination).
+
+## [3. 중점 검토 항목]
+1. 논리 오류: 엣지 케이스(Null, 0, 경계값)에서 로직이 깨지지 않는가?
+2. 안정성: 예외가 발생했을 때 시스템이 안전하게 복구되거나 종료되는가? (Silent Failure 방지)
+3. 보안: SQL 인젝션, XSS, 민감 정보(비번/키) 노출이 있는가?
+4. 효율성: 불필요한 반복문(O(n²))이나 메모리 누수가 있는가?
+
+## [4. 출력 형식]
+발견된 문제가 없다면 "특이사항 없음"이라고 하십시오. 문제가 있다면 아래 양식으로 핵심만 적어주세요.
+
+### 🚨 치명적 문제 (Critical)
+- 위치: [라인 번호 또는 코드 스니펫]
+- 이유: (왜 위험한지 기술적 설명)
+- 해결책: (수정된 코드 블록)
+
+### ⚠️ 개선 제안 (Warning)
+- 위치: [라인 번호]
+- 내용: (잠재적 위험 또는 가독성/성능 개선 제안)
+
+-->
+
+<!-- 코드 리뷰 프롬프트(심화버전) -->
+
+# 코드 리뷰 프롬프트
+다음 지침에 따라 코드를 검토하고 코드 리뷰 레포트(code_review_report.md)를 작성해주세요.
+
+## [1. 분석 컨텍스트]
+정확한 분석을 위해 아래 정보를 기반으로 코드를 검토하십시오.
+- 언어/프레임워크: (예: Python 3.11, React 18, Spring Boot)
+- 코드의 목적: (예: 사용자 인증, 데이터 파싱, 결제 트랜잭션)
+- 주요 제약사항: (예: 높은 동시성, 메모리 최적화, 엄격한 보안 기준)
+
+## [2. 역할 및 원칙]
+당신은 '무관용 원칙'을 가진 수석 소프트웨어 아키텍트입니다.
+- 목표: 칭찬보다는 결함(Bug), 보안 취약점, 성능 병목, 유지보수 저해 요소를 찾아내는 데 집중하십시오.
+- 금지: 코드에 없는 내용을 추측하여 지적하지 마십시오(Zero Hallucination).
+- 기준: "작동한다"에 만족하지 말고, "견고하고 안전한가"를 기준으로 판단하십시오.
+
+## [3. 사전 단계: 의도 파악]
+분석 전, 이 코드가 수행하는 핵심 로직을 3줄 이내로 요약하여, 당신이 코드를 올바르게 이해했는지 먼저 보여주십시오.
+
+## [4. 심층 검토 체크리스트]
+다음 항목을 기준으로 코드를 해부하십시오.
+### 1. 논리 및 엣지 케이스 (Logic & Edge Cases)
+- 가상 실행: 코드를 한 줄씩 추적하며 변수 상태 변화를 검증했는가?
+- 경계값: Null, 빈 값, 음수, 최대값 등 극한의 입력에서 로직이 깨지지 않는가?
+- 예외 처리: 에러를 단순히 삼키지 않고(Silent Failure), 적절히 처리하거나 전파하는가?
+- 모듈성 및 API 설계: 함수/클래스의 공개 인터페이스(Public Interface)가 직관적이고 일관성이 있는가? 테스트 용이성(Testability)을 위해 의존성이 잘 분리되었는가?
+
+### 2. 보안 및 안정성 (Security & Stability)
+- 입력 검증: SQL 인젝션, XSS, 버퍼 오버플로우 취약점이 없는가?
+- 정보 노출: 비밀번호, API 키, PII(개인정보)가 하드코딩되거나 로그에 남지 않는가?
+- 자원 관리 및 메모리 안정성:
+    - 일반: 파일, DB 연결, 네트워크 소켓 등 모든 자원은 예외 발생 시에도 확실히 해제되는가?
+    - 언어별 핵심 원칙 (조건부 검증):
+        - (C++ 프로젝트인 경우): Raw pointer (`new`/`delete`)가 발견되지 않는가? 동적 자원은 스마트 포인터(RAII)로 관리되며, 함수가 예외 안전성을 제공하는가?
+        - (Python 프로젝트인 경우): 불필요한 참조 순환이나 메모리 누수 패턴이 없는가? 멀티스레딩 환경에서 동시성(Locking) 처리가 올바른가?
+
+### 3. 동시성 및 성능 (Concurrency & Performance)
+- 동기화: (해당 시) 경쟁 상태(Race Condition), 데드락, 스레드 안전성 문제가 없는가?
+- 효율성: 불필요한 중첩 반복문(O(n²))이나 중복 연산이 없는가?
+- 시스템 성능:
+    - I/O 병목: DB 쿼리나 네트워크 호출이 불필요하게 반복(N+1 쿼리)되거나 동기적으로 실행되어 시스템 전체를 막는 부분이 없는가?
+    - C++ (캐시 효율): 대용량 데이터 구조 설계 시 CPU 캐시 효율성(Cache Locality)이 고려되었는가?
+
+## [5. 출력 형식: 결함 보고서]
+발견된 문제가 없다면 "특이사항 없음"으로 명시하십시오. 문제가 있다면 아래 양식을 엄수해 주세요.
+
+### 🚨 치명적 문제 (Critical Issues)
+(서비스 중단, 데이터 손실/오염, 보안 사고 위험이 있는 경우)
+
+[C-1] 문제 제목
+├─ 위치: [파일경로:라인] 또는 [코드 스니펫 3~5줄]
+├─ 원인: [기술적 원인 설명]
+├─ 재현/조건: [문제가 발생하는 상황]
+└─ 해결책: [수정된 코드 블록 (Auto-Fix)]
+
+### ⚠️ 개선 제안 (Warnings & Improvements)
+(성능 저하, 유지보수성 부족, 잠재적 버그)
+
+[W-1] 문제 제목
+├─ 위치: [파일경로:라인] 또는 [코드 스니펫]
+├─ 분석: [문제점 설명]
+└─ 권장 조치: [리팩토링 제안]
+
+### ✅ 잘된 점 (Strengths)
+(핵심적인 장점 1~2가지만 간결하게)

docs/user_guide.md

@@ -0,0 +1,132 @@
+# AutoCoinTrader 사용 가이드
+
+## 개요
+AutoCoinTrader는 Upbit 시세 데이터를 기반으로 MACD, SMA, ADX 지표를 활용해 매수/매도 신호를 분석하고(`dry_run` 모드), 설정에 따라 자동 주문까지 수행할 수 있는 트레이딩 보조/자동화 도구입니다. 모든 주요 상태 파일(`holdings.json`, `trades.json`, `pending_orders.json`)은 `data/` 디렉터리 하위에서 관리됩니다.
+
+## 1. 사전 준비
+### 1.1 필수 요구사항
+1. Python 3.11 이상
+2. 가상환경 권장 (venv, pyenv, Conda 등)
+3. Upbit API 키 (자동매매 사용 시)
+4. Telegram Bot Token & Chat ID (알림 사용 시)
+
+### 1.2 설치
+```powershell
+python -m venv .venv; .\.venv\Scripts\activate
+pip install -r requirements.txt
+```
+
+### 1.3 환경변수 설정 (`.env`)
+`.env` 파일에 아래 항목을 필요 시 추가:
+```bash
+TELEGRAM_BOT_TOKEN=123456789:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+TELEGRAM_CHAT_ID=123456789
+UPBIT_ACCESS_KEY=YOUR_UPBIT_ACCESS
+UPBIT_SECRET_KEY=YOUR_UPBIT_SECRET
+
+# 선택 기능
+AGGREGATE_ALERTS=false
+TELEGRAM_TEST=0
+AUTO_TRADE_ENABLED=0   # require_env_confirm 활성화 시 1로 설정해야 자동매매 진행
+ORDER_MONITOR_TIMEOUT=120
+ORDER_POLL_INTERVAL=3
+ORDER_MAX_RETRIES=1
+ORDER_MAX_CONSECUTIVE_ERRORS=5
+```
+`UPBIT_*` 키는 실거래(dry_run=False) + 자동매매(trading_mode=auto_trade/mixed)에서 필수.
+`.env`는 반드시 `.gitignore`에 포함시키십시오.
+
+## 2. 설정 파일 (`config/config.json`)
+미존재 시 기본값이 내부 로직에서 자동 로드됩니다. 핵심 항목:
+| 키 | 설명 | 기본값 |
+|----|------|--------|
+| candle_count | 각 심볼 지표 계산에 사용하는 캔들 개수 | 200 |
+| buy_check_interval_minutes | 매수 조건 검사 주기 | 240 |
+| stop_loss_check_interval_minutes | 손절 검사 주기 | 60 |
+| profit_taking_check_interval_minutes | 익절 검사 주기 | 240 |
+| loop | True면 주기적 루프 실행 | True |
+| dry_run | True면 시뮬레이션 기록만 | True |
+| max_threads | 병렬 스레드 수 | 3 |
+| trading_mode | signal_only / auto_trade / mixed | signal_only |
+| auto_trade.buy_enabled | 자동 매수 허용 여부 | False |
+| auto_trade.buy_amount_krw | 1회 매수 금액 | 10000 |
+| auto_trade.min_order_value_krw | 최소 주문 허용 KRW | 5000 |
+| auto_trade.loss_threshold | 손절 기준(%) | -5.0 |
+| auto_trade.profit_threshold_1 | 부분 익절 시작 수익률(%) | 10.0 |
+| auto_trade.profit_threshold_2 | 전량 익절 고수익 기준(%) | 30.0 |
+| auto_trade.drawdown_1 | 중간 구간 트레일링 하락률(%) | 5.0 |
+| auto_trade.drawdown_2 | 고수익 구간 트레일링 하락률(%) | 15.0 |
+
+## 3. 주요 데이터 파일 (data/)
+| 파일 | 용도 |
+|------|------|
+| holdings.json | 현재 보유 코인 상태 (매수 평균가, 수량, max_price 등) |
+| trades.json | 매수/매도 기록 (원자적 저장) |
+| pending_orders.json | 사용자 확인 대기 중인 주문 토큰 목록 |
+
+모든 경로는 코드 내부에서 `src.common`의 상수를 통해 관리되므로 재배치 시 해당 상수만 수정하면 됩니다.
+
+## 4. 실행 방법
+### 4.1 기본 실행 (드라이런)
+```powershell
+python main.py
+```
+루프 모드, 설정 주기에 따라 매수/손절/익절 검사 수행. `data/` 하위에 기록 생성.
+
+### 4.2 벤치마크 실행
+```powershell
+python main.py --benchmark
+```
+순차/병렬 처리 시간 비교 후 로그 출력.
+
+### 4.3 실거래 모드 전환
+1. `config.json`에서 `dry_run`을 `false`, `trading_mode`를 `auto_trade` 또는 `mixed`로 설정.
+2. `.env`에 `UPBIT_ACCESS_KEY`, `UPBIT_SECRET_KEY` 추가.
+3. (선택) `AUTO_TRADE_ENABLED=1` 설정 (require_env_confirm일 경우 필수).
+4. 소액으로 먼저 검증 후 확장.
+
+### 4.4 Telegram 알림 테스트
+`.env`에 `TELEGRAM_TEST=1` 설정 후 최초 실행 시 시작 메시지 전송.
+
+## 5. 매수/매도 로직 개요
+1. 매수 조건: MACD 교차, SMA 단기>장기, ADX 임계 초과 조합 (3가지 패턴)
+2. 매도 조건: 손절(초기 하락), 부분 익절 후 수익 보호, 트레일링 익절 (구간별 다른 하락률 적용)
+3. 부분 익절 1회 후 `partial_sell_done` 플래그로 중복 익절 방지.
+
+## 6. 수동 확인 기반 주문 흐름
+자동매매 모드에서 주문은 `pending_orders.json`에 기록 → 사용자가 `confirm_<토큰>` 파일 생성 → 타임아웃 내 확인되면 주문 실행.
+
+## 7. 로그
+`logs/AutoCoinTrader.log` 회전 로그(최대 10MB, 백업 7개). `LOG_DIR`, `LOG_LEVEL` 환경변수로 조정 가능.
+
+## 8. Troubleshooting
+| 증상 | 원인 | 해결 |
+|------|------|------|
+| 실거래 안 됨 | API 키 미설정 | `.env` 키 추가 및 dry_run False |
+| 텔레그램 알림 없음 | 토큰/채팅ID 누락 | `.env` 값 확인 |
+| 부분 체결 후 holdings 미반영 | 네트워크 지연 | 로그에서 monitor 결과 확인 후 수동 조정 |
+| trades.json 손상 | 비정상 종료 | 자동 백업(`.corrupted.<ts>`) 후 재생성됨 |
+
+## 9. 성능 & 안정성 팁
+1. 스레드 수(`max_threads`)를 심볼 수 대비 과도하게 늘리지 말 것 (IO 포화 발생 가능).
+2. 캔들 개수(`candle_count`)는 필요 이상 크게 하면 지표 계산 비용 증가.
+3. 네트워크 오류 다발 시 `ORDER_MAX_CONSECUTIVE_ERRORS` 조정.
+
+## 10. 백테스트 확장 (향후 계획)
+`data/` 구조 유지 + 별도 `backtest/` 모듈에서 동일 지표 계산 후 결과 비교, `trades.json` 포맷 재사용. (구현 예정)
+
+## 11. FAQ
+**Q: dry_run과 auto_trade 차이?**  
+A: dry_run은 모든 거래를 기록만 하고 실제 주문을 보내지 않음. auto_trade는 조건 충족 시 주문 API 호출.
+
+**Q: 부분 익절 후 재매도는 어떻게?**  
+A: `partial_sell_done` 플래그 True 후 트레일링 조건 또는 수익 보호 조건 충족 시 전량 매도.
+
+**Q: trades.json 손상 시?**  
+A: 자동으로 `.corrupted.<timestamp>` 백업 후 새로 시작. 백업 파일 검토 가능.
+
+**Q: 설정 변경 반영 시점?**  
+A: 프로세스 재시작 필요. 장기 실행 중에는 실시간 반영 안 함.
+
+**Q: 최소 주문 금액 미만 상황?**  
+A: 매도/매수 모두 안전하게 건너뛰고 로그와 텔레그램 알림(선택)으로 통지.

docs/workflow.md

@@ -0,0 +1,70 @@
+<!-- 사용 방법 (워크플로우) -->
+
+# Automated Development Workflow Protocol
+
+이 문서는 AI가 프로젝트를 **자동으로 진행**하기 위한 행동 수칙을 정의합니다.
+사용자가 **"워크플로우로 진행해줘"**라고 명령하면, AI는 아래 **[Execution Loop]**를 따릅니다.
+
+## 🔄 Execution Loop (반복 실행 규칙)
+
+AI는 다음 순서를 엄격히 준수해야 합니다.
+
+1.  **Status Check (상태 확인):**
+    - `implementation_plan.md`를 읽고, **체크되지 않은( `[ ]` ) 가장 첫 번째 Phase**를 식별합니다.
+2.  **Proposal & Approval (제안 및 승인 요청):**
+    - 사용자에게 현재 진행해야 할 Phase와 수행할 작업 내용을 요약하여 보고합니다.
+    - **"Phase X 작업을 시작하시겠습니까?"** 라고 묻고, **사용자의 승인(Yes/Go)을 대기**합니다. (즉시 코드를 작성하지 마십시오.)
+3.  **Execution (실행):**
+    - 사용자가 승인하면, 아래 **[Phase Detail Prompts]**에 정의된 해당 단계의 지침에 따라 코드를 작성합니다.
+    - 이때 반드시 `copilot-instructions.md`의 C++/Python 규칙과 `project_requirements.md`의 요구사항을 준수합니다.
+4.  **Update Plan (플랜 업데이트):**
+    - 작업이 완료되면 `implementation_plan.md`의 해당 항목을 체크(`[x]`) 표시하여 업데이트합니다.
+5.  **Self-Correction (자가 점검):**
+    - 작성된 코드가 `review_prompt.md`의 기준(성능, 예외 처리 등)을 충족하는지 확인하고, 부족한 점이 있다면 스스로 수정합니다.
+
+---
+
+## 📋 Phase Detail Prompts (단계별 수행 지침)
+
+AI는 실행 단계(Execution)에서 현재 Phase에 맞는 아래 지침을 수행합니다.
+
+### Phase 1: 환경 설정 (Setup)
+- **목표:** 프로젝트 기반 마련 및 의존성 설정
+- **지침:**
+  1. `copilot-instructions.md`의 Tech Stack을 확인하여 폴더 구조 생성.
+  2. Python(`requirements.txt`, `.env`) 및 C++(`CMakeLists.txt`) 설정 파일 작성.
+  3. `.gitignore` 및 기본 설정 파일 생성.
+
+### Phase 2: 코어 로직 구현 (Core Domain)
+- **목표:** 비즈니스 로직 및 데이터 모델 구현
+- **지침:**
+  1. 코딩 전, **알고리즘 설계와 시간 복잡도**를 주석으로 먼저 작성.
+  2. `copilot-instructions.md`의 **Core Principles**를 준수하여 순수 함수/클래스 구현.
+  3. 반드시 **단위 테스트(Unit Test)** 코드를 함께 작성.
+
+### Phase 3: 인터페이스 연동 (Integration)
+- **목표:** 외부 API, DB, UI 연동
+- **지침:**
+  1. 외부 시스템과의 통신 로직 구현.
+  2. **Error Handling:** 네트워크 실패, 타임아웃 등을 대비한 방어 코드(`try-except`, `RAII`) 작성.
+  3. `project_requirements.md`의 데이터 흐름(Data Flow) 준수 확인.
+
+### Phase 4: 시스템 통합 (System Interface)
+- **목표:** 메인 진입점 및 전체 프로세스 연결
+- **지침:**
+  1. `main.py` 또는 `main.cpp` 진입점 구현.
+  2. 전체 모듈을 연결하고 통합 테스트(Integration Test) 시나리오 작성.
+  3. 실제 실행 가능한 상태인지 검증.
+
+### Phase 5: 최적화 및 리팩토링 (Refinement)
+- **목표:** 품질 향상 및 안정화
+- **지침:**
+  1. `review_prompt.md`를 기준으로 전체 코드 리뷰 수행.
+  2. 성능 병목(O(N^2) 이상) 및 메모리 누수 점검.
+  3. 최종 문서(README.md) 작성.
+
+---
+
+## 🛑 Exception Handling
+- 작업 중 에러가 발생하거나 정보가 부족하면 즉시 중단하고 사용자에게 구체적인 질문을 하십시오.
+- 사용자가 "중단" 또는 "수정"을 요청하면 즉시 루프를 멈추고 지시를 따르십시오.

docs/workflow_manual.md

@@ -0,0 +1,91 @@
+<!-- 사용 방법 (워크플로우) -->
+
+# Manual Usage & Prompt Guide
+
+이 문서는 **자동 워크플로우(`workflow.md`)를 사용하지 않거나**, 특정 단계만 **수동으로 실행/재실행**해야 할 때 사용하는 프롬프트 모음집입니다. 상황에 맞는 프롬프트를 선택하여 AI에게 복사-붙여넣기 하세요.
+
+---
+
+## 1. 프로젝트 시작 및 초기화 (Initialization)
+
+**상황:** 새로운 세션을 시작하거나, AI가 프로젝트 문맥을 잊어버렸을 때 사용합니다.
+
+### 📂 Step 1: 문맥 주입 (Context Loading)
+> "첨부된 `copilot-instructions.md`, `project_requirements.md`, `implementation_plan.md`를 모두 읽고, 이 프로젝트의 목표와 내가 구축하려는 시스템의 아키텍처를 요약해주세요. 그리고 `implementation_plan.md`의 단계들이 적절한지 검토해주세요."
+
+### 🔍 Step 2: 계획 검증 (Plan Validation)
+> "`implementation_plan.md`의 내용이 충분히 구체적인가? 만약 부족한 부분이 있다면 Python/C++ 프로젝트 표준에 맞춰서 수정해주세요. (수정이 없다면 이 단계는 생략)"
+
+---
+
+## 2. 단계별 실행 프롬프트 (Phase Execution)
+
+**상황:** `implementation_plan.md`의 특정 단계를 실행할 때 사용합니다. (원하는 단계만 골라서 사용 가능)
+
+### 🚀 Phase 1: 환경 설정 (Setup)
+> "`implementation_plan.md`의 **[Phase 1]** 작업을 시작한다.
+> `copilot-instructions.md`의 **Tech Stack**에 맞춰 폴더 구조를 잡고, 필요한 설정 파일(.env, requirements.txt, CMakeLists.txt 등)을 작성해줘.
+> 작성 후에는 `implementation_plan.md`의 해당 항목을 체크(x)해주세요."
+
+### 🧩 Phase 2: 코어 로직 구현 (Core Domain)
+> "`implementation_plan.md`의 **[Phase 2]** 작업을 수행한다.
+> `copilot-instructions.md`의 **Core Principles**를 준수하여 비즈니스 로직과 도메인 모델을 구현해주세요.
+> **중요:** 코드를 작성하기 전에 **로직 설계와 시간 복잡도**를 먼저 설명하고, 반드시 **단위 테스트(Unit Test)** 코드를 함께 작성해주세요."
+
+### 🔌 Phase 3: 인터페이스 연동 (Integration)
+> "`implementation_plan.md`의 **[Phase 3]** 작업을 수행한다.
+> 외부 API 연동, DB 연결, 또는 UI 컴포넌트를 구현해주세요.
+> **Error Handling:** 예외 상황(네트워크 실패, DB 연결 끊김 등)에 대한 처리를 `try-except`(Python) 또는 `RAII/Exception Safety`(C++) 규칙에 맞춰 견고하게 작성해주세요."
+
+### 🖥️ Phase 4: 시스템 통합 (System Interface)
+> "`implementation_plan.md`의 **[Phase 4]** 작업을 수행한다.
+> 전체 모듈을 하나로 묶는 메인 진입점(Main Entry Point)을 작성하고, 전체 프로세스가 유기적으로 동작하는지 검증하는 **통합 테스트(Integration Test)** 시나리오를 작성해주세요."
+
+### ⚡ Phase 5: 최적화 및 리팩토링 (Refinement)
+> "`implementation_plan.md`의 **[Phase 5]** 작업을 수행한다.
+> 현재 코드에서 **성능 병목(O(N^2) 이상)**이 발생할 수 있는 구간이나 **메모리 누수** 가능성을 분석해주세요.
+> 그 후, `review_prompt.md`의 기준에 따라 스스로 코드를 리뷰하고 개선안을 적용해주세요."
+
+---
+
+## 3. 자동 진행 및 복구 (Auto-Pilot & Recovery)
+
+**상황:** 다음 할 일을 AI가 스스로 찾게 하거나, 꼬인 상황을 풀 때 사용합니다.
+
+### 🤖 Auto-Pilot (알아서 다음 단계 진행)
+> "`implementation_plan.md`를 확인해서 **아직 완료되지 않은(체크되지 않은) 가장 첫 번째 작업**을 수행해주세요.
+> `copilot-instructions.md`의 규칙을 철저히 지켜서 코드를 작성하고, 작업이 끝나면 플랜 파일을 업데이트해주세요."
+
+### 🚑 Troubleshooting (품질/방향성 교정)
+
+**Q. AI가 엉뚱하거나 질 낮은 코드를 작성할 때**
+> "방금 작성한 코드를 멈추고, `review_prompt.md`를 기준으로 다시 리뷰해주세요. 치명적인 결함이나 개선할 점을 찾아서 보고하고 코드를 수정해주세요."
+
+**Q. 진행 상황(체크박스)이 실제와 다를 때**
+*(사용자가 파일을 직접 수정한 뒤 명령)*
+> "`implementation_plan.md` 파일을 다시 읽어봐. 내가 현재 진행 상황을 업데이트했으니, 체크되지 않은 항목부터 다시 작업을 이어가주세요."
+
+
+
+
+
+copilot-instructions.md 지침을 따라서 작업해주세요.
+project_requirements.md 파일에 작성된 템플릿에 맞춰 프로그램 요구사항을 작성한 후
+implementation_plan.md 파일에 작성된 템플릿에 맞춰 작업계획을 작성해주세요.
+프로그램 요구사항과 작업계획을 작성하기전에 필요한 데이터가 부족하면 물어보고 데이터 준비가 완료되면 작성해주세요.
+프로그램에 요구되는 기능은 다음과 같습니다.
+
+현재 개발된 코드에 추가적인 기능을 구현하려합니다.
+제가 알고있기로는 trades.json 파일에 매수/매도한 종목을 기록하고있는것으로 알고있습니다.
+매수/매도한 종목을 기록할때 "매수 평가" 또는 "매도 평가" 항목을 추가..의미가 없을 듯..
+
+백테스트 프로젝트를 따로 만들고 백테스트 기능과 매매 평가 기능 추가 후 시뮬레이션 및 튜닝
+
+
+더 필요한 내용이 있다면 물어봐주세요.
+
+workflow.md 지침에 따라 작업을 진행해주세요.
+
+review_prompt.md 지침에 따라 코드를 검토해주세요.
+
+이 프로그램을 사용하는 방법을 user_guide.md 파일에 작성해줘.