You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

5.8 KiB

Raw Blame History

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

1. 목적

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

2. 스케줄링 원칙

원천 데이터 수집은 source 특성에 맞춘다.
정규화/적재는 raw 저장 성공 이후에만 실행한다.
하루 운영 배치와 장기 백필 배치는 같은 코드 경로를 사용한다.
한 job 실패가 전체 DAG를 막지 않도록 source별 격리한다.
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:

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를 지원합니다.

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 예시

# 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: 현재 실행만 마무리 후 중단

설정 예시:

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별 실패 격리가 동작해야 합니다.
운영자가 특정 잡만 선택 재실행할 수 있어야 합니다.

5.8 KiB Raw Blame History