# 영우님 VPP/Settlement 연동용 데이터 기준 — v3

## 지금 받을 수 있는 것

이 묶음은 **수아님 데이터 기준 전달본**이다. 버전은 `handoff_data_basis_v3`, 연결용 계약은 `vpp_data_basis_v1`이다. D01~D03 합의와 원본에서 확인한 ID·용량·시간 기준을 고정했다. 공식 정산 최종 승인, 수신자의 실제 파이프라인 통과, 실제 Forecast/OOF 성능은 별도다.

| 영우님 요청 | 파일/위치 | 상태 |
|---|---|---|
| Data Contract/버전 | `../data_contract.json`, `integration_contract.json` | 데이터 담당자 전달 기준 고정; 영우님 수신 확인 대기 |
| 253개 Plant ID·Capacity | `plant_master.csv` | 원본과 253개 전부 대조 |
| Timestamp/Timezone | 계약의 `time` | KST, 1시간 구간 끝 기준 |
| Train/Validation·holdout | `../outputs/oibc_1121/split_config.json` | 5개 구간과 계절 site ID 포함 |
| Feature Availability | `../outputs/oibc_1122/feature_policy.json`, `feature_availability_matrix.csv` | 합의 v2 유지 |
| Leakage 기준 | 아래 체크리스트 및 계약 `oof` | 미래 정답 사용 금지, cutoff·holdout 잠금 |
| D01~D03 합의 결과 | `../AGREEMENT_D01_D03.md`, `../forecast_round_policy.json`, `../decisions.csv` | 합의 반영 완료 |
| 파일별 SHA256 | `../manifest.json`, 계약 `linked_files` | 배포본 버전 일치 확인용 |

## ID·용량·정밀도

- `site_id` 253개는 문자열 `PV001`~`PV253`이고 중복이 없다. 목록 파일을 기준으로 정확히 join한다. 행 순서로 결합하거나 앞의 0을 제거하지 않는다.
- `capacity_kw`는 원본을 손실 없이 소수 3자리로 표현한 **kW**다. 합계 **42,655.370kW**. 원본은 최대 소수 3자리여서 끝의 0을 덧붙여도 값이 달라지지 않는다.
- `capacity_w`는 `capacity_kw × 1000`의 **정수 W**다. 합계 **42,655,370W**. 용량 합계·경계 비교는 이 열을 쓰면 이진 소수 오차를 피할 수 있다.
- 임의 반올림/절사나 epsilon 여유를 두지 않는다. 정확한 정수 W 비교이며 허용 오차는 **0W**다. 원본보다 정밀한 잘못된 값은 조용히 반올림하지 말고 기준표 불일치로 보고한다. 수신 코드에서는 Decimal/정수 파싱을 사용한다.
- 기존 팀/README 기준인 그룹별 최소 20MW를 검사할 때는 `sum(capacity_w) >= 20,000,000`으로 비교한다. 이 수치는 기존 규정 참조이며 이번 데이터 전달이 공식 규정 승인까지 대신하지 않는다.
- `current_group_reference`는 원본 참조 그룹이다. 최종 최적화 배정이나 PM 승인 배정을 뜻하지 않는다.

## 시간·단위·시장값

- 표준 시간대는 `Asia/Seoul`이다. CSV/JSON의 권장 전송 형식은 `2025-06-01T01:00:00+09:00`. UTC도 같은 순간으로 변환해서 확인할 수 있으나 시간대 없는 값과 비정시 값은 거부한다. 단순히 UTC 값에 KST 이름만 붙이지 않는다.
- `ts`는 `(ts-1시간, ts]`의 끝이다. 대상일 D의 24시간은 D 01시~D+1 00시이며, 자정은 전날 마지막 구간이다. 예측 기준은 D-1 17시 KST다.
- 공식 평가 시간축은 2025-06-01 01시~2026-06-01 00시, 8,760시간이다. 전체 입력 기대 조합은 **253×8,760 = 2,216,280개**다. 이 개수 확인은 구조 기준이며 실제 모델 성능 검증이 아니다.
- `actual/prediction/residual`은 시간 구간당 **kWh**, 용량은 **kW**, SMP는 **원/kWh**, 정산 결과는 **원**이다. 1시간 자료에 불필요한 1,000배 변환이나 시간 계수를 곱하지 않는다.
- 평가 `smp.csv`는 `ts,smp,k`, 학습 `train/smp.csv`는 `ts,smp`다. 학습 정산에서 k가 필요하면 **명시적으로** KST 구간 끝 `ts.hour`가 11~15이면 3, 나머지 1로 생성한다. 평가 k는 원본 값을 보존하고 시간 규칙과 대조한다. 이는 README 근거 기준이며 공식 정산 승인은 별도다.
- 0원 SMP는 정상값이다. 누락/NaN/Inf나 음수 값이 들어오면 임의 clamp·0 채움·행 삭제를 하지 않고 점검 대상으로 보고한다. 영우님 현재 정산기가 지원하지 않는 음수 actual/prediction은 실패를 드러내고 정책 검토한다. 공식 실격 규칙을 임의로 확정하지 않는다.

## Split·Feature·Leakage 인수 체크

1. 계약의 원본 SHA256, split/feature/round 정책 버전 및 각 파일 hash가 실제 artifact metadata와 같은지 확인한다.
2. fold별 학습 시작·cutoff 이전 데이터로만 모델·전처리·학습 통계를 만든다. 기존 cutoff는 발행일 00시라는 보수적 설계이며 실제 수신 지연 확인을 대신하지 않는다.
3. 발전량 lag는 제외한다. 예보·설비·달력으로 시작하고 학습 구간만의 고정 발전소 통계는 허용한다. 검증/평가 정답으로 해당 fold 통계를 갱신하지 않는다.
4. 17시 결측은 같은 제공사/관측소/대상 시각/변수의 10시로 대체하고 원래 결측/대체 표시를 보존한다. 향후 양 회차 실험은 대칭 규칙이다. 두 회차 동시 결측 처리의 세부법은 미합의다.
5. 7월은 고정224개소의 발전소 지표만 비교한다. 총36,300.895kW여서 2×20MW 조건을 만족할 수 없다. 10월252개소도 전체253개소와 다른 집합임을 표시한다. 여름 잔차를 253개소로 0 채움하지 않는다.
6. DEV_JAN/DEV_FEB는 253개소 구간이다. VPP 선택에는 선택 시점 전에 가용한 과거 out-of-time 잔차만 사용한다. 같은 fold의 정답으로 배정을 최적화하고 그 fold 수익을 미사용 검증으로 보고하지 않는다.
7. 2025년3~5월 HOLDOUT은 마지막 평가용이다. 그 정답/잔차로 모델·feature·그룹을 선택하지 않는다.
8. `residual = actual_kwh - prediction_kwh`. 양수는 과소예측, 음수는 과대예측이다. 정산은 발전소 값을 VPP/시각별로 먼저 합산하고 절대오차를 적용한다.
9. 평가 기간의 실제 발전량/잔차는 제공되지 않는다. Prediction-only 파일에 actual/residual을 합성하거나 0으로 채우지 않는다. 실제 정산이 불가능하면 `SKIPPED_NO_ACTUALS` 등으로 구분한다.
10. Forecast/OOF는 모델·fold·site_id·ts로 식별하고 누락/중복/추가 키, 시간 정렬, metadata 일치를 검사한다. 기존 출력 열 계약은 아직 `forecast_output_proposal`이며 상재님/영우님 양쪽의 실제 열 매핑 확인이 남아 있다.

## 지금 확인하는 명령

상위 폴더(README_FIRST.md가 있는 폴더)에서 실행한다. 아래는 Python 표준 라이브러리만 사용한다.

```text
python verify_handoff.py
python tools/verify_vpp_data_basis.py --source "원본 ZIP의 절대경로"
```

첫 명령은 배포본/계약의 일치, 두 번째 명령은 원본의 253개 용량 및 평가 시간축/k와 직접 대조한다. 원본 없이도 두 번째 명령에서 `--source`를 생략해 기준표와 경계 규칙을 확인할 수 있다. 결과 `failed=0`은 수아 측 검사이며 영우님 코드의 PASS가 아니다.

## 공유 상태와 다음 행동

수아 측 데이터 기준 파일은 이번 v3 전달로 준비됐다. **영우님 수신 확인은 아직 없음**. 영우님이 수신·검사한 뒤 `WAITING_FOR_DATA_CONTRACT`를 해소했는지 판단한다.

실제 Forecast/OOF와 모델 버전·SHA256·학습 범위·cutoff 근거는 상재님 산출물이며 이번 묶음에는 없다. 현재 실제 OOF 검증은 `WAITING_FOR_FORECAST_OOF`다. 두 입력을 모두 수신하고 확인한 뒤에만 `READY_FOR_REAL_OOF_VALIDATION`으로 기록한다.

| 미결 | 담당 | 현재 상태/공유 시점 |
|---|---|---|
| D04 실제 수신 지연·공식 cutoff 해석 | PM/수아/상재 | 수신 로그·정본 확인 대기, 확약된 완료 시점 없음 |
| D05 공식 정산·반올림·음수 정책 | PM/영우 | 공식 정본 대조/승인 대기, 확약된 완료 시점 없음 |
| D06 실제 출력 열 매핑·수신자 실행 | 상재/영우/수아 | 실제 Forecast/OOF 제공 후 확인, 제공 시각 미확정 |
| 두 회차 동시 결측 시 구체 대체 | 수아/상재 | 현재 점검 범위0건, 발생 시 명시적 처리 합의 필요 |

공식 점수·실제 Revenue 개선·공식 제출은 여전히 HOLD다. 406 PASS와 253×8,760 합성 입력 구조 검증은 영우님 측 보고이며 이 자료의 검사 결과와 합산하지 않는다.

공유 원본 위치: Redmine #1123 첨부 v3, GitHub PR #191. 모델/잔차 실데이터가 생기면 파일별 SHA256과 `integration_contract.json`의 metadata 항목을 함께 전달한다.
