system-specs/components/phase3/simulation.md

# simulation - 시뮬레이션 환경

## 개요

**simulation** 컴포넌트는 Paper Trading, 시나리오 테스트, 파라미터 최적화를 제공하여 실전 전 검증을 지원합니다.

### 책임

- Paper Trading 계좌/주문 실행
- 전략 시뮬레이션 및 비교
- 파라미터 최적화 및 과최적화 검증
- 몬테카를로 및 스트레스 테스트
- 실계좌 전환 계획 생성

### 의존성

```mermaid
graph LR
    Simulation[simulation] --> Strategy[strategy]
    Simulation --> Risk[risk]
    Simulation --> Data[data]
    Simulation --> Analytics[analytics]
    Simulation --> DB[(Database)]

    Audit[audit] --> Simulation

    style Simulation fill:#607D8B,color:#fff
```

## 주요 기능

### 1. Paper Trading

```typescript
createPaperAccount(config: PaperAccountConfig): PaperAccount
executePaperTrade(order: Order): PaperOrderResult
```

### 2. 전략 시뮬레이션

```typescript
runSimulation(config: SimulationConfig): SimulationResult
compareStrategies(strategyIds: string[], config: SimulationConfig): ComparisonResult
```

### 3. 파라미터 최적화

```typescript
optimizeParameters(strategyId: string, searchSpace: ParameterSpace): OptimizationResult
validateOptimization(result: OptimizationResult, outOfSampleData: MarketData): ValidationResult
```

### 4. 시나리오 테스트

```typescript
testScenario(containerId: string, scenario: Scenario): ScenarioResult
runMonteCarloSimulation(containerId: string, iterations: number): MonteCarloResult
```

### 5. 전환 지원

```typescript
promoteToProd(paperAccountId: string, realAccountId: string): MigrationPlan
cloneContainer(sourceId: string, targetAccountId: string): Container
```

## 데이터 모델

```typescript
interface PaperAccount {
  id: string
  name: string
  balance: {
    initialCash: number
    currentCash: number
    positions: Position[]
    totalEquity: number
  }
  settings: {
    commissionModel: 'FIXED' | 'PERCENTAGE'
    commissionRate: number
    slippageModel: 'FIXED_BPS' | 'VOLUME_BASED'
    slippageBps: number
  }
  isActive: boolean
  createdAt: Date
}

interface SimulationConfig {
  strategyId: string
  startDate: Date
  endDate: Date
  initialCapital: number
  universe: string[]
  costs: {
    commission: number
    slippage: number
    tax: number
  }
  constraints: RiskLimits
  rebalanceFrequency: string
}

interface SimulationResult {
  config: SimulationConfig
  performance: PerformanceMetrics
  equity: {
    date: Date
    value: number
  }[]
  trades: {
    date: Date
    symbol: string
    action: 'BUY' | 'SELL'
    quantity: number
    price: number
  }[]
  drawdowns: {
    start: Date
    end: Date
    depth: number
    recovery: number
  }[]
  completedAt: Date
}

interface ParameterSpace {
  parameters: {
    name: string
    type: 'INTEGER' | 'FLOAT' | 'CATEGORICAL'
    min?: number
    max?: number
    step?: number
    values?: any[]
  }[]
}

interface OptimizationResult {
  strategyId: string
  searchSpace: ParameterSpace
  bestParameters: Record<string, any>
  bestMetric: number
  trials: {
    parameters: Record<string, any>
    metrics: PerformanceMetrics
  }[]
  optimizationTime: number
  warnings: {
    overfitting: boolean
    insufficientData: boolean
    unstableParameters: string[]
  }
}

interface MonteCarloResult {
  iterations: number
  returns: {
    mean: number
    median: number
    std: number
    percentiles: {
      p5: number
      p25: number
      p75: number
      p95: number
    }
  }
  drawdowns: {
    mean: number
    max: number
    percentiles: {
      p95: number
      p99: number
    }
  }
  probabilities: {
    profit: number
    loss10pct: number
    loss20pct: number
  }
  distribution: number[]
}
```

## API 명세

### POST /api/simulation/run
시뮬레이션 실행

### POST /api/simulation/optimize
파라미터 최적화

## 구현 고려사항

- 과최적화 경고 기준을 명확히 정의합니다.
- Paper Trading과 실계좌 체결 차이를 리포트에 표시합니다.

## 관련 문서

- [구현 로드맵](../../docs/05-roadmap.md)
- [주요 워크플로우](../../docs/04-workflows.md)

### 관련 컴포넌트
- [strategy - 전략 관리](../phase1/strategy.md)
- [risk - 리스크 관리](../phase1/risk.md)
- [analytics - 성과 분석](../phase2/analytics.md)
- [audit - 감사 및 로깅](./audit.md)