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

2026-01-11 21:01:34 +09:00
parent 8553f586c9
commit 6c6ca894cf
23 changed files with 8388 additions and 0 deletions
--- a/components/phase2/analytics.md
+++ b/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)
--- a/components/phase2/monitor.md
+++ b/components/phase2/monitor.md
@@ -0,0 +1,209 @@
+# monitor - 모니터링 및 알림
+
+## 개요
+
+**monitor** 컴포넌트는 시스템 상태 감시, 이상 탐지, 알림 발송을 담당합니다.
+
+### 책임
+
+- 컴포넌트 헬스 체크 및 연결 상태 모니터링
+- 이상 거래/리스크 이벤트 탐지
+- 알림 규칙 관리 및 다채널 발송
+- 대시보드용 실시간 지표 제공
+
+### 의존성
+
+```mermaid
+graph LR
+    Monitor[monitor] --> Balance[balance]
+    Monitor --> Analytics[analytics]
+    Monitor --> Risk[risk]
+    Monitor --> DB[(Database)]
+
+    Scheduler[scheduler] --> Monitor
+
+    style Monitor fill:#009688,color:#fff
+```
+
+## 주요 기능
+
+### 1. 시스템 헬스 체크
+
+```typescript
+checkSystemHealth(): HealthStatus
+monitorApiConnections(): ConnectionStatus[]
+```
+
+### 2. 이상 거래 탐지
+
+```typescript
+detectAnomalies(containerId: string): Anomaly[]
+checkMarketConditions(): MarketAlert[]
+```
+
+### 3. 알림 관리
+
+```typescript
+sendAlert(alert: Alert): void
+configureAlertRules(rules: AlertRule[]): void
+getAlertHistory(from: Date, severity?: AlertSeverity): Alert[]
+```
+
+### 4. 대시보드 데이터
+
+```typescript
+getDashboardData(): DashboardSnapshot
+getRealtimeMetrics(containerId: string): RealtimeMetrics
+```
+
+### 5. 성능 모니터링
+
+```typescript
+trackLatency(operation: string, duration: number): void
+logError(error: Error, context: any): void
+```
+
+## 데이터 모델
+
+```typescript
+interface HealthStatus {
+  overall: 'HEALTHY' | 'DEGRADED' | 'DOWN'
+  components: {
+    name: string
+    status: 'UP' | 'DOWN' | 'SLOW'
+    responseTime?: number
+    lastCheck: Date
+    message?: string
+  }[]
+  connections: {
+    broker: 'CONNECTED' | 'DISCONNECTED' | 'ERROR'
+    database: 'CONNECTED' | 'DISCONNECTED'
+    dataProviders: Record<string, 'CONNECTED' | 'DISCONNECTED'>
+  }
+  resources: {
+    cpuUsage: number
+    memoryUsage: number
+    diskUsage: number
+  }
+  checkedAt: Date
+}
+
+interface Anomaly {
+  type: 'POSITION_SPIKE' | 'UNUSUAL_ORDER' | 'UNEXPECTED_FILL' | 'HIGH_IMPACT'
+  severity: 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL'
+  containerId: string
+  description: string
+  details: {
+    expected?: any
+    actual: any
+    threshold?: any
+  }
+  detectedAt: Date
+  resolved: boolean
+}
+
+interface Alert {
+  id: string
+  type: 'SYSTEM' | 'RISK' | 'EXECUTION' | 'PERFORMANCE' | 'ANOMALY'
+  severity: 'INFO' | 'WARNING' | 'ERROR' | 'CRITICAL'
+  title: string
+  message: string
+  source: string
+  containerId?: string
+  channels: ('EMAIL' | 'SMS' | 'PUSH' | 'SLACK')[]
+  sentAt?: Date
+  acknowledged: boolean
+  acknowledgedAt?: Date
+  acknowledgedBy?: string
+  createdAt: Date
+}
+
+interface AlertRule {
+  id: string
+  name: string
+  description: string
+  condition: {
+    metric: string
+    operator: '>' | '<' | '=' | '>=' | '<='
+    threshold: number
+  }
+  severity: AlertSeverity
+  channels: AlertChannel[]
+  throttle: {
+    enabled: boolean
+    minIntervalMinutes: number
+  }
+  isActive: boolean
+}
+
+interface DashboardSnapshot {
+  accounts: {
+    accountId: string
+    totalEquity: number
+    cashBalance: number
+    todayPnL: number
+    todayReturn: number
+  }[]
+  containers: {
+    containerId: string
+    name: string
+    status: 'ACTIVE' | 'PAUSED'
+    equity: number
+    todayReturn: number
+    activeStrategy: string
+    lastRebalanced: Date
+  }[]
+  recentExecutions: {
+    executionId: string
+    containerId: string
+    status: string
+    completedAt: Date
+  }[]
+  activeAlerts: Alert[]
+  systemHealth: 'HEALTHY' | 'DEGRADED' | 'DOWN'
+  timestamp: Date
+}
+
+interface RealtimeMetrics {
+  containerId: string
+  current: {
+    equity: number
+    cash: number
+    positionsCount: number
+  }
+  today: {
+    pnl: number
+    return: number
+    tradesCount: number
+  }
+  risk: {
+    currentDrawdown: number
+    VaR95: number
+    leverage: number
+  }
+  updatedAt: Date
+}
+```
+
+## API 명세
+
+### GET /api/monitor/health
+헬스 체크 상태 조회
+
+### GET /api/monitor/alerts
+알림 이력 조회
+
+## 구현 고려사항
+
+- 알림 폭주를 방지하기 위해 스로틀 정책을 필수로 둡니다.
+- 심각도 기준을 명확히 정의하고 대시보드에 반영합니다.
+
+## 관련 문서
+
+- [주요 워크플로우](../../docs/04-workflows.md)
+- [구현 로드맵](../../docs/05-roadmap.md)
+
+### 관련 컴포넌트
+- [analytics - 성과 분석](./analytics.md)
+- [risk - 리스크 관리](../phase1/risk.md)
+- [balance - 계좌 관리](../phase1/balance.md)