fithia2/dev/finished/phase2_deliverables/implementation_plan.md

Phase 2 구현 계획

이 문서는 AI 코딩 에이전트가 Phase 2를 실제로 구현할 수 있도록 작업 순서, 산출물, 완료 기준을 정의합니다.

1. 구현 원칙

1. 작은 단위로 쪼개서 머지 가능한 PR 수준으로 작업합니다.
2. 각 단계는 테스트 가능한 산출물을 남겨야 합니다.
3. raw-first / idempotent / replayable 원칙을 절대 깨지 않습니다.
4. TODO로 남기는 것보다 최소 동작 경로를 먼저 완성합니다.
5. Phase 2 범위 밖 기능을 섞지 않습니다.

2. 선행조건

아래가 준비되어 있어야 합니다.

• Phase 0 문서 승인
• Phase 1 문서 승인
• 저장소 구조 초기화
• PostgreSQL/DuckDB 연결 확인
• 공통 설정 로더 및 로깅 유틸 준비
• Phase 1 DB migration baseline 적용

3. 작업 분할

Workstream A — 공통 실행 프레임

A1. Job Runner 공통 모듈

구현:

• run_id 생성기
• job context
• structured log helper
• 상태 전이 helper
• retry helper

완료 기준:

• 샘플 job이 created → running → completed까지 상태를 남길 수 있어야 함

A2. Checkpoint Store

구현:

• checkpoint load/save 인터페이스
• source/job별 namespace
• optimistic update 또는 atomic update

완료 기준:

• 샘플 key에 대해 저장/조회/갱신 가능
• race condition 기본 테스트 통과

A3. Raw File Store

구현:

• temp write → checksum → atomic rename
• sidecar 메타 저장
• path builder

완료 기준:

• 샘플 payload에 대해 raw + sidecar 저장 가능
• checksum mismatch 시 예외 발생

Workstream B — SEC 수집기

B1. submissions poll

구현:

• CIK 목록 입력
• submissions JSON fetch
• raw 저장
• filing header staging 생성
• documents upsert

완료 기준:

• 최소 1개 CIK에 대해 최신 submissions 처리 성공
• 신규 accession 탐지 가능

B2. filing fetch

구현:

• accession 대상 fetch
• filing text/index/exhibit 저장
• artifact inventory 생성

완료 기준:

• accession 1건에 대해 filing 본문과 99.1 저장 가능

B3. xbrl extract

구현:

• XBRL 대상 식별
• 주요 fact rows 추출
• canonical fact 저장

완료 기준:

• accession 1건에서 fact rows 생성 가능

Workstream C — Alpaca 수집기

C1. daily bars backfill

구현:

• symbol/date range 입력
• raw 저장
• canonical daily bars 생성
• PostgreSQL/Parquet 저장

완료 기준:

• 3개 이상 심볼, 20일 이상 backfill 성공

C2. intraday bars poll

구현:

• symbol list 입력
• 지정 trading day intraday 수집
• canonical intraday bars 생성

완료 기준:

• 1개 trading day에 대해 분봉 데이터 저장 가능

Workstream D — FRED / FINRA 수집기

D1. FRED series sync

구현:

• series_id 목록 설정
• series metadata + observations 저장

완료 기준:

• 3개 이상 series 동기화 성공

D2. FINRA short volume

구현:

• 거래일 파일 fetch
• 파싱 및 구조화
• 비정상 행 검출

완료 기준:

• 1일 파일 처리 및 symbol row 저장 성공

Workstream E — 검증 및 운영

E1. Data Quality Validator

구현:

• uniqueness 검사
• null/empty 검사
• timestamp/date 범위 검사
• freshness 검사

완료 기준:

• source별 검증 리포트 생성 가능

E2. CLI + Cron friendly entrypoints

구현:

• 각 잡 CLI
• dry_run / backfill / replay 지원

완료 기준:

• 문서에 있는 CLI 예시가 실제로 동작

E3. Runbook support

구현:

• failed run 재시도 명령
• quarantine 조회 명령
• lineage 조회 유틸

완료 기준:

• 운영자가 CLI만으로 기본 진단 가능

4. 권장 구현 순서

1. Workstream A
2. Workstream B1
3. Workstream C1
4. Workstream D1 / D2
5. Workstream B2
6. Workstream C2
7. Workstream B3
8. Workstream E

이 순서의 이유:

• 먼저 공통 런타임을 안정화해야 함
• 그 다음 전략에 가장 중요한 SEC + 일봉 가격부터 확보
• 나머지 소스는 이후 붙여도 연구가 가능

5. AI 코딩 에이전트용 세부 지시

5.1 구현 스타일

• 각 collector는 main.py, runner.py, client.py, normalize.py, write.py로 분리
• source별 하드코딩 최소화
• 공통 로직은 libs/common, libs/adapters, libs/db로 이동
• 타입힌트 필수
• 테스트 fixture를 먼저 만들고 구현

5.2 금지사항

• source adapter 내부에서 전략 점수 계산 금지
• raw 저장 없이 structured write 금지
• print 기반 로그 금지
• 전역 mutable state 금지
• silent failure 금지

5.3 필수 구현 항목

• dry_run
• replay
• force
• run_id propagation
• checksum capture
• structured log
• checkpoint persistence

6. 각 PR 또는 작업 단위의 Definition of Done

모든 작업은 아래를 만족해야 완료로 봅니다.

• 코드 구현 완료
• 단위 테스트 추가
• 최소 1개 통합 테스트 추가
• README 또는 해당 문서 갱신
• 예외/오류 메시지 사람이 이해 가능
• 로그에 run_id 포함
• idempotent 재실행 확인

7. 최종 완료 기준

Phase 2 전체 완료 조건:

• SEC / Alpaca / FRED / FINRA 수집기가 모두 동작한다.
• poll/backfill/replay 3모드가 적어도 핵심 source에 구현돼 있다.
• raw/staging/structured lineage가 연결된다.
• job_runs / checkpoint / quality result가 기록된다.
• 운영자가 runbook만 보고 수집 상태를 확인하고 재실행할 수 있다.