# Configuration and Schemas

## 1. 목표

Phase 4는 모든 실험을 manifest 기반으로 실행해야 합니다.
설정 파일은 사람이 읽기 쉬운 YAML/JSON을 허용하되,
실행 직전 반드시 JSON Schema 검증을 통과해야 합니다.

## 2. 설정 계층

### 2.1 Base strategy config

전략 기본값.
예: 진입 규칙, exit 규칙, scoring threshold.

### 2.2 Environment config

데이터 위치, snapshot id, output base path.

### 2.3 Experiment manifest

실험 한 번을 완전히 정의하는 파일.

## 3. 필수 설정 항목

### 3.1 Universe

- allowed asset types
- min price
- min dollar volume
- exclude ADR/SPAC/ETF

### 3.2 Signal

- score threshold
- max candidates per day
- ranking fields
- decision timing
- execution timing

### 3.3 Risk

- per_trade_risk_pct
- max_daily_new_risk_pct
- max_positions
- max_positions_per_sector
- max_position_value_pct

### 3.4 Execution

- entry fill model
- exit fill model
- slippage model
- commission model
- stop/take-profit priority rule

### 3.5 Reporting

- output formats
- plot generation on/off
- attribution buckets

## 4. 결과 디렉터리 구조

권장 구조:

```text
runs/
  {run_id}/
    manifest.json
    resolved_config.json
    metadata.json
    logs/
    metrics/
      metrics_summary.json
      attribution_by_event_type.csv
      attribution_by_sector.csv
      score_bucket_report.csv
    artifacts/
      trade_blotter.parquet
      daily_equity_curve.parquet
      position_timeline.parquet
    plots/
      equity_curve.png
      drawdown_curve.png
      monthly_heatmap.png
    notes/
      run_notes.md
```

## 5. config merge 규칙

1. base config
2. strategy profile override
3. experiment manifest override
4. CLI override (가능하면 최소화)

최종 resolved config를 반드시 저장해야 합니다.

## 6. versioning

다음은 metadata에 반드시 남깁니다.

- code commit hash
- dataset snapshot id
- feature schema version
- parser prompt version
- config hash
- run timestamp
- timezone

## 7. schema 검증 정책

- 실행 전 manifest schema 검증 필수
- config merge 후 resolved config schema 재검증 필수
- unknown key는 기본적으로 에러 처리
- 타입 coercion 자동 수행 금지

## 8. output contract

실험 결과는 downstream Phase 5/6이 재사용할 수 있어야 합니다.
따라서 trade blotter와 metrics summary의 필드명은 안정적으로 유지합니다.

## 9. CLI 예시

```bash
python -m apps.backtester.run \
  --manifest configs/experiments/baseline_v1.json \
  --snapshot-id snapshot_2026_03_20 \
  --output-root ./runs
```

## 10. 필수 metadata.json 예시 필드

```json
{
  "run_id": "bt_fgce_v1_snapshot_20260315_20260320_153000_a81c92",
  "strategy_name": "fgce_v1",
  "dataset_snapshot_id": "snapshot_2026_03_20",
  "feature_schema_version": "1.0.0",
  "config_hash": "...",
  "git_commit": "...",
  "started_at_et": "2026-03-20T15:30:00-04:00",
  "completed_at_et": "2026-03-20T15:31:40-04:00"
}
```