수정본

2026-02-22 17:23:20 +09:00
parent b147498c31
commit 32e2263f0a
109 changed files with 13979 additions and 4580 deletions
--- a/docs/PROJECT_STRUCTURE.md
+++ b/docs/PROJECT_STRUCTURE.md
@@ -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는 언제나 환영합니다!