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.
332 lines
6.2 KiB
Markdown
332 lines
6.2 KiB
Markdown
# 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가 모두 연결되어야 합니다.
|