# ============================================================
# 股票筛选条件（★ 可直接修改）
# 对应 plan.md §4/§5 的 MarketFilter / RiskFilter / DividendFilter /
# FinancialQualityFilter。
#
# 所有阈值只允许出现在本文件；代码中不得硬编码。
# 修改后 config_hash 变化，历史 run 仍可完整复现。
# ============================================================
version: 1
name: high_dividend_universe

evaluation:
  # point_in_time —— 每个 asof 日期独立求值（回测必须用这个）
  # latest        —— 仅在最新交易日求值一次
  mode: point_in_time
  asof: latest

# ------------------------------------------------------------
# MarketFilter —— 市场属性
# ------------------------------------------------------------
market:
  # 交易所白名单。需要北交所时加 BSE。
  exchanges: [SZSE, SSE]
  # 板块白名单：主板 / 创业板 / 科创板 / 北交所
  markets: [主板, 创业板, 科创板]
  # 上市年限下限（年）—— plan.md §4「上市 ≥ 10 年」
  min_listing_years: 10
  # 总市值下限（元）—— plan.md §4「市值 ≥ 500 亿」
  min_market_cap: 50000000000
  # 流通市值下限（元）；null = 不限制
  min_float_market_cap: null
  # 近 20 日日均成交额下限（元）—— 流动性过滤
  min_avg_amount_20d: 20000000
  # 要求 asof 当日正常交易（非停牌）
  require_trading_on_asof: true

# ------------------------------------------------------------
# 行业豁免（对 RiskFilter 与 FinancialQualityFilter 同时生效）
# 银行/保险/证券的负债率天然在 90% 上下、且没有「自由现金流」的概念，
# 若不做豁免，高股息策略里最重要的银行板块会被全部误杀
# （实测：招商银行 90.2% 会被 risk.max_debt_to_assets 直接淘汰）。
# ------------------------------------------------------------
industry_exemptions:
  # 豁免资产负债率上限的行业
  leverage: [银行, 保险, 证券, 信托]
  # 豁免「自由现金流为正 / FCF 覆盖分红 / 经营现金流对利润」要求的行业
  free_cash_flow: [银行, 保险, 证券, 信托]

# ------------------------------------------------------------
# RiskFilter —— 风险过滤
# ------------------------------------------------------------
risk:
  # 排除 ST / *ST（依据 stock_name_history 按日期还原，而非只看当前名）
  exclude_st: true
  st_lookback_from_history: true
  # 排除退市整理 / 已退市
  exclude_delisting: true
  # 排除 asof 当日停牌
  exclude_suspended: true
  # 排除净资产为负
  exclude_negative_equity: true
  # 资产负债率上限；null = 不限制。金融股由 industry_exemptions.leverage 豁免
  max_debt_to_assets: 0.80
  # 大股东质押比例上限；null = 不限制（需额外数据源）
  max_pledge_ratio: null
  # 重大诉讼；当前无数据源，保持 false
  exclude_major_litigation: false
  # 商誉异常；当前无数据源，保持 false
  exclude_goodwill_anomaly: false

# ------------------------------------------------------------
# DividendFilter —— 分红过滤
# ------------------------------------------------------------
dividend:
  # 股息率口径：
  #   computed —— 自算 PIT-TTM（按 imp_ann_date 生效），无未来函数【回测主口径】
  #   dv_ttm   —— 直接用 daily_basic.dv_ttm（仅交叉校验）
  yield_source: computed
  # 当前股息率下限 —— plan.md §4「股息率 ≥ 3%」
  min_dividend_yield: 0.03

  # 连续分红年限下限 —— plan.md §4「连续现金分红 ≥ 5 年」
  min_continuous_years: 5
  # 认定一次分红的规则（D6 决策）：
  #   cash_div_tax_gt_0 —— 税前现金分红 > 0，且 div_proc='实施'，且有 ex_date 或 pay_date
  continuous_rule: cash_div_tax_gt_0
  # 考察窗口（年）
  window_years: 6
  # 窗口内最少分红年数
  min_dividend_years_in_window: 5

  # 分红支付率上下限；null = 不限制
  max_payout_ratio: 1.00
  min_payout_ratio: null
  # 5 年 DPS 复合增速下限；null = 不限制
  min_dps_cagr_5y: null
  # 要求自由现金流为正
  require_positive_fcf: true
  # 自由现金流对分红的覆盖倍数下限（FCF / 现金分红总额）
  min_fcf_dividend_cover: 1.0

  # 当「验证所需的数据缺失」时如何处理（安全边际策略的关键取舍）：
  #   pass   —— 放行（宽松）。避免因数据未同步而误杀，但会让「无法验证现金流」
  #             的股票进入组合，与「安全边际」的初衷相悖。
  #   reject —— 淘汰（严格）。忠于「FCF 必须为正」的策略逻辑，
  #             但结果会依赖数据完整度（数据补齐前后股票池会变化）。
  # 实测：当前全部在市股票均有现金流数据，缺失的 10 只均为 1990 年代退市股
  # （已被 risk.exclude_delisting 排除），因此两种设置结果相同。
  # 若你希望「宁可错过、不可踩雷」，改为 reject。
  on_missing_data: pass

# ------------------------------------------------------------
# FinancialQualityFilter —— 财务质量过滤
# ------------------------------------------------------------
quality:
  # 5 年平均 ROE 下限
  min_roe_5y_avg: 0.08
  # 5 年平均 ROIC 下限；null = 不限制
  min_roic_5y_avg: null
  min_gross_margin: null
  min_net_margin: null
  # 经营现金流 / 净利润 下限（盈利质量）
  min_ocf_to_profit: 0.60
  # 覆盖 risk.max_debt_to_assets；null = 不覆盖
  max_debt_to_assets: null
  # 利息保障倍数下限；null = 不限制
  min_interest_cover: null
  # 兼容字段：留空则使用顶层的 industry_exemptions
  exempt_industries: []
  # PIT 纪律：只使用公告日 <= asof 的财报
  pit_rule: announce_date_le_asof
  # 用哪一期财报：latest_announced（最近已公告）/ ttm
  report_basis: latest_announced

# ------------------------------------------------------------
# 输出控制
# ------------------------------------------------------------
output:
  # 成员数少于该值触发 WARN（可能是条件过严或数据缺口）
  min_members: 10
  # 成员数上限；null = 不限制。用于回测时控制持仓候选规模
  max_members: 200
  warn_on_empty: true