system-specs/components/phase2/analytics.md

# analytics - 성과 분석 및 리포팅

## 개요

**analytics** 컴포넌트는 실거래 성과 측정, 귀속 분석, 리포팅을 담당합니다.

### 책임

- 기간별 수익률 및 리스크 지표 계산
- 귀속 분석(자산 배분, 종목 선택, 타이밍)
- 거래 분석 및 비용 추정
- 정기 리포트 생성 및 배포
- 벤치마크 대비 성과 비교

### 의존성

```mermaid
graph LR
    Analytics[analytics] --> Mgmt[mgmt]
    Analytics --> Balance[balance]
    Analytics --> Data[data]
    Analytics --> DB[(Database)]

    Monitor[monitor] --> Analytics

    style Analytics fill:#3F51B5,color:#fff
```

## 주요 기능

### 1. 성과 측정

```typescript
calculatePerformance(containerId: string, period: DateRange): PerformanceReport
getReturnsTimeseries(containerId: string, from: Date): TimeseriesData
```

### 2. 귀속 분석

```typescript
analyzeReturns(containerId: string, period: DateRange): AttributionReport
```

### 3. 거래 분석

```typescript
analyzeTrades(containerId: string, from: Date): TradeAnalysis
calculateTradingCosts(containerId: string, period: DateRange): CostAnalysis
```

### 4. 리포트 생성

```typescript
generateReport(containerId: string, type: ReportType, period: DateRange): Report
scheduleReport(config: ReportSchedule): void
```

### 5. 벤치마크 비교

```typescript
compareWithBenchmark(containerId: string, benchmarkSymbol: string, period: DateRange): ComparisonReport
```

## 데이터 모델

```typescript
interface PerformanceReport {
  containerId: string
  period: DateRange
  returns: {
    total: number
    annualized: number
    daily: number
    weekly: number
    monthly: number
    ytd: number
  }
  risk: {
    volatility: number
    sharpeRatio: number
    sortinoRatio: number
    maxDrawdown: number
    calmarRatio: number
  }
  benchmark?: {
    symbol: string
    returns: number
    excessReturn: number
    beta: number
    alpha: number
    trackingError: number
    informationRatio: number
  }
  generatedAt: Date
}

interface AttributionReport {
  containerId: string
  period: DateRange
  totalReturn: number
  attribution: {
    assetAllocation: number
    stockSelection: number
    timing: number
    interaction: number
  }
  sectorContribution: {
    sector: string
    weight: number
    return: number
    contribution: number
  }[]
  topContributors: {
    symbol: string
    contribution: number
  }[]
  topDetractors: {
    symbol: string
    contribution: number
  }[]
}

interface TradeAnalysis {
  containerId: string
  period: DateRange
  summary: {
    totalTrades: number
    winningTrades: number
    losingTrades: number
    winRate: number
    avgWin: number
    avgLoss: number
    profitFactor: number
    avgHoldingPeriod: number
    turnoverRate: number
  }
  longestWinStreak: number
  longestLossStreak: number
  largestWin: {
    symbol: string
    return: number
    date: Date
  }
  largestLoss: {
    symbol: string
    return: number
    date: Date
  }
}

interface CostAnalysis {
  period: DateRange
  costs: {
    commission: number
    estimatedSlippage: number
    tax: number
    other: number
    total: number
  }
  impact: {
    grossReturn: number
    netReturn: number
    costDrag: number
  }
  costByType: {
    buy: number
    sell: number
  }
}

interface Report {
  id: string
  containerId: string
  type: ReportType
  period: DateRange
  sections: {
    summary: PerformanceSummary
    positions: CurrentPositions
    trades: RecentTrades
    performance: PerformanceCharts
    attribution: AttributionAnalysis
    risk: RiskMetrics
  }
  format: 'PDF' | 'HTML' | 'JSON'
  fileUrl?: string
  generatedAt: Date
}
```

## API 명세

### GET /api/analytics/containers/:containerId/performance
성과 리포트 조회

### POST /api/analytics/containers/:containerId/reports
리포트 생성

## 구현 고려사항

- 성과 계산 시 배당/분할 조정 데이터를 일관되게 사용합니다.
- 리포트 생성은 비동기 작업으로 처리합니다.

## 관련 문서

- [공통 데이터 모델](../../docs/03-data-models.md)
- [구현 로드맵](../../docs/05-roadmap.md)

### 관련 컴포넌트
- [data - 데이터 관리](../phase1/data.md)
- [monitor - 모니터링](./monitor.md)
- [risk - 리스크 관리](../phase1/risk.md)