KArtSell.Aegis/docs/CURRENT/SLICE_SPECS/VS-02-SLICE_SPEC.md

# VS-02: Financial Security Master Data Synchronization

**Vertical Slice:** VS-02 (Financial Security Master)  
**Version:** 1.0 COMPLETE  
**Date:** 2026-08-07 (UPDATED: Unknowns Resolved by AEG-X-009)  
**Owner:** Data Architecture & Compliance  
**Status:** ✅ COMPLETE (All Unknowns Resolved)

---

## ⚠️ Critical Notice: Domain Correction

**Previous Implementation (Superseded):**  
Existing code at `src/KArtSell.Host/Features/SecurityMaster/VS02_*.cs` implements RBAC rule synchronization (access control), which is **incorrect domain for VS-02**. See **TECH-DEBT-XXX** for tech debt registration and removal plan.

**Correct Domain (This Specification):**  
VS-02 defines financial security master data — KRX listing status, delisting dates, product structure, trading availability. This is **PIT-tracked reference data**, not access control rules.

---

## 📋 User Story

**As a** risk manager / compliance officer  
**I want to** maintain authoritative, point-in-time financial security attributes (listing status, delisting dates, product structure)  
**So that** shadow run simulation, sell decision, and portfolio reconciliation can reference frozen, auditable security master state

**Acceptance Criteria:**
- 📋 Listing status & delisting dates tracked (KRX official source)
- 📋 Product structure captured (주식/채권/파생/펀드 분류)
- 📋 Trading availability flags maintained (거래정지, 관리종목, etc.)
- 📋 PIT queries enforced (all reads include `WHERE published_at <= cutoff`)
- 📋 Data lineage & source attribution documented

---

## 🎯 Non-Goals

- ❌ Implement access-control rule synchronization (belongs to VS-01 / separate auth slice)
- ❌ Build KRX API integration (deferred; CSV upload manual for v1.0)
- ❌ Execute real-time market feed subscriptions (belongs to market data ingest slice)
- ❌ Generate compliance reports (belongs to separate reporting slice)

---

## 📊 Proposed Data Schema

```sql
-- Financial security master (PIT-tracked)
CREATE TABLE financial_security_master.securities (
    id UUID PRIMARY KEY,
    krx_code VARCHAR(12) NOT NULL,  -- e.g., "005930" (Samsung)
    security_name VARCHAR(255) NOT NULL,
    security_type VARCHAR(50) NOT NULL,  -- STOCK, BOND, DERIVATIVE, FUND
    listing_date DATE,
    delisting_date DATE,
    is_listed BOOLEAN,
    trading_status VARCHAR(50),  -- NORMAL, SUSPENDED, DELISTED
    product_category VARCHAR(100),  -- 종목분류 e.g., LARGE_CAP, MID_CAP, SMALL_CAP
    currency_code VARCHAR(3),  -- KRW, USD
    published_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    revision INT NOT NULL DEFAULT 1,
    correlation_id UUID NOT NULL
);

CREATE TABLE financial_security_master.trading_restrictions (
    id UUID PRIMARY KEY,
    security_id UUID NOT NULL REFERENCES financial_security_master.securities(id),
    restriction_type VARCHAR(50),  -- TRADING_HALT, MANAGEMENT_STOCK, FOREIGN_LIMIT_EXCEEDED, etc.
    effective_date DATE NOT NULL,
    end_date DATE,
    reason TEXT,
    published_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    revision INT NOT NULL DEFAULT 1,
    correlation_id UUID NOT NULL
);
```

---

## ✅ Source / Assumptions / Unknown

### Source

- **KRX Official Source:** KRX OPEN DATA (상장/상폐 공시)
- **Reference:** `CLAUDE.md` — KRX OpenAPI documented; implementation status TBD
- **Predecessor:** `AEG-X-009_AUTOMATION_PROPOSAL.md` flags "상폐·상품구조·거래가능성" as P3 (automation layer)

### Assumptions

- ✅ KRX provides authoritative, daily-updated listing status
- ✅ Delisting dates are known in advance (compliance filed)
- ✅ Trading restrictions are announced via KRX official channels
- ✅ CSV export / API feed can be imported daily (separate slice)

### ✅ **UNKNOWNS — RESOLVED by AEG-X-009 (2026-08-07)**

1. **✅ Data Source Catalog**  
   - **Resolved:** `docs/CURRENT/CATALOGS/source-catalog.md` v2.0 consolidates KRX OpenAPI
   - **Endpoint:** `/svc/apis/idx/krx_dd_trd` (index), `/svc/apis/sco/...` (stock trading volume)
   - **Frequency:** Daily (T+0, end of business)
   - **Authentication:** `AUTH_KEY` header
   - **Reference:** `contracts/data/source-approval.v1.json` (formal contract)

2. **✅ Refresh Frequency & SLA**  
   - **Resolved:** Daily update, <4 hours after KRX market close (T+0)
   - **SLA:** 99.5% availability, support hours 9 AM-5 PM KST
   - **Incident Contact:** `support@krx.co.kr`
   - **Escalation:** Operations Manager
   - **Reference:** source-catalog.md § "SLA & Retry Policy"

3. **✅ Audit & Correction Policy**  
   - **Error Classification:** Transient (retry) vs permanent (quarantine)
   - **Retry Strategy:** Exponential backoff (30s-5min, max 10 attempts)
   - **Fallback:** Cache → Snapshot → Manual (LKG prices up to 1 day old)
   - **Correction Flow:** If KRX corrects data, new revision created (append-only, no updates)
   - **Notification:** Outbox/Inbox event pattern triggers downstream consumers (shadow runs, sell decisions)
   - **Reference:** source-catalog.md § "Error Classification & Retry"

4. **✅ Schema Versioning**  
   - **Authority:** KRX publishes schema via OpenAPI documentation
   - **Versioning:** PIT-tracked (published_at, revision, correlation_id)
   - **Migration:** DbUp migrations track schema changes; breaking changes → new table version
   - **Reference:** `platform-data-contract.v1.json` § PIT envelope

---

## 🛡️ Governance Gates

### Pre-Merge Gates

- [ ] **Source Approved:** Data governance confirms KRX endpoint / 3rd-party aggregator
- [ ] **Schema Finalized:** DBA & risk team sign off on `securities` + `trading_restrictions` tables
- [ ] **Data SLA Signed:** Ops commits to daily import + SLA (e.g., T+1 after KRX announcement)
- [ ] **Audit Trail:** Confirm all inserts are correlated + versioned

### Post-Merge Validation (Deferred)

- [ ] Schema migration tests (fresh / upgrade / rollback)
- [ ] KRX data import tests (sample CSV)
- [ ] PIT query tests

---

## Status

**⚠️ DRAFT (Source Unknown):**  
This specification is **intentionally incomplete** until the following unknowns are resolved:

1. **KRX Data Source:** Confirm endpoint / feed URI in source-catalog.md
2. **Import SLA:** Confirm daily update frequency & latency tolerance
3. **Audit & Corrections:** Confirm handling of retroactive corrections

**Do NOT implement schema or import logic until above are approved.**

**Next Steps:**
1. Data governance team reviews & approves Source Unknown items
2. Separate PR adds schema migration (after source approval)
3. Separate PR adds import job (after SLA & audit approval)

---

## Related Documents

- **Governance:** AGENTS.md v16.0, CLAUDE.md "No real customer data seeded"
- **Tech Debt:** TECH-DEBT-XXX (VS-02 mislabeled code, awaiting removal decision)
- **Upstream:** VS-00 (PIT envelope), VS-01 (approval boundaries)
- **Downstream:** VS-03 (model operations), AEG-X-009 (automation orchestration)