# Phase 1 개발문서 패키지

이 문서는 **Phase 0에서 고정한 전략/리스크/데이터 정책**을 바탕으로, AI 코딩 에이전트가 실제 구현을 시작할 수 있도록 만든 **Phase 1 상세 개발문서**입니다.

## 목표

Phase 1의 목표는 아래 4가지를 확정하는 것입니다.

1. **개발 환경과 저장 구조를 표준화**한다.
2. **데이터 소스별 adapter 계약**을 정의한다.
3. **DB/파일 스키마**를 고정한다.
4. **파서 출력 형식과 테스트 기준**을 고정한다.

## 포함 문서

- `architecture_and_repo_plan.md`
  - 전체 아키텍처
  - 모듈 경계
  - 저장소 구조
  - 서비스별 책임
  - 실행 흐름
  - 환경변수 정책
- `implementation_plan.md`
  - AI 코딩 에이전트용 작업 순서
  - 선행조건
  - 단계별 산출물
  - 완료 조건
  - 작업 분할 단위
- `db_schema.md`
  - PostgreSQL 운영 테이블
  - DuckDB/Parquet 연구용 저장 규칙
  - 인덱스/중복 방지 키
  - 상태 테이블 설계
  - SQL DDL 초안
- `service_contracts.md`
  - source adapter 계약
  - normalize/parser/feature builder 계약
  - 실행 엔진 계약
  - job 상태 기록 방식
  - 표준 에러/로그 포맷
- `parser_json_schema.md`
  - 이벤트 파서 출력 JSON 규격
  - 필드 정의
  - 필수/선택 항목
  - confidence와 provenance 정책
- `parser_event.schema.json`
  - 실제 JSON Schema 초안
- `testing_checklist.md`
  - 단위 테스트
  - 통합 테스트
  - 리플레이 테스트
  - 데이터 검증
  - 운영 전 점검표
- `coding_rules.md`
  - 코딩 규칙
  - 예외 처리 원칙
  - idempotency 원칙
  - retry/timeout 정책
  - 보안/비밀값 처리 원칙

## Phase 1 범위

Phase 1에서는 아래까지만 구현합니다.

- 로컬 재현 가능한 개발환경
- PostgreSQL/DuckDB 연결
- SEC / Alpaca / FRED / FINRA adapter 기본 골격
- raw/staging/structured 저장 파이프라인
- 이벤트 문서 파서 입출력 규격
- job 실행/에러/재시도 표준
- 최소한의 테스트 자동화

## Phase 1에서 일부러 하지 않는 것

- 실거래 주문 로직의 full implementation
- YouTube/Yahoo/Wikimedia attention layer 본 구현
- 대시보드 UI
- LLM 최적화
- 포트폴리오 최적화
- 숏 전략
- 초단타 intraday engine

## 권장 실행 순서

1. `architecture_and_repo_plan.md` 읽기
2. `coding_rules.md` 읽기
3. `db_schema.md` 기반으로 DB migration 작성
4. `service_contracts.md` 기반으로 adapter skeleton 작성
5. `parser_event.schema.json` 기준으로 parser I/O 고정
6. `implementation_plan.md` 순서대로 구현
7. `testing_checklist.md`로 검증

## 완료 기준

Phase 1 종료 시 아래가 가능해야 합니다.

- 한 명의 개발자가 로컬에서 전체 환경을 띄울 수 있다.
- SEC filing 하나를 수집해서 raw/staging/structured로 적재할 수 있다.
- Alpaca 일봉/분봉 데이터를 정규화 테이블에 넣을 수 있다.
- FRED/FINRA 데이터를 일자별로 수집할 수 있다.
- parser가 schema-valid JSON을 반환한다.
- 중복 실행 시 데이터가 두 번 쌓이지 않는다.
- 실패한 job을 안전하게 재시도할 수 있다.
- 최소 단위 테스트와 통합 테스트가 자동으로 돈다.