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