feat: 프로젝트 개요 및 컴포넌트별 명세, 로드맵 등 문서 추가
This commit is contained in:
279
docs/01-overview.md
Normal file
279
docs/01-overview.md
Normal file
@@ -0,0 +1,279 @@
|
||||
# QuantBench 시스템 개요
|
||||
|
||||
## 1. 프로젝트 소개
|
||||
|
||||
**QuantBench**는 개인 투자자를 위한 퀀트 트레이딩 플랫폼으로, 다중 계좌 관리, 전략 기반 자동매매, 리스크 관리, 성과 분석을 통합 제공합니다.
|
||||
|
||||
### 핵심 가치 제안
|
||||
|
||||
- **다중 계좌 통합 관리**: 한국투자증권, 삼성증권, 키움증권 등 여러 증권사 계좌를 하나의 플랫폼에서 관리
|
||||
- **컨테이너 기반 자산 격리**: 하나의 계좌에서 여러 전략을 안전하게 병렬 운영
|
||||
- **전략 자동화**: 백테스트부터 실전 운영까지 일관된 전략 실행 환경
|
||||
- **리스크 우선 설계**: 사전 주문 검증 및 실시간 리스크 모니터링
|
||||
- **투명한 성과 분석**: 실시간 성과 추적 및 귀속 분석
|
||||
|
||||
## 2. 주요 기능
|
||||
|
||||
### 2.1 계좌 및 자산 관리
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
A[투자자] --> B[QuantBench]
|
||||
B --> C[한국투자증권]
|
||||
B --> D[삼성증권]
|
||||
B --> E[키움증권]
|
||||
|
||||
B --> F[컨테이너 1<br/>성장주 전략]
|
||||
B --> G[컨테이너 2<br/>배당주 전략]
|
||||
B --> H[컨테이너 3<br/>ETF 전략]
|
||||
|
||||
style F fill:#e3f2fd
|
||||
style G fill:#e3f2fd
|
||||
style H fill:#e3f2fd
|
||||
```
|
||||
|
||||
- 여러 증권사 계좌 통합 관리
|
||||
- 계좌 내 가상 컨테이너 생성으로 전략별 자산 격리
|
||||
- 실시간 잔고 조회 및 포지션 추적
|
||||
- 컨테이너 간 자산 이동 및 재배분
|
||||
|
||||
### 2.2 전략 실행
|
||||
|
||||
- **전략 등록 및 버전 관리**: 전략 코드 및 파라미터의 버전별 관리
|
||||
- **백테스트**: 과거 데이터 기반 전략 검증 및 성과 분석
|
||||
- **자동 실행**: 스케줄 기반 자동 매매 신호 생성 및 주문 실행
|
||||
- **승인 워크플로우**: 자동 실행 또는 사용자 승인 후 실행 선택
|
||||
|
||||
### 2.3 리스크 관리
|
||||
|
||||
- **사전 주문 검증**: 모든 주문의 리스크 사전 체크
|
||||
- **포지션 한도 관리**: 단일 종목, 섹터, 총 익스포저 제한
|
||||
- **손절/익절 자동화**: 조건 기반 자동 청산
|
||||
- **VaR 계산**: 포트폴리오 리스크 정량화
|
||||
- **스트레스 테스트**: 극단 시나리오 대비
|
||||
|
||||
### 2.4 성과 분석 및 모니터링
|
||||
|
||||
- **실시간 성과 추적**: 수익률, 리스크 지표 실시간 업데이트
|
||||
- **귀속 분석**: 수익 원천 분해 (자산 배분, 종목 선택, 타이밍)
|
||||
- **벤치마크 비교**: 시장 지수 대비 성과 분석
|
||||
- **이상 탐지**: 비정상 거래 및 리스크 이벤트 자동 감지
|
||||
- **다채널 알림**: 이메일, SMS, 푸시, Slack 알림
|
||||
|
||||
## 3. 핵심 개념
|
||||
|
||||
### 3.1 컨테이너 (Container)
|
||||
|
||||
컨테이너는 **하나의 실제 계좌 내에서 가상으로 분리된 자산 공간**입니다.
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "실제 계좌 (1억원)"
|
||||
subgraph "컨테이너 A (3천만원)"
|
||||
A1[현금: 500만원]
|
||||
A2[삼성전자: 2500만원]
|
||||
end
|
||||
|
||||
subgraph "컨테이너 B (5천만원)"
|
||||
B1[현금: 1000만원]
|
||||
B2[KODEX 200: 4000만원]
|
||||
end
|
||||
|
||||
subgraph "컨테이너 C (2천만원)"
|
||||
C1[현금: 2000만원]
|
||||
end
|
||||
end
|
||||
|
||||
style A1 fill:#fff9c4
|
||||
style A2 fill:#c8e6c9
|
||||
style B1 fill:#fff9c4
|
||||
style B2 fill:#c8e6c9
|
||||
style C1 fill:#fff9c4
|
||||
```
|
||||
|
||||
**특징**:
|
||||
- 각 컨테이너는 독립적인 가상 잔고를 유지
|
||||
- 하나의 컨테이너에 하나의 전략 할당
|
||||
- 컨테이너별 독립적인 리스크 한도 설정
|
||||
- 실제 계좌 잔고 = 모든 컨테이너 잔고의 합
|
||||
|
||||
**장점**:
|
||||
- 전략 간 간섭 없이 병렬 운영
|
||||
- 전략별 성과를 명확히 추적
|
||||
- 리스크를 전략 단위로 통제
|
||||
|
||||
### 3.2 전략 (Strategy)
|
||||
|
||||
전략은 **매매 신호를 생성하는 알고리즘**입니다.
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
A[시장 데이터] --> B[전략 엔진]
|
||||
B --> C[매매 신호]
|
||||
C --> D{리스크 체크}
|
||||
D -->|통과| E[주문 실행]
|
||||
D -->|실패| F[실행 중단]
|
||||
|
||||
style B fill:#2196f3,color:#fff
|
||||
style D fill:#f44336,color:#fff
|
||||
style E fill:#4caf50,color:#fff
|
||||
```
|
||||
|
||||
**구성 요소**:
|
||||
- **전략 코드**: 신호 생성 로직 구현
|
||||
- **파라미터**: 전략 동작을 조정하는 변수들
|
||||
- **버전**: 전략 수정 이력 관리
|
||||
- **백테스트 결과**: 과거 성과 검증 데이터
|
||||
|
||||
**내장 전략 예시**:
|
||||
- Bold Asset Allocation: 주식/채권 고정 비중 전략
|
||||
- Momentum: 모멘텀 기반 종목 선택
|
||||
- Value: 가치 지표 기반 매매
|
||||
|
||||
### 3.3 워크플로우 (Workflow)
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant 스케줄러
|
||||
participant 전략
|
||||
participant 리스크
|
||||
participant 증권사
|
||||
participant 사용자
|
||||
|
||||
스케줄러->>전략: 신호 생성 요청
|
||||
전략-->>스케줄러: 매매 신호
|
||||
스케줄러->>리스크: 리스크 검증
|
||||
|
||||
alt 리스크 통과
|
||||
리스크-->>스케줄러: 승인
|
||||
|
||||
alt 자동 실행 모드
|
||||
스케줄러->>증권사: 주문 제출
|
||||
else 승인 필요 모드
|
||||
스케줄러->>사용자: 승인 요청
|
||||
사용자-->>스케줄러: 승인
|
||||
스케줄러->>증권사: 주문 제출
|
||||
end
|
||||
|
||||
증권사-->>스케줄러: 체결 완료
|
||||
else 리스크 실패
|
||||
리스크-->>스케줄러: 거부
|
||||
스케줄러->>사용자: 실패 알림
|
||||
end
|
||||
```
|
||||
|
||||
## 4. 개발 단계
|
||||
|
||||
### Phase 1: MVP (3-4개월)
|
||||
|
||||
**목표**: 안전하게 전략을 실행하고 리스크를 통제할 수 있는 기본 시스템 구축
|
||||
|
||||
**핵심 컴포넌트**:
|
||||
- `balance`: 증권사 API 연동 및 계좌 관리
|
||||
- `mgmt`: 컨테이너 생명주기 관리
|
||||
- `strategy`: 전략 실행 및 백테스트
|
||||
- `scheduler`: 자동 실행 스케줄링
|
||||
- `risk`: 사전 주문 검증
|
||||
- `data`: 시장 데이터 수집 및 관리
|
||||
|
||||
**핵심 기능**:
|
||||
- 1개 증권사 연동 (한국투자증권 우선)
|
||||
- 기본 전략 실행 (Bold Asset Allocation)
|
||||
- 주문 전 리스크 체크
|
||||
- 수동 승인 워크플로우
|
||||
|
||||
### Phase 2: Production Ready (2-3개월)
|
||||
|
||||
**목표**: 실전 운영을 위한 모니터링, 분석, 알림 체계 구축
|
||||
|
||||
**추가 컴포넌트**:
|
||||
- `analytics`: 성과 분석 및 리포팅
|
||||
- `monitor`: 시스템 모니터링 및 알림
|
||||
|
||||
**핵심 기능**:
|
||||
- 실시간 성과 대시보드
|
||||
- 자동 리포트 생성 (일/주/월)
|
||||
- 이상 거래 탐지
|
||||
- 다채널 알림 시스템
|
||||
|
||||
### Phase 3: Enterprise Grade (2-3개월)
|
||||
|
||||
**목표**: 규제 대응, 감사 추적, 고급 시뮬레이션
|
||||
|
||||
**추가 컴포넌트**:
|
||||
- `audit`: 불변 감사 로그
|
||||
- `simulation`: Paper Trading 및 시뮬레이션
|
||||
|
||||
**핵심 기능**:
|
||||
- 모든 거래의 감사 추적
|
||||
- Paper Trading 환경
|
||||
- 파라미터 최적화
|
||||
- 스트레스 테스트
|
||||
|
||||
## 5. 기술 스택
|
||||
|
||||
### 백엔드
|
||||
- **언어**: TypeScript/Node.js 또는 Python
|
||||
- **데이터베이스**: PostgreSQL (관계형), TimescaleDB (시계열)
|
||||
- **캐시**: Redis
|
||||
- **메시지 큐**: Kafka 또는 RabbitMQ
|
||||
- **스토리지**: AWS S3 또는 MinIO
|
||||
|
||||
### 프론트엔드
|
||||
- **프레임워크**: React 또는 Next.js
|
||||
- **차트**: TradingView, Chart.js
|
||||
- **상태 관리**: Redux 또는 Zustand
|
||||
|
||||
### 인프라
|
||||
- **컨테이너**: Docker
|
||||
- **오케스트레이션**: Kubernetes (선택)
|
||||
- **모니터링**: Prometheus + Grafana
|
||||
- **로깅**: ELK Stack (Elasticsearch, Logstash, Kibana)
|
||||
|
||||
## 6. 비기능 요구사항
|
||||
|
||||
### 6.1 성능
|
||||
- 주문 처리 지연시간: < 1초
|
||||
- 백테스트 속도: 1년 데이터 < 10초
|
||||
- 실시간 데이터 업데이트: < 5초
|
||||
|
||||
### 6.2 안정성
|
||||
- 시스템 가용성: 99.9% (장중 시간 기준)
|
||||
- 데이터 정합성: 100% (계좌 잔고 일치)
|
||||
- 주문 실패 복구: 자동 재시도 및 알림
|
||||
|
||||
### 6.3 보안
|
||||
- API 키 암호화 저장
|
||||
- 통신 TLS 암호화
|
||||
- 역할 기반 접근 제어 (RBAC)
|
||||
- 감사 로그 불변성 보장
|
||||
|
||||
### 6.4 확장성
|
||||
- 다중 증권사 지원 (플러그인 아키텍처)
|
||||
- 수평 확장 가능한 데이터 처리
|
||||
- 무제한 컨테이너/전략 생성
|
||||
|
||||
## 7. 관련 문서
|
||||
|
||||
- [전체 아키텍처](./02-architecture.md)
|
||||
- [공통 데이터 모델](./03-data-models.md)
|
||||
- [주요 워크플로우](./04-workflows.md)
|
||||
- [구현 로드맵](./05-roadmap.md)
|
||||
|
||||
### 구성요소 상세 문서
|
||||
|
||||
**Phase 1**:
|
||||
- [balance - 계좌 관리](../components/phase1/balance.md)
|
||||
- [mgmt - 컨테이너 관리](../components/phase1/mgmt.md)
|
||||
- [strategy - 전략 관리](../components/phase1/strategy.md)
|
||||
- [scheduler - 실행 스케줄러](../components/phase1/scheduler.md)
|
||||
- [risk - 리스크 관리](../components/phase1/risk.md)
|
||||
- [data - 데이터 관리](../components/phase1/data.md)
|
||||
|
||||
**Phase 2**:
|
||||
- [analytics - 성과 분석](../components/phase2/analytics.md)
|
||||
- [monitor - 모니터링](../components/phase2/monitor.md)
|
||||
|
||||
**Phase 3**:
|
||||
- [audit - 감사 로깅](../components/phase3/audit.md)
|
||||
- [simulation - 시뮬레이션](../components/phase3/simulation.md)
|
||||
592
docs/02-architecture.md
Normal file
592
docs/02-architecture.md
Normal file
@@ -0,0 +1,592 @@
|
||||
# QuantBench 시스템 아키텍처
|
||||
|
||||
## 1. 전체 시스템 구조
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "사용자 레이어"
|
||||
UI[사용자 인터페이스<br/>Web/Mobile/Desktop]
|
||||
end
|
||||
|
||||
subgraph "API 레이어"
|
||||
Gateway[API Gateway<br/>인증 & Rate Limiting]
|
||||
end
|
||||
|
||||
subgraph "Phase 1: 핵심 컴포넌트"
|
||||
Balance[balance<br/>계좌 관리]
|
||||
Mgmt[mgmt<br/>컨테이너 관리]
|
||||
Strategy[strategy<br/>전략 관리]
|
||||
Scheduler[scheduler<br/>실행 스케줄러]
|
||||
Risk[risk<br/>리스크 관리]
|
||||
Data[data<br/>데이터 관리]
|
||||
end
|
||||
|
||||
subgraph "Phase 2: 프로덕션"
|
||||
Analytics[analytics<br/>성과 분석]
|
||||
Monitor[monitor<br/>모니터링 & 알림]
|
||||
end
|
||||
|
||||
subgraph "Phase 3: 엔터프라이즈"
|
||||
Audit[audit<br/>감사 로깅]
|
||||
Simulation[simulation<br/>시뮬레이션]
|
||||
end
|
||||
|
||||
subgraph "인프라"
|
||||
MQ[Message Queue<br/>Kafka/RabbitMQ]
|
||||
DB[(Database<br/>PostgreSQL)]
|
||||
Cache[(Cache<br/>Redis)]
|
||||
Storage[(Object Storage<br/>S3)]
|
||||
end
|
||||
|
||||
subgraph "외부 시스템"
|
||||
Broker1[한국투자증권 API]
|
||||
Broker2[삼성증권 API]
|
||||
Broker3[키움증권 API]
|
||||
DataProvider[데이터 제공자<br/>Yahoo/Alpha Vantage]
|
||||
end
|
||||
|
||||
UI --> Gateway
|
||||
Gateway --> Mgmt
|
||||
Gateway --> Strategy
|
||||
Gateway --> Scheduler
|
||||
Gateway --> Analytics
|
||||
Gateway --> Monitor
|
||||
Gateway --> Simulation
|
||||
|
||||
Scheduler --> Strategy
|
||||
Scheduler --> Mgmt
|
||||
Scheduler --> Risk
|
||||
Scheduler --> Balance
|
||||
|
||||
Strategy --> Data
|
||||
Strategy --> Risk
|
||||
|
||||
Mgmt --> Balance
|
||||
Mgmt --> Risk
|
||||
|
||||
Analytics --> Mgmt
|
||||
Analytics --> Data
|
||||
|
||||
Monitor --> Mgmt
|
||||
Monitor --> Balance
|
||||
Monitor --> Scheduler
|
||||
|
||||
Simulation --> Strategy
|
||||
Simulation --> Data
|
||||
Simulation --> Risk
|
||||
|
||||
Audit -.-> Mgmt
|
||||
Audit -.-> Strategy
|
||||
Audit -.-> Scheduler
|
||||
Audit -.-> Balance
|
||||
|
||||
Balance --> Broker1
|
||||
Balance --> Broker2
|
||||
Balance --> Broker3
|
||||
|
||||
Data --> DataProvider
|
||||
Data --> Broker1
|
||||
|
||||
Mgmt --> DB
|
||||
Strategy --> DB
|
||||
Analytics --> DB
|
||||
Audit --> DB
|
||||
|
||||
Data --> Cache
|
||||
Monitor --> Cache
|
||||
|
||||
Analytics --> Storage
|
||||
Audit --> Storage
|
||||
|
||||
Scheduler --> MQ
|
||||
Monitor --> MQ
|
||||
|
||||
style Balance fill:#e1f5ff
|
||||
style Mgmt fill:#e1f5ff
|
||||
style Strategy fill:#e1f5ff
|
||||
style Scheduler fill:#e1f5ff
|
||||
style Risk fill:#e1f5ff
|
||||
style Data fill:#e1f5ff
|
||||
|
||||
style Analytics fill:#fff4e1
|
||||
style Monitor fill:#fff4e1
|
||||
|
||||
style Audit fill:#f0e1ff
|
||||
style Simulation fill:#f0e1ff
|
||||
```
|
||||
|
||||
## 2. 컴포넌트 개요
|
||||
|
||||
### 2.1 Phase 1: 핵심 컴포넌트
|
||||
|
||||
| 컴포넌트 | 책임 | 주요 기능 |
|
||||
|---------|------|----------|
|
||||
| **balance** | 증권사 API 통합 및 계좌 자산 관리 | 계좌 연동, 잔고 조회, 시세 조회, 주문 처리 |
|
||||
| **mgmt** | 가상 자산 컨테이너 생성 및 운영 관리 | 컨테이너 생명주기, 자산 격리, 밸런스 조정 |
|
||||
| **strategy** | 투자 전략 구현, 백테스트, 버전 관리 | 전략 등록, 신호 생성, 백테스트, 파라미터 관리 |
|
||||
| **scheduler** | 전략 실행 자동화 및 리밸런싱 관리 | 스케줄 관리, 실행 트리거, 승인 워크플로우 |
|
||||
| **risk** | 포지션 리스크 통제 및 사전 주문 검증 | 주문 검증, 리스크 모니터링, 손절/익절 |
|
||||
| **data** | 시계열 데이터 수집, 저장, 제공 | 데이터 수집, 품질 관리, 데이터 제공 |
|
||||
|
||||
### 2.2 Phase 2: 프로덕션 컴포넌트
|
||||
|
||||
| 컴포넌트 | 책임 | 주요 기능 |
|
||||
|---------|------|----------|
|
||||
| **analytics** | 실거래 성과 측정 및 리포팅 | 성과 측정, 귀속 분석, 거래 분석, 리포트 생성 |
|
||||
| **monitor** | 시스템 상태 감시 및 이상 탐지 | 헬스 체크, 이상 탐지, 알림 관리, 대시보드 |
|
||||
|
||||
### 2.3 Phase 3: 엔터프라이즈 컴포넌트
|
||||
|
||||
| 컴포넌트 | 책임 | 주요 기능 |
|
||||
|---------|------|----------|
|
||||
| **audit** | 불변 감사 로그 및 규제 리포팅 | 감사 로그, 변경 추적, 규제 리포팅, 무결성 검증 |
|
||||
| **simulation** | 실전 배포 전 안전한 테스트 환경 제공 | Paper Trading, 시뮬레이션, 파라미터 최적화 |
|
||||
|
||||
## 3. 컴포넌트 상호작용
|
||||
|
||||
### 3.1 Phase 1 컴포넌트 관계도
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
subgraph "Phase 1: MVP"
|
||||
subgraph "핵심 거래"
|
||||
Mgmt[mgmt<br/>컨테이너 관리]
|
||||
Strategy[strategy<br/>전략 엔진]
|
||||
Scheduler[scheduler<br/>스케줄러]
|
||||
end
|
||||
|
||||
subgraph "안전성 & 통제"
|
||||
Risk[risk<br/>리스크 관리]
|
||||
Data[data<br/>데이터 수집]
|
||||
end
|
||||
|
||||
subgraph "증권사 연동"
|
||||
Balance[balance<br/>계좌 연동]
|
||||
end
|
||||
end
|
||||
|
||||
Scheduler -->|1. 트리거| Strategy
|
||||
Strategy -->|2. 신호 생성| Risk
|
||||
Risk -->|3. 검증 통과| Scheduler
|
||||
Scheduler -->|4. 주문 생성| Balance
|
||||
Balance -->|5. 체결 결과| Mgmt
|
||||
|
||||
Strategy -->|시세 조회| Data
|
||||
Risk -->|리스크 데이터| Data
|
||||
Mgmt -->|자산 할당| Balance
|
||||
|
||||
style Mgmt fill:#4CAF50,color:#fff
|
||||
style Strategy fill:#2196F3,color:#fff
|
||||
style Scheduler fill:#FF9800,color:#fff
|
||||
style Risk fill:#F44336,color:#fff
|
||||
style Data fill:#9C27B0,color:#fff
|
||||
style Balance fill:#00BCD4,color:#fff
|
||||
```
|
||||
|
||||
### 3.2 Phase별 의존성
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Phase 3: Enterprise"
|
||||
P3_1[audit<br/>감사]
|
||||
P3_2[simulation<br/>시뮬레이션]
|
||||
end
|
||||
|
||||
subgraph "Phase 2: Production"
|
||||
P2_1[analytics<br/>분석]
|
||||
P2_2[monitor<br/>모니터링]
|
||||
end
|
||||
|
||||
subgraph "Phase 1: MVP"
|
||||
P1_1[balance<br/>계좌]
|
||||
P1_2[mgmt<br/>컨테이너]
|
||||
P1_3[strategy<br/>전략]
|
||||
P1_4[scheduler<br/>스케줄러]
|
||||
P1_5[risk<br/>리스크]
|
||||
P1_6[data<br/>데이터]
|
||||
end
|
||||
|
||||
P1_1 --> P2_1
|
||||
P1_2 --> P2_1
|
||||
P1_3 --> P2_1
|
||||
P1_6 --> P2_1
|
||||
|
||||
P1_1 --> P2_2
|
||||
P1_2 --> P2_2
|
||||
P1_4 --> P2_2
|
||||
|
||||
P2_1 --> P3_1
|
||||
P1_4 --> P3_1
|
||||
P1_1 --> P3_1
|
||||
|
||||
P1_3 --> P3_2
|
||||
P1_6 --> P3_2
|
||||
P1_5 --> P3_2
|
||||
|
||||
style P1_1 fill:#e3f2fd
|
||||
style P1_2 fill:#e3f2fd
|
||||
style P1_3 fill:#e3f2fd
|
||||
style P1_4 fill:#e3f2fd
|
||||
style P1_5 fill:#e3f2fd
|
||||
style P1_6 fill:#e3f2fd
|
||||
|
||||
style P2_1 fill:#fff9c4
|
||||
style P2_2 fill:#fff9c4
|
||||
|
||||
style P3_1 fill:#f3e5f5
|
||||
style P3_2 fill:#f3e5f5
|
||||
```
|
||||
|
||||
## 4. 데이터 흐름
|
||||
|
||||
### 4.1 시장 데이터 흐름
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
subgraph "외부 소스"
|
||||
Broker[증권사 API]
|
||||
Yahoo[Yahoo Finance]
|
||||
Alpha[Alpha Vantage]
|
||||
end
|
||||
|
||||
subgraph "데이터 수집"
|
||||
Collector[Data Collector]
|
||||
RealTime[실시간 스트림]
|
||||
Historical[과거 데이터 수집]
|
||||
end
|
||||
|
||||
subgraph "데이터 처리"
|
||||
Validator[데이터 검증]
|
||||
Adjuster[조정 처리]
|
||||
QualityCheck[품질 체크]
|
||||
end
|
||||
|
||||
subgraph "저장소"
|
||||
Cache[(Redis<br/>실시간)]
|
||||
TimeSeries[(TimescaleDB<br/>과거)]
|
||||
Metadata[(Metadata<br/>종목 정보)]
|
||||
end
|
||||
|
||||
subgraph "소비자"
|
||||
Strategy[전략 엔진]
|
||||
Backtest[백테스트]
|
||||
Analytics[분석]
|
||||
Monitor[모니터]
|
||||
end
|
||||
|
||||
Broker --> RealTime
|
||||
Yahoo --> Historical
|
||||
Alpha --> Historical
|
||||
|
||||
RealTime --> Collector
|
||||
Historical --> Collector
|
||||
|
||||
Collector --> Validator
|
||||
Validator --> QualityCheck
|
||||
QualityCheck -->|통과| Adjuster
|
||||
QualityCheck -->|실패| Alert[품질 알림]
|
||||
|
||||
Adjuster --> Cache
|
||||
Adjuster --> TimeSeries
|
||||
Adjuster --> Metadata
|
||||
|
||||
Cache --> Strategy
|
||||
Cache --> Monitor
|
||||
|
||||
TimeSeries --> Backtest
|
||||
TimeSeries --> Analytics
|
||||
|
||||
Metadata --> Strategy
|
||||
|
||||
style Cache fill:#FF6B6B,color:#fff
|
||||
style TimeSeries fill:#4ECDC4,color:#fff
|
||||
style Metadata fill:#45B7D1,color:#fff
|
||||
```
|
||||
|
||||
### 4.2 주문 실행 흐름
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
Start([스케줄 트리거]) --> GetContainer[컨테이너 정보 조회]
|
||||
GetContainer --> GenerateSignals[신호 생성]
|
||||
GenerateSignals --> GetMarketData[시장 데이터 조회]
|
||||
GetMarketData --> Calculate[매매 신호 계산]
|
||||
|
||||
Calculate --> RiskCheck[리스크 검증]
|
||||
|
||||
RiskCheck --> CheckResult{검증 결과}
|
||||
CheckResult -->|실패| SendAlert[실패 알림]
|
||||
CheckResult -->|통과| CheckMode{실행 모드}
|
||||
|
||||
CheckMode -->|AUTO| ExecuteOrder
|
||||
CheckMode -->|APPROVAL| RequestApproval[승인 요청]
|
||||
RequestApproval --> WaitApproval[승인 대기]
|
||||
WaitApproval --> ExecuteOrder[주문 실행]
|
||||
|
||||
ExecuteOrder --> SubmitToBroker[증권사에 주문 제출]
|
||||
SubmitToBroker --> WaitFill[체결 대기]
|
||||
WaitFill --> UpdatePosition[포지션 업데이트]
|
||||
UpdatePosition --> Reconcile[밸런스 조정]
|
||||
Reconcile --> CalcPerformance[성과 계산]
|
||||
CalcPerformance --> CheckAnomaly[이상 탐지]
|
||||
CheckAnomaly --> End([완료])
|
||||
|
||||
SendAlert --> End
|
||||
|
||||
style RiskCheck fill:#f44336,color:#fff
|
||||
style ExecuteOrder fill:#4caf50,color:#fff
|
||||
style CheckAnomaly fill:#ff9800,color:#fff
|
||||
```
|
||||
|
||||
## 5. 인프라 아키텍처
|
||||
|
||||
### 5.1 배포 구조
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "로드 밸런서"
|
||||
LB[Load Balancer<br/>Nginx/ALB]
|
||||
end
|
||||
|
||||
subgraph "애플리케이션 레이어"
|
||||
API1[API Gateway 1]
|
||||
API2[API Gateway 2]
|
||||
|
||||
Worker1[Worker 1<br/>scheduler/strategy]
|
||||
Worker2[Worker 2<br/>analytics]
|
||||
end
|
||||
|
||||
subgraph "데이터 레이어"
|
||||
PG_Master[(PostgreSQL<br/>Primary)]
|
||||
PG_Replica[(PostgreSQL<br/>Replica)]
|
||||
|
||||
Redis_Master[(Redis<br/>Primary)]
|
||||
Redis_Replica[(Redis<br/>Replica)]
|
||||
|
||||
TS[(TimescaleDB<br/>시계열)]
|
||||
end
|
||||
|
||||
subgraph "메시지 큐"
|
||||
Kafka[Kafka Cluster]
|
||||
end
|
||||
|
||||
subgraph "스토리지"
|
||||
S3[(S3<br/>리포트/백업)]
|
||||
end
|
||||
|
||||
subgraph "모니터링"
|
||||
Prometheus[Prometheus]
|
||||
Grafana[Grafana]
|
||||
ELK[ELK Stack]
|
||||
end
|
||||
|
||||
LB --> API1
|
||||
LB --> API2
|
||||
|
||||
API1 --> Worker1
|
||||
API2 --> Worker2
|
||||
|
||||
Worker1 --> PG_Master
|
||||
Worker2 --> PG_Replica
|
||||
|
||||
Worker1 --> Redis_Master
|
||||
Worker2 --> Redis_Replica
|
||||
|
||||
Worker1 --> TS
|
||||
Worker2 --> TS
|
||||
|
||||
Worker1 --> Kafka
|
||||
Worker2 --> Kafka
|
||||
|
||||
Worker1 --> S3
|
||||
Worker2 --> S3
|
||||
|
||||
PG_Master -.->|복제| PG_Replica
|
||||
Redis_Master -.->|복제| Redis_Replica
|
||||
|
||||
API1 --> Prometheus
|
||||
Worker1 --> Prometheus
|
||||
Prometheus --> Grafana
|
||||
|
||||
API1 --> ELK
|
||||
Worker1 --> ELK
|
||||
|
||||
style PG_Master fill:#4CAF50,color:#fff
|
||||
style Redis_Master fill:#FF6B6B,color:#fff
|
||||
style Kafka fill:#FF9800,color:#fff
|
||||
```
|
||||
|
||||
### 5.2 데이터베이스 스키마 분리
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "PostgreSQL"
|
||||
subgraph "Core Schema"
|
||||
Accounts[accounts<br/>계좌 정보]
|
||||
Containers[containers<br/>컨테이너]
|
||||
Strategies[strategies<br/>전략]
|
||||
Orders[orders<br/>주문]
|
||||
Positions[positions<br/>포지션]
|
||||
end
|
||||
|
||||
subgraph "Config Schema"
|
||||
RiskLimits[risk_limits<br/>리스크 한도]
|
||||
Schedules[schedules<br/>스케줄]
|
||||
AlertRules[alert_rules<br/>알림 규칙]
|
||||
end
|
||||
|
||||
subgraph "Analytics Schema"
|
||||
Performance[performance<br/>성과 데이터]
|
||||
Reports[reports<br/>리포트]
|
||||
end
|
||||
|
||||
subgraph "Audit Schema"
|
||||
AuditLogs[audit_logs<br/>감사 로그]
|
||||
ChangeLogs[change_logs<br/>변경 이력]
|
||||
end
|
||||
end
|
||||
|
||||
subgraph "TimescaleDB"
|
||||
PriceBars[price_bars<br/>가격 데이터]
|
||||
Metrics[metrics<br/>메트릭]
|
||||
Trades[trades<br/>거래 이력]
|
||||
end
|
||||
|
||||
subgraph "Redis"
|
||||
RealtimePrices[실시간 시세]
|
||||
SessionCache[세션 캐시]
|
||||
RateLimits[Rate Limit]
|
||||
end
|
||||
|
||||
Containers --> Accounts
|
||||
Strategies --> Containers
|
||||
Orders --> Containers
|
||||
Positions --> Containers
|
||||
|
||||
RiskLimits --> Containers
|
||||
Schedules --> Containers
|
||||
|
||||
Performance --> Containers
|
||||
Reports --> Performance
|
||||
|
||||
AuditLogs --> Containers
|
||||
ChangeLogs --> Containers
|
||||
|
||||
style Accounts fill:#e3f2fd
|
||||
style Containers fill:#e3f2fd
|
||||
style AuditLogs fill:#f3e5f5
|
||||
style PriceBars fill:#fff9c4
|
||||
```
|
||||
|
||||
## 6. 보안 아키텍처
|
||||
|
||||
### 6.1 인증 및 권한
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
User[사용자] --> Auth[인증 서비스]
|
||||
Auth --> JWT[JWT 토큰 발급]
|
||||
JWT --> Gateway[API Gateway]
|
||||
|
||||
Gateway --> RBAC[권한 체크]
|
||||
RBAC -->|관리자| AdminAPI[관리 API]
|
||||
RBAC -->|일반 사용자| UserAPI[사용자 API]
|
||||
RBAC -->|읽기 전용| ReadOnlyAPI[조회 API]
|
||||
|
||||
AdminAPI --> Services[백엔드 서비스]
|
||||
UserAPI --> Services
|
||||
ReadOnlyAPI --> Services
|
||||
|
||||
Services --> AuditLog[감사 로그]
|
||||
|
||||
style Auth fill:#4CAF50,color:#fff
|
||||
style RBAC fill:#FF9800,color:#fff
|
||||
style AuditLog fill:#F44336,color:#fff
|
||||
```
|
||||
|
||||
### 6.2 API 키 관리
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
User[사용자] -->|API 키 입력| Encrypt[암호화]
|
||||
Encrypt -->|AES-256| Store[(암호화 저장소)]
|
||||
|
||||
Scheduler[스케줄러] -->|필요 시| Decrypt[복호화]
|
||||
Store -->|암호화된 데이터| Decrypt
|
||||
Decrypt -->|평문 키| BrokerAPI[증권사 API]
|
||||
|
||||
BrokerAPI -->|응답| Scheduler
|
||||
|
||||
Note1[메모리에만 평문 존재]
|
||||
Note2[로그에 절대 기록 안함]
|
||||
|
||||
style Encrypt fill:#4CAF50,color:#fff
|
||||
style Store fill:#F44336,color:#fff
|
||||
style Decrypt fill:#FF9800,color:#fff
|
||||
```
|
||||
|
||||
## 7. 확장성 고려사항
|
||||
|
||||
### 7.1 수평 확장
|
||||
|
||||
- **API Gateway**: 로드 밸런서를 통한 다중 인스턴스
|
||||
- **Worker 프로세스**: 메시지 큐 기반 작업 분산
|
||||
- **데이터베이스**: Read Replica를 통한 읽기 부하 분산
|
||||
- **캐시**: Redis Cluster를 통한 분산 캐싱
|
||||
|
||||
### 7.2 증권사 플러그인 아키텍처
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Core"
|
||||
BrokerInterface[BrokerAdapter<br/>인터페이스]
|
||||
end
|
||||
|
||||
subgraph "플러그인"
|
||||
KoreaInvestment[한국투자증권<br/>Adapter]
|
||||
Samsung[삼성증권<br/>Adapter]
|
||||
Kiwoom[키움증권<br/>Adapter]
|
||||
Future[미래 증권사<br/>Adapter]
|
||||
end
|
||||
|
||||
BrokerInterface -.->|구현| KoreaInvestment
|
||||
BrokerInterface -.->|구현| Samsung
|
||||
BrokerInterface -.->|구현| Kiwoom
|
||||
BrokerInterface -.->|구현| Future
|
||||
|
||||
Balance[balance 컴포넌트] --> BrokerInterface
|
||||
|
||||
style BrokerInterface fill:#2196F3,color:#fff
|
||||
style Future fill:#ddd
|
||||
```
|
||||
|
||||
## 8. 장애 복구
|
||||
|
||||
### 8.1 장애 시나리오 및 대응
|
||||
|
||||
| 시나리오 | 영향 | 복구 방안 |
|
||||
|---------|------|----------|
|
||||
| 증권사 API 장애 | 주문 실행 불가 | 자동 재시도 (지수 백오프), 수동 개입 알림 |
|
||||
| 데이터베이스 장애 | 시스템 전체 중단 | Replica로 자동 Failover |
|
||||
| 시장 데이터 지연 | 신호 생성 지연 | 캐시 데이터 활용, 타임아웃 처리 |
|
||||
| Worker 프로세스 다운 | 특정 작업 중단 | 헬스 체크 실패 시 자동 재시작 |
|
||||
| 메시지 큐 장애 | 비동기 작업 중단 | 메시지 영속화, 큐 복구 후 재처리 |
|
||||
|
||||
### 8.2 백업 전략
|
||||
|
||||
- **데이터베이스**: 일일 전체 백업 + 트랜잭션 로그 백업 (Point-in-Time Recovery)
|
||||
- **설정**: Git 기반 버전 관리
|
||||
- **감사 로그**: S3에 불변 저장 (법적 보존 기간 준수)
|
||||
- **백테스트 결과**: 주요 결과만 장기 보관
|
||||
|
||||
## 9. 관련 문서
|
||||
|
||||
- [시스템 개요](./01-overview.md)
|
||||
- [공통 데이터 모델](./03-data-models.md)
|
||||
- [주요 워크플로우](./04-workflows.md)
|
||||
- [구현 로드맵](./05-roadmap.md)
|
||||
|
||||
### 구성요소 상세 문서
|
||||
- [Phase 1 컴포넌트](../components/phase1/)
|
||||
- [Phase 2 컴포넌트](../components/phase2/)
|
||||
- [Phase 3 컴포넌트](../components/phase3/)
|
||||
656
docs/03-data-models.md
Normal file
656
docs/03-data-models.md
Normal file
@@ -0,0 +1,656 @@
|
||||
# QuantBench 공통 데이터 모델
|
||||
|
||||
이 문서는 시스템 전반에서 사용되는 핵심 데이터 모델을 정의합니다.
|
||||
|
||||
## 1. 계좌 및 자산 관련
|
||||
|
||||
### 1.1 Account (계좌)
|
||||
|
||||
```typescript
|
||||
interface Account {
|
||||
id: string // 계좌 고유 ID
|
||||
brokerId: string // 증권사 식별자
|
||||
accountNumber: string // 계좌 번호
|
||||
accountName: string // 계좌 별칭
|
||||
accountType: AccountType // 계좌 유형
|
||||
credentials: EncryptedCredentials // 암호화된 인증 정보
|
||||
isActive: boolean // 활성 상태
|
||||
createdAt: Date // 생성 일시
|
||||
updatedAt: Date // 수정 일시
|
||||
}
|
||||
|
||||
type AccountType = 'STOCK' | 'FUTURES' | 'FOREX'
|
||||
|
||||
interface EncryptedCredentials {
|
||||
encryptedData: string // AES-256 암호화된 데이터
|
||||
iv: string // 초기화 벡터
|
||||
algorithm: string // 암호화 알고리즘
|
||||
}
|
||||
```
|
||||
|
||||
### 1.2 Balance (잔고)
|
||||
|
||||
```typescript
|
||||
interface Balance {
|
||||
accountId: string // 계좌 ID
|
||||
cash: CashBalance // 현금 잔고
|
||||
positions: Position[] // 보유 포지션
|
||||
totalEquity: number // 총 자산 평가액
|
||||
buyingPower: number // 매수 가능 금액
|
||||
withdrawableCash: number // 출금 가능 금액
|
||||
timestamp: Date // 조회 시점
|
||||
}
|
||||
|
||||
interface CashBalance {
|
||||
krw: number // 원화
|
||||
usd: number // 달러
|
||||
[currency: string]: number // 기타 통화
|
||||
}
|
||||
```
|
||||
|
||||
### 1.3 Position (포지션)
|
||||
|
||||
```typescript
|
||||
interface Position {
|
||||
symbol: string // 종목 코드
|
||||
symbolName?: string // 종목명
|
||||
quantity: number // 보유 수량
|
||||
averagePrice: number // 평균 매입가
|
||||
currentPrice: number // 현재가
|
||||
marketValue: number // 평가 금액
|
||||
unrealizedPnL: number // 평가 손익
|
||||
unrealizedPnLPct: number // 평가 손익률 (%)
|
||||
realizedPnL?: number // 실현 손익
|
||||
updatedAt: Date // 업데이트 시점
|
||||
}
|
||||
```
|
||||
|
||||
## 2. 컨테이너 관련
|
||||
|
||||
### 2.1 Container (컨테이너)
|
||||
|
||||
```typescript
|
||||
interface Container {
|
||||
id: string // 컨테이너 ID
|
||||
accountId: string // 소속 계좌 ID
|
||||
name: string // 컨테이너 이름
|
||||
description?: string // 설명
|
||||
strategyId?: string // 연결된 전략 ID
|
||||
|
||||
allocation: Allocation // 자산 할당
|
||||
constraints: Constraints // 제약 조건
|
||||
rebalancing: RebalancingConfig // 리밸런싱 설정
|
||||
|
||||
status: ContainerStatus // 상태
|
||||
createdAt: Date // 생성 일시
|
||||
updatedAt: Date // 수정 일시
|
||||
lastRebalancedAt?: Date // 마지막 리밸런싱 일시
|
||||
}
|
||||
|
||||
interface Allocation {
|
||||
initialAmount: number // 초기 할당 금액
|
||||
currentEquity: number // 현재 총 자산
|
||||
cashReserve: number // 최소 현금 보유량
|
||||
}
|
||||
|
||||
interface Constraints {
|
||||
maxSinglePositionPct: number // 단일 종목 최대 비중 (%)
|
||||
maxDrawdown: number // 최대 허용 낙폭 (%)
|
||||
allowedAssetClasses: string[] // 투자 가능 자산군
|
||||
maxLeverage?: number // 최대 레버리지 배수
|
||||
}
|
||||
|
||||
interface RebalancingConfig {
|
||||
frequency: RebalancingFrequency
|
||||
dayOfWeek?: number // WEEKLY인 경우 (1=월, 7=일)
|
||||
dayOfMonth?: number // MONTHLY인 경우 (1-31)
|
||||
autoExecute: boolean // 자동 실행 여부
|
||||
}
|
||||
|
||||
type RebalancingFrequency = 'DAILY' | 'WEEKLY' | 'MONTHLY' | 'QUARTERLY' | 'MANUAL'
|
||||
type ContainerStatus = 'ACTIVE' | 'PAUSED' | 'ARCHIVED'
|
||||
```
|
||||
|
||||
### 2.2 VirtualBalance (가상 잔고)
|
||||
|
||||
```typescript
|
||||
interface VirtualBalance {
|
||||
containerId: string // 컨테이너 ID
|
||||
cash: number // 현금
|
||||
positions: Position[] // 보유 종목
|
||||
totalValue: number // 총 가치
|
||||
availableCash: number // 주문 가능 현금
|
||||
allocatedValue: number // 할당받은 금액
|
||||
timestamp: Date // 조회 시점
|
||||
}
|
||||
```
|
||||
|
||||
## 3. 전략 관련
|
||||
|
||||
### 3.1 Strategy (전략)
|
||||
|
||||
```typescript
|
||||
interface Strategy {
|
||||
id: string // 전략 ID
|
||||
name: string // 전략 이름
|
||||
description: string // 설명
|
||||
category: StrategyCategory // 카테고리
|
||||
|
||||
versions: StrategyVersion[] // 버전 목록
|
||||
currentVersion: string // 현재 버전
|
||||
|
||||
parameters: Parameter[] // 파라미터 정의
|
||||
requiredData: string[] // 필요한 데이터 종류
|
||||
|
||||
createdBy: string // 작성자
|
||||
createdAt: Date // 생성 일시
|
||||
updatedAt: Date // 수정 일시
|
||||
isPublic: boolean // 공개 여부
|
||||
}
|
||||
|
||||
type StrategyCategory =
|
||||
| 'ASSET_ALLOCATION' // 자산 배분
|
||||
| 'MOMENTUM' // 모멘텀
|
||||
| 'VALUE' // 가치 투자
|
||||
| 'MEAN_REVERSION' // 평균 회귀
|
||||
| 'ARBITRAGE' // 차익 거래
|
||||
| 'CUSTOM' // 사용자 정의
|
||||
|
||||
interface StrategyVersion {
|
||||
version: string // 버전 번호 (예: "1.0.0")
|
||||
code: string // 전략 구현 코드
|
||||
changelog?: string // 변경 사항
|
||||
createdAt: Date // 생성 일시
|
||||
backtestResults?: BacktestResult[] // 백테스트 결과
|
||||
}
|
||||
|
||||
interface Parameter {
|
||||
name: string // 파라미터 이름
|
||||
type: ParameterType // 데이터 타입
|
||||
defaultValue: any // 기본값
|
||||
description?: string // 설명
|
||||
min?: number // 최소값 (숫자형)
|
||||
max?: number // 최대값 (숫자형)
|
||||
options?: string[] // 선택 옵션 (카테고리형)
|
||||
required: boolean // 필수 여부
|
||||
}
|
||||
|
||||
type ParameterType = 'INTEGER' | 'FLOAT' | 'BOOLEAN' | 'STRING' | 'CATEGORICAL'
|
||||
```
|
||||
|
||||
### 3.2 Signal (매매 신호)
|
||||
|
||||
```typescript
|
||||
interface Signal {
|
||||
symbol: string // 종목 코드
|
||||
action: SignalAction // 행동
|
||||
targetWeight?: number // 목표 비중 (0-1)
|
||||
targetQuantity?: number // 목표 수량
|
||||
reason?: string // 신호 발생 이유
|
||||
confidence?: number // 신호 신뢰도 (0-1)
|
||||
generatedAt: Date // 생성 시점
|
||||
metadata?: Record<string, any> // 추가 메타데이터
|
||||
}
|
||||
|
||||
type SignalAction = 'BUY' | 'SELL' | 'HOLD'
|
||||
```
|
||||
|
||||
### 3.3 BacktestResult (백테스트 결과)
|
||||
|
||||
```typescript
|
||||
interface BacktestResult {
|
||||
id: string // 결과 ID
|
||||
strategyId: string // 전략 ID
|
||||
strategyVersion: string // 전략 버전
|
||||
config: BacktestConfig // 설정
|
||||
|
||||
equity: EquityPoint[] // 자산 변화 시계열
|
||||
trades: Trade[] // 거래 내역
|
||||
metrics: PerformanceMetrics // 성과 지표
|
||||
|
||||
runAt: Date // 실행 일시
|
||||
duration: number // 실행 시간 (초)
|
||||
}
|
||||
|
||||
interface BacktestConfig {
|
||||
startDate: Date // 시작일
|
||||
endDate: Date // 종료일
|
||||
initialCapital: number // 초기 자본
|
||||
universe: string[] // 투자 대상 종목
|
||||
benchmark?: string // 벤치마크 (예: 'KOSPI')
|
||||
costs: TradingCosts // 거래 비용
|
||||
}
|
||||
|
||||
interface TradingCosts {
|
||||
commission: number // 거래 수수료 (%)
|
||||
slippage: number // 슬리피지 (bps)
|
||||
tax?: number // 세금 (%)
|
||||
}
|
||||
|
||||
interface EquityPoint {
|
||||
date: Date // 날짜
|
||||
value: number // 자산 가치
|
||||
cash: number // 현금
|
||||
positions: Record<string, number> // 보유 종목 (종목코드: 수량)
|
||||
}
|
||||
|
||||
interface Trade {
|
||||
date: Date // 거래 일시
|
||||
symbol: string // 종목 코드
|
||||
action: 'BUY' | 'SELL' // 매수/매도
|
||||
quantity: number // 수량
|
||||
price: number // 체결 가격
|
||||
commission: number // 수수료
|
||||
slippage: number // 슬리피지
|
||||
}
|
||||
```
|
||||
|
||||
## 4. 주문 관련
|
||||
|
||||
### 4.1 Order (주문)
|
||||
|
||||
```typescript
|
||||
interface Order {
|
||||
orderId?: string // 주문 ID
|
||||
accountId: string // 계좌 ID
|
||||
containerId?: string // 컨테이너 ID (있는 경우)
|
||||
symbol: string // 종목 코드
|
||||
side: OrderSide // 매수/매도
|
||||
orderType: OrderType // 주문 유형
|
||||
quantity: number // 주문 수량
|
||||
price?: number // 지정가 (LIMIT인 경우)
|
||||
stopPrice?: number // 스톱 가격 (STOP인 경우)
|
||||
|
||||
status: OrderStatus // 주문 상태
|
||||
filledQuantity?: number // 체결 수량
|
||||
averageFillPrice?: number // 평균 체결가
|
||||
commission?: number // 수수료
|
||||
|
||||
submittedAt?: Date // 제출 일시
|
||||
executedAt?: Date // 체결 일시
|
||||
cancelledAt?: Date // 취소 일시
|
||||
|
||||
metadata?: Record<string, any> // 추가 메타데이터
|
||||
}
|
||||
|
||||
type OrderSide = 'BUY' | 'SELL'
|
||||
type OrderType = 'MARKET' | 'LIMIT' | 'STOP' | 'STOP_LIMIT'
|
||||
type OrderStatus =
|
||||
| 'PENDING' // 대기 중
|
||||
| 'SUBMITTED' // 제출됨
|
||||
| 'PARTIALLY_FILLED' // 부분 체결
|
||||
| 'FILLED' // 완전 체결
|
||||
| 'CANCELLED' // 취소됨
|
||||
| 'REJECTED' // 거부됨
|
||||
| 'EXPIRED' // 만료됨
|
||||
```
|
||||
|
||||
## 5. 시장 데이터 관련
|
||||
|
||||
### 5.1 PriceBar (가격 바)
|
||||
|
||||
```typescript
|
||||
interface PriceBar {
|
||||
symbol: string // 종목 코드
|
||||
timestamp: Date // 시간
|
||||
interval: Interval // 주기
|
||||
open: number // 시가
|
||||
high: number // 고가
|
||||
low: number // 저가
|
||||
close: number // 종가
|
||||
volume: number // 거래량
|
||||
adjustedClose?: number // 조정 종가
|
||||
}
|
||||
|
||||
type Interval = '1m' | '5m' | '15m' | '1h' | '4h' | '1d' | '1w' | '1M'
|
||||
```
|
||||
|
||||
### 5.2 Quote (현재가)
|
||||
|
||||
```typescript
|
||||
interface Quote {
|
||||
symbol: string // 종목 코드
|
||||
price: number // 현재가
|
||||
change: number // 전일 대비 변동
|
||||
changePct: number // 변동률 (%)
|
||||
volume: number // 거래량
|
||||
bidPrice: number // 매수 호가
|
||||
askPrice: number // 매도 호가
|
||||
bidSize: number // 매수 호가 수량
|
||||
askSize: number // 매도 호가 수량
|
||||
timestamp: Date // 시세 시간
|
||||
}
|
||||
```
|
||||
|
||||
## 6. 리스크 관련
|
||||
|
||||
### 6.1 RiskLimits (리스크 한도)
|
||||
|
||||
```typescript
|
||||
interface RiskLimits {
|
||||
containerId: string // 컨테이너 ID
|
||||
|
||||
position: PositionLimits // 포지션 한도
|
||||
loss: LossLimits // 손실 한도
|
||||
exposure: ExposureLimits // 익스포저 한도
|
||||
}
|
||||
|
||||
interface PositionLimits {
|
||||
maxSinglePositionPct: number // 단일 종목 최대 비중 (%)
|
||||
maxSectorPct: number // 단일 섹터 최대 비중 (%)
|
||||
maxTotalLeverage: number // 최대 레버리지 배수
|
||||
minPositionSize?: number // 최소 포지션 크기
|
||||
}
|
||||
|
||||
interface LossLimits {
|
||||
maxDailyLossPct: number // 일일 최대 손실 (%)
|
||||
maxDrawdownPct: number // 최대 낙폭 (%)
|
||||
stopLossEnabled: boolean // 손절 활성화
|
||||
takeProfitEnabled?: boolean // 익절 활성화
|
||||
}
|
||||
|
||||
interface ExposureLimits {
|
||||
maxLongExposure: number // 최대 롱 익스포저
|
||||
maxShortExposure: number // 최대 숏 익스포저
|
||||
maxGrossExposure: number // 최대 총 익스포저
|
||||
maxNetExposure?: number // 최대 순 익스포저
|
||||
}
|
||||
```
|
||||
|
||||
### 6.2 RiskCheckResult (리스크 검증 결과)
|
||||
|
||||
```typescript
|
||||
interface RiskCheckResult {
|
||||
passed: boolean // 통과 여부
|
||||
violations: RiskViolation[] // 위반 항목
|
||||
recommendations?: string[] // 권장 사항
|
||||
timestamp: Date // 검증 시점
|
||||
}
|
||||
|
||||
interface RiskViolation {
|
||||
rule: string // 규칙 이름
|
||||
severity: ViolationSeverity // 심각도
|
||||
message: string // 메시지
|
||||
currentValue: number // 현재 값
|
||||
limitValue: number // 한도 값
|
||||
}
|
||||
|
||||
type ViolationSeverity = 'BLOCKING' | 'WARNING' | 'INFO'
|
||||
```
|
||||
|
||||
## 7. 스케줄 및 실행 관련
|
||||
|
||||
### 7.1 Schedule (스케줄)
|
||||
|
||||
```typescript
|
||||
interface Schedule {
|
||||
id: string // 스케줄 ID
|
||||
containerId: string // 컨테이너 ID
|
||||
name: string // 스케줄 이름
|
||||
|
||||
trigger: ScheduleTrigger // 트리거 설정
|
||||
executionMode: ExecutionMode // 실행 모드
|
||||
constraints: ScheduleConstraints // 제약 조건
|
||||
|
||||
isActive: boolean // 활성 상태
|
||||
nextRun?: Date // 다음 실행 시간
|
||||
lastRun?: Date // 마지막 실행 시간
|
||||
createdAt: Date // 생성 일시
|
||||
}
|
||||
|
||||
interface ScheduleTrigger {
|
||||
type: TriggerType // 트리거 유형
|
||||
expression?: string // Cron 표현식 (CRON인 경우)
|
||||
intervalMinutes?: number // 주기 (INTERVAL인 경우)
|
||||
event?: TriggerEvent // 이벤트 (EVENT인 경우)
|
||||
}
|
||||
|
||||
type TriggerType = 'CRON' | 'INTERVAL' | 'EVENT'
|
||||
type TriggerEvent = 'MARKET_OPEN' | 'MARKET_CLOSE' | 'CUSTOM'
|
||||
type ExecutionMode = 'AUTO' | 'APPROVAL_REQUIRED'
|
||||
|
||||
interface ScheduleConstraints {
|
||||
marketHoursOnly: boolean // 장 시간만
|
||||
skipHolidays: boolean // 휴일 건너뛰기
|
||||
minIntervalHours?: number // 최소 실행 간격 (시간)
|
||||
}
|
||||
```
|
||||
|
||||
### 7.2 Execution (실행)
|
||||
|
||||
```typescript
|
||||
interface Execution {
|
||||
id: string // 실행 ID
|
||||
containerId: string // 컨테이너 ID
|
||||
strategyId: string // 전략 ID
|
||||
scheduleId?: string // 스케줄 ID (자동 실행인 경우)
|
||||
|
||||
status: ExecutionStatus // 상태
|
||||
signals: Signal[] // 생성된 신호
|
||||
plannedOrders: Order[] // 계획된 주문
|
||||
executedOrders: Order[] // 실행된 주문
|
||||
|
||||
estimatedCost: EstimatedCost // 예상 비용
|
||||
approvalRequest?: ApprovalRequest // 승인 요청 (있는 경우)
|
||||
|
||||
startedAt?: Date // 시작 일시
|
||||
completedAt?: Date // 완료 일시
|
||||
error?: string // 에러 메시지
|
||||
}
|
||||
|
||||
type ExecutionStatus =
|
||||
| 'PENDING' // 대기
|
||||
| 'APPROVED' // 승인됨
|
||||
| 'REJECTED' // 거부됨
|
||||
| 'RUNNING' // 실행 중
|
||||
| 'COMPLETED' // 완료
|
||||
| 'FAILED' // 실패
|
||||
|
||||
interface EstimatedCost {
|
||||
commission: number // 예상 수수료
|
||||
slippage: number // 예상 슬리피지
|
||||
totalValue: number // 총 거래 금액
|
||||
}
|
||||
|
||||
interface ApprovalRequest {
|
||||
id: string // 요청 ID
|
||||
executionId: string // 실행 ID
|
||||
summary: ApprovalSummary // 요약
|
||||
orders: Order[] // 주문 목록
|
||||
requestedAt: Date // 요청 일시
|
||||
expiresAt: Date // 만료 일시
|
||||
approvedAt?: Date // 승인 일시
|
||||
approvedBy?: string // 승인자
|
||||
decision?: ApprovalDecision // 결정
|
||||
}
|
||||
|
||||
interface ApprovalSummary {
|
||||
numOrders: number // 주문 건수
|
||||
buyValue: number // 매수 금액
|
||||
sellValue: number // 매도 금액
|
||||
estimatedCommission: number // 예상 수수료
|
||||
}
|
||||
|
||||
type ApprovalDecision = 'APPROVED' | 'REJECTED'
|
||||
```
|
||||
|
||||
## 8. 성과 분석 관련
|
||||
|
||||
### 8.1 PerformanceMetrics (성과 지표)
|
||||
|
||||
```typescript
|
||||
interface PerformanceMetrics {
|
||||
// 수익률
|
||||
totalReturn: number // 총 수익률 (%)
|
||||
cagr: number // 연평균 성장률 (%)
|
||||
annualizedReturn: number // 연율화 수익률 (%)
|
||||
|
||||
// 리스크
|
||||
volatility: number // 변동성 (%, 연율화)
|
||||
maxDrawdown: number // 최대 낙폭 (%)
|
||||
downsideDeviation: number // 하방 편차 (%)
|
||||
|
||||
// 리스크 조정 수익률
|
||||
sharpeRatio: number // 샤프 비율
|
||||
sortinoRatio: number // 소르티노 비율
|
||||
calmarRatio: number // 칼마 비율
|
||||
|
||||
// 거래 지표
|
||||
winRate: number // 승률 (%)
|
||||
avgWin: number // 평균 수익 (%)
|
||||
avgLoss: number // 평균 손실 (%)
|
||||
profitFactor: number // 손익비
|
||||
|
||||
// 기타
|
||||
tradingDays: number // 거래 일수
|
||||
totalTrades: number // 총 거래 건수
|
||||
turnover: number // 회전율 (연율화)
|
||||
}
|
||||
```
|
||||
|
||||
## 9. 모니터링 및 알림 관련
|
||||
|
||||
### 9.1 Alert (알림)
|
||||
|
||||
```typescript
|
||||
interface Alert {
|
||||
id: string // 알림 ID
|
||||
type: AlertType // 알림 유형
|
||||
severity: AlertSeverity // 심각도
|
||||
|
||||
title: string // 제목
|
||||
message: string // 내용
|
||||
|
||||
source: string // 발생 컴포넌트
|
||||
containerId?: string // 컨테이너 ID (있는 경우)
|
||||
accountId?: string // 계좌 ID (있는 경우)
|
||||
|
||||
channels: AlertChannel[] // 발송 채널
|
||||
sentAt?: Date // 발송 일시
|
||||
|
||||
acknowledged: boolean // 확인 여부
|
||||
acknowledgedAt?: Date // 확인 일시
|
||||
acknowledgedBy?: string // 확인자
|
||||
|
||||
createdAt: Date // 생성 일시
|
||||
metadata?: Record<string, any> // 추가 메타데이터
|
||||
}
|
||||
|
||||
type AlertType =
|
||||
| 'SYSTEM' // 시스템
|
||||
| 'RISK' // 리스크
|
||||
| 'EXECUTION' // 실행
|
||||
| 'PERFORMANCE' // 성과
|
||||
| 'ANOMALY' // 이상
|
||||
|
||||
type AlertSeverity = 'INFO' | 'WARNING' | 'ERROR' | 'CRITICAL'
|
||||
type AlertChannel = 'EMAIL' | 'SMS' | 'PUSH' | 'SLACK' | 'WEBHOOK'
|
||||
```
|
||||
|
||||
## 10. 감사 관련
|
||||
|
||||
### 10.1 AuditEvent (감사 이벤트)
|
||||
|
||||
```typescript
|
||||
interface AuditEvent {
|
||||
id: string // 이벤트 ID
|
||||
timestamp: Date // 발생 시간
|
||||
|
||||
eventType: AuditEventType // 이벤트 유형
|
||||
action: string // 행동 (CREATE, UPDATE, DELETE 등)
|
||||
|
||||
userId?: string // 사용자 ID
|
||||
accountId?: string // 계좌 ID
|
||||
containerId?: string // 컨테이너 ID
|
||||
|
||||
entity: string // 엔티티 타입
|
||||
entityId: string // 엔티티 ID
|
||||
|
||||
before?: any // 변경 전 상태
|
||||
after?: any // 변경 후 상태
|
||||
|
||||
metadata: AuditMetadata // 메타데이터
|
||||
|
||||
hash: string // 무결성 검증용 해시
|
||||
previousHash?: string // 이전 이벤트 해시 (체인)
|
||||
}
|
||||
|
||||
type AuditEventType =
|
||||
| 'ORDER' // 주문
|
||||
| 'CONFIG_CHANGE' // 설정 변경
|
||||
| 'EXECUTION' // 실행
|
||||
| 'LOGIN' // 로그인
|
||||
| 'DATA_EXPORT' // 데이터 내보내기
|
||||
| 'APPROVAL' // 승인
|
||||
|
||||
interface AuditMetadata {
|
||||
ipAddress?: string // IP 주소
|
||||
userAgent?: string // User Agent
|
||||
reason?: string // 사유
|
||||
source?: string // 출처
|
||||
}
|
||||
```
|
||||
|
||||
## 11. 데이터 관계도
|
||||
|
||||
```mermaid
|
||||
erDiagram
|
||||
Account ||--o{ Container : has
|
||||
Account ||--o{ Balance : has
|
||||
Container ||--o{ VirtualBalance : has
|
||||
Container ||--o| Strategy : uses
|
||||
Container ||--o{ Schedule : has
|
||||
Container ||--o{ RiskLimits : has
|
||||
Container ||--o{ Execution : has
|
||||
|
||||
Strategy ||--o{ StrategyVersion : has
|
||||
Strategy ||--o{ BacktestResult : generates
|
||||
|
||||
Execution ||--o{ Signal : generates
|
||||
Execution ||--o{ Order : creates
|
||||
Execution ||--o| ApprovalRequest : requires
|
||||
|
||||
Order }o--|| Account : belongs_to
|
||||
Order }o--o| Container : belongs_to
|
||||
|
||||
Balance ||--o{ Position : contains
|
||||
VirtualBalance ||--o{ Position : contains
|
||||
|
||||
Container ||--o{ Alert : triggers
|
||||
Execution ||--o{ AuditEvent : generates
|
||||
Order ||--o{ AuditEvent : generates
|
||||
|
||||
Account {
|
||||
string id PK
|
||||
string brokerId
|
||||
string accountNumber
|
||||
AccountType accountType
|
||||
}
|
||||
|
||||
Container {
|
||||
string id PK
|
||||
string accountId FK
|
||||
string strategyId FK
|
||||
ContainerStatus status
|
||||
}
|
||||
|
||||
Strategy {
|
||||
string id PK
|
||||
string name
|
||||
StrategyCategory category
|
||||
}
|
||||
|
||||
Order {
|
||||
string orderId PK
|
||||
string accountId FK
|
||||
string containerId FK
|
||||
OrderStatus status
|
||||
}
|
||||
```
|
||||
|
||||
## 12. 관련 문서
|
||||
|
||||
- [시스템 개요](./01-overview.md)
|
||||
- [전체 아키텍처](./02-architecture.md)
|
||||
- [주요 워크플로우](./04-workflows.md)
|
||||
- [구현 로드맵](./05-roadmap.md)
|
||||
695
docs/04-workflows.md
Normal file
695
docs/04-workflows.md
Normal file
@@ -0,0 +1,695 @@
|
||||
# QuantBench 주요 워크플로우
|
||||
|
||||
이 문서는 시스템의 핵심 워크플로우를 상세히 설명합니다.
|
||||
|
||||
## 1. 전략 실행 워크플로우
|
||||
|
||||
### 1.1 전체 흐름
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant S as Scheduler
|
||||
participant M as Mgmt
|
||||
participant ST as Strategy
|
||||
participant D as Data
|
||||
participant R as Risk
|
||||
participant B as Balance
|
||||
participant A as Analytics
|
||||
participant MO as Monitor
|
||||
|
||||
Note over S: 스케줄 트리거 발생
|
||||
|
||||
S->>M: 1. 컨테이너 정보 조회
|
||||
M-->>S: 컨테이너 설정 & 현재 포지션
|
||||
|
||||
S->>ST: 2. 전략 실행 요청
|
||||
ST->>D: 2.1 시장 데이터 조회
|
||||
D-->>ST: 최신 시세 데이터
|
||||
ST->>ST: 2.2 신호 생성
|
||||
ST-->>S: 매매 신호 반환
|
||||
|
||||
S->>R: 3. 리스크 체크
|
||||
R->>R: 3.1 포지션 사이즈 검증
|
||||
R->>R: 3.2 VaR 계산
|
||||
R->>R: 3.3 한도 확인
|
||||
|
||||
alt 리스크 체크 실패
|
||||
R-->>S: 검증 실패
|
||||
S->>MO: 알림 발송
|
||||
MO-->>S: 알림 완료
|
||||
Note over S: 실행 중단
|
||||
else 리스크 체크 통과
|
||||
R-->>S: 검증 통과
|
||||
|
||||
alt 승인 필요 모드
|
||||
S->>S: 승인 요청 생성
|
||||
S->>MO: 사용자에게 알림
|
||||
Note over S: 사용자 승인 대기
|
||||
S->>S: 승인 완료
|
||||
end
|
||||
|
||||
S->>B: 4. 주문 제출
|
||||
B->>B: 4.1 증권사 API 호출
|
||||
B-->>S: 주문 접수 완료
|
||||
|
||||
Note over B: 체결 대기...
|
||||
|
||||
B->>B: 4.2 체결 확인
|
||||
B->>M: 5. 포지션 업데이트
|
||||
M->>M: 5.1 컨테이너 밸런스 갱신
|
||||
|
||||
M->>A: 6. 성과 계산 트리거
|
||||
A->>A: 6.1 수익률 계산
|
||||
A->>A: 6.2 리스크 지표 갱신
|
||||
|
||||
A->>MO: 7. 메트릭 업데이트
|
||||
MO->>MO: 7.1 대시보드 갱신
|
||||
MO->>MO: 7.2 이상 탐지
|
||||
|
||||
alt 이상 탐지 시
|
||||
MO->>MO: 알림 발송
|
||||
end
|
||||
|
||||
S->>S: 8. 실행 완료 기록
|
||||
end
|
||||
```
|
||||
|
||||
### 1.2 상세 단계
|
||||
|
||||
#### 1단계: 스케줄 트리거
|
||||
```typescript
|
||||
// 스케줄러가 설정된 시간에 실행을 트리거
|
||||
scheduler.onTrigger(schedule => {
|
||||
const container = mgmt.getContainer(schedule.containerId)
|
||||
const execution = scheduler.createExecution(container, schedule)
|
||||
scheduler.executeStrategy(execution)
|
||||
})
|
||||
```
|
||||
|
||||
#### 2단계: 신호 생성
|
||||
```typescript
|
||||
// 전략이 시장 데이터를 기반으로 신호 생성
|
||||
const marketData = await data.getMarketData(container.strategyUniverse)
|
||||
const signals = await strategy.generateSignals(marketData, container.parameters)
|
||||
|
||||
// 생성된 신호 예시
|
||||
// [
|
||||
// { symbol: 'AAPL', action: 'BUY', targetWeight: 0.3 },
|
||||
// { symbol: 'GOOGL', action: 'SELL', targetWeight: 0 }
|
||||
// ]
|
||||
```
|
||||
|
||||
#### 3단계: 리스크 검증
|
||||
```typescript
|
||||
// 신호를 주문으로 변환
|
||||
const plannedOrders = strategy.signalsToOrders(signals, container)
|
||||
|
||||
// 리스크 검증
|
||||
const riskResult = await risk.validateOrders(plannedOrders, container)
|
||||
|
||||
if (!riskResult.passed) {
|
||||
// 리스크 위반 시 실행 중단
|
||||
await monitor.sendAlert({
|
||||
type: 'RISK',
|
||||
severity: 'ERROR',
|
||||
message: `리스크 검증 실패: ${riskResult.violations}`,
|
||||
containerId: container.id
|
||||
})
|
||||
return
|
||||
}
|
||||
```
|
||||
|
||||
#### 4단계: 주문 실행
|
||||
```typescript
|
||||
// 승인 필요 모드인 경우
|
||||
if (schedule.executionMode === 'APPROVAL_REQUIRED') {
|
||||
const approvalRequest = await scheduler.requestApproval(execution)
|
||||
await monitor.sendNotification(approvalRequest)
|
||||
|
||||
// 승인 대기
|
||||
const approved = await scheduler.waitForApproval(approvalRequest)
|
||||
if (!approved) return
|
||||
}
|
||||
|
||||
// 주문 제출
|
||||
const executedOrders = []
|
||||
for (const order of plannedOrders) {
|
||||
const result = await balance.placeOrder(order)
|
||||
executedOrders.push(result)
|
||||
}
|
||||
```
|
||||
|
||||
#### 5단계: 포지션 업데이트
|
||||
```typescript
|
||||
// 체결 완료 후 컨테이너 밸런스 업데이트
|
||||
for (const order of executedOrders) {
|
||||
if (order.status === 'FILLED') {
|
||||
await mgmt.updatePosition(container.id, {
|
||||
symbol: order.symbol,
|
||||
quantity: order.side === 'BUY' ? order.filledQuantity : -order.filledQuantity,
|
||||
price: order.averageFillPrice
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
// 밸런스 조정 (reconciliation)
|
||||
await mgmt.reconcileContainer(container.id)
|
||||
```
|
||||
|
||||
## 2. 리스크 관리 워크플로우
|
||||
|
||||
### 2.1 사전 주문 검증
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
Start([주문 요청]) --> GetPosition[현재 포지션 조회]
|
||||
GetPosition --> CalcNewPosition[신규 포지션 계산]
|
||||
|
||||
CalcNewPosition --> CheckBalance{잔고 충분?}
|
||||
CheckBalance -->|No| Reject1[주문 거부:<br/>잔고 부족]
|
||||
CheckBalance -->|Yes| CheckSize
|
||||
|
||||
CheckSize{포지션 사이즈<br/>한도 내?}
|
||||
CheckSize -->|No| Reject2[주문 거부:<br/>사이즈 초과]
|
||||
CheckSize -->|Yes| CheckConcentration
|
||||
|
||||
CheckConcentration{집중도<br/>한도 내?}
|
||||
CheckConcentration -->|No| Reject3[주문 거부:<br/>집중도 초과]
|
||||
CheckConcentration -->|Yes| CalcVaR
|
||||
|
||||
CalcVaR[VaR 계산]
|
||||
CalcVaR --> CheckVaR{VaR<br/>한도 내?}
|
||||
CheckVaR -->|No| Warning1[경고 발생<br/>계속 진행]
|
||||
CheckVaR -->|Yes| CheckDrawdown
|
||||
|
||||
Warning1 --> CheckDrawdown
|
||||
|
||||
CheckDrawdown{최대 낙폭<br/>한도 내?}
|
||||
CheckDrawdown -->|No| Reject4[주문 거부:<br/>MDD 초과]
|
||||
CheckDrawdown -->|Yes| CheckLeverage
|
||||
|
||||
CheckLeverage{레버리지<br/>한도 내?}
|
||||
CheckLeverage -->|No| Reject5[주문 거부:<br/>레버리지 초과]
|
||||
CheckLeverage -->|Yes| Approve
|
||||
|
||||
Approve([검증 통과:<br/>주문 실행])
|
||||
|
||||
Reject1 --> Log[리스크 로그 기록]
|
||||
Reject2 --> Log
|
||||
Reject3 --> Log
|
||||
Reject4 --> Log
|
||||
Reject5 --> Log
|
||||
|
||||
Approve --> ExecuteOrder[주문 제출]
|
||||
ExecuteOrder --> Monitor[실시간 모니터링]
|
||||
|
||||
Monitor --> CheckStop{손절/익절<br/>조건 충족?}
|
||||
CheckStop -->|Yes| AutoClose[자동 청산]
|
||||
CheckStop -->|No| Monitor
|
||||
|
||||
style Start fill:#4CAF50,color:#fff
|
||||
style Approve fill:#4CAF50,color:#fff
|
||||
style Reject1 fill:#F44336,color:#fff
|
||||
style Reject2 fill:#F44336,color:#fff
|
||||
style Reject3 fill:#F44336,color:#fff
|
||||
style Reject4 fill:#F44336,color:#fff
|
||||
style Reject5 fill:#F44336,color:#fff
|
||||
style Warning1 fill:#FF9800,color:#fff
|
||||
```
|
||||
|
||||
### 2.2 실시간 리스크 모니터링
|
||||
|
||||
```typescript
|
||||
// 실시간 포지션 모니터링
|
||||
monitor.watchContainer(container.id, async (positions, marketData) => {
|
||||
// 손절 조건 체크
|
||||
for (const position of positions) {
|
||||
const stopLoss = risk.getStopLoss(container.id, position.symbol)
|
||||
if (stopLoss && position.unrealizedPnLPct <= -stopLoss.pct) {
|
||||
// 손절 트리거
|
||||
await scheduler.executeEmergencyClose(container.id, position.symbol)
|
||||
await monitor.sendAlert({
|
||||
type: 'RISK',
|
||||
severity: 'WARNING',
|
||||
message: `손절 실행: ${position.symbol} ${position.unrealizedPnLPct}%`
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
// MDD 체크
|
||||
const performance = await analytics.getCurrentPerformance(container.id)
|
||||
const limits = await risk.getRiskLimits(container.id)
|
||||
|
||||
if (performance.currentDrawdown >= limits.loss.maxDrawdownPct) {
|
||||
// 컨테이너 일시 정지
|
||||
await mgmt.pauseContainer(container.id)
|
||||
await monitor.sendAlert({
|
||||
type: 'RISK',
|
||||
severity: 'CRITICAL',
|
||||
message: `최대 낙폭 초과: ${performance.currentDrawdown}%`
|
||||
})
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
## 3. 승인 워크플로우
|
||||
|
||||
### 3.1 승인 요청 및 처리
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
Trigger[스케줄 트리거] --> GenerateSignals[신호 생성]
|
||||
GenerateSignals --> RiskCheck[리스크 체크]
|
||||
|
||||
RiskCheck --> CheckMode{실행 모드}
|
||||
|
||||
CheckMode -->|AUTO| AutoExecute[자동 실행]
|
||||
CheckMode -->|APPROVAL| CreateRequest
|
||||
|
||||
CreateRequest[승인 요청 생성]
|
||||
CreateRequest --> SendNotification[알림 발송]
|
||||
SendNotification --> WaitApproval[승인 대기]
|
||||
|
||||
WaitApproval --> CheckTimeout{타임아웃?}
|
||||
CheckTimeout -->|Yes| Expired[요청 만료]
|
||||
CheckTimeout -->|No| WaitApproval
|
||||
|
||||
WaitApproval --> UserDecision{사용자 결정}
|
||||
|
||||
UserDecision -->|승인| Execute[주문 실행]
|
||||
UserDecision -->|거부| Rejected[실행 거부]
|
||||
|
||||
AutoExecute --> Execute
|
||||
|
||||
Execute --> PlaceOrders[주문 제출]
|
||||
PlaceOrders --> Success{성공?}
|
||||
|
||||
Success -->|Yes| NotifySuccess[성공 알림]
|
||||
Success -->|No| NotifyFail[실패 알림]
|
||||
|
||||
Rejected --> LogRejection[거부 로그]
|
||||
Expired --> LogExpired[만료 로그]
|
||||
|
||||
NotifySuccess --> End([완료])
|
||||
NotifyFail --> End
|
||||
LogRejection --> End
|
||||
LogExpired --> End
|
||||
|
||||
style Execute fill:#4CAF50,color:#fff
|
||||
style Rejected fill:#F44336,color:#fff
|
||||
style Expired fill:#FF9800,color:#fff
|
||||
style AutoExecute fill:#2196F3,color:#fff
|
||||
```
|
||||
|
||||
### 3.2 승인 요청 생성
|
||||
|
||||
```typescript
|
||||
async function createApprovalRequest(execution: Execution): Promise<ApprovalRequest> {
|
||||
// 주문 요약 생성
|
||||
const summary = {
|
||||
numOrders: execution.plannedOrders.length,
|
||||
buyValue: execution.plannedOrders
|
||||
.filter(o => o.side === 'BUY')
|
||||
.reduce((sum, o) => sum + o.quantity * o.price!, 0),
|
||||
sellValue: execution.plannedOrders
|
||||
.filter(o => o.side === 'SELL')
|
||||
.reduce((sum, o) => sum + o.quantity * o.price!, 0),
|
||||
estimatedCommission: execution.estimatedCost.commission
|
||||
}
|
||||
|
||||
// 승인 요청 생성
|
||||
const request = await scheduler.createApprovalRequest({
|
||||
executionId: execution.id,
|
||||
summary,
|
||||
orders: execution.plannedOrders,
|
||||
expiresAt: new Date(Date.now() + 30 * 60 * 1000) // 30분 후 만료
|
||||
})
|
||||
|
||||
// 알림 발송
|
||||
await monitor.sendNotification({
|
||||
type: 'EXECUTION',
|
||||
severity: 'INFO',
|
||||
title: '주문 승인 요청',
|
||||
message: `
|
||||
${summary.numOrders}건의 주문이 대기 중입니다.
|
||||
매수: ${summary.buyValue.toLocaleString()}원
|
||||
매도: ${summary.sellValue.toLocaleString()}원
|
||||
예상 수수료: ${summary.estimatedCommission.toLocaleString()}원
|
||||
`,
|
||||
channels: ['EMAIL', 'PUSH']
|
||||
})
|
||||
|
||||
return request
|
||||
}
|
||||
```
|
||||
|
||||
## 4. 컨테이너 생명주기
|
||||
|
||||
### 4.1 상태 전이도
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> Created: createContainer()
|
||||
|
||||
Created --> Active: activate()
|
||||
Created --> [*]: delete()
|
||||
|
||||
Active --> Running: scheduler trigger
|
||||
Active --> Paused: pause()
|
||||
Active --> [*]: delete()
|
||||
|
||||
Running --> Active: execution complete
|
||||
Running --> Error: execution failed
|
||||
Running --> Paused: emergency stop
|
||||
|
||||
Paused --> Active: resume()
|
||||
Paused --> [*]: delete()
|
||||
|
||||
Error --> Active: resolve & restart
|
||||
Error --> Paused: manual intervention
|
||||
Error --> [*]: delete()
|
||||
|
||||
state Running {
|
||||
[*] --> GenerateSignals
|
||||
GenerateSignals --> RiskCheck
|
||||
RiskCheck --> PlaceOrders: pass
|
||||
RiskCheck --> [*]: fail
|
||||
PlaceOrders --> AwaitFill
|
||||
AwaitFill --> UpdatePosition
|
||||
UpdatePosition --> [*]
|
||||
}
|
||||
```
|
||||
|
||||
### 4.2 컨테이너 생성 및 활성화
|
||||
|
||||
```typescript
|
||||
// 1. 컨테이너 생성
|
||||
const container = await mgmt.createContainer({
|
||||
accountId: 'account-123',
|
||||
name: '성장주 전략',
|
||||
allocation: {
|
||||
initialAmount: 10000000, // 1천만원
|
||||
cashReserve: 1000000 // 최소 100만원 현금 보유
|
||||
},
|
||||
constraints: {
|
||||
maxSinglePositionPct: 20, // 단일 종목 최대 20%
|
||||
maxDrawdown: 15, // 최대 낙폭 15%
|
||||
allowedAssetClasses: ['STOCK']
|
||||
}
|
||||
})
|
||||
|
||||
// 2. 전략 할당
|
||||
await mgmt.assignStrategy(container.id, 'strategy-momentum-v1')
|
||||
|
||||
// 3. 리스크 한도 설정
|
||||
await risk.setRiskLimits(container.id, {
|
||||
position: {
|
||||
maxSinglePositionPct: 20,
|
||||
maxSectorPct: 40,
|
||||
maxTotalLeverage: 1.0
|
||||
},
|
||||
loss: {
|
||||
maxDailyLossPct: 5,
|
||||
maxDrawdownPct: 15,
|
||||
stopLossEnabled: true
|
||||
}
|
||||
})
|
||||
|
||||
// 4. 스케줄 설정
|
||||
await scheduler.createSchedule({
|
||||
containerId: container.id,
|
||||
trigger: {
|
||||
type: 'CRON',
|
||||
expression: '0 9 * * 1-5' // 평일 오전 9시
|
||||
},
|
||||
executionMode: 'APPROVAL_REQUIRED',
|
||||
constraints: {
|
||||
marketHoursOnly: true,
|
||||
skipHolidays: true
|
||||
}
|
||||
})
|
||||
|
||||
// 5. 컨테이너 활성화
|
||||
await mgmt.activateContainer(container.id)
|
||||
```
|
||||
|
||||
## 5. 백테스트 워크플로우
|
||||
|
||||
### 5.1 백테스트 실행
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant U as 사용자
|
||||
participant ST as Strategy
|
||||
participant D as Data
|
||||
participant BE as Backtest Engine
|
||||
participant A as Analytics
|
||||
|
||||
U->>ST: 백테스트 요청
|
||||
ST->>D: 과거 데이터 조회
|
||||
D-->>ST: 시계열 데이터
|
||||
|
||||
ST->>BE: 백테스트 시작
|
||||
|
||||
loop 각 날짜마다
|
||||
BE->>ST: 신호 생성
|
||||
ST-->>BE: 매매 신호
|
||||
BE->>BE: 가상 주문 체결
|
||||
BE->>BE: 포트폴리오 업데이트
|
||||
end
|
||||
|
||||
BE->>A: 성과 계산
|
||||
A-->>BE: 성과 지표
|
||||
|
||||
BE-->>U: 백테스트 결과
|
||||
```
|
||||
|
||||
### 5.2 백테스트 구현
|
||||
|
||||
```typescript
|
||||
async function runBacktest(config: BacktestConfig): Promise<BacktestResult> {
|
||||
// 1. 데이터 로드
|
||||
const marketData = await data.getHistoricalPrices(
|
||||
config.universe,
|
||||
config.startDate,
|
||||
config.endDate
|
||||
)
|
||||
|
||||
// 2. 초기 상태 설정
|
||||
let portfolio = {
|
||||
cash: config.initialCapital,
|
||||
positions: {} as Record<string, number>,
|
||||
equity: [{ date: config.startDate, value: config.initialCapital }]
|
||||
}
|
||||
|
||||
const trades: Trade[] = []
|
||||
|
||||
// 3. 시뮬레이션 실행
|
||||
for (const date of marketData.dates) {
|
||||
// 신호 생성
|
||||
const signals = await strategy.generateSignals(
|
||||
marketData.getDataAsOf(date)
|
||||
)
|
||||
|
||||
// 주문 생성 및 체결
|
||||
for (const signal of signals) {
|
||||
if (signal.action === 'HOLD') continue
|
||||
|
||||
const price = marketData.getPrice(signal.symbol, date)
|
||||
const quantity = calculateQuantity(signal, portfolio, price)
|
||||
|
||||
// 슬리피지 및 수수료 적용
|
||||
const executionPrice = applySlippage(price, signal.action, config.costs.slippage)
|
||||
const commission = executionPrice * quantity * config.costs.commission
|
||||
|
||||
// 포트폴리오 업데이트
|
||||
if (signal.action === 'BUY') {
|
||||
portfolio.cash -= executionPrice * quantity + commission
|
||||
portfolio.positions[signal.symbol] = (portfolio.positions[signal.symbol] || 0) + quantity
|
||||
} else {
|
||||
portfolio.cash += executionPrice * quantity - commission
|
||||
portfolio.positions[signal.symbol] -= quantity
|
||||
}
|
||||
|
||||
// 거래 기록
|
||||
trades.push({
|
||||
date,
|
||||
symbol: signal.symbol,
|
||||
action: signal.action,
|
||||
quantity,
|
||||
price: executionPrice,
|
||||
commission
|
||||
})
|
||||
}
|
||||
|
||||
// 일일 자산 가치 계산
|
||||
const positionsValue = Object.entries(portfolio.positions)
|
||||
.reduce((sum, [symbol, qty]) => {
|
||||
return sum + qty * marketData.getPrice(symbol, date)
|
||||
}, 0)
|
||||
|
||||
portfolio.equity.push({
|
||||
date,
|
||||
value: portfolio.cash + positionsValue,
|
||||
cash: portfolio.cash,
|
||||
positions: { ...portfolio.positions }
|
||||
})
|
||||
}
|
||||
|
||||
// 4. 성과 지표 계산
|
||||
const metrics = await analytics.calculateMetrics({
|
||||
equity: portfolio.equity,
|
||||
trades,
|
||||
benchmark: config.benchmark
|
||||
})
|
||||
|
||||
return {
|
||||
id: generateId(),
|
||||
strategyId: config.strategyId,
|
||||
config,
|
||||
equity: portfolio.equity,
|
||||
trades,
|
||||
metrics,
|
||||
runAt: new Date(),
|
||||
duration: Date.now() - startTime
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 6. 데이터 수집 워크플로우
|
||||
|
||||
### 6.1 데이터 수집 파이프라인
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
subgraph "외부 소스"
|
||||
Broker[증권사 API]
|
||||
Yahoo[Yahoo Finance]
|
||||
Alpha[Alpha Vantage]
|
||||
end
|
||||
|
||||
subgraph "데이터 수집"
|
||||
Collector[Data Collector]
|
||||
RealTime[실시간 스트림]
|
||||
Historical[과거 데이터 수집]
|
||||
end
|
||||
|
||||
subgraph "데이터 처리"
|
||||
Validator[데이터 검증]
|
||||
Adjuster[조정 처리]
|
||||
QualityCheck[품질 체크]
|
||||
end
|
||||
|
||||
subgraph "저장소"
|
||||
Cache[(Redis<br/>실시간)]
|
||||
TimeSeries[(TimescaleDB<br/>과거)]
|
||||
Metadata[(Metadata<br/>종목 정보)]
|
||||
end
|
||||
|
||||
Broker --> RealTime
|
||||
Yahoo --> Historical
|
||||
Alpha --> Historical
|
||||
|
||||
RealTime --> Collector
|
||||
Historical --> Collector
|
||||
|
||||
Collector --> Validator
|
||||
Validator --> QualityCheck
|
||||
QualityCheck -->|통과| Adjuster
|
||||
QualityCheck -->|실패| Alert[품질 알림]
|
||||
|
||||
Adjuster --> Cache
|
||||
Adjuster --> TimeSeries
|
||||
Adjuster --> Metadata
|
||||
|
||||
style Cache fill:#FF6B6B,color:#fff
|
||||
style TimeSeries fill:#4ECDC4,color:#fff
|
||||
style Metadata fill:#45B7D1,color:#fff
|
||||
```
|
||||
|
||||
### 6.2 데이터 품질 관리
|
||||
|
||||
```typescript
|
||||
// 데이터 수집 및 검증
|
||||
async function collectAndValidateData(symbols: string[], date: Date) {
|
||||
for (const symbol of symbols) {
|
||||
// 1. 데이터 수집
|
||||
const rawData = await dataProvider.fetchPriceData(symbol, date)
|
||||
|
||||
// 2. 데이터 검증
|
||||
const validationResult = await data.validateData(rawData)
|
||||
|
||||
if (!validationResult.isValid) {
|
||||
// 품질 문제 감지
|
||||
await monitor.sendAlert({
|
||||
type: 'SYSTEM',
|
||||
severity: 'WARNING',
|
||||
message: `데이터 품질 문제: ${symbol} - ${validationResult.issues.join(', ')}`
|
||||
})
|
||||
|
||||
// 결측치 보정 시도
|
||||
if (validationResult.canFill) {
|
||||
rawData = await data.fillMissingData(rawData, 'FORWARD_FILL')
|
||||
} else {
|
||||
continue // 보정 불가능하면 skip
|
||||
}
|
||||
}
|
||||
|
||||
// 3. 기업 행동 조정 (배당, 액면분할 등)
|
||||
const adjustedData = await data.adjustForCorporateActions(rawData, symbol)
|
||||
|
||||
// 4. 저장
|
||||
await data.storePriceData(adjustedData)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 7. 성과 분석 워크플로우
|
||||
|
||||
### 7.1 일일 성과 계산
|
||||
|
||||
```typescript
|
||||
// 매일 장 마감 후 실행
|
||||
scheduler.scheduleDaily('MARKET_CLOSE', async () => {
|
||||
const containers = await mgmt.getActiveContainers()
|
||||
|
||||
for (const container of containers) {
|
||||
// 1. 현재 포지션 평가
|
||||
const positions = await mgmt.getPositions(container.id)
|
||||
const marketData = await data.getLatestPrices(positions.map(p => p.symbol))
|
||||
|
||||
// 2. 일일 수익률 계산
|
||||
const dailyReturn = await analytics.calculateDailyReturn(
|
||||
container.id,
|
||||
positions,
|
||||
marketData
|
||||
)
|
||||
|
||||
// 3. 누적 성과 업데이트
|
||||
await analytics.updatePerformance(container.id, {
|
||||
date: new Date(),
|
||||
return: dailyReturn,
|
||||
equity: positions.reduce((sum, p) => sum + p.marketValue, 0)
|
||||
})
|
||||
|
||||
// 4. 리스크 지표 재계산
|
||||
const riskMetrics = await analytics.calculateRiskMetrics(container.id)
|
||||
|
||||
// 5. 이상 탐지
|
||||
if (dailyReturn < -5) { // 일일 손실 5% 초과
|
||||
await monitor.sendAlert({
|
||||
type: 'PERFORMANCE',
|
||||
severity: 'WARNING',
|
||||
message: `일일 손실 초과: ${container.name} ${dailyReturn.toFixed(2)}%`
|
||||
})
|
||||
}
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
## 8. 관련 문서
|
||||
|
||||
- [시스템 개요](./01-overview.md)
|
||||
- [전체 아키텍처](./02-architecture.md)
|
||||
- [공통 데이터 모델](./03-data-models.md)
|
||||
- [구현 로드맵](./05-roadmap.md)
|
||||
513
docs/05-roadmap.md
Normal file
513
docs/05-roadmap.md
Normal file
@@ -0,0 +1,513 @@
|
||||
# QuantBench 구현 로드맵
|
||||
|
||||
## 1. 전체 일정 개요
|
||||
|
||||
```mermaid
|
||||
gantt
|
||||
title QuantBench 개발 일정
|
||||
dateFormat YYYY-MM-DD
|
||||
section Phase 1: MVP
|
||||
프로젝트 설정 :p1_1, 2024-01-01, 2w
|
||||
balance 구현 :p1_2, after p1_1, 4w
|
||||
data 구현 :p1_3, after p1_1, 4w
|
||||
mgmt 구현 :p1_4, after p1_2, 3w
|
||||
strategy 구현 :p1_5, after p1_3, 4w
|
||||
scheduler 구현 :p1_6, after p1_4, 3w
|
||||
risk 구현 :p1_7, after p1_5, 3w
|
||||
통합 테스트 :p1_8, after p1_6, 2w
|
||||
|
||||
section Phase 2: Production
|
||||
analytics 구현 :p2_1, after p1_8, 4w
|
||||
monitor 구현 :p2_2, after p1_8, 4w
|
||||
대시보드 개발 :p2_3, after p2_1, 3w
|
||||
통합 및 테스트 :p2_4, after p2_2, 2w
|
||||
|
||||
section Phase 3: Enterprise
|
||||
audit 구현 :p3_1, after p2_4, 4w
|
||||
simulation 구현 :p3_2, after p2_4, 4w
|
||||
최종 통합 및 배포 :p3_3, after p3_1, 3w
|
||||
```
|
||||
|
||||
### 전체 일정 요약
|
||||
|
||||
| Phase | 기간 | 주요 산출물 |
|
||||
|-------|------|------------|
|
||||
| **Phase 1: MVP** | 3-4개월 | 기본 거래 시스템 |
|
||||
| **Phase 2: Production** | 2-3개월 | 모니터링 & 분석 |
|
||||
| **Phase 3: Enterprise** | 2-3개월 | 감사 & 시뮬레이션 |
|
||||
| **총 기간** | 7-10개월 | 완전한 퀀트 시스템 |
|
||||
|
||||
## 2. Phase 1: MVP (3-4개월)
|
||||
|
||||
### 목표
|
||||
안전하게 전략을 실행하고 리스크를 통제할 수 있는 기본 시스템 구축
|
||||
|
||||
### 2.1 프로젝트 설정 (1-2주)
|
||||
|
||||
**작업 항목**:
|
||||
- [ ] 레포지토리 구조 설정
|
||||
- [ ] 개발 환경 구축 (Docker, Docker Compose)
|
||||
- [ ] CI/CD 파이프라인 설정
|
||||
- [ ] 코드 스타일 가이드 및 린팅 설정
|
||||
- [ ] 데이터베이스 스키마 초기 설계
|
||||
- [ ] API 인증/인가 구조 설계
|
||||
|
||||
**기술 스택 결정**:
|
||||
- 백엔드: TypeScript + Node.js (또는 Python + FastAPI)
|
||||
- 데이터베이스: PostgreSQL + TimescaleDB
|
||||
- 캐시: Redis
|
||||
- 메시지 큐: RabbitMQ (또는 Kafka)
|
||||
|
||||
### 2.2 Week 1-4: balance + data 기본 구현
|
||||
|
||||
#### balance 컴포넌트 (2-3주)
|
||||
|
||||
**우선순위 1: 한국투자증권 API 연동**
|
||||
- [ ] BrokerAdapter 인터페이스 정의
|
||||
- [ ] 한국투자증권 Adapter 구현
|
||||
- [ ] 인증 및 세션 관리
|
||||
- [ ] 계좌 잔고 조회
|
||||
- [ ] 현재가 조회
|
||||
- [ ] 주문 제출 (시장가, 지정가)
|
||||
- [ ] 주문 상태 조회
|
||||
- [ ] 주문 취소
|
||||
- [ ] API 키 암호화 저장
|
||||
- [ ] 에러 처리 및 재시도 로직
|
||||
- [ ] 단위 테스트 작성
|
||||
|
||||
**우선순위 2: 계좌 관리 기능**
|
||||
- [ ] 계좌 등록/수정/삭제 API
|
||||
- [ ] 계좌 목록 조회
|
||||
- [ ] 계좌 상태 관리
|
||||
|
||||
#### data 컴포넌트 (2-3주)
|
||||
|
||||
**우선순위 1: 데이터 수집**
|
||||
- [ ] 데이터 소스 추상화 인터페이스
|
||||
- [ ] Yahoo Finance 연동 (과거 데이터)
|
||||
- [ ] 한국투자증권 API를 통한 실시간 시세 조회
|
||||
- [ ] 데이터 검증 로직
|
||||
- [ ] 결측치 탐지
|
||||
- [ ] 이상치 탐지
|
||||
- [ ] 데이터 연속성 체크
|
||||
|
||||
**우선순위 2: 데이터 저장**
|
||||
- [ ] TimescaleDB 스키마 설계
|
||||
- [ ] 가격 데이터 저장 (PriceBar)
|
||||
- [ ] Redis 캐시 연동 (실시간 시세)
|
||||
- [ ] 데이터 조회 API
|
||||
- [ ] 과거 데이터 조회
|
||||
- [ ] 최신 시세 조회
|
||||
- [ ] 다중 종목 배치 조회
|
||||
|
||||
### 2.3 Week 5-8: mgmt + strategy 핵심 기능
|
||||
|
||||
#### mgmt 컴포넌트 (3주)
|
||||
|
||||
**우선순위 1: 컨테이너 생명주기**
|
||||
- [ ] 컨테이너 생성/수정/삭제 API
|
||||
- [ ] 가상 잔고 관리
|
||||
- [ ] 초기 자산 할당
|
||||
- [ ] 현금 및 포지션 추적
|
||||
- [ ] 밸런스 조정 (reconciliation)
|
||||
- [ ] 컨테이너 상태 관리 (ACTIVE/PAUSED/ARCHIVED)
|
||||
|
||||
**우선순위 2: 자산 관리**
|
||||
- [ ] 컨테이너 간 자산 이동
|
||||
- [ ] 실제 계좌 vs 가상 컨테이너 일치성 검증
|
||||
- [ ] 컨테이너 조회 API
|
||||
|
||||
#### strategy 컴포넌트 (4주)
|
||||
|
||||
**우선순위 1: 전략 인터페이스**
|
||||
- [ ] StrategyInterface 정의
|
||||
- [ ] 전략 등록 및 관리 API
|
||||
- [ ] 전략 버전 관리
|
||||
- [ ] 파라미터 관리
|
||||
|
||||
**우선순위 2: 신호 생성**
|
||||
- [ ] 신호 생성 엔진
|
||||
- [ ] 신호를 주문으로 변환
|
||||
- [ ] 내장 전략 구현: Bold Asset Allocation
|
||||
- [ ] 고정 비중 자산 배분
|
||||
- [ ] 리밸런싱 로직
|
||||
|
||||
**우선순위 3: 백테스트**
|
||||
- [ ] 백테스트 엔진 구현
|
||||
- [ ] 과거 데이터 기반 시뮬레이션
|
||||
- [ ] 거래 비용 및 슬리피지 모델링
|
||||
- [ ] 성과 지표 계산 (수익률, 샤프 비율, MDD 등)
|
||||
|
||||
### 2.4 Week 9-12: scheduler + risk
|
||||
|
||||
#### scheduler 컴포넌트 (3주)
|
||||
|
||||
**우선순위 1: 스케줄 관리**
|
||||
- [ ] 스케줄 생성/수정/삭제 API
|
||||
- [ ] Cron 기반 트리거
|
||||
- [ ] 시장 시간 체크 (개장/마감)
|
||||
- [ ] 휴일 감지 및 자동 스킵
|
||||
|
||||
**우선순위 2: 실행 관리**
|
||||
- [ ] 실행 트리거 로직
|
||||
- [ ] 전략 실행 오케스트레이션
|
||||
- [ ] 컨테이너 정보 조회
|
||||
- [ ] 신호 생성 요청
|
||||
- [ ] 리스크 검증
|
||||
- [ ] 주문 제출
|
||||
- [ ] 실행 이력 관리
|
||||
|
||||
**우선순위 3: 승인 워크플로우**
|
||||
- [ ] 승인 요청 생성
|
||||
- [ ] 승인 대기 및 타임아웃 처리
|
||||
- [ ] 승인/거부 처리
|
||||
- [ ] 자동 실행 모드
|
||||
|
||||
#### risk 컴포넌트 (3주)
|
||||
|
||||
**우선순위 1: 사전 주문 검증**
|
||||
- [ ] 잔고 충분성 체크
|
||||
- [ ] 포지션 사이즈 한도 검증
|
||||
- [ ] 집중도 리스크 체크 (단일 종목, 섹터)
|
||||
- [ ] 레버리지 한도 검증
|
||||
|
||||
**우선순위 2: 리스크 한도 관리**
|
||||
- [ ] 리스크 한도 설정 API
|
||||
- [ ] 컨테이너별 한도 조회
|
||||
|
||||
**우선순위 3: 손절/익절**
|
||||
- [ ] 손절 조건 설정
|
||||
- [ ] 익절 조건 설정
|
||||
- [ ] 자동 청산 트리거
|
||||
|
||||
### 2.5 Week 13-16: 통합 테스트 및 버그 수정
|
||||
|
||||
**통합 테스트**:
|
||||
- [ ] 전체 워크플로우 End-to-End 테스트
|
||||
- [ ] 컨테이너 생성 → 전략 할당 → 스케줄 설정 → 자동 실행
|
||||
- [ ] 리스크 시나리오 테스트
|
||||
- [ ] 잔고 부족 시나리오
|
||||
- [ ] 리스크 한도 초과 시나리오
|
||||
- [ ] 손절 트리거 시나리오
|
||||
- [ ] 증권사 API 연동 테스트 (Paper Trading 계좌)
|
||||
|
||||
**버그 수정 및 개선**:
|
||||
- [ ] 발견된 버그 수정
|
||||
- [ ] 성능 최적화
|
||||
- [ ] 에러 처리 개선
|
||||
- [ ] 로깅 강화
|
||||
|
||||
**문서화**:
|
||||
- [ ] API 문서 (Swagger/OpenAPI)
|
||||
- [ ] 사용자 가이드
|
||||
- [ ] 운영 매뉴얼
|
||||
|
||||
### Phase 1 완료 기준
|
||||
|
||||
- [ ] 한국투자증권 계좌 연동 완료
|
||||
- [ ] 1개 이상의 전략 백테스트 성공
|
||||
- [ ] Paper Trading 환경에서 자동 매매 성공
|
||||
- [ ] 모든 리스크 체크 통과
|
||||
- [ ] 전체 시스템 안정성 검증
|
||||
|
||||
## 3. Phase 2: Production Ready (2-3개월)
|
||||
|
||||
### 목표
|
||||
실전 운영을 위한 모니터링, 분석, 알림 체계 구축
|
||||
|
||||
### 3.1 Week 1-4: analytics 구현
|
||||
|
||||
#### analytics 컴포넌트 (4주)
|
||||
|
||||
**우선순위 1: 성과 측정**
|
||||
- [ ] 일일 수익률 계산
|
||||
- [ ] 누적 수익률 추적
|
||||
- [ ] 리스크 지표 계산
|
||||
- [ ] 변동성 (Volatility)
|
||||
- [ ] 샤프 비율 (Sharpe Ratio)
|
||||
- [ ] 소르티노 비율 (Sortino Ratio)
|
||||
- [ ] 최대 낙폭 (MDD)
|
||||
|
||||
**우선순위 2: 귀속 분석**
|
||||
- [ ] 수익 원천 분해
|
||||
- [ ] 자산 배분 효과
|
||||
- [ ] 종목 선택 효과
|
||||
- [ ] 타이밍 효과
|
||||
- [ ] 섹터별 기여도 분석
|
||||
- [ ] 종목별 기여도 분석
|
||||
|
||||
**우선순위 3: 거래 분석**
|
||||
- [ ] 거래 통계 (승률, 손익비 등)
|
||||
- [ ] 거래 비용 분석
|
||||
- [ ] 회전율 계산
|
||||
|
||||
**우선순위 4: 리포트 생성**
|
||||
- [ ] 일일/주간/월간 리포트 템플릿
|
||||
- [ ] PDF 리포트 생성
|
||||
- [ ] HTML 리포트 생성
|
||||
- [ ] 이메일 자동 발송
|
||||
|
||||
### 3.2 Week 5-8: monitor 구현
|
||||
|
||||
#### monitor 컴포넌트 (4주)
|
||||
|
||||
**우선순위 1: 시스템 헬스 체크**
|
||||
- [ ] 컴포넌트별 헬스 체크
|
||||
- [ ] API 연결 상태 모니터링
|
||||
- [ ] 데이터베이스 응답 시간 추적
|
||||
- [ ] 리소스 사용률 모니터링 (CPU, 메모리)
|
||||
|
||||
**우선순위 2: 이상 탐지**
|
||||
- [ ] 급격한 포지션 변화 감지
|
||||
- [ ] 비정상 주문 탐지
|
||||
- [ ] 시장 이상 조건 감지 (극심한 변동성, 유동성 부족)
|
||||
|
||||
**우선순위 3: 알림 시스템**
|
||||
- [ ] 알림 규칙 엔진
|
||||
- [ ] 다채널 알림 발송
|
||||
- [ ] 이메일 (SendGrid/AWS SES)
|
||||
- [ ] SMS (Twilio)
|
||||
- [ ] 푸시 알림 (Firebase)
|
||||
- [ ] Slack 웹훅
|
||||
- [ ] 알림 이력 관리
|
||||
- [ ] 알림 빈도 제한 (Throttling)
|
||||
|
||||
**우선순위 4: 대시보드 데이터**
|
||||
- [ ] 실시간 메트릭 수집
|
||||
- [ ] 대시보드 API
|
||||
- [ ] WebSocket을 통한 실시간 업데이트
|
||||
|
||||
### 3.3 Week 9-12: 대시보드 개발 및 통합
|
||||
|
||||
**프론트엔드 개발** (3주):
|
||||
- [ ] 프로젝트 설정 (React + TypeScript)
|
||||
- [ ] 주요 화면 개발
|
||||
- [ ] 대시보드 홈 (전체 계좌 요약)
|
||||
- [ ] 컨테이너 상세 (포지션, 성과, 차트)
|
||||
- [ ] 전략 관리 (등록, 수정, 백테스트 실행)
|
||||
- [ ] 주문 승인 화면
|
||||
- [ ] 알림 센터
|
||||
- [ ] 설정 화면
|
||||
- [ ] 차트 컴포넌트 (TradingView, Chart.js)
|
||||
- [ ] 실시간 업데이트 (WebSocket)
|
||||
|
||||
**통합 및 테스트** (2주):
|
||||
- [ ] 프론트엔드-백엔드 통합
|
||||
- [ ] E2E 테스트
|
||||
- [ ] 성능 테스트
|
||||
- [ ] 사용자 시나리오 테스트
|
||||
|
||||
### Phase 2 완료 기준
|
||||
|
||||
- [ ] 실시간 대시보드 동작
|
||||
- [ ] 자동 리포트 생성 및 발송
|
||||
- [ ] 알림 시스템 정상 작동
|
||||
- [ ] 이상 탐지 시나리오 검증
|
||||
- [ ] 사용자 인수 테스트 통과
|
||||
|
||||
## 4. Phase 3: Enterprise Grade (2-3개월)
|
||||
|
||||
### 목표
|
||||
규제 대응, 감사 추적, 고급 시뮬레이션
|
||||
|
||||
### 4.1 Week 1-4: audit 구현
|
||||
|
||||
#### audit 컴포넌트 (4주)
|
||||
|
||||
**우선순위 1: 감사 로그**
|
||||
- [ ] 감사 이벤트 정의
|
||||
- [ ] 불변 로그 저장 (Append-Only)
|
||||
- [ ] 해시 체인 구현 (무결성 보장)
|
||||
- [ ] 주요 이벤트 자동 기록
|
||||
- [ ] 주문 생성/취소/체결
|
||||
- [ ] 설정 변경
|
||||
- [ ] 승인/거부
|
||||
- [ ] 로그인
|
||||
|
||||
**우선순위 2: 변경 추적**
|
||||
- [ ] 엔티티별 변경 이력
|
||||
- [ ] Before/After 스냅샷
|
||||
- [ ] 변경 사유 기록
|
||||
|
||||
**우선순위 3: 규제 리포팅**
|
||||
- [ ] 거래 내역 보고서
|
||||
- [ ] 포지션 명세서
|
||||
- [ ] 이상 거래 보고서
|
||||
- [ ] CSV/JSON 내보내기
|
||||
|
||||
**우선순위 4: 무결성 검증**
|
||||
- [ ] 감사 로그 무결성 체크
|
||||
- [ ] 해시 체인 검증
|
||||
- [ ] 주기적 무결성 검사 스케줄
|
||||
|
||||
### 4.2 Week 5-8: simulation 구현
|
||||
|
||||
#### simulation 컴포넌트 (4주)
|
||||
|
||||
**우선순위 1: Paper Trading**
|
||||
- [ ] 가상 계좌 생성
|
||||
- [ ] 가상 주문 체결 엔진
|
||||
- [ ] 실시간 호가 기반 체결 시뮬레이션
|
||||
- [ ] 슬리피지 모델링
|
||||
- [ ] 수수료 계산
|
||||
- [ ] 가상 포트폴리오 관리
|
||||
|
||||
**우선순위 2: 시뮬레이션 환경**
|
||||
- [ ] 과거 데이터 리플레이
|
||||
- [ ] 다중 시나리오 테스트
|
||||
- [ ] 스트레스 테스트
|
||||
- [ ] 극단 변동성 시나리오
|
||||
- [ ] 유동성 부족 시나리오
|
||||
- [ ] 블랙스완 이벤트
|
||||
|
||||
**우선순위 3: 파라미터 최적화**
|
||||
- [ ] 그리드 서치
|
||||
- [ ] 랜덤 서치
|
||||
- [ ] 베이지안 최적화 (선택)
|
||||
- [ ] Walk-Forward 분석
|
||||
- [ ] 과최적화 검증
|
||||
|
||||
**우선순위 4: 실계좌 전환**
|
||||
- [ ] Paper → Real 전환 검증
|
||||
- [ ] 설정 복제 및 검증
|
||||
- [ ] 점진적 자산 이전
|
||||
|
||||
### 4.3 Week 9-12: 최종 통합 및 배포
|
||||
|
||||
**보안 강화** (2주):
|
||||
- [ ] 침투 테스트 (Penetration Testing)
|
||||
- [ ] API 키 관리 강화
|
||||
- [ ] 역할 기반 접근 제어 (RBAC) 세밀화
|
||||
- [ ] 감사 로그 접근 제어
|
||||
|
||||
**성능 최적화** (1주):
|
||||
- [ ] 데이터베이스 쿼리 최적화
|
||||
- [ ] 캐싱 전략 개선
|
||||
- [ ] API 응답 시간 최적화
|
||||
- [ ] 부하 테스트
|
||||
|
||||
**배포 준비** (2주):
|
||||
- [ ] 프로덕션 환경 설정
|
||||
- [ ] 데이터베이스 마이그레이션 스크립트
|
||||
- [ ] 백업 및 복구 절차 수립
|
||||
- [ ] 모니터링 및 알림 설정 (Prometheus, Grafana)
|
||||
- [ ] 장애 복구 계획 (DR Plan)
|
||||
- [ ] 운영 문서 작성
|
||||
|
||||
**최종 검증** (1주):
|
||||
- [ ] 전체 시스템 통합 테스트
|
||||
- [ ] 보안 검증
|
||||
- [ ] 성능 검증
|
||||
- [ ] 사용자 인수 테스트 (UAT)
|
||||
|
||||
### Phase 3 완료 기준
|
||||
|
||||
- [ ] 모든 거래가 감사 로그에 기록됨
|
||||
- [ ] Paper Trading 환경 정상 작동
|
||||
- [ ] 파라미터 최적화 기능 검증
|
||||
- [ ] 보안 감사 통과
|
||||
- [ ] 프로덕션 배포 완료
|
||||
|
||||
## 5. 마일스톤
|
||||
|
||||
```mermaid
|
||||
timeline
|
||||
title QuantBench 주요 마일스톤
|
||||
section Phase 1
|
||||
M1.1 : 증권사 API 연동 완료
|
||||
M1.2 : 첫 백테스트 성공
|
||||
M1.3 : Paper Trading 자동매매 성공
|
||||
M1.4 : Phase 1 완료
|
||||
section Phase 2
|
||||
M2.1 : 실시간 대시보드 런칭
|
||||
M2.2 : 자동 리포트 시스템 가동
|
||||
M2.3 : Phase 2 완료
|
||||
section Phase 3
|
||||
M3.1 : 감사 시스템 가동
|
||||
M3.2 : Paper Trading 환경 오픈
|
||||
M3.3 : 프로덕션 배포
|
||||
```
|
||||
|
||||
| 마일스톤 | 예상 일정 | 주요 산출물 |
|
||||
|---------|----------|------------|
|
||||
| **M1.1** | 1개월차 | 한국투자증권 API 연동, 데이터 수집 |
|
||||
| **M1.2** | 2개월차 | Bold Asset Allocation 전략 백테스트 성공 |
|
||||
| **M1.3** | 3개월차 | Paper Trading 환경에서 자동매매 |
|
||||
| **M1.4** | 4개월차 | Phase 1 완료 (MVP) |
|
||||
| **M2.1** | 5개월차 | 실시간 대시보드 |
|
||||
| **M2.2** | 6개월차 | 자동 리포트 시스템 |
|
||||
| **M2.3** | 7개월차 | Phase 2 완료 (Production Ready) |
|
||||
| **M3.1** | 8개월차 | 감사 시스템 |
|
||||
| **M3.2** | 9개월차 | Paper Trading 플랫폼 |
|
||||
| **M3.3** | 10개월차 | 프로덕션 배포 완료 |
|
||||
|
||||
## 6. 리스크 및 대응 방안
|
||||
|
||||
| 리스크 | 영향 | 확률 | 대응 방안 |
|
||||
|-------|------|------|----------|
|
||||
| 증권사 API 변경 | 높음 | 중간 | 추상화 레이어 강화, 다중 증권사 지원 |
|
||||
| 데이터 품질 문제 | 중간 | 높음 | 데이터 검증 강화, 다중 데이터 소스 |
|
||||
| 성능 병목 | 중간 | 중간 | 초기부터 부하 테스트, 확장 가능 아키텍처 |
|
||||
| 보안 취약점 | 높음 | 낮음 | 정기 보안 감사, 침투 테스트 |
|
||||
| 일정 지연 | 중간 | 높음 | 애자일 방식, 2주 단위 스프린트, 우선순위 조정 |
|
||||
| 규제 변경 | 중간 | 낮음 | 감사 로그 강화, 유연한 설계 |
|
||||
|
||||
## 7. 추가 고려사항
|
||||
|
||||
### 7.1 다중 증권사 지원 계획
|
||||
|
||||
**Phase 1.5 (선택)**: 삼성증권 또는 키움증권 추가 연동
|
||||
- 예상 기간: 2-3주
|
||||
- BrokerAdapter 패턴 검증
|
||||
- 다중 계좌 통합 관리 테스트
|
||||
|
||||
### 7.2 고급 전략 추가
|
||||
|
||||
**Phase 2.5 (선택)**: 추가 전략 구현
|
||||
- Momentum 전략
|
||||
- Value 전략
|
||||
- Mean Reversion 전략
|
||||
- 각 전략당 2-3주 소요
|
||||
|
||||
### 7.3 글로벌 시장 지원
|
||||
|
||||
**Phase 4 (선택)**: 미국 주식 시장 지원
|
||||
- Interactive Brokers API 연동
|
||||
- 시간대 처리 (타임존)
|
||||
- 환율 처리
|
||||
- 예상 기간: 2-3개월
|
||||
|
||||
## 8. 성공 지표 (KPI)
|
||||
|
||||
### Phase 1 완료 시
|
||||
|
||||
- [ ] 시스템 가동률: 95% 이상
|
||||
- [ ] API 응답 시간: 평균 < 500ms
|
||||
- [ ] 주문 처리 성공률: 99% 이상
|
||||
- [ ] 백테스트 정확도: 실제 거래 대비 ±1% 이내
|
||||
|
||||
### Phase 2 완료 시
|
||||
|
||||
- [ ] 시스템 가동률: 99% 이상
|
||||
- [ ] 알림 발송 성공률: 99.5% 이상
|
||||
- [ ] 리포트 생성 시간: < 10초
|
||||
- [ ] 대시보드 로딩 시간: < 2초
|
||||
|
||||
### Phase 3 완료 시
|
||||
|
||||
- [ ] 시스템 가동률: 99.9% 이상
|
||||
- [ ] 감사 로그 무결성: 100%
|
||||
- [ ] Paper Trading 정확도: 실거래 대비 ±0.5% 이내
|
||||
- [ ] 보안 취약점: 0건 (Critical/High)
|
||||
|
||||
## 9. 관련 문서
|
||||
|
||||
- [시스템 개요](./01-overview.md)
|
||||
- [전체 아키텍처](./02-architecture.md)
|
||||
- [공통 데이터 모델](./03-data-models.md)
|
||||
- [주요 워크플로우](./04-workflows.md)
|
||||
|
||||
### 구성요소 상세 문서
|
||||
- [Phase 1 컴포넌트](../components/phase1/)
|
||||
- [Phase 2 컴포넌트](../components/phase2/)
|
||||
- [Phase 3 컴포넌트](../components/phase3/)
|
||||
Reference in New Issue
Block a user