# Phase 2 오케스트레이션 및 스케줄링

## 1. 목적

Phase 2에서는 복잡한 큐 시스템보다 **명시적 배치 실행과 체크포인트 기반 스케줄링**을 우선합니다.
이 문서는 각 잡의 실행 시점, 의존성, 백필 방식, 재처리 방식을 정의합니다.

## 2. 스케줄링 원칙

1. **원천 데이터 수집은 source 특성에 맞춘다.**
2. **정규화/적재는 raw 저장 성공 이후에만 실행한다.**
3. **하루 운영 배치와 장기 백필 배치는 같은 코드 경로를 사용한다.**
4. **한 job 실패가 전체 DAG를 막지 않도록 source별 격리**한다.
5. **job 순서는 time-critical source를 먼저**, low-frequency source를 나중에 둔다.

## 3. 권장 스케줄 표

### 3.1 일일/주기 스케줄

#### SEC submissions poll
- 주기: 평일 장중/장후 10~15분 간격
- 목적: 신규 filing accession 탐지
- 후속 작업: `sec_filing_fetch`

#### SEC filing fetch
- 주기: submissions poll 성공 후 즉시 트리거
- 목적: filing 본문 및 exhibit 저장
- 후속 작업: `sec_xbrl_extract`

#### SEC xbrl extract
- 주기: filing fetch 성공 후 지연 실행 가능
- 목적: XBRL facts 추출
- 비고: filing 원문 저장과 분리 가능

#### Alpaca daily bars
- 주기: 거래일 종료 후 1회
- 목적: 일봉 적재
- 비고: 운영 시각은 보수적으로 장 종료 이후 충분한 지연을 둠

#### Alpaca intraday bars
- 주기: 거래시간 동안 5~15분 간격 또는 거래일 종료 후 일괄 수집
- 목적: 기본 분봉 적재
- 비고: 무료 제약상 Phase 2는 일괄 수집 우선

#### FRED series sync
- 주기: 일 1회
- 목적: 거시 레짐 데이터 업데이트

#### FINRA short volume
- 주기: 일 1회
- 목적: 당일 게시된 직전 거래일 파일 적재

## 4. 잡 의존성

기본 DAG:

```text
sec_submissions_poll
  → sec_filing_fetch
    → sec_xbrl_extract
    → sec_document_header_write

alpaca_daily_bars_backfill
  → market_bars_daily_write

alpaca_intraday_bars_poll
  → market_bars_intraday_write

fred_series_sync
  → macro_series_write

finra_short_volume_fetch
  → short_volume_write
```

원칙:
- SEC 계열 DAG와 market 계열 DAG는 독립적으로 돌아야 합니다.
- FRED/FINRA 실패가 SEC/Alpaca 수집을 막으면 안 됩니다.

## 5. 실행 모드

### 5.1 Poll

운영 배치 모드입니다.
- 최신 데이터만 증분 수집
- 체크포인트 사용
- 기본 모드

### 5.2 Backfill

과거 기간을 채우는 모드입니다.
- 날짜 범위 명시
- 진행률 기록 필수
- 중간 실패 후 resume 가능해야 함

### 5.3 Replay

기존 raw를 다시 파싱/적재하는 모드입니다.
- 외부 source 호출 없음
- parser drift / schema 변경 / 버그 수정 시 사용

## 6. 백필 정책

### 6.1 날짜 분할

백필은 반드시 작은 단위 chunk로 나눕니다.

예:
- SEC: CIK batch 또는 accession batch
- Alpaca: 심볼 x 월 단위
- FRED: series별 연 단위
- FINRA: 거래일 단위

### 6.2 진행률 저장

`backfill_runs` 또는 `job_runs`에 아래를 남깁니다.

- 전체 대상 수
- 완료 수
- 실패 수
- 마지막 성공 chunk
- 재시작 포인터

### 6.3 재시작 규칙

중간 실패 시 마지막 성공 chunk 다음부터 재시작합니다.

## 7. Replay 정책

Replay는 아래 경우에만 사용합니다.

- parser 로직 변경
- canonical schema 변경
- structured write 버그 수정
- source 응답 포맷 drift 대응

Replay의 기본 원칙:
- raw는 불변
- staging/structured만 다시 생성
- replay run_id를 별도로 부여
- 기존 결과를 덮어쓸지, 버전 테이블로 남길지 사전에 결정

## 8. CLI 표준

모든 잡은 아래 형태의 CLI를 지원합니다.

```bash
python -m apps.collector.sec_collector.main \
  --mode poll \
  --run-id <RUN_ID>

python -m apps.collector.alpaca_collector.main \
  --mode backfill \
  --symbols AAPL,MSFT,NVDA \
  --start-date 2025-01-01 \
  --end-date 2025-03-31 \
  --run-id <RUN_ID>
```

필수 규칙:
- `run_id` 명시 가능
- 없으면 시스템 생성
- `dry_run` 지원
- `force` 지원

## 9. Cron 예시

```cron
# SEC submissions poll every 15 minutes on weekdays
*/15 * * * 1-5 python -m apps.collector.sec_collector.main --mode poll

# Daily bars after market close
30 22 * * 1-5 python -m apps.collector.alpaca_collector.main --mode poll --timeframe 1D

# FRED once nightly
15 23 * * 1-5 python -m apps.collector.fred_collector.main --mode poll

# FINRA once nightly
30 23 * * 1-5 python -m apps.collector.finra_collector.main --mode poll
```

실제 시각은 환경/타임존에 맞춰 config에서 오버라이드 가능해야 합니다.

## 10. 실패 처리

### 10.1 Soft Failure

예:
- 일부 심볼 실패
- 일부 series 실패
- 일부 accession 실패

처리:
- 실패 객체만 기록
- 전체 job는 partial success 가능
- 실패 목록은 후속 retry 대상

### 10.2 Hard Failure

예:
- 인증/환경설정 오류
- 저장소 write 불가
- checkpoint load 실패
- schema registry 로드 실패

처리:
- 전체 job 중단
- `failed_terminal` 또는 `failed_retriable`

## 11. Freeze / Drain 모드

운영자가 문제 source를 잠시 멈출 수 있어야 합니다.

- `freeze`: 신규 poll 중단
- `drain`: 현재 실행만 마무리 후 중단

설정 예시:

```yaml
sources:
  sec:
    frozen: false
  alpaca:
    frozen: false
jobs:
  sec_xbrl_extract:
    frozen: true
```

## 12. 운영 알림

최소 알림 조건:
- 2회 이상 연속 실패
- checkpoint lag가 허용치 초과
- raw 저장 성공률 급락
- structured validation 실패
- quarantine 발생

## 13. 완료 기준

- poll/backfill/replay가 모두 작동해야 합니다.
- 체크포인트 기반 resume가 가능해야 합니다.
- source별 실패 격리가 동작해야 합니다.
- 운영자가 특정 잡만 선택 재실행할 수 있어야 합니다.