"""Auditable catalog for multi-factor trading-strategy inputs.

The catalog is descriptive only.  Factor values remain computed by the
no-lookahead validation and runtime overlay modules.
"""

from __future__ import annotations

from typing import Any


_GROUPS = {
    "oldwang": "老王趨勢與守線",
    "volume": "量價行為",
    "candle": "K 線與影線",
    "institutional": "法人籌碼",
    "chip": "籌碼與風險",
    "technical": "技術指標",
    "momentum": "中長線動能",
    "pattern": "組合型交易策略",
    "regime": "市場環境",
}


def _entry(group: str, zh_name: str, strategy: str) -> dict[str, str]:
    return {"group": group, "group_zh": _GROUPS[group], "zh_name": zh_name, "strategy": strategy}


FACTOR_STRATEGIES: dict[str, dict[str, str]] = {
    "oldwang_trend": _entry("oldwang", "三陽開泰 / 三聲無奈", "連續多空 K 線與均線方向形成趨勢加減分。"),
    "oldwang_trend_reversal_pressure": _entry("oldwang", "老王趨勢反向壓力實驗", "研究用：驗證連續趨勢訊號在高波動資料中是否更像短線反轉壓力。"),
    "oldwang_guard": _entry("oldwang", "MA5、投信 10MA、外資 20MA 守線", "守住支撐加分，跌破法人相關支撐扣分。"),
    "oldwang_guard_support": _entry("oldwang", "老王守線支撐", "只計算 MA5、投信 10MA、外資 20MA 守住的支撐分數。"),
    "oldwang_guard_lowbase_support": _entry("oldwang", "低基期守線支撐實驗", "研究用：只在非高基期時把守住 MA5/10MA/20MA 視為支撐。"),
    "oldwang_guard_highbase_risk": _entry("oldwang", "高基期守線追高風險實驗", "研究用：高基期仍守線時不追價，視為短線過熱風險。"),
    "oldwang_guard_break_risk": _entry("oldwang", "老王守線跌破風險", "只計算投信 10MA、外資 20MA 跌破的風險分數。"),
    "oldwang_volume": _entry("oldwang", "爆大量高低點突破", "爆量後突破前高加分，跌破低點扣分。"),
    "intraday_60k_volume_low_guard": _entry("volume", "60K 爆量低點守住", "Yahoo 60 分 K 爆量低點守住時加分；無資料保持中性。"),
    "intraday_60k_fresh_low_guard": _entry("volume", "新鮮 60K 爆量低點守住實驗", "研究用：僅在爆量低點事件新鮮且非高基期時加分。"),
    "intraday_60k_stale_guard_risk": _entry("volume", "陳舊/高基期 60K 守線風險實驗", "研究用：守線訊號陳舊或處在高基期時改視為追高風險。"),
    "intraday_60k_volume_low_break": _entry("volume", "60K 爆量低點跌破", "Yahoo 60 分 K 爆量低點跌破時扣分；無資料保持中性。"),
    "big_player_buy": _entry("chip", "大戶買進金額強度", "僅使用券商或外部匯入買進金額；缺資料不可由成交量推估。"),
    "big_player_sell": _entry("chip", "大戶賣出金額強度", "僅使用券商或外部匯入賣出金額；缺資料不可由成交量推估。"),
    "volume_expansion": _entry("volume", "交易量放大", "量能高於近期基準時依方向調整。"),
    "volume_spike": _entry("volume", "爆大量", "近期量能 z-score 明顯升高時標記。"),
    "volume_surge": _entry("volume", "量能趨勢", "相對量能強弱作為確認訊號。"),
    "volume_contraction_after_spike": _entry("volume", "爆量後量縮", "爆量後健康量縮加分，低檔失敗量縮扣分。"),
    "candle_shadow": _entry("candle", "上下影線淨訊號", "長下影偏支撐，長上影偏壓力。"),
    "candle_lower_support": _entry("candle", "下影線支撐拆分", "只計算下影線與陰高炮守低支撐，不混入上影線壓力。"),
    "candle_upper_pressure": _entry("candle", "上影線壓力拆分", "只計算上影線賣壓。"),
    "yin_gao_pao_support": _entry("candle", "陰高炮支撐拆分", "陰高炮型態與守低確認作為支撐訊號。"),
    "yin_gao_pao_risk": _entry("candle", "陰高炮失敗風險", "陰高炮跌破失敗時作為風險訊號。"),
    "upper_shadow": _entry("candle", "長上影線", "上檔賣壓風險。"),
    "lower_shadow": _entry("candle", "長下影線 / 陰高炮守低", "下檔支撐與陰高炮守低確認。"),
    "bullish_upper_shadow": _entry("candle", "紅棒收長上影", "上漲過程出現上影線時視為壓力。"),
    "high_base": _entry("candle", "高基期", "接近 120 日高點且短期漲幅偏高時降低追價權重。"),
    "high_volume_upper_shadow": _entry("candle", "高檔爆大量長上影", "高基期、爆量、長上影共同出現時作為短線風險。"),
    "short_term_battle": _entry("candle", "短線多空交戰", "小實體搭配長上影時標記短線拉扯風險。"),
    "foreign_flow": _entry("institutional", "外資買賣超", "外資相對成交量方向。"),
    "trust_flow": _entry("institutional", "投信買賣超", "投信相對成交量方向。"),
    "dealer_flow": _entry("institutional", "自營商買賣超", "自營商相對成交量方向。"),
    "institutional_flow": _entry("institutional", "三大法人合計買賣超", "法人一致性、連續性與 20 日 z-score。"),
    "chip_score": _entry("chip", "籌碼集中度", "已有籌碼分數；缺資料保持中性。"),
    "margin_risk": _entry("chip", "融資融券風險", "融資、融券與買進壓力的風險調整。"),
    "short_pressure": _entry("chip", "借券與放空壓力", "借券餘額與融券比率提高時扣分。"),
    "macd_momentum": _entry("technical", "MACD 動能", "MACD 柱體與零軸狀態。"),
    "macd_reversal_pressure": _entry("technical", "MACD 追高反轉壓力實驗", "研究用：驗證 MACD 強勢在短線標籤下是否應視為反轉壓力。"),
    "rsi_trend": _entry("technical", "RSI 趨勢", "RSI 中短期趨勢方向。"),
    "rsi_trend_reversal": _entry("technical", "RSI 趨勢反向實驗", "研究用：驗證 RSI 趨勢高低是否更適合均值回歸式解讀。"),
    "rsi_reversal": _entry("technical", "RSI 反轉", "超買超賣反轉傾向。"),
    "bb_reversion": _entry("technical", "布林通道均值回歸", "價格靠近上下通道時評估回歸。"),
    "ma_alignment": _entry("technical", "均線排列", "多頭與空頭均線排列。"),
    "momentum_20d": _entry("momentum", "20 日動能", "短中期報酬方向。"),
    "momentum_60d": _entry("momentum", "60 日動能", "中期報酬方向。"),
    "momentum_120d": _entry("momentum", "120 日動能", "長期報酬方向。"),
    "volatility_risk": _entry("chip", "波動風險", "高波動與 ATR 偏高時扣分。"),
    "liquidity_quality": _entry("chip", "流動性品質", "成交流動性品質調整。"),
    "bt_yi_yin_ya_breakout": _entry("pattern", "一陰壓突破", "近期大黑棒壓力被紅棒突破時加分，失敗跌破時扣分。"),
    "bt_yi_yin_ya_breakout_risk": _entry("pattern", "一陰壓突破追價風險實驗", "研究用：驗證突破訊號在短線標籤下是否更像追價風險。"),
    "bt_yi_yang_ding_breakdown": _entry("pattern", "一陽頂跌破", "跌破近期大紅棒支撐時扣分。"),
    "bt_shadow_cluster_support_resistance": _entry("pattern", "影線群支撐壓力", "突破上影壓力或守住下影支撐加分，跌破支撐扣分。"),
    "bt_yang_gao_pao": _entry("pattern", "陽高炮", "接近最高收盤的強勢紅棒作為延續訊號。"),
    "bt_yang_gao_pao_risk": _entry("pattern", "陽高炮反向風險實驗", "研究用：驗證陽高炮在目前資料中是否更像短線過熱風險。"),
    "bt_bull_engulf": _entry("pattern", "多方吞噬組合", "紅棒吞噬或接近吞噬前一黑棒時加分。"),
    "bt_bull_engulf_risk": _entry("pattern", "多方吞噬反向風險實驗", "研究用：驗證多方吞噬在目前資料中是否存在追高風險。"),
    "bt_bull_engulf_bear": _entry("pattern", "多方後空方吞噬風險", "連續紅棒後被黑棒吞噬時扣分。"),
    "tej_lstm_trend_signal": _entry("regime", "趨勢代理訊號", "以均線、RSI、KD、MACD 與動能近似趨勢狀態。"),
    "tej_lstm_chop_filter": _entry("regime", "盤整過濾代理", "趨勢持續度與震盪懲罰共同形成 regime filter。"),
    "tej_macro_risk_proxy": _entry("regime", "總體風險代理", "大盤、費半、匯率、利率與 VIX 共同形成市場環境分數。"),
    "tej_macro_risk_contrarian": _entry("regime", "總體環境反向實驗", "研究用：驗證總體順風在短線標籤下是否造成追高風險。"),
}


def catalog_rows(factor_names: list[str]) -> list[dict[str, Any]]:
    """Return stable report rows for selected factors."""
    rows = []
    for name in factor_names:
        item = FACTOR_STRATEGIES.get(name, _entry("technical", name, "尚未登錄策略說明。"))
        rows.append({"factor": name, **item})
    return rows