# 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)