"""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
]

# Required columns for portfolio (position) parquet files.
# A position is a tradable integer holding derived from a target weight under
# A-share lot/board rules. Produced by the `portfolio build` phase.
POSITION_COLUMNS: Final[list[str]] = [
    "symbol_id",        # str
    "date",             # date
    "portfolio_name",   # str: identifies this construction run
    "target_weight",    # float64: w = alpha / sum(|alpha|); signed, sum(|w|)=1
    "target_value",     # float64: v_target = booksize * w (signed dollar exposure)
    "target_shares",    # float64: q_target = v_target / price (continuous, signed)
    "position_shares",  # int64: discretized + repaired integer shares (signed)
    "position_value",   # float64: position_shares * price (signed)
    "price",            # float64: construction price (close by default)
]

# Required columns for execution-simulator fill parquet files.
FILL_COLUMNS: Final[list[str]] = [
    "symbol_id",        # str
    "date",             # date: the EXECUTION date (open[t+1] of the target date)
    "portfolio_name",   # str
    "prev_shares",      # int64: realized position carried in
    "target_shares",    # int64: requested target for this execution
    "traded_shares",    # int64: signed delta actually executed
    "realized_shares",  # int64: resulting position (blocked trades revert to prev)
    "blocked",          # int: 1 if the trade was (fully or partially) blocked
    "trade_cost",       # float64: commission + slippage in yuan
]

# Required columns for execution-simulator per-day PnL parquet files.
PNL_COLUMNS: Final[list[str]] = [
    "date",             # date
    "portfolio_name",   # str
    "gross_exposure",   # float64: sum(|position_value|)
    "net_exposure",     # float64: sum(signed position_value)
    "pnl",              # float64: daily mark-to-market PnL (yuan), net of cost
    "cost",             # float64: total trade cost that day (yuan)
    "turnover",         # float64: sum(|traded_value|) / booksize
    "n_positions",      # int: count of nonzero holdings
]