# KBX v21 External Data Governance

## 1. 목적

외부 Provider 응답을 화면이 직접 소비하지 않고 `Provider Adapter → Normalizer → Canonical Projection → Provenance` 경계를 통과시킨다. 외부 데이터는 읽기 입력이며 OMS/WMS/ERP Transaction의 Domain Truth가 아니다.

## 2. 시간 의미

- `providerObservedAt`: Provider가 명시한 데이터 기준시각. 제공되지 않으면 `null`로 둔다.
- `requestedAt`: KBX가 Provider 호출을 시작한 시각.
- `receivedAt`: 응답을 KBX가 수신한 시각.
- `ingestedAt`: 정상화 후 KBX cache에 기록한 시각.
- `freshUntil`: KBX 운영정책상 fresh로 표현 가능한 시각.
- `usableUntil`: stale-while-revalidate 정책에서 마지막 정상값을 명시적으로 사용할 수 있는 최종 시각.

`providerObservedAt`이 없다고 `receivedAt`을 시장/공시 기준시각으로 이름을 바꾸지 않는다.

## 3. Freshness Mode

### strict

만료된 값을 최신값으로 사용하지 않는다. v21 Reference에서는 KIS 현재가가 이 정책을 사용한다.

### stale-while-revalidate

Fresh 기간이 지나도 `usableUntil` 안에서는 마지막 정상값을 **Stale임을 명시하여** 보여줄 수 있고 Background Refresh를 예약한다. OPENDART 회사개황/공시목록 Reference가 이 정책을 사용한다.

### provider-defined

공급자의 승인 서비스마다 의미가 달라 범용 TTL을 설정하지 않는다. KRX 승인서비스 template이 여기에 해당하며 서비스별 Definition 없이 Runtime 사용을 거부한다.

위 Freshness 숫자는 KBX 운영정책이며 공급자의 공식 Rate Limit 또는 데이터 보장주기를 의미하지 않는다.

## 4. 재현성

기본적으로 raw Provider payload를 DB에 저장하지 않는다. 대신 다음을 남긴다.

- canonical `request_descriptor` — Secret을 제외한 재현 가능한 조회조건
- `payload_sha256`
- `normalizer_version`
- received/ingested timestamps
- correlation id
- normalized projection

Raw payload 저장이 필요하면 라이선스·보안·보존정책을 별도로 승인하고 `encrypted-raw` 정책으로 명시해야 한다.

## 5. Normalization

공통 Normalizer가 Provider-specific field를 business screen까지 전달하지 않는다.

- OPENDART 회사개황 → `KbxCompanyProfileSnapshot`
- OPENDART 공시목록 → `KbxDisclosureSummarySnapshot`
- KIS 현재가 → `KbxMarketPriceSnapshot`
- KRX → 승인된 서비스별 `IKrxApprovedServiceNormalizer`

KRX는 서비스 명세 없이 universal field mapping을 추정하지 않는다.

## 6. UI

`KbxDataProvenance`는 Source, Fresh/Stale/Expired, 기준/수신/정규화 시각, normalizer version, payload hash를 표현한다. 일반 업무 화면에서는 compact 형태를 사용하고 상세 운영 화면에서 전체 provenance를 확인한다.

## 7. 실패 처리

- Provider failure를 Domain failure로 바꾸지 않는다.
- strict dataset은 expired cache fallback을 금지한다.
- stale-while-revalidate는 stale 표시와 background refresh를 함께 사용한다.
- Secret은 request descriptor, telemetry, audit diff, UI에 저장하지 않는다.