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