# Phase 3 구현 계획

## 1. 선행조건

- Phase 0 승인 완료
- Phase 1 저장소/DB/서비스 계약 구현 완료
- Phase 2 ingestion 파이프라인이 raw/staging/structured 데이터를 안정적으로 제공
- parser_event.schema.json 사용 가능

## 2. 구현 단위

### Workstream A. Parser foundation
목표:
- 문서 선택기
- 텍스트 normalizer
- rule parser skeleton
- span mapper

완료 조건:
- 8-K + EX-99.1 문서를 정규화 텍스트로 만들 수 있다.

### Workstream B. LLM enrichment
목표:
- llm client wrapper
- schema validation
- prompt registry
- cache layer
- raw response logging

완료 조건:
- 동일 문서 재호출 없이 schema-valid 응답을 저장할 수 있다.

### Workstream C. Canonicalization
목표:
- rule + llm 병합
- provenance 저장
- disagreement 탐지
- review queue 생성

완료 조건:
- canonical event record를 event_records에 적재할 수 있다.

### Workstream D. Feature builder
목표:
- event/document/numeric/market/regime/attention feature 계산
- as_of_ts / available_ts 저장
- leakage validator

완료 조건:
- event_feature_records 생성 가능

### Workstream E. Labeling
목표:
- reaction date 계산
- entry convention별 label 생성
- MFE/MAE 계산
- snapshot export

완료 조건:
- train/valid/test parquet snapshot 생성 가능

### Workstream F. QA and review
목표:
- gold set loader
- parser evaluator
- review queue tooling
- weekly quality report skeleton

완료 조건:
- 골드셋 회귀 검증과 review queue triage 가능

## 3. 권장 작업 순서

1. document selector + normalizer 구현
2. rule parser 기본 필드 구현
3. line/span reference 구현
4. llm wrapper + schema validator 구현
5. canonical merge 구현
6. event feature builder 구현
7. market/regime feature join 구현
8. labeler 구현
9. dataset snapshot exporter 구현
10. review queue / gold set evaluator 구현

## 4. 금지사항

- 규칙/LLM 출력 형식을 중간에 자주 바꾸기
- evidence 없이 핵심 필드 저장
- as_of_ts 없는 feature 저장
- future leakage 검사 없이 label 생성
- raw response를 버리고 normalized output만 저장

## 5. Task slicing 예시

### Task 1
`apps/parser/document_selector.py`
- 입력: filing_documents
- 출력: parser_jobs
- 테스트: 8-K with EX-99.1 prioritization

### Task 2
`libs/common/text_normalizer.py`
- HTML to text
- disclaimer strip option
- hash generation

### Task 3
`apps/parser/rule_parser.py`
- guidance keywords
- one-off keywords
- demand/pricing/margin keywords

### Task 4
`libs/llm/client.py`
- invoke
- cache
- retry
- raw response persistence

### Task 5
`apps/parser/canonicalize.py`
- merge policy
- disagreement flags
- review queue write

### Task 6
`apps/feature_builder/build_event_features.py`
- parser-derived features
- availability metadata

### Task 7
`apps/feature_builder/build_market_features.py`
- reaction day price/volume features
- regime join

### Task 8
`apps/labeler/generate_labels.py`
- reaction_date
- entry_date
- 1D/3D/5D labels
- MFE/MAE

### Task 9
`apps/qa/evaluate_gold_set.py`
- parser metrics
- regression compare

## 6. 완료 정의

Phase 3 완료는 아래를 모두 만족해야 합니다.
- parser output schema validation 100%
- gold set core metrics가 baseline 이상
- feature leakage tests pass
- snapshot export reproducible
- review queue 생성/소진 흐름 작동
- operator가 파싱 실패 원인과 review 대상을 추적 가능