02-data-models

🏛️ DATA MODELING — GOBERNANZA FINOS CDM v3.0

PRINCIPIO FUNDAMENTAL

Todo dato que cruce una frontera de fase DEBE ser:

1. Pydantic BaseModel con model_config = ConfigDict(frozen=True)
2. Validado al construirse (Pydantic v2 lo hace automático)
3. Con data_lineage: DataLineage obligatorio — NUNCA opcional
4. Con exchange_timestamp en UTC timezone-aware

Un MarketSnapshot sin linaje es un "dato huérfano" → rechazado por cualquier motor Fase B/C.

PATRÓN BASE — MarketSnapshot

from pydantic import BaseModel, ConfigDict, Field, field_validator
from decimal import Decimal
from datetime import datetime

class DataLineage(BaseModel):
    model_config = ConfigDict(frozen=True)
    source: str                          # "fmp" | "massive" | "local"
    ingestion_latency_ms: int = Field(ge=0)
    raw_field_count: int = Field(ge=0)

class MarketSnapshot(BaseModel):
    model_config = ConfigDict(frozen=True)
    ticker: str
    exchange: str
    price: Decimal = Field(ge=Decimal("0"))  # ← Decimal, nunca float
    volume: int = Field(ge=0)
    exchange_timestamp: datetime             # ← debe ser UTC aware
    data_lineage: DataLineage                # ← JAMÁS Optional

    @field_validator("ticker")
    @classmethod
    def ticker_uppercase(cls, v: str) -> str:
        return v.upper().strip()

    @field_validator("exchange_timestamp")
    @classmethod
    def must_be_utc(cls, v: datetime) -> datetime:
        if v.tzinfo is None:
            raise ValueError("exchange_timestamp debe ser UTC aware")
        return v

MODELOS DERIVADOS — Herencia correcta

# ✅ CORRECTO — extiende sin debilitar el contrato
class EnrichedSnapshot(MarketSnapshot):
    vpin_score: float
    ofi_score: float
    # frozen=True heredado automáticamente

# ❌ PROHIBIDO — debilita el tipo de precio
class BadSnapshot(MarketSnapshot):
    price: float           # Tipo más débil → RECHAZAR

# ❌ PROHIBIDO — hace el linaje opcional
class IncompleteSnapshot(MarketSnapshot):
    data_lineage: DataLineage | None = None  # RECHAZAR