# 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만 보고 새 개발자가 환경을 띄울 수 있음