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

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