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