# Phase 2 Source Adapter 상세 명세

이 문서는 Phase 2에서 구현할 핵심 source adapter의 상세 규격을 정의합니다.
모든 adapter는 다음 공통 인터페이스를 따라야 합니다.

## 1. 공통 인터페이스

### 1.1 입력

- `run_id: str`
- `mode: Literal["poll", "backfill", "replay"]`
- `start_date: date | None`
- `end_date: date | None`
- `symbols: list[str] | None`
- `force: bool = False`
- `dry_run: bool = False`

### 1.2 출력

표준 실행 요약 객체:

```json
{
  "run_id": "...",
  "job_name": "...",
  "source": "...",
  "status": "completed",
  "raw_objects_written": 0,
  "staging_records_written": 0,
  "structured_records_written": 0,
  "warnings": [],
  "errors": []
}
```

### 1.3 예외 분류

- `RetriableSourceError`
- `TerminalSourceError`
- `SchemaValidationError`
- `CheckpointCorruptionError`
- `RawWriteError`
- `StructuredWriteError`

## 2. SEC Adapter

### 2.1 책임

- 회사 submissions JSON 수집
- filing index / filing text / exhibit 문서 다운로드
- accession / form_type / filing_date / acceptance_datetime 추출
- XBRL facts 추출 대상 식별

### 2.2 세부 job

#### A. `sec_submissions_poll`

입력:
- CIK 목록 또는 symbol master 기반 CIK 맵

raw 출력:
- submissions JSON

staging 출력:
- filing header row 목록
- 신규 accession 후보 목록

structured 출력:
- `documents`
- `document_versions`

#### B. `sec_filing_fetch`

입력:
- accession 목록

raw 출력:
- filing text/html
- filing index
- exhibit 문서

staging 출력:
- exhibit inventory
- 99.1 / xbrl 관련 링크

structured 출력:
- `raw_objects`
- `document_artifacts`

#### C. `sec_xbrl_extract`

입력:
- XBRL 가능 accession

staging 출력:
- canonical fact rows

structured 출력:
- `xbrl_facts`

### 2.3 체크포인트

- 마지막 submissions fetch 시각
- accession별 fetch 완료 상태
- accession별 xbrl extract 완료 상태

### 2.4 idempotency key

- submissions: `(source, cik, fetched_at_date, checksum)`
- filing fetch: `(source, accession, artifact_name, checksum)`
- xbrl facts: `(accession, concept, period_end, unit, segment_hash)`

### 2.5 구현 주의사항

- accession formatting을 내부 표준으로 통일
- 동일 accession의 문서/artifact는 checksum이 다를 때만 새 버전 생성
- raw write 전에 checksum 계산
- 99.1, 8-K, 10-Q, 10-K, 6-K, 20-F 우선

### 2.6 실패 조건

retriable:
- 일시적 네트워크 오류
- 응답 타임아웃
- 일시적 source unavailable

terminal:
- accession 식별 불가
- 필수 filing metadata 누락
- artifact MIME/type 해석 불가

## 3. Alpaca Adapter

### 3.1 책임

- 일봉 수집
- 분봉 수집(Phase 2에서는 1분/5분 중 하나만 선택)
- 심볼별 거래일 범위 backfill

### 3.2 세부 job

#### A. `alpaca_daily_bars_backfill`

입력:
- symbol list
- date range

raw 출력:
- 원본 bars payload

staging 출력:
- canonical daily bars

structured 출력:
- `market_bars_daily`
- Parquet partition `bars_daily/trading_date=YYYY-MM-DD/`

#### B. `alpaca_intraday_bars_poll`

입력:
- symbol list
- trading day

raw 출력:
- intraday bars payload

staging 출력:
- canonical intraday bars

structured 출력:
- `market_bars_intraday`
- Parquet partition `bars_intraday/trading_date=YYYY-MM-DD/`

### 3.3 체크포인트

- symbol / timeframe / date 단위 완료 플래그
- intraday는 마지막 timestamp

### 3.4 idempotency key

- `(symbol, timeframe, timestamp)`

### 3.5 구현 주의사항

- timezone normalization을 내부 표준으로 강제
- 반일장 / 휴장일 처리
- 동일 바 중복 수신 시 마지막 checksum만 허용

### 3.6 실패 조건

retriable:
- 네트워크 오류
- 일시적 rate-limit

terminal:
- symbol invalid
- timestamp parse 실패
- 필수 OHLCV 필드 누락

## 4. FRED Adapter

### 4.1 책임

- 지정 series_id 목록 sync
- daily/weekly/monthly frequency series 공통 적재

### 4.2 세부 job

#### A. `fred_series_sync`

입력:
- series_id 목록
- optional date range

raw 출력:
- series observations payload

staging 출력:
- canonical series rows

structured 출력:
- `macro_series_observations`

### 4.3 체크포인트

- series_id별 마지막 observation date

### 4.4 idempotency key

- `(series_id, observation_date)`

### 4.5 구현 주의사항

- 숫자/결측 문자열 처리 규칙 고정
- revision이 가능한 시계열은 overwrite 가능한 upsert 허용
- source metadata(series title, units, frequency)도 별도 저장

## 5. FINRA Adapter

### 5.1 책임

- daily short sale volume 파일 다운로드
- 파일 파싱 및 종목별 행 생성

### 5.2 세부 job

#### A. `finra_short_volume_fetch`

입력:
- trading date range

raw 출력:
- 원본 txt/csv 파일

staging 출력:
- parsed rows

structured 출력:
- `short_sale_volume_daily`

### 5.3 체크포인트

- trading_date 파일 존재 여부
- checksum

### 5.4 idempotency key

- `(trade_date, symbol)`

### 5.5 구현 주의사항

- header drift 대응
- symbol 정규화
- total_volume == 0 또는 short_volume > total_volume 같은 비정상 레코드 검출

## 6. 공통 구현 요구사항

### 6.1 로그

모든 adapter는 최소 아래 필드를 구조화 로그로 남겨야 합니다.

- `run_id`
- `job_name`
- `source`
- `mode`
- `status`
- `object_count`
- `duration_ms`
- `warning_count`
- `error_count`

### 6.2 메트릭

최소 메트릭:
- fetch success rate
- fetch latency
- raw write latency
- staging rows written
- structured rows written
- checkpoint lag

### 6.3 Dry Run

모든 adapter는 `dry_run` 모드를 지원해야 합니다.

`dry_run=True`일 때:
- 원격 요청은 수행 가능
- raw/structured write는 하지 않음
- validation과 실행 계획만 출력

### 6.4 Replay

모든 adapter는 특정 raw object를 replay input으로 받을 수 있어야 합니다.

예:
- `--raw-path data/raw/sec/.../filing.txt`
- `--raw-path data/raw/finra/.../file.txt`

### 6.5 Source Freeze

특정 source가 이상 동작할 때 운영자가 source별 수집을 중단할 수 있어야 합니다.

예:
- `configs/source_freeze.yaml`
- source/job 단위 on/off

## 7. 완료 기준

- 각 adapter는 poll/backfill/replay를 모두 지원해야 합니다.
- 동일 input에서 동일 output을 만들어야 합니다.
- raw sidecar, structured rows, checkpoint, job_runs가 모두 연결되어야 합니다.