# 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는 언제나 환영합니다!