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에 저장하지 않는다.

3.1 KiB Raw Blame History