fithia2/dev/phase2_deliverables/ingestion_architecture.md

Phase 2 데이터 수집 아키텍처

1. 목적

Phase 2의 목적은 전략 판단 이전 단계의 데이터 공급 계층을 완성하는 것입니다. 이 단계에서 만드는 시스템은 다음 성질을 만족해야 합니다.

1. 재실행 가능해야 한다.
2. 부분 실패에 안전해야 한다.
3. 원문(raw)을 보존해야 한다.
4. 정규화와 적재가 분리되어야 한다.
5. 체크포인트 기반 증분 수집이 가능해야 한다.
6. 백필과 운영 실행이 동일한 코드 경로를 사용해야 한다.

2. 상위 구조

External Sources
  ├─ SEC EDGAR / data.sec.gov
  ├─ Alpaca Market Data
  ├─ FRED API
  └─ FINRA Daily Short Sale Volume

        ↓
[Source Adapter Layer]
  - source client
  - fetch policy
  - raw payload writer
  - source checksum

        ↓
[Raw Zone]
  - immutable payload files
  - fetch metadata sidecar

        ↓
[Normalizer / Extractor Layer]
  - canonical field mapping
  - record decomposition
  - validation

        ↓
[Staging Zone]
  - parseable intermediate outputs
  - extracted metadata
  - entity identifiers

        ↓
[Structured Writer Layer]
  - PostgreSQL upsert
  - Parquet append/replace partition
  - dedupe / idempotency guard

        ↓
[Operational State]
  - job_runs
  - checkpoints
  - source_status
  - write_manifest

3. 처리 단위

모든 수집 작업은 job + run_id + source checkpoint 단위로 동작합니다.

3.1 Job

예:

• sec_submissions_poll
• sec_filing_fetch
• sec_xbrl_extract
• alpaca_daily_bars_backfill
• alpaca_intraday_bars_poll
• fred_series_sync
• finra_short_volume_fetch

3.2 Run ID

모든 실행은 고유한 run_id를 가져야 하며, raw sidecar / job_runs / structured manifest에 동일하게 남겨야 합니다.

예시:

• 2026-03-12T21:05:14Z_sec_submissions_poll_001

3.3 Checkpoint

각 source/job 조합은 다음 형태의 체크포인트를 가져야 합니다.

• 시간 기반: 마지막 성공 시각
• 페이지 기반: 마지막 page token / cursor
• 파일 기반: 마지막 accession / filename / date
• 심볼 기반: 마지막 심볼/날짜 조합

4. 계층별 책임

4.1 Source Adapter

역할:

• 외부 API/file endpoint 요청
• response 수신
• raw payload 저장
• sidecar 메타데이터 기록
• 최소 검증(응답 비어 있음, 상태코드 오류, checksum 등)

금지:

• 전략 점수 계산
• event classification
• feature engineering

4.2 Normalizer / Extractor

역할:

• source-specific payload를 canonical schema로 변환
• 필요한 key field 추출
• 식별자 생성
• staging output 생성

예:

• SEC filing index에서 accession, filing_date, form_type, exhibit list 추출
• Alpaca bars 응답을 symbol/timestamp/ohlcv schema로 변환
• FRED series response를 series_id/date/value schema로 변환
• FINRA txt를 symbol/date/short_volume/total_volume schema로 변환

4.3 Structured Writer

역할:

• PostgreSQL upsert
• Parquet partition write
• write manifest 기록
• 중복 write 방지

4.4 Data Quality Validator

역할:

• null 비율 검사
• 날짜/시간 일관성 검사
• primary key uniqueness 검사
• partition completeness 검사
• source freshness 검사

5. 원칙

5.1 Raw First

원문 저장이 실패하면 downstream 단계는 진행하지 않습니다.

5.2 Deterministic Output

동일 input payload는 동일 normalized output을 만들어야 합니다.

5.3 Idempotent Writes

동일 raw payload를 다시 처리해도 structured 결과가 중복되면 안 됩니다.

5.4 Explicit Status Transition

작업 상태는 아래처럼 명시적으로 이동해야 합니다.

created
→ running
→ raw_saved
→ staged
→ structured_written
→ validated
→ completed

실패 시:

running
→ failed_retriable
or
running
→ failed_terminal

6. 체크포인트 전략

6.1 SEC

• submissions poll: 마지막 성공 시각 + 최근 처리 accession 목록
• filing fetch: accession 단위 완료 플래그
• xbrl extract: accession + taxonomy 버전 단위 완료 플래그

6.2 Alpaca

• 심볼 / timeframe / trading_date 단위 완료 플래그
• intraday poll은 마지막 bar timestamp 기록

6.3 FRED

• series_id / latest observation date

6.4 FINRA

• trading_date 파일 존재 여부 + checksum

7. 재시도 정책

7.1 공통

• 네트워크 오류: exponential backoff
• 응답 5xx: 재시도 가능
• 응답 4xx: 기본은 terminal, 단 rate-limit 계열은 retriable
• schema validation 실패: terminal
• raw write 실패: retriable
• structured deadlock/connection error: retriable

7.2 최대 재시도

기본값:

• 즉시 재시도 3회
• 이후 다음 scheduler tick에 다시 시도
• 같은 payload가 3번 연속 schema validation 실패 시 quarantine

8. Quarantine

아래 경우 quarantine 디렉터리와 quarantine 테이블에 기록합니다.

• parsing 불가 raw
• schema violation raw
• 필수 식별자 누락
• 비정상적으로 큰 payload
• source format drift 의심

경로 예시:

data/quarantine/sec/2026-03-12/{run_id}/...

9. 운영 상태 저장

PostgreSQL에는 최소 아래가 필요합니다.

• job_runs
• source_checkpoints
• raw_objects
• write_manifests
• data_quality_results
• quarantine_records

세부 컬럼은 Phase 1의 db_schema.md를 따르되, Phase 2에서 필요한 상태 컬럼을 추가합니다.

10. 구성 요소별 구현 우선순위

1. SEC submissions / filing fetch
2. Alpaca daily bars
3. FRED series sync
4. FINRA short volume
5. Alpaca intraday bars
6. SEC XBRL extract

이 순서가 중요한 이유는, 전략 연구의 최소 요건이 이벤트 원문 + 일봉 가격 + 거시 레짐 + crowding 보조지표이기 때문입니다.

11. Phase 2 성공 기준

• 하루치 수집이 아니라, 기간 백필이 안전하게 가능해야 합니다.
• 새 실행과 재실행이 동일한 코드 경로를 타야 합니다.
• raw/staging/structured 간 lineage를 역추적할 수 있어야 합니다.
• 운영자가 특정 거래일의 데이터 누락 원인을 추적할 수 있어야 합니다.