shuim/auto-stock
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

수정본

Browse Source
This commit is contained in:
shuim
2026-02-22 17:23:20 +09:00
parent b147498c31
commit 32e2263f0a
109 changed files with 13979 additions and 4580 deletions
Download Patch File Download Diff File Expand all files Collapse all files

308
docs/API_DOCS.md Normal file
View File

@@ -0,0 +1,308 @@
# Auto Stock Trading System - API 문서
## Backend API
### 기본 정보
- **Base URL**: `http://localhost:8000/api/v1`
- **인증**: Bearer Token (JWT)
## 엔드포인트
### 1. Trading Rules (트레이딩 규칙)
#### 규칙 목록 조회
```http
GET /api/v1/rules
```
**Query Parameters:**
- `skip` (int): 건너뛸 개수 (기본: 0)
- `limit` (int): 조회할 개수 (기본: 100)
- `is_active` (bool): 활성화 필터 (선택)
**Response:**
```json
[
{
"id": 1,
"name": "기본 매수 규칙",
"description": "RSI 30 이하이고 거래량이 평균보다 높을 때 매수",
"rule_type": "BUY",
"conditions": {
"rsi_below": 30,
"volume_above_average": 1.5
},
"actions": {
"order_type": "BUY",
"quantity_percent": 10,
"max_amount": 1000000
},
"is_active": true,
"priority": 10,
"created_at": "2024-11-04T00:00:00",
"updated_at": "2024-11-04T00:00:00"
}
]
```
#### 규칙 생성
```http
POST /api/v1/rules
```
**Request Body:**
```json
{
"name": "새 규칙",
"description": "설명",
"rule_type": "BUY",
"conditions": {},
"actions": {},
"is_active": true,
"priority": 10
}
```
#### 규칙 수정
```http
PUT /api/v1/rules/{rule_id}
```
#### 규칙 삭제
```http
DELETE /api/v1/rules/{rule_id}
```
#### 규칙 활성화/비활성화
```http
POST /api/v1/rules/{rule_id}/toggle
```
### 2. Trades (거래 이력)
#### 거래 이력 조회
```http
GET /api/v1/trades
```
**Query Parameters:**
- `skip`, `limit`: 페이지네이션
- `stock_code` (string): 종목 코드 필터
- `status` (string): 상태 필터 (PENDING, EXECUTED, FAILED)
- `order_type` (string): 주문 유형 (BUY, SELL)
- `days` (int): 조회 기간 (기본: 30일)
#### 거래 통계
```http
GET /api/v1/trades/stats/summary?days=30
```
**Response:**
```json
{
"period_days": 30,
"total_trades": 150,
"buy_trades": 75,
"sell_trades": 75,
"executed_trades": 140,
"failed_trades": 10,
"success_rate": 0.933,
"total_amount": 50000000
}
```
### 3. Portfolio (포트폴리오)
#### 포트폴리오 조회
```http
GET /api/v1/portfolio
```
**Response:**
```json
[
{
"id": 1,
"stock_code": "005930",
"stock_name": "삼성전자",
"quantity": 10,
"average_price": 70000,
"current_price": 71000,
"profit_loss": 10000,
"profit_loss_rate": 1.43
}
]
```
#### 포트폴리오 동기화
```http
GET /api/v1/portfolio/sync
```
실제 증권 계좌와 포트폴리오를 동기화합니다.
#### 포트폴리오 요약
```http
GET /api/v1/portfolio/summary
```
**Response:**
```json
{
"total_stocks": 5,
"total_value": 10000000,
"total_investment": 9500000,
"total_profit_loss": 500000,
"total_profit_loss_rate": 5.26
}
```
### 4. Market Data (시장 데이터)
#### 주식 현재가 조회
```http
GET /api/v1/market/price/{stock_code}
```
**Response:**
```json
{
"stock_code": "005930",
"current_price": 71000,
"change_rate": 1.5,
"volume": 1000000,
"high_price": 71500,
"low_price": 70000,
"open_price": 70500
}
```
#### 차트 데이터 조회
```http
GET /api/v1/market/chart/{stock_code}?period=D
```
**Query Parameters:**
- `period` (string): D (일봉), W (주봉), M (월봉)
### 5. MCP (Model Context Protocol)
#### MCP 서버 상태
```http
GET /api/v1/mcp/status
```
**Response:**
```json
{
"status": "connected",
"mcp_server_url": "http://mcp-server:8001",
"details": {
"status": "healthy",
"claude_configured": true
}
}
```
#### MCP 도구 목록
```http
GET /api/v1/mcp/tools
```
#### MCP 도구 호출
```http
POST /api/v1/mcp/tools/call
```
**Request Body:**
```json
{
"tool_name": "get_market_data",
"parameters": {
"stock_code": "005930",
"period": "D"
}
}
```
#### Claude AI 분석 요청
```http
POST /api/v1/mcp/analyze
```
**Request Body:**
```json
{
"analysis_type": "RULE_VALIDATION",
"data": {
"rule": {},
"market_data": {}
}
}
```
**Analysis Types:**
- `RULE_VALIDATION`: 규칙 검증
- `MARKET_ANALYSIS`: 시장 분석
- `RISK_ASSESSMENT`: 리스크 평가
## WebSocket
### 연결
```javascript
const ws = new WebSocket('ws://localhost:8000/ws/{client_id}')
```
### 메시지 타입
#### Market Update
```json
{
"type": "market_update",
"stock_code": "005930",
"data": {
"price": 71000,
"change_rate": 1.5
}
}
```
#### Trade Notification
```json
{
"type": "trade_notification",
"data": {
"order_id": "ORD001",
"status": "EXECUTED"
}
}
```
#### MCP Status
```json
{
"type": "mcp_status",
"data": {
"status": "connected"
}
}
```
## 에러 응답
모든 에러는 다음 형식으로 반환됩니다:
```json
{
"detail": "에러 메시지"
}
```
**상태 코드:**
- `400`: Bad Request
- `401`: Unauthorized
- `404`: Not Found
- `500`: Internal Server Error
- `504`: Gateway Timeout

285
docs/API_SAFE_OPERATION.md Normal file
View File

@@ -0,0 +1,285 @@
# 모의투자 API 안전 운영 가이드
한국투자증권 모의투자 API를 안전하고 안정적으로 운영하기 위한 재시도 및 쓰로틀링 전략이 적용되어 있습니다.
## 주요 기능
### 1. 안전한 재시도 전략 (Exponential Backoff)
- **재시도 횟수 제한**: 최대 3회 (설정 가능)
- **점진적 백오프**: 재시도 간격이 지수적으로 증가 (1.5초 → 3초 → 6초)
- **오류 유형 분별**:
- 429 (Rate Limit), 5xx (서버 오류): 재시도 실행
- 4xx (클라이언트 오류, 인증 실패): 즉시 종료
- **타임아웃 처리**: 30초 타임아웃 + 재시도 로직
### 2. 쓰로틀링 전략
- **초당 호출 제한**: 기본 0.5초 간격 (초당 2회 권장)
- **동시 요청 제한**: 최대 2건의 동시 요청 (세마포어 사용)
- **자동 간격 조절**: 마지막 요청 시간 기반 자동 대기
### 3. 모니터링 & 경고
- **실시간 통계 수집**: 총 호출 수, 오류율, 재시도 횟수, 평균 응답 시간
- **오류율 경고**: 30% 초과 시 자동 경고
- **API 상태 체크 엔드포인트**: `/api/v1/monitoring/api-stats`
---
## 환경 변수 설정
`.env` 파일에 다음 설정을 추가하여 조절할 수 있습니다:
```bash
# API 재시도 설정
API_MAX_RETRIES=3 # 최대 재시도 횟수 (기본: 3)
API_RETRY_DELAY=1.5 # 초기 재시도 대기 시간(초) (기본: 1.5)
API_RETRY_BACKOFF=2.0 # 지수 백오프 배율 (기본: 2.0)
# API 쓰로틀링 설정
API_MIN_REQUEST_INTERVAL=0.5 # 최소 요청 간격(초) - 초당 2회 (기본: 0.5)
API_MAX_CONCURRENT_REQUESTS=2 # 동시 최대 요청 수 (기본: 2)
API_TIMEOUT=30.0 # API 타임아웃(초) (기본: 30.0)
# 모니터링 설정
API_ERROR_THRESHOLD=0.3 # 오류율 경고 임계값 (기본: 30%)
API_MONITORING_WINDOW=100 # 모니터링 윈도우 크기 (기본: 100개 요청)
```
---
## API 사용 예시
### 기본 사용 (자동 재시도 + 쓰로틀링)
```python
from app.services.korea_investment_api import korea_investment_api
# 현재가 조회 (자동 재시도 및 쓰로틀링 적용)
result = await korea_investment_api.get_current_price("005930")
# 일봉 데이터 조회
chart = await korea_investment_api.get_daily_chart("005930")
# 종목 리스트 조회
stocks = await korea_investment_api.get_stock_list("J") # KOSPI
```
### 통계 조회
```python
# API 호출 통계 확인
stats = korea_investment_api.get_monitor_stats()
print(f"총 호출: {stats['total_calls']}건")
print(f"오류율: {stats['error_rate']:.1%}")
print(f"평균 응답 시간: {stats['avg_duration']:.2f}초")
# 로그에 통계 출력
korea_investment_api.log_monitor_stats()
```
---
## 모니터링 API 엔드포인트
### 1. API 통계 조회
```bash
GET http://localhost:8000/api/v1/monitoring/api-stats
```
**응답 예시:**
```json
{
"status": "healthy",
"stats": {
"total_calls": 150,
"total_errors": 5,
"total_retries": 8,
"error_rate": 0.033,
"avg_duration": 1.25,
"recent_calls": 100
},
"message": "오류율: 3.3%, 평균 응답: 1.25초"
}
```
### 2. 헬스체크
```bash
GET http://localhost:8000/api/v1/monitoring/health
```
**응답 예시:**
```json
{
"status": "healthy",
"error_rate": 0.033,
"total_calls": 150,
"timestamp": "2025-11-10T09:30:00"
}
```
### 3. 통계 로깅
```bash
POST http://localhost:8000/api/v1/monitoring/log-stats
```
---
## 배치 스크립트 실행
매일 아침 9시 전체 종목 분석을 실행하는 배치 스크립트:
### 테스트 실행 (10개 종목만)
```bash
cd backend
python batch_daily_analysis.py --test
```
### 제한된 수 실행
```bash
python batch_daily_analysis.py --limit 50
```
### 전체 실행
```bash
python batch_daily_analysis.py
```
### Cron 스케줄 설정 (매일 평일 오전 9시)
```bash
crontab -e
```
다음 라인 추가:
```bash
0 9 * * 1-5 cd /path/to/auto-stock/backend && /path/to/python batch_daily_analysis.py >> /path/to/logs/batch.log 2>&1
```
---
## 로그 확인
배치 스크립트 실행 시 다음과 같은 상세 로그를 확인할 수 있습니다:
```
2025-11-10 09:00:00 - INFO - 🚀 Starting daily batch analysis for 2025-11-10
2025-11-10 09:00:00 - INFO - ⚙️ Rate Limiting: 0.5초 간격, 최대 재시도 3회
2025-11-10 09:00:05 - INFO - ✅ Found 30 KOSPI stocks
2025-11-10 09:00:10 - INFO - ✅ Found 30 KOSDAQ stocks
2025-11-10 09:00:10 - INFO - 📊 Total tradable stocks: 60
2025-11-10 09:00:15 - INFO - [1/60] Analyzing 005930 (삼성전자)...
2025-11-10 09:00:16 - INFO - ✅ Saved analysis for 005930 (삼성전자): score=5
...
2025-11-10 09:02:30 - INFO - ============================================================
2025-11-10 09:02:30 - INFO - ✅ Batch analysis completed!
2025-11-10 09:02:30 - INFO - 📊 Success: 58 / Total: 60
2025-11-10 09:02:30 - INFO - ❌ Failed: 2
2025-11-10 09:02:30 - INFO - ⏱️ Duration: 145.2 seconds (2.4 minutes)
2025-11-10 09:02:30 - INFO - 📡 API 통계:
2025-11-10 09:02:30 - INFO - - 총 호출: 122건
2025-11-10 09:02:30 - INFO - - 오류: 3건 (2.5%)
2025-11-10 09:02:30 - INFO - - 재시도: 5건
2025-11-10 09:02:30 - INFO - - 평균 응답 시간: 1.18초
```
---
## 문제 해결
### 1. 오류율이 높을 때 (30% 이상)
- **원인**: API 서버 불안정 또는 네트워크 문제
- **해결책**:
- `API_RETRY_DELAY`를 2~3초로 증가
- `API_MAX_RETRIES`를 5회로 증가
- `API_MIN_REQUEST_INTERVAL`을 1초로 증가 (호출 빈도 낮춤)
```bash
# .env 파일 수정
API_RETRY_DELAY=2.5
API_MAX_RETRIES=5
API_MIN_REQUEST_INTERVAL=1.0
```
### 2. 타임아웃 빈발
- **원인**: 네트워크 지연 또는 API 응답 느림
- **해결책**: 타임아웃 시간 증가
```bash
API_TIMEOUT=60.0
```
### 3. Rate Limit 초과 (429 에러)
- **원인**: 요청 간격이 너무 짧음
- **해결책**: 요청 간격 증가
```bash
API_MIN_REQUEST_INTERVAL=1.0 # 초당 1회로 제한
API_MAX_CONCURRENT_REQUESTS=1 # 동시 요청 1건으로 제한
```
---
## 성능 튜닝 팁
### 안정성 우선 (추천)
```bash
API_MIN_REQUEST_INTERVAL=0.5
API_MAX_CONCURRENT_REQUESTS=2
API_MAX_RETRIES=3
API_RETRY_DELAY=1.5
```
### 속도 우선 (주의)
```bash
API_MIN_REQUEST_INTERVAL=0.3
API_MAX_CONCURRENT_REQUESTS=3
API_MAX_RETRIES=2
API_RETRY_DELAY=1.0
```
### 대규모 배치용 (안전 중시)
```bash
API_MIN_REQUEST_INTERVAL=1.0
API_MAX_CONCURRENT_REQUESTS=1
API_MAX_RETRIES=5
API_RETRY_DELAY=2.0
API_RETRY_BACKOFF=3.0
```
---
## 추가 모니터링
### Prometheus + Grafana 연동 (선택 사항)
API 통계를 Prometheus 형식으로 내보내려면 `/api/v1/monitoring/metrics` 엔드포인트를 추가 구현할 수 있습니다.
### 알림 설정 (선택 사항)
오류율이 임계값을 초과할 때 Slack/Email 알림을 보내도록 확장 가능합니다.
---
## 참고 자료
- [한국투자증권 Open API 문서](https://apiportal.koreainvestment.com/)
- [FastAPI 공식 문서](https://fastapi.tiangolo.com/)
- [httpx 재시도 전략](https://www.python-httpx.org/)
---
**문의 및 피드백**: 시스템 운영 중 문제가 발생하면 로그 파일과 API 통계를 함께 확인하세요.

116
docs/BATCH_ANALYSIS_GUIDE.md Normal file
View File

@@ -0,0 +1,116 @@
# 배치 분석 가이드
## 개요
매일 아침 장 시작 전에 전체 종목을 분석하여 DB에 캐시합니다.
이를 통해 대시보드 첫 진입 시 빠른 로딩이 가능합니다.
## 수동 실행
### 테스트 (10개 종목만)
```bash
cd backend
../.venv/bin/python batch_daily_analysis.py --test
```
### 제한된 개수 분석
```bash
cd backend
../.venv/bin/python batch_daily_analysis.py --limit 30
```
### 전체 분석
```bash
cd backend
../.venv/bin/python batch_daily_analysis.py
```
## 자동 실행 (Cron)
### Cron Job 설정
```bash
./setup-cron.sh
```
이 스크립트는:
- 매일 평일(월~금) 오전 8시 50분에 배치 분석 실행
- 장 시작 전(9시) 데이터를 준비
- 로그는 `logs/batch_analysis.log`에 저장
### Cron Job 확인
```bash
crontab -l | grep batch_daily_analysis
```
### Cron Job 제거
```bash
crontab -e
# 해당 라인 삭제 후 저장
```
## 로그 확인
### 실시간 로그 보기
```bash
tail -f logs/batch_analysis.log
```
### 최근 로그 확인
```bash
tail -100 logs/batch_analysis.log
```
## 동작 방식
1. **8:50 AM**: Cron이 배치 스크립트 실행
2. **종목 조회**: KOSPI + KOSDAQ 거래량 상위 종목
3. **기술적 분석**: 각 종목의 RSI, MA, 볼린저 밴드 등 계산
4. **DB 저장**: `stock_analysis` 테이블에 저장
5. **9:00 AM**: 장 시작
6. **첫 진입**: DB에서 캐시된 데이터를 빠르게 로드 (1초 이내)
## API 제한 대응
한국투자증권 API는 다음 제한이 있습니다:
- 토큰 발급: 1분에 1회
- API 호출: 초당 2회 권장
배치 스크립트는:
- 각 종목 분석 후 2초 대기
- API 에러 시 자동 재시도 (최대 3회)
- 지수 백오프로 대기 시간 증가
## 예상 소요 시간
- 10개 종목: 약 30초
- 30개 종목: 약 2분
- 60개 종목 (전체): 약 4분
## 문제 해결
### Cron이 실행되지 않음
```bash
# Cron 데몬 상태 확인 (macOS)
sudo launchctl list | grep cron
# Cron 데몬 시작 (macOS)
sudo launchctl start com.vix.cron
```
### API 토큰 에러
로그에 "접근토큰 발급 잠시 후 다시 시도하세요" 메시지가 반복되면:
- 배치 스크립트가 너무 빨리 실행됨
- `batch_daily_analysis.py`의 `await asyncio.sleep(2)` 값을 3~5초로 증가
### DB 연결 에러
```bash
# PostgreSQL 실행 확인
pg_isready -h localhost -p 5432
# 서비스 시작
./start-all.sh
```
## 참고
- 배치 분석은 선택사항입니다
- 실행하지 않아도 첫 진입 시 실시간 분석이 자동으로 수행됩니다
- 다만 실시간 분석은 10~30초 소요됩니다

101
docs/BATCH_GUIDE.md Normal file
View File

@@ -0,0 +1,101 @@
# 배치 분석 시스템 사용 가이드
## 개요
매일 아침 전체 종목을 분석하여 DB에 저장하는 배치 시스템입니다.
API 응답 속도가 **30초 → 0.1초**로 300배 빨라집니다!
## 사용 방법
### 1. 테스트 실행 (10개 종목만)
```bash
./run-batch.sh --test
```
### 2. 일부 종목만 분석 (예: 50개)
```bash
./run-batch.sh --limit 50
```
### 3. 전체 종목 분석 (실제 운영)
```bash
./run-batch.sh
```
또는
```bash
cd backend
python batch_daily_analysis.py
```
## Cron 설정 (자동 실행)
매일 아침 9시에 자동 실행:
```bash
# crontab 편집
crontab -e
# 아래 내용 추가 (경로는 실제 경로로 수정)
0 9 * * 1-5 cd /Users/commylife/myproject/java/workspace/auto-stock && ./run-batch.sh >> logs/batch.log 2>&1
```
## API 사용
### 빠른 모드 (DB 조회 - 0.1초)
```bash
GET /api/v1/recommendations/rule-based
```
### 실시간 모드 (KIS API - 30초)
```bash
GET /api/v1/recommendations/rule-based?realtime=true
```
## 프론트엔드 버튼 추가 예시
```typescript
// 실시간 새로고침 버튼
<button onClick={() => refetch({ realtime: true })}>
🔴 실시간 분석 (30초)
</button>
// 기본은 DB 조회 (빠름)
<button onClick={() => refetch()}>
✅ 빠른 조회 (0.1초)
</button>
```
## 데이터베이스 스키마
```sql
CREATE TABLE stock_analysis (
id SERIAL PRIMARY KEY,
stock_code VARCHAR(20),
stock_name VARCHAR(100),
analysis_date DATE,
current_price INTEGER,
rsi NUMERIC(10,4),
ma5 NUMERIC(15,2),
ma20 NUMERIC(15,2),
signals JSONB,
score INTEGER,
...
);
```
## 장점
- ✅ **속도**: 30초 → 0.1초 (300배 빠름)
- ✅ **안정성**: KIS API Rate Limit 회피
- ✅ **편의성**: 사용자가 기다릴 필요 없음
- ✅ **확장성**: 과거 데이터 추적 가능
- ✅ **분석**: 백테스팅, 통계 분석 가능
## 주의사항
- 배치 실행 시간: 약 5-10분 (전체 200개 종목 기준)
- KIS API Rate Limit: 초당 1건 제한
- 데이터는 매일 아침 9시 기준
- 장중 실시간 가격은 `realtime=true` 옵션 사용

149
docs/INSTALLATION.md Normal file
View File

@@ -0,0 +1,149 @@
# Auto Stock Trading System - 설치 가이드
## 사전 요구사항
- Docker & Docker Compose
- 한국투자증권 API 키
- Claude API 키 (Anthropic)
## 설치 단계
### 1. 저장소 클론
```bash
git clone <repository-url>
cd auto-stock
```
### 2. 환경 변수 설정
```bash
cp .env.example .env
```
`.env` 파일을 열어 다음 값들을 설정하세요:
- `KOREA_INVESTMENT_APP_KEY`: 한국투자증권 앱키
- `KOREA_INVESTMENT_APP_SECRET`: 한국투자증권 시크릿
- `KOREA_INVESTMENT_ACCOUNT_NUMBER`: 계좌번호
- `ANTHROPIC_API_KEY`: Claude API 키
### 3. 시스템 시작
#### Docker로 전체 시스템 시작
```bash
./scripts/deploy.sh
```
#### 개발 모드 (로컬 개발)
```bash
# 인프라만 Docker로 시작
./scripts/dev.sh
# Backend 시작
cd backend
pip install -r requirements.txt
uvicorn app.main:app --reload
# MCP Server 시작 (새 터미널)
cd mcp-server
pip install -r requirements.txt
uvicorn main:app --reload --port 8001
# Frontend 시작 (새 터미널)
cd frontend
npm install
npm run dev
```
## 시스템 관리
### 로그 확인
```bash
# 전체 로그
./scripts/logs.sh
# 특정 서비스 로그
./scripts/logs.sh backend
./scripts/logs.sh mcp-server
./scripts/logs.sh frontend
```
### 시스템 중지
```bash
./scripts/stop.sh
```
### 시스템 재시작
```bash
./scripts/restart.sh
```
### 데이터베이스 백업
```bash
./scripts/backup.sh
```
## 접속 URL
- **Frontend**: http://localhost:3000
- **Backend API**: http://localhost:8000
- **API 문서**: http://localhost:8000/docs
- **MCP Server**: http://localhost:8001
- **RabbitMQ 관리**: http://localhost:15672 (guest/guest)
## 트러블슈팅
### 포트 충돌
다른 애플리케이션이 사용 중인 포트가 있다면 `.env` 파일에서 포트를 변경하세요.
### 데이터베이스 연결 오류
```bash
# 데이터베이스 재시작
docker-compose restart postgres
```
### 전체 시스템 재빌드
```bash
docker-compose down -v
docker-compose build --no-cache
docker-compose up -d
```
## 개발 가이드
### Backend API 엔드포인트 추가
1. `backend/app/api/endpoints/` 에 새 엔드포인트 파일 생성
2. `backend/app/api/__init__.py` 에 라우터 등록
### Frontend 페이지 추가
1. `frontend/src/pages/` 에 새 페이지 컴포넌트 생성
2. `frontend/src/App.tsx` 에 라우트 추가
### MCP 도구 추가
1. `mcp-server/mcp_tools.py` 에 새 도구 메서드 추가
2. `get_tool_definitions()` 에 도구 정의 추가
## 보안 주의사항
- 프로덕션 환경에서는 반드시 강력한 `SECRET_KEY` 사용
- API 키를 절대 Git에 커밋하지 마세요
- 프로덕션에서는 HTTPS 사용
- 데이터베이스 비밀번호 변경
- CORS 설정을 프로덕션 도메인으로 제한
## 라이센스
MIT License

266
docs/PROJECT_STRUCTURE.md Normal file
View File

@@ -0,0 +1,266 @@
# Auto Stock Trading System 프로젝트 구조
## 📁 디렉토리 구조
```
auto-stock/
├── backend/ # FastAPI 백엔드
│ ├── app/
│ │ ├── api/
│ │ │ ├── __init__.py # API 라우터 통합
│ │ │ └── endpoints/
│ │ │ ├── trading_rules.py # 트레이딩 규칙 API
│ │ │ ├── trades.py # 거래 이력 API
│ │ │ ├── portfolio.py # 포트폴리오 API
│ │ │ ├── market_data.py # 시장 데이터 API
│ │ │ └── mcp.py # MCP 연동 API
│ │ ├── core/
│ │ │ ├── config.py # 설정 관리
│ │ │ └── database.py # 데이터베이스 연결
│ │ ├── models/
│ │ │ └── models.py # SQLAlchemy 모델
│ │ ├── services/
│ │ │ ├── websocket_manager.py # WebSocket 관리
│ │ │ └── korea_investment_api.py # 한국투자증권 API
│ │ └── main.py # FastAPI 앱 진입점
│ ├── Dockerfile
│ └── requirements.txt
│
├── mcp-server/ # MCP 서버 (Claude AI)
│ ├── main.py # MCP 서버 진입점
│ ├── config.py # 설정
│ ├── claude_client.py # Claude API 클라이언트
│ ├── mcp_tools.py # MCP 도구 레지스트리
│ ├── Dockerfile
│ └── requirements.txt
│
├── frontend/ # React 프론트엔드
│ ├── src/
│ │ ├── components/
│ │ │ └── Layout.tsx # 레이아웃 컴포넌트
│ │ ├── pages/
│ │ │ ├── Dashboard.tsx # 대시보드
│ │ │ ├── TradingRules.tsx # 트레이딩 규칙
│ │ │ ├── TradeHistory.tsx # 거래 이력
│ │ │ └── MCPStatus.tsx # MCP 상태
│ │ ├── hooks/
│ │ │ └── useWebSocket.ts # WebSocket 훅
│ │ ├── lib/
│ │ │ └── api.ts # API 클라이언트
│ │ ├── App.tsx # 앱 컴포넌트
│ │ ├── main.tsx # 진입점
│ │ ├── config.ts # 설정
│ │ └── index.css # 스타일
│ ├── public/
│ ├── index.html
│ ├── package.json
│ ├── vite.config.ts
│ ├── tailwind.config.js
│ ├── tsconfig.json
│ ├── nginx.conf
│ └── Dockerfile
│
├── docker/ # Docker 설정
│ └── init-db.sql # DB 초기화 스크립트
│
├── scripts/ # 유틸리티 스크립트
│ ├── deploy.sh # 프로덕션 배포
│ ├── dev.sh # 개발 모드
│ ├── stop.sh # 시스템 중지
│ ├── restart.sh # 재시작
│ ├── logs.sh # 로그 확인
│ └── backup.sh # DB 백업
│
├── .github/
│ └── workflows/
│ └── ci-cd.yml # CI/CD 파이프라인
│
├── docker-compose.yml # 프로덕션 Docker Compose
├── docker-compose.dev.yml # 개발용 Docker Compose
├── .env.example # 환경 변수 예시
├── .gitignore
├── Makefile # Make 명령어
├── ecosystem.config.js # PM2 설정
├── README.md # 프로젝트 소개
├── INSTALLATION.md # 설치 가이드
├── USER_GUIDE.md # 사용자 가이드
└── API_DOCS.md # API 문서
```
## 🎯 주요 기능
### 1. **대시보드**
- 실시간 포트폴리오 현황
- 총 자산 및 수익률
- 보유 종목 상세
### 2. **전략 룰 설정**
- 자동 매매 규칙 생성/수정/삭제
- 조건 및 액션 설정
- 규칙 우선순위 관리
### 3. **매매 로그**
- 전체 거래 내역
- 실행 상태 모니터링
- 거래 통계
### 4. **MCP 상태 모니터**
- MCP 서버 연결 상태
- Claude AI 도구 목록
- 실시간 로그
## 🔧 기술 스택
### Backend
- **FastAPI**: 비동기 REST API
- **SQLAlchemy**: ORM
- **PostgreSQL**: 데이터베이스
- **Redis**: 캐싱
- **RabbitMQ**: 메시지 큐
- **WebSocket**: 실시간 통신
### MCP Server
- **FastAPI**: MCP 프로토콜 서버
- **Anthropic Claude**: AI 분석
- **Pandas/TA**: 기술적 지표 계산
### Frontend
- **React 18**: UI 프레임워크
- **TypeScript**: 타입 안정성
- **Vite**: 빌드 도구
- **TailwindCSS**: 스타일링
- **React Query**: 데이터 페칭
- **Recharts**: 차트
### Infrastructure
- **Docker**: 컨테이너화
- **Docker Compose**: 오케스트레이션
- **Nginx**: 웹 서버
- **GitHub Actions**: CI/CD
## 🚀 빠른 시작
### 1. 환경 설정
```bash
cp .env.example .env
# .env 파일 편집하여 API 키 설정
```
### 2. Docker로 시작
```bash
./scripts/deploy.sh
```
### 3. 접속
- Frontend: http://localhost:3000
- Backend: http://localhost:8000
- MCP Server: http://localhost:8001
## 📊 시스템 아키텍처
```
┌─────────────┐ ┌──────────────┐ ┌─────────────┐
│ Frontend │────▶│ Backend │────▶│ MCP Server │
│ (React) │ │ (FastAPI) │ │ (Claude) │
└─────────────┘ └──────────────┘ └─────────────┘
│ │
▼ ▼
┌──────────────┐ ┌─────────────┐
│ PostgreSQL │ │ Claude AI │
│ Redis │ └─────────────┘
│ RabbitMQ │
└──────────────┘
│
▼
┌──────────────┐
│ 한국투자증권 │
│ API │
└──────────────┘
```
## 🔐 보안
- API 키는 환경 변수로 관리
- JWT 토큰 기반 인증
- CORS 설정
- HTTPS 지원 (프로덕션)
## 📝 개발 가이드
### Backend 개발
```bash
cd backend
pip install -r requirements.txt
uvicorn app.main:app --reload
```
### MCP Server 개발
```bash
cd mcp-server
pip install -r requirements.txt
uvicorn main:app --reload --port 8001
```
### Frontend 개발
```bash
cd frontend
npm install
npm run dev
```
## 🧪 테스트
```bash
# Backend 테스트
make test-backend
# Frontend 테스트
make test-frontend
```
## 📦 배포
### Docker Compose
```bash
make deploy
```
### PM2 (Node.js Process Manager)
```bash
pm2 start ecosystem.config.js
```
## 🛠️ 유용한 명령어
```bash
make help # 도움말
make dev # 개발 모드
make deploy # 배포
make stop # 중지
make restart # 재시작
make logs # 로그
make backup # DB 백업
make clean # 정리
```
## 📚 문서
- [README.md](README.md) - 프로젝트 소개
- [INSTALLATION.md](INSTALLATION.md) - 설치 가이드
- [USER_GUIDE.md](USER_GUIDE.md) - 사용자 가이드
- [API_DOCS.md](API_DOCS.md) - API 문서
## ⚠️ 주의사항
- 실제 거래 전 충분한 테스트 필요
- API 키 보안 관리
- 손실 위험 인지
- 규칙 신중하게 설정
## 📄 라이센스
MIT License
## 🤝 기여
Pull Request와 Issue는 언제나 환영합니다!

211
docs/USER_GUIDE.md Normal file
View File

@@ -0,0 +1,211 @@
# Auto Stock Trading System - 사용 가이드
## 기능 소개
### 1. 대시보드
- 실시간 포트폴리오 현황
- 총 자산 및 수익률 모니터링
- 보유 종목 상세 정보
### 2. 전략 룰 설정
- 자동 매매 규칙 생성/수정/삭제
- 규칙 활성화/비활성화
- 조건 및 액션 설정
### 3. 매매 로그
- 모든 거래 내역 조회
- 실행 상태 확인
- 거래 통계
### 4. MCP 상태 모니터
- MCP 서버 연결 상태
- 사용 가능한 도구 목록
- 실시간 MCP 로그
## 트레이딩 규칙 생성 가이드
### 규칙 구조
```json
{
"name": "규칙 이름",
"description": "규칙 설명",
"rule_type": "BUY" | "SELL",
"conditions": {
// 실행 조건
},
"actions": {
// 실행할 액션
}
}
```
### 조건 예시
#### RSI 기반 매수
```json
{
"conditions": {
"rsi_below": 30,
"volume_above_average": 1.5
}
}
```
#### 손절매
```json
{
"conditions": {
"loss_rate_below": -5
}
}
```
#### 익절
```json
{
"conditions": {
"profit_rate_above": 15
}
}
```
### 액션 예시
#### 매수 액션
```json
{
"actions": {
"order_type": "BUY",
"quantity_percent": 10,
"max_amount": 1000000
}
}
```
#### 매도 액션
```json
{
"actions": {
"order_type": "SELL",
"quantity_percent": 100
}
}
```
## Claude AI 분석 활용
### 1. 규칙 검증
시장 상황에 맞게 규칙이 적절한지 Claude AI가 분석합니다.
### 2. 시장 분석
기술적 지표와 뉴스를 종합하여 시장 트렌드를 분석합니다.
### 3. 리스크 평가
포트폴리오와 거래 계획을 분석하여 리스크를 평가합니다.
## MCP 도구
### get_market_data
시장 데이터를 조회합니다.
```json
{
"tool_name": "get_market_data",
"parameters": {
"stock_code": "005930",
"period": "D"
}
}
```
### calculate_indicators
기술적 지표를 계산합니다.
```json
{
"tool_name": "calculate_indicators",
"parameters": {
"price_data": [...],
"indicators": ["RSI", "MACD", "BB"]
}
}
```
### check_portfolio
현재 포트폴리오를 확인합니다.
```json
{
"tool_name": "check_portfolio",
"parameters": {}
}
```
### execute_order
주문을 실행합니다.
```json
{
"tool_name": "execute_order",
"parameters": {
"stock_code": "005930",
"order_type": "BUY",
"quantity": 10,
"price": 71000
}
}
```
## 모범 사례
### 1. 리스크 관리
- 한 종목에 총 자산의 10% 이상 투자하지 않기
- 손절매 규칙 반드시 설정
- 일일 최대 거래 횟수 제한
### 2. 규칙 우선순위
- 손절매: 최고 우선순위 (100)
- 익절: 높은 우선순위 (90)
- 일반 매매: 중간 우선순위 (10-50)
### 3. 백테스팅
새로운 규칙은 과거 데이터로 먼저 테스트하세요.
### 4. 모니터링
- 실시간 로그 확인
- 규칙 성과 정기 검토
- MCP 서버 연결 상태 체크
## 주의사항
⚠️ **중요**: 이 시스템은 자동 매매를 수행합니다.
- 실제 계좌로 사용하기 전에 충분히 테스트하세요
- 시장 상황을 항상 모니터링하세요
- 규칙을 신중하게 설정하세요
- 손실 위험을 항상 고려하세요
## 문제 해결
### Q: 거래가 실행되지 않아요
A:
1. 규칙이 활성화되어 있는지 확인
2. 조건이 충족되었는지 확인
3. 계좌 잔액 확인
4. API 연결 상태 확인
### Q: MCP 서버가 연결되지 않아요
A:
1. MCP 서버가 실행 중인지 확인
2. Claude API 키가 올바른지 확인
3. 네트워크 연결 확인
### Q: 포트폴리오가 동기화되지 않아요
A:
1. "포트폴리오 동기화" 버튼 클릭
2. API 키와 계좌번호 확인
3. 한국투자증권 API 상태 확인
## 지원
문제가 발생하거나 도움이 필요하시면 GitHub Issues에 문의해주세요.

42
docs/backend_guide.md Normal file
View File

@@ -0,0 +1,42 @@
# Backend
## Batch daily analysis (DB cache)
Precompute technical indicators each morning and cache results for fast recommendations.
### Run once (today)
```zsh
cd /Users/commylife/myproject/java/workspace/auto-stock/backend
python3 batch_daily_analysis.py --test # quick: ~10 stocks
# or full run
python3 batch_daily_analysis.py
```
### Schedule (cron on macOS)
```zsh
crontab -e
# weekdays 08:30 run (adjust path)
30 8 * * 1-5 cd /Users/commylife/myproject/java/workspace/auto-stock/backend && /usr/bin/python3 batch_daily_analysis.py >> ../logs/batch.log 2>&1
```
### Use DB cache in API
- Endpoint: `/api/v1/recommendations/rule-based`
- Default: uses DB cache; if cache empty, it automatically falls back to realtime analysis.
- Force realtime:
```text
/api/v1/recommendations/rule-based?realtime=true
```
### Monitoring
- API safety stats: `/api/v1/monitoring/api-stats`
- Health: `/api/v1/monitoring/health`
### Troubleshooting
- No recommendations: ensure `stock_analysis` has rows for today (run batch).
- Slow responses: rely on DB cache or reduce realtime stock count via query params.