system-specs/components/phase2/monitor.md

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