fithia2/dev/phase1_deliverables/implementation_plan.md

Phase 1 구현 계획

이 문서는 AI 코딩 에이전트가 실제 구현을 시작할 때 사용할 상세 작업 계획입니다.

1. 구현 우선순위

Phase 1 구현은 아래 순서를 강제합니다.

1. 공통 기반
2. DB 스키마와 migration
3. SEC adapter
4. Alpaca adapter
5. FRED adapter
6. FINRA adapter
7. parser I/O schema
8. event parser skeleton
9. feature builder skeleton
10. 테스트 자동화

이 순서를 바꾸지 않는 이유:

• 공통 기반 없이는 adapter 품질이 흔들립니다.
• DB 스키마가 없으면 모든 출력 계약이 흔들립니다.
• SEC가 핵심 source입니다.
• parser는 source 수집과 스키마가 고정된 뒤에 만들어야 합니다.

2. 작업 분할 단위

Task Group A — 공통 기반

A1. config loader

완료 조건:

• .env + YAML config를 읽을 수 있음
• 환경별 override 가능
• 누락된 필수 키는 즉시 실패

A2. logging module

완료 조건:

• JSON logger 제공
• job_run_id 주입 가능
• exception helper 제공

A3. time_utils

완료 조건:

• UTC ↔ US/Eastern 변환
• 거래일 helper
• date partition helper

A4. ids

완료 조건:

• document_id 생성
• event_id 생성
• checksum 생성

Task Group B — DB와 migration

B1. SQLAlchemy/Pydantic 모델

완료 조건:

• 핵심 테이블 모델 정의
• enum과 상태값 정의

B2. migration

완료 조건:

• 빈 DB에 초기 schema 적용 가능
• rollback 가능

B3. db helper

완료 조건:

• upsert helper
• transaction wrapper
• health check

Task Group C — SEC adapter

C1. submissions fetcher

완료 조건:

• 특정 CIK에 대한 submissions JSON 수집 가능
• raw 저장 성공

C2. filing downloader

완료 조건:

• accession 기반 filing index 다운로드
• filing text/html 저장
• exhibit 목록 추출

C3. metadata normalizer

완료 조건:

• documents 테이블에 canonical metadata 적재
• duplicate safe

C4. xbrl fetcher

완료 조건:

• facts/companyfacts 수집 가능
• 핵심 재무 필드 추출 가능

Task Group D — Alpaca adapter

D1. daily bars fetcher

완료 조건:

• 여러 symbol의 일봉 수집 가능
• canonical OHLCV 적재 가능

D2. intraday bars fetcher

완료 조건:

• 분봉 수집 가능
• 시간대 정규화 완료

Task Group E — FRED / FINRA adapter

E1. FRED

완료 조건:

• 시리즈별 시계열 수집
• observation 적재

E2. FINRA

완료 조건:

• daily short sale file download
• symbol별 파싱
• ratio 계산용 컬럼 적재

Task Group F — Parser

F1. parser schema validator

완료 조건:

• JSON schema validation 가능
• 실패 시 상세 에러 반환

F2. rule-based event parser

완료 조건:

• item number 추출
• guidance keyword 추출
• one-off keyword 추출
• event type 분류

F3. llm parser stub

완료 조건:

• 입력/출력 인터페이스만 고정
• 실제 호출은 feature flag로 disable 가능

Task Group G — Feature Builder

G1. market features

완료 조건:

• reaction-day return
• volume ratio
• close location
• ATR 기초값

G2. event features

완료 조건:

• guidance_direction
• oneoff_flags
• document_quality_score_raw

Task Group H — 테스트 자동화

H1. unit tests

H2. integration tests

H3. replay tests

H4. sample fixture set

3. 권장 구현 순서별 산출물

Step 1

산출물:

• libs/common/*
• configs/env.example
• Makefile 또는 bootstrap script

Step 2

산출물:

• DB migration 0001
• ORM models
• base repository helpers

Step 3

산출물:

• libs/adapters/sec/*
• apps/collector/sec_collector/*
• SEC fixture 기반 통합 테스트

Step 4

산출물:

• libs/adapters/alpaca/*
• daily/intraday collector

Step 5

산출물:

• libs/adapters/fred/*
• libs/adapters/finra/*

Step 6

산출물:

• parser schema
• parser validator
• rule parser

Step 7

산출물:

• feature builder skeleton
• sample feature row generation

Step 8

산출물:

• test suite
• CI command set

4. 금지 사항

• source adapter 내부에서 전략 점수 계산 금지
• parser 내부에서 DB 직접 접근 금지
• 테스트 없이 production migration 추가 금지
• raw 원문 overwrite 금지
• 외부 API 실패 시 silent ignore 금지
• timezone naive datetime 저장 금지

5. AI 코딩 에이전트용 작업 방식

권장 방식:

1. 각 Task Group 별로 브랜치 또는 PR 단위 생성
2. 테스트 먼저 작성
3. fixture 기반으로 개발
4. 구현 후 idempotency 검증
5. 문서 갱신

6. 완료 정의

Phase 1은 아래가 모두 만족될 때 완료입니다.

• 모든 핵심 source adapter가 최소 1개 fixture와 1개 실제 샘플로 검증됨
• DB migration이 처음부터 끝까지 깨끗하게 적용됨
• parser schema가 고정되고 샘플 문서에 대해 valid JSON 생성됨
• feature builder가 최소한 market/event feature 한 줄을 생성함
• pytest 기준 unit/integration 테스트가 자동 실행됨
• README만 보고 새 개발자가 환경을 띄울 수 있음