"""Column contracts for pipeline parquet files."""

from typing import Final

# Required columns for data parquet files (daily bars, alternative data, etc.)
DATA_COLUMNS: Final[list[str]] = [
    "symbol_id",     # str: internal code like 'sh600000'
    "symbol_name",   # str: stock name like '浦发银行'
    "date",          # date
    "open",          # float64
    "high",          # float64
    "low",           # float64
    "close",         # float64
    "preclose",      # float64: previous trading day's close
    "volume",        # float64 (shares)
    "amount",        # float64 (turnover in yuan, raw/unadjusted)
    "vwap",          # float64: daily VWAP = amount / volume. NB raw price scale —
                     #   NOT comparable with adjusted OHLC under qfq/hfq.
    "turn",          # float64: turnover rate (%)
    "pctChg",        # float64: daily % change
    "tradestatus",   # int: 1 = traded, 0 = suspended
    "isST",          # int: 1 = ST/special-treatment, 0 = normal
    "peTTM",         # float64: trailing-12m P/E
    "pbMRQ",         # float64: P/B (most recent quarter)
    "psTTM",         # float64: trailing-12m P/S
    "pcfNcfTTM",     # float64: P/CF (net cash flow, TTM)
]

# Required columns for alpha parquet files.
# Alphas are position WEIGHTS: positive=long, negative=short.
ALPHA_COLUMNS: Final[list[str]] = [
    "symbol_id",   # str: matches DATA_COLUMNS symbol_id
    "date",        # date: aligned with data dates
    "alpha_name",  # str: identifies which alpha (e.g. 'reversal_5d')
    "weight",      # float64: position weight, signed
]

# Required columns for combo parquet files.
COMBO_COLUMNS: Final[list[str]] = [
    "symbol_id",   # str
    "date",        # date
    "combo_name",  # str: identifies which combo (e.g. 'equal_weight')
    "weight",      # float64: combined weight, signed
]