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

-- 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)