68 lines
3.1 KiB
Markdown
68 lines
3.1 KiB
Markdown
# 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에 저장하지 않는다.
|