# 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만 보고 수집 상태를 확인하고 재실행할 수 있다.