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 DRAFT  
**Date:** 2026-08-07  
**Owner:** Data Architecture & Compliance  
**Status:** ⚠️ DRAFT (Source Unknown — See Issues Below)

---

## ⚠️ 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 — Blocking Full Specification**

1. **Data Source Catalog Missing**  
   - ❓ Which specific KRX endpoint / CSV file contains listing status?  
   - ❓ Is there a 3rd-party data aggregator (Bloomberg, FactSet)?  
   - ❓ Is CSV manual upload acceptable for v1.0, or must we have automated ingest?  
   - **Status:** Not found in `source-catalog.md` — requires data governance review

2. **Refresh Frequency & SLA**  
   - ❓ Daily update sufficient, or intraday?  
   - ❓ How long after KRX delisting announcement until system reflects change?  
   - **Status:** No SLA documented in CLAUDE.md

3. **Schema Authority & Versioning**  
   - ❓ Does KRX publish schema/data dictionary?  
   - ❓ If schema changes (new trading restriction type), how do we version?  
   - **Status:** Deferred to data contract review

4. **Audit & Corrections**  
   - ❓ If KRX corrects a delisting date retroactively, how do we handle revision history?  
   - ❓ Do we notify downstream (shadow runs, sell decisions) of corrections?  
   - **Status:** Assumed append-only, no updates; confirm with risk team

---

## 🛡️ 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)