# Phase 2 Job Catalog

이 문서는 Phase 2에서 구현할 배치 작업을 표준 이름, 입력, 출력, 실행 시점 기준으로 정리한 목록입니다.

## 1. 공통 필드

모든 job은 아래 공통 필드를 가져야 합니다.

- `job_name`
- `source`
- `mode`
- `run_id`
- `started_at`
- `ended_at`
- `status`
- `input_scope`
- `output_counts`

## 2. Job 목록

### 2.1 `sec_submissions_poll`

**source**: sec  
**목적**: 신규 submissions JSON 수집 및 filing header 추출  
**입력**: CIK 목록  
**출력**: raw submissions, filing headers, documents upsert  
**권장 주기**: 평일 10~15분 간격  
**mode 지원**: poll, backfill, replay(제한적)

예시:

```bash
python -m apps.collector.sec_collector.main --job sec_submissions_poll --mode poll
```

### 2.2 `sec_filing_fetch`

**source**: sec  
**목적**: filing 본문, index, exhibit 다운로드  
**입력**: accession 목록  
**출력**: raw filing artifacts, artifact inventory  
**권장 주기**: submissions poll 후 즉시  
**mode 지원**: poll, backfill, replay

### 2.3 `sec_xbrl_extract`

**source**: sec  
**목적**: XBRL facts 추출  
**입력**: accession 목록 또는 pending xbrl queue  
**출력**: xbrl_facts rows  
**권장 주기**: filing fetch 후 배치  
**mode 지원**: poll, backfill, replay

### 2.4 `alpaca_daily_bars_backfill`

**source**: alpaca  
**목적**: 일봉 수집/백필  
**입력**: symbol list, date range  
**출력**: daily bars raw/staging/structured  
**권장 주기**: 장 종료 후 1회 + 필요 시 backfill  
**mode 지원**: poll, backfill, replay

예시:

```bash
python -m apps.collector.alpaca_collector.main \
  --job alpaca_daily_bars_backfill \
  --mode backfill \
  --symbols AAPL,MSFT \
  --start-date 2026-01-01 \
  --end-date 2026-01-31
```

### 2.5 `alpaca_intraday_bars_poll`

**source**: alpaca  
**목적**: 분봉 수집  
**입력**: symbol list, trading day  
**출력**: intraday bars raw/staging/structured  
**권장 주기**: 거래일 종료 후 또는 장중 5~15분 간격  
**mode 지원**: poll, backfill, replay

### 2.6 `fred_series_sync`

**source**: fred  
**목적**: 거시 시계열 수집  
**입력**: series_id 목록  
**출력**: series metadata, observation rows  
**권장 주기**: 일 1회  
**mode 지원**: poll, backfill, replay

예시:

```bash
python -m apps.collector.fred_collector.main \
  --job fred_series_sync \
  --mode poll
```

### 2.7 `finra_short_volume_fetch`

**source**: finra  
**목적**: 일별 short volume 파일 수집  
**입력**: trade_date 또는 date range  
**출력**: raw file, parsed rows, structured rows  
**권장 주기**: 일 1회  
**mode 지원**: poll, backfill, replay

### 2.8 `dq_validate_source_batch`

**source**: internal  
**목적**: source별 데이터 품질 검증  
**입력**: source, date range  
**출력**: quality result rows, warnings/errors  
**권장 주기**: 각 적재 후 후속 실행  
**mode 지원**: poll, replay

### 2.9 `lineage_verify_batch`

**source**: internal  
**목적**: raw/staging/structured lineage 검증  
**입력**: source, run_id 또는 date range  
**출력**: lineage verification result  
**권장 주기**: 일 1회 또는 배포 후 1회  
**mode 지원**: poll, replay

## 3. 우선순위

### P0 (반드시 구현)
- `sec_submissions_poll`
- `sec_filing_fetch`
- `alpaca_daily_bars_backfill`
- `fred_series_sync`
- `finra_short_volume_fetch`

### P1 (Phase 2 내 구현 권장)
- `sec_xbrl_extract`
- `alpaca_intraday_bars_poll`
- `dq_validate_source_batch`

### P2 (필요 시)
- `lineage_verify_batch`

## 4. 운영자가 자주 쓰는 조합

### 시나리오 A: 평시 일일 배치
1. `sec_submissions_poll`
2. `sec_filing_fetch`
3. `sec_xbrl_extract`
4. `alpaca_daily_bars_backfill` (당일)
5. `fred_series_sync`
6. `finra_short_volume_fetch`
7. `dq_validate_source_batch`

### 시나리오 B: 과거 기간 백필
1. `alpaca_daily_bars_backfill`
2. `sec_submissions_poll` (범위 제한)
3. `sec_filing_fetch`
4. `sec_xbrl_extract`
5. `fred_series_sync`
6. `finra_short_volume_fetch`

### 시나리오 C: 버그 수정 후 재처리
1. `sec_filing_fetch --mode replay`
2. `sec_xbrl_extract --mode replay`
3. `dq_validate_source_batch`
4. `lineage_verify_batch`

## 5. 완료 기준

- 위 P0 job은 모두 실제 코드 entrypoint를 가져야 합니다.
- 각 job은 문서에 나온 입력/출력/상태 규칙을 따라야 합니다.
- 운영자는 job 이름만 보고 역할을 이해할 수 있어야 합니다.