# Phase 3 개발문서 패키지

이 문서는 **Phase 0의 전략/리스크/데이터 정책**, **Phase 1의 저장소 구조/DB/서비스 계약**, **Phase 2의 ingestion 계약**을 바탕으로,
AI 코딩 에이전트가 **문서 파서, feature builder, 라벨 생성, 품질검증 파이프라인**을 구현할 수 있도록 만든 **Phase 3 상세 개발문서**입니다.

## 목표

Phase 3의 목표는 아래 8가지를 실제 코드 수준으로 구현하는 것입니다.

1. **공시/첨부문서를 표준 이벤트 레코드로 변환하는 parser 계층**을 구현한다.
2. **규칙 기반 추출과 LLM 보강 추출의 역할 분담**을 고정한다.
3. **이벤트/문서/가격/레짐/attention 피처 생성 규칙**을 고정한다.
4. **1D/3D/5D forward outcome 라벨 생성 규칙**을 고정한다.
5. **수동 검수(review queue)와 품질 보증(QA) 절차**를 만든다.
6. **학습용/리서치용 데이터셋 스냅샷 생성 규칙**을 만든다.
7. **LLM 호출을 캐시/버전관리/재현 가능하게** 만든다.
8. **Phase 4 백테스터가 바로 사용할 수 있는 canonical feature dataset**을 제공한다.

## 포함 문서

- `parser_and_feature_architecture.md`
  - Phase 3 전체 아키텍처
  - parse → normalize → enrich → feature → label 흐름
  - 서비스 경계와 데이터 계약
- `document_parser_design.md`
  - 문서 파서 상세 설계
  - 규칙 기반/LLM 기반 역할 분리
  - 필드별 추출 규칙
  - fallback / retry / confidence 정책
- `feature_catalog.md`
  - 이벤트/문서/가격/레짐/attention feature 정의
  - 계산식
  - null 처리
  - 누수(leakage) 금지 규칙
- `labeling_and_dataset_spec.md`
  - 라벨 생성 규칙
  - reaction day / entry day 정의
  - 1D/3D/5D labels, MFE/MAE
  - 학습/검증용 스냅샷 생성 규칙
- `prompt_and_llm_policy.md`
  - LLM 프롬프트 정책
  - JSON schema 사용 방식
  - 모델 버전/프롬프트 버전/캐시 키
  - 비용 통제와 fallback 원칙
- `quality_assurance_and_review.md`
  - 수동 검수 흐름
  - disagreement triage
  - parser 품질 지표
  - gold set 운영 방식
- `implementation_plan.md`
  - AI 코딩 에이전트용 구현 순서
  - 작업 분할
  - 완료 조건
  - 금지사항
- `testing_checklist.md`
  - 단위 테스트
  - 통합 테스트
  - replay 테스트
  - 품질/운영 전 체크리스트
- `review_queue_contract.md`
  - review queue 스키마
  - 상태 전이
  - 검수 UI/CLI 요구사항
- `feature_record.schema.json`
  - canonical feature record JSON Schema
- `review_record.schema.json`
  - 수동 검수 레코드 JSON Schema

## Phase 3 범위

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

- 문서 파서
- LLM 호출 래퍼와 캐시
- 파서 출력 정규화
- feature builder
- labeling job
- review queue
- gold set 평가
- canonical dataset export

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

- 모델 학습 자동화의 full pipeline
- 전략 점수식 최종 확정
- portfolio optimizer
- live 주문 엔진
- 대시보드 고도화
- attention source 신규 수집기 구현

## 권장 실행 순서

1. `parser_and_feature_architecture.md` 읽기
2. `document_parser_design.md` 읽기
3. `prompt_and_llm_policy.md` 읽기
4. `feature_catalog.md` 기반으로 feature builder 구현
5. `labeling_and_dataset_spec.md` 기반으로 labeler 구현
6. `review_queue_contract.md` 기반으로 review workflow 구현
7. `implementation_plan.md` 순서대로 구현
8. `testing_checklist.md`로 검증
9. `quality_assurance_and_review.md`로 품질 점검

## 완료 기준

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

- SEC 이벤트 문서 하나를 canonical parser output으로 변환할 수 있다.
- parser output이 schema-valid JSON을 반환한다.
- 규칙 기반 추출과 LLM 보강 추출이 provenance와 confidence를 남긴다.
- feature builder가 event/document/market/regime/attention 피처를 한 레코드로 결합한다.
- 1D/3D/5D label과 MFE/MAE를 계산할 수 있다.
- 수동 검수 대상이 review queue에 자동 등록된다.
- gold set에 대해 parser 품질 리포트를 생성할 수 있다.
- canonical dataset을 Parquet/JSONL로 export할 수 있다.