feat: 프로젝트 개요 및 컴포넌트별 명세, 로드맵 등 문서 추가

components/phase2/analytics.md

@@ -0,0 +1,211 @@
+# 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)