# scheduler - 실행 스케줄러

## 개요

**scheduler** 컴포넌트는 전략 실행 자동화, 리밸런싱, 승인 워크플로우를 관리합니다.

### 책임

- 컨테이너별 실행 일정 관리
- 실행 트리거 및 리밸런싱 스케줄링
- 승인 요청 및 실행 흐름 제어
- 실행 이력 저장 및 알림

### 의존성

```mermaid
graph LR
    Scheduler[scheduler] --> Mgmt[mgmt]
    Scheduler --> Strategy[strategy]
    Scheduler --> Risk[risk]
    Scheduler --> Balance[balance]
    Scheduler --> Monitor[monitor]
    Scheduler --> DB[(Database)]

    style Scheduler fill:#FF9800,color:#fff
```

## 주요 기능

### 1. 스케줄 관리

```typescript
createSchedule(containerId: string, schedule: ScheduleConfig): Schedule
updateSchedule(scheduleId: string, config: Partial<ScheduleConfig>): Schedule
pauseSchedule(scheduleId: string): boolean
resumeSchedule(scheduleId: string): boolean
```

- Cron/interval/이벤트 기반 트리거를 지원합니다.
- 시장 시간 및 휴일을 고려해 다음 실행 시점을 계산합니다.

### 2. 실행 트리거

```typescript
executeStrategy(containerId: string, mode: 'AUTO' | 'MANUAL'): Execution
scheduleRebalancing(containerId: string): void
```

- 신호 생성 → 리스크 체크 → 주문 생성 → 승인 처리 순서로 실행합니다.

### 3. 승인 워크플로우

```typescript
requestApproval(execution: Execution): ApprovalRequest
approveExecution(requestId: string, approved: boolean): boolean
autoExecuteWithNotification(execution: Execution): ExecutionResult
```

- 승인 모드에서는 예상 주문 내역과 비용을 사용자에게 제공합니다.

### 4. 실행 이력 관리

```typescript
getExecutionHistory(containerId: string, from: Date): Execution[]
getExecutionDetail(executionId: string): ExecutionDetail
```

## 데이터 모델

```typescript
interface Schedule {
  id: string
  containerId: string
  trigger: {
    type: 'CRON' | 'INTERVAL' | 'EVENT'
    expression?: string
    intervalMinutes?: number
    event?: 'MARKET_OPEN' | 'MARKET_CLOSE'
  }
  executionMode: 'AUTO' | 'APPROVAL_REQUIRED'
  constraints: {
    marketHoursOnly: boolean
    skipHolidays: boolean
    minIntervalHours?: number
  }
  isActive: boolean
  nextRun?: Date
  lastRun?: Date
}

interface Execution {
  id: string
  containerId: string
  strategyId: string
  status: 'PENDING' | 'APPROVED' | 'REJECTED' | 'RUNNING' | 'COMPLETED' | 'FAILED'
  signals: Signal[]
  plannedOrders: Order[]
  executedOrders: Order[]
  estimatedCost: {
    commission: number
    totalValue: number
  }
  approvalRequest?: ApprovalRequest
  startedAt?: Date
  completedAt?: Date
  error?: string
}

interface ApprovalRequest {
  id: string
  executionId: string
  summary: {
    numOrders: number
    buyValue: number
    sellValue: number
    estimatedCommission: number
  }
  orders: Order[]
  requestedAt: Date
  expiresAt: Date
  approvedAt?: Date
  approvedBy?: string
  decision?: 'APPROVED' | 'REJECTED'
}
```

## API 명세

### POST /api/schedules
스케줄 생성

### POST /api/executions/:executionId/approve
승인/거부 처리

## 구현 고려사항

- 승인 만료 처리 및 재요청 정책을 정의해야 합니다.
- 실행 실패 시 재시도/중단 기준을 명확히 둡니다.

## 관련 문서

- [주요 워크플로우](../../docs/04-workflows.md)
- [공통 데이터 모델](../../docs/03-data-models.md)

### 관련 컴포넌트
- [mgmt - 컨테이너 관리](./mgmt.md)
- [strategy - 전략 관리](./strategy.md)
- [risk - 리스크 관리](./risk.md)
- [balance - 계좌 관리](./balance.md)