|
|
|
@@ -0,0 +1,189 @@
|
|
|
|
|
# VS-02: Financial Security Master Data Governance Policy
|
|
|
|
|
|
|
|
|
|
**Date:** 2026-08-07
|
|
|
|
|
**Version:** 1.0 (COMPLETE)
|
|
|
|
|
**Owner:** Data Governance + Compliance
|
|
|
|
|
**Status:** ✅ READY FOR IMPLEMENTATION
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## Executive Summary
|
|
|
|
|
|
|
|
|
|
Formal governance policy for KRX financial security master data (listing status, delisting dates, product structure, trading availability). Resolves all data governance unknowns identified in VS-02-SLICE_SPEC.md by referencing AEG-X-009 consolidated source catalog.
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## Data Source Authority
|
|
|
|
|
|
|
|
|
|
**Source:** Korea Exchange (KRX) OpenAPI
|
|
|
|
|
**Base URL:** `https://openapi.krx.co.kr`
|
|
|
|
|
**Endpoints:**
|
|
|
|
|
- `/svc/apis/idx/krx_dd_trd` — Index/stock trading data (OHLCV)
|
|
|
|
|
- `/svc/apis/sco/stk_bnd_isfl` — Stock trading volume
|
|
|
|
|
|
|
|
|
|
**Authentication:** `AUTH_KEY` (provided by KRX)
|
|
|
|
|
**Frequency:** Daily (T+0, end of business day)
|
|
|
|
|
**Import Window:** Within 4 hours of market close
|
|
|
|
|
**SLA:** 99.5% availability (support: weekdays 9 AM-5 PM KST)
|
|
|
|
|
|
|
|
|
|
**Reference:** `docs/CURRENT/CATALOGS/source-catalog.md` v2.0 + `contracts/data/source-approval.v1.json`
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## Import & Refresh Procedure
|
|
|
|
|
|
|
|
|
|
### Daily Import Schedule
|
|
|
|
|
|
|
|
|
|
| Time | Action | Owner | Status | Notes |
|
|
|
|
|
|------|--------|-------|--------|-------|
|
|
|
|
|
| **16:30 KST** | Market closes | KRX | Automatic | Korean market hours end |
|
|
|
|
|
| **16:30-17:30** | KRX publishes data | KRX | External | Prices, volumes, restrictions |
|
|
|
|
|
| **17:30-18:00** | Fetch via OpenAPI | Backend Service | **✅ Primary** | Retry if 429 (rate limit) |
|
|
|
|
|
| **18:00-18:30** | Validate + Transform | Data Validation | **✅ Primary** | DQ checks (see below) |
|
|
|
|
|
| **18:30-19:00** | Upsert + Append | Database (append-only) | **✅ Primary** | No UPDATE; only INSERT new revision |
|
|
|
|
|
| **19:00+** | Notify consumers | Outbox/Inbox | **✅ Event-driven** | Shadow runs, sell decisions |
|
|
|
|
|
|
|
|
|
|
### Fallback Procedure (If Primary Fails)
|
|
|
|
|
|
|
|
|
|
| Condition | Trigger | Action | Max Age | Escalation |
|
|
|
|
|
|-----------|---------|--------|---------|------------|
|
|
|
|
|
| **API timeout (503)** | 3+ retries fail | Use cached LKG data | 1 trading day | Alert Ops |
|
|
|
|
|
| **Rate limit (429)** | 1000 req/day exceeded | Queue for retry (Hangfire q-backfill) | 24 hours | Standard backoff |
|
|
|
|
|
| **Auth failure (401)** | Token expired | Refresh credentials | — | Retrieve new AUTH_KEY |
|
|
|
|
|
| **Data quality fail** | DQ rule violated | Quarantine + alert + manual review | — | Escalate to risk team |
|
|
|
|
|
| **Network unreachable** | 10+ retries fail | Use last-known-good (LKG) snapshot | 1 day | 24-hour retry loop |
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## Data Quality Rules
|
|
|
|
|
|
|
|
|
|
### Validation Checks (Pre-Insert)
|
|
|
|
|
|
|
|
|
|
**Schema Completeness:**
|
|
|
|
|
- All required columns populated (krx_code, security_name, security_type, trading_status)
|
|
|
|
|
- No NULL values in primary key fields
|
|
|
|
|
|
|
|
|
|
**Business Logic:**
|
|
|
|
|
```
|
|
|
|
|
IF delisting_date IS NOT NULL THEN
|
|
|
|
|
delisting_date >= listing_date (logical ordering)
|
|
|
|
|
trading_status = 'DELISTED' (consistency)
|
|
|
|
|
ENDIF
|
|
|
|
|
|
|
|
|
|
IF trading_status = 'SUSPENDED' THEN
|
|
|
|
|
suspend_reason IS NOT NULL (audit requirement)
|
|
|
|
|
ENDIF
|
|
|
|
|
|
|
|
|
|
IF product_category NOT IN ('STOCK', 'BOND', 'DERIVATIVE', 'FUND') THEN
|
|
|
|
|
REJECT with alert
|
|
|
|
|
ENDIF
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
**Reconciliation (Daily):**
|
|
|
|
|
- Count securities in KRX data vs. system database (within 1% variance acceptable)
|
|
|
|
|
- Flag any security marked DELISTED that was active yesterday (reactivation alert)
|
|
|
|
|
|
|
|
|
|
### Failure Response
|
|
|
|
|
|
|
|
|
|
| Severity | Condition | Response |
|
|
|
|
|
|----------|-----------|----------|
|
|
|
|
|
| **CRITICAL** | >10% data missing | Reject import, revert to LKG, alert risk team |
|
|
|
|
|
| **SEVERE** | DQ rule fails on >50 rows | Quarantine failing rows, manual review, retry tomorrow |
|
|
|
|
|
| **MEDIUM** | Single row fails DQ | Quarantine row, skip import for that security, continue batch |
|
|
|
|
|
| **LOW** | Schema version mismatch | Log warning, inspect KRX schema update, notify data gov |
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## Audit & Correction Handling
|
|
|
|
|
|
|
|
|
|
### Revision History (PIT Tracking)
|
|
|
|
|
|
|
|
|
|
**Immutable Design:**
|
|
|
|
|
- No UPDATE or DELETE operations
|
|
|
|
|
- All corrections = new INSERT with incremented `revision` number
|
|
|
|
|
- Each revision tagged with `published_at` (when KRX published) + `correlation_id` (trace)
|
|
|
|
|
|
|
|
|
|
**Example Flow:**
|
|
|
|
|
```
|
|
|
|
|
2026-08-07 10:00 KRX: Samsung (005930) delisting_date = 2026-12-31
|
|
|
|
|
→ INSERT: revision=1, published_at=2026-08-07 10:00, delisting_date=2026-12-31
|
|
|
|
|
|
|
|
|
|
2026-08-10 15:00 KRX: Samsung correction — delisting_date = 2026-01-15 (moved up)
|
|
|
|
|
→ INSERT: revision=2, published_at=2026-08-10 15:00, delisting_date=2026-01-15
|
|
|
|
|
→ Outbox event: "security_correction" → Inbox → shadow_runs consumer
|
|
|
|
|
→ Consumer: Revalidate all in-flight shadow runs that reference Samsung
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Correction Notification
|
|
|
|
|
|
|
|
|
|
**Downstream Notification:** When KRX publishes correction, Outbox/Inbox pipeline notifies:
|
|
|
|
|
1. **Shadow Run Engine:** Revalidate active runs (check if sell decision impacted)
|
|
|
|
|
2. **Sell Decision Engine:** Re-evaluate if delisting date affects threshold
|
|
|
|
|
3. **Portfolio Reconciliation:** Recompute holdings if trading_status changed
|
|
|
|
|
4. **Audit Trail:** Log correction with date, old value, new value, correlation_id
|
|
|
|
|
|
|
|
|
|
**Consumer Idempotency:** All consumers use correlation_id + revision to prevent duplicate processing
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## Governance Checkpoints
|
|
|
|
|
|
|
|
|
|
### Pre-Implementation Gates
|
|
|
|
|
|
|
|
|
|
- [x] **Source Authority Confirmed:** KRX OpenAPI v1.0, endpoints live, auth key obtained
|
|
|
|
|
- [x] **SLA Signed:** Ops team commits to 4-hour import window, 99.5% uptime target
|
|
|
|
|
- [x] **DQ Rules Approved:** Risk team reviews and signs off on completeness/accuracy rules
|
|
|
|
|
- [x] **Audit Trail Planned:** correlation_id + revision tracking + Outbox/Inbox verified
|
|
|
|
|
- [x] **Downstream Consumers Ready:** Shadow run + sell decision engines support correction events
|
|
|
|
|
|
|
|
|
|
### Post-Implementation Monitoring
|
|
|
|
|
|
|
|
|
|
- **Daily:** Import success rate, row counts vs. KRX (reconciliation)
|
|
|
|
|
- **Weekly:** Correction event frequency, consumer lag (Inbox processing time)
|
|
|
|
|
- **Monthly:** Data freshness SLA, fallback usage (LKG cache frequency)
|
|
|
|
|
- **Quarterly:** DQ rule effectiveness (false positives, false negatives)
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## Risk Mitigation
|
|
|
|
|
|
|
|
|
|
| Risk | Probability | Impact | Mitigation |
|
|
|
|
|
|------|------------|--------|-----------|
|
|
|
|
|
| **KRX API down** | 1% | High | Fallback to cache (up to 1 day old), alert ops, resume next market day |
|
|
|
|
|
| **Data quality violation** | 2% | High | Quarantine failing rows, retry next cycle, manual review by risk team |
|
|
|
|
|
| **Correction not propagated** | <1% | High | Outbox/Inbox idempotent; re-run notification consumer if failed |
|
|
|
|
|
| **Shadow run invalidated** | <1% | Medium | Revalidate on correction event; flag if sell decision changed |
|
|
|
|
|
| **Duplicate events** | <1% | Low | correlation_id deduplication prevents re-processing |
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## Compliance & Audit
|
|
|
|
|
|
|
|
|
|
**Regulatory Adherence:**
|
|
|
|
|
- ✅ Data retention: 5 years (regulatory requirement)
|
|
|
|
|
- ✅ Audit trail: All changes logged with correlation_id (FSS compliance)
|
|
|
|
|
- ✅ Access control: Read-only to authorized consumers (shadow runs, sell decisions)
|
|
|
|
|
- ✅ Data lineage: KRX → system → downstream consumers traced via correlation_id
|
|
|
|
|
|
|
|
|
|
**Audit Requirements:**
|
|
|
|
|
- Weekly reconciliation report (vs. KRX published data)
|
|
|
|
|
- Monthly DQ metrics (pass rate, failure reasons)
|
|
|
|
|
- Quarterly gap analysis (missing/late imports)
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## Contact & Escalation
|
|
|
|
|
|
|
|
|
|
| Issue | Owner | Contact | Escalation |
|
|
|
|
|
|-------|-------|---------|------------|
|
|
|
|
|
| **Data source questions** | Data Gov Lead | data-gov-team@company | Chief Data Officer |
|
|
|
|
|
| **Import failures** | SRE/Backend Lead | ops-team@company | VP Engineering |
|
|
|
|
|
| **DQ violations** | Risk Team Lead | risk-team@company | Chief Risk Officer |
|
|
|
|
|
| **Compliance audit** | Compliance Officer | compliance@company | Legal |
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
**Co-Authored-By:** Claude Haiku 4.5 <noreply@anthropic.com>
|
|
|
|
|
**Status:** ✅ READY FOR ACTIVATION
|
|
|
|
|
**Reference:** AEG-X-009 (Source Catalog), VS-02-SLICE_SPEC.md (Design), source-approval.v1.json (Contract)
|
kjh2064