quantnodes 3.0.0__py3-none-any.whl

QuantNodes/research/factor_test/pipeline_runner.py

@@ -0,0 +1,305 @@
+# coding: utf-8
+"""Pipeline Runner / 管线编排器
+
+混合模式数据传递:
+- Phase 1 (严格串联): LoadData >> SampleFilter >> TradabilityFilter >>
+  AdjustDate >> Preprocess >> Neutralize
+- Phase 2 (Context 共享): ICAnalyzer / GroupAnalyzer / FactorScore / RiskCorrelation
+- Phase 3 (依赖分析): LongShort
+- Phase 4 (输出): FactorTestReport
+
+FactorFeedback 集成 (Week 1.5, 可选):
+- feedback.enabled=False: 现有行为完全不变 (向后兼容)
+- feedback.enabled=True:  5 个分析节点返回值自动包装为 FactorFeedback,
+  聚合到 ctx['Feedback'], 可选持久化到 feedback.output_dir
+
+Phase R2 重构 (2026-06-19):
+- 12 阶段从手写 137 行缩减为 PIPELINE_SPEC 数据驱动 (~30 行 run loop)
+- Feedback 包装拆到 feedback_wrapper.py
+- Evolution 适配拆到 evolution_adapter.py
+- 指标提取拆到 utils/metrics_extractor.py
+- 公共 API (`PipelineRunner.run()` / `.run_evolution()`) 完全兼容
+"""
+
+from __future__ import annotations
+
+import logging
+import uuid
+from typing import TYPE_CHECKING, List, Optional
+
+import pandas as pd
+import yaml
+
+from QuantNodes.core.feedback import FactorFeedback
+from QuantNodes.research.factor_test.config import SingleFactorTestConfig
+from QuantNodes.research.factor_test.evolution_adapter import (
+    build_evolution_loop,
+    build_quality_gate,
+    build_trajectory_pool,
+    evaluate_candidate,
+    run_evolution as _run_evolution,
+    run_one_factor,
+)
+from QuantNodes.research.factor_test.feedback_wrapper import (
+    ANALYSIS_NODES as _ANALYSIS_NODES,  # noqa: F401  re-export 兼容
+    build_feedback,
+    maybe_build_judge,
+    maybe_persist_feedback,
+)
+from QuantNodes.research.factor_test.pipeline_spec import PIPELINE_SPEC, PhaseSpec
+from QuantNodes.research.factor_test.utils.metrics_extractor import (
+    extract_metrics_from_ctx as _extract_metrics_from_ctx,  # noqa: F401  re-export
+)
+
+if TYPE_CHECKING:
+    from QuantNodes.core.evolution import EvolutionResult, FactorCandidate
+    from QuantNodes.core.feedback import LLMJudge
+    from QuantNodes.core.quality_gate import QualityGateNode
+    from QuantNodes.core.trajectory import TrajectoryPool
+
+
+logger = logging.getLogger(__name__)
+
+
+class PipelineRunner:
+    """单因子回测管线编排器
+
+    用法:
+        config = SingleFactorTestConfig(...)
+        runner = PipelineRunner(config)
+        result = runner.run()
+
+        # 或从 YAML:
+        runner = PipelineRunner.from_yaml("config.yaml")
+        result = runner.run()
+
+    FactorFeedback 集成:
+        当 config.feedback.enabled=True 时, 5 个分析节点返回值会自动包装为
+        FactorFeedback, 聚合到 ctx['Feedback'] = {node_name: FactorFeedback}。
+        若 config.feedback.output_dir 不为 None, 还会持久化到该目录。
+    """
+
+    def __init__(
+        self,
+        config: SingleFactorTestConfig,
+        specs: Optional[List["PhaseSpec"]] = None,
+    ):
+        """
+        Args:
+            config: 单因子回测配置.
+            specs: PR-QN-2 (2026-06-21) 新增. 自定义 phase 列表 (**追加**到
+                标准 12 阶段之后). 默认 None = 使用 ``list(PIPELINE_SPEC)``.
+                若要**完全替换** 12 阶段, 用 ``list(PIPELINE_SPEC) + specs``
+                显式拼接.
+
+        Note:
+            不传 specs 时, 行为与 PR-QN-2 之前**完全一致**. 4608+ 现有
+            tests 无需任何修改.
+        """
+        self.config = config
+        self._context: dict = {}
+        # PR-QN-2: 实例级 _specs (默认 = 标准 12 阶段; 传 specs 时**追加**)
+        if specs:
+            self._specs: list = list(PIPELINE_SPEC) + list(specs)
+        else:
+            self._specs = list(PIPELINE_SPEC)
+
+    @classmethod
+    def from_yaml(cls, yaml_path: str) -> "PipelineRunner":
+        """从 YAML 配置文件创建 Runner"""
+        with open(yaml_path, "r", encoding="utf-8") as f:
+            raw = yaml.safe_load(f)
+        return cls(SingleFactorTestConfig(**raw))
+
+    @classmethod
+    def from_dict(
+        cls,
+        data: dict,
+        extra_phases: Optional[List["PhaseSpec"]] = None,
+    ) -> "PipelineRunner":
+        """从 dict 创建 Runner
+
+        Args:
+            data: 配置 dict.
+            extra_phases: PR-QN-2 (2026-06-21) 新增. 追加的自定义 phase 列表
+                (在标准 12 阶段之后执行). 默认 None = 与 PR 之前完全一致.
+        """
+        return cls(SingleFactorTestConfig(**data), specs=extra_phases)
+
+    # ============================================================
+    # Phase R2: 声明式 12 节点 run loop
+    # ============================================================
+
+    def run(self) -> dict:
+        """执行完整单因子回测管线
+
+        Returns:
+            dict: 完整结果, 各节点输出按 ``ctx[node_name]`` 索引
+                  当 ``config.feedback.enabled=True`` 时, 还包含 'Feedback' 键
+        """
+        cfg = self.config
+        ctx, pre_seeded = self._seed_ctx()
+
+        feedback_enabled = cfg.feedback.enabled
+        factor_id = str(uuid.uuid4())
+        factor_name = cfg.factor.name
+        judge = maybe_build_judge(cfg) if feedback_enabled else None
+
+        logger.info("=" * 60)
+        logger.info("单因子回测: %s", cfg.factor.name)
+        logger.info(
+            "时间范围: %s ~ %s",
+            cfg.preprocess.adj_date_beg,
+            cfg.preprocess.adj_date_end,
+        )
+        if feedback_enabled:
+            logger.info("FactorFeedback: ENABLED (factor_id=%s...)", factor_id[:8])
+        logger.info("=" * 60)
+
+        for spec in self._specs:
+            self._run_phase(spec, ctx, pre_seeded)
+
+        # FactorFeedback 自动包装 (可选)
+        if feedback_enabled:
+            ctx["Feedback"] = build_feedback(ctx, factor_id, factor_name, cfg, judge)
+            maybe_persist_feedback(ctx["Feedback"], cfg)
+            n_passed = sum(1 for fb in ctx["Feedback"].values() if fb.decision)
+            logger.info(
+                "\n[Feedback] 包装完成: %d 节点, %d 通过",
+                len(ctx["Feedback"]),
+                n_passed,
+            )
+
+        logger.info("\n" + "=" * 60)
+        logger.info("单因子回测完成!")
+        logger.info("=" * 60)
+        return ctx
+
+    def _seed_ctx(self) -> tuple[dict, bool]:
+        """初始化 ctx; 若已注入 LoadData, 复用之, 否则空 dict.
+
+        Returns:
+            (ctx, pre_seeded) — pre_seeded=True 表示 LoadData 已外部注入
+        """
+        if "LoadData" in self._context:
+            ctx = dict(self._context)
+            shape = ctx["LoadData"].get("factor", pd.DataFrame()).shape
+            logger.info("  [LoadData 跳过] 使用已注入数据 (factor shape: %s)", shape)
+            return ctx, True
+        return {}, False
+
+    def _run_phase(self, spec: PhaseSpec, ctx: dict, pre_seeded: bool) -> None:
+        """执行单个阶段 (含 skip / log)."""
+        if spec.skip_if_in_ctx and spec.name in ctx:
+            return
+        logger.info("\n[Phase %d] %s...", spec.phase_no, spec.title)
+        node = spec.node_cls(config=spec.build_cfg(self.config))
+        ctx[spec.name] = node.execute(context=ctx)
+        if spec.log_summary is not None:
+            line = spec.log_summary(self.config, ctx[spec.name])
+            if line:
+                logger.info(line)
+
+    # ============================================================
+    # 兼容旧 API: 私有方法 facade re-export
+    # ============================================================
+
+    def _build_feedback(
+        self,
+        ctx: dict,
+        factor_id: str,
+        factor_name: str,
+        judge: Optional["LLMJudge"],
+    ) -> dict:
+        """向后兼容: 委托给 ``feedback_wrapper.build_feedback``."""
+        return build_feedback(ctx, factor_id, factor_name, self.config, judge)
+
+    def _maybe_persist_feedback(
+        self,
+        feedbacks: dict,
+        cfg: SingleFactorTestConfig,
+    ) -> None:
+        """向后兼容: 委托给 ``feedback_wrapper.maybe_persist_feedback``."""
+        maybe_persist_feedback(feedbacks, cfg)
+
+    @staticmethod
+    def _maybe_build_judge(cfg: SingleFactorTestConfig) -> Optional["LLMJudge"]:
+        """向后兼容: 委托给 ``feedback_wrapper.maybe_build_judge``."""
+        return maybe_build_judge(cfg)
+
+    # ============================================================
+    # Week 4: 演化集成 (向后兼容 facade, 实现在 evolution_adapter.py)
+    # ============================================================
+
+    def _build_quality_gate(self) -> Optional["QualityGateNode"]:
+        return build_quality_gate(self)
+
+    def _build_trajectory_pool(self) -> Optional["TrajectoryPool"]:
+        return build_trajectory_pool(self)
+
+    def _build_evolution_loop(
+        self,
+        pool: "TrajectoryPool",
+        quality_gate: Optional["QualityGateNode"],
+        workers: int = 1,
+    ):
+        return build_evolution_loop(self, pool, quality_gate, workers=workers)
+
+    def _evaluate_candidate(
+        self,
+        candidate: "FactorCandidate",
+    ) -> tuple[bool, dict, "FactorFeedback"]:
+        return evaluate_candidate(self, candidate)
+
+    def _run_one_factor(self, candidate: "FactorCandidate") -> dict:
+        return run_one_factor(self, candidate)
+
+    def run_evolution(
+        self,
+        initial_directions: list[str] | None = None,
+        initial_candidates: list["FactorCandidate"] | None = None,
+        workers: int = 1,
+    ) -> "EvolutionResult":
+        """多轮演化主入口 (委托给 ``evolution_adapter.run_evolution``)."""
+        return _run_evolution(
+            self,
+            initial_directions=initial_directions,
+            initial_candidates=initial_candidates,
+            workers=workers,
+        )
+
+    @property
+    def context(self) -> dict:
+        """获取当前上下文"""
+        return self._context
+
+
+# ============================================================
+# 便捷函数
+# ============================================================
+
+
+def run_single_factor_test(config: dict) -> dict:
+    """便捷函数: 从 dict 配置运行单因子回测
+
+    Args:
+        config: 配置字典
+
+    Returns:
+        dict: 完整结果
+    """
+    runner = PipelineRunner.from_dict(config)
+    return runner.run()
+
+
+def run_single_factor_test_yaml(yaml_path: str) -> dict:
+    """便捷函数: 从 YAML 配置运行单因子回测
+
+    Args:
+        yaml_path: YAML 配置文件路径
+
+    Returns:
+        dict: 完整结果
+    """
+    runner = PipelineRunner.from_yaml(yaml_path)
+    return runner.run()

QuantNodes/research/factor_test/pipeline_spec.py

@@ -0,0 +1,216 @@
+# coding: utf-8
+"""声明式 12 节点 Pipeline / Pipeline Spec.
+
+把 ``pipeline_runner.run()`` 中 137 行手写阶段拆为 ``PIPELINE_SPEC`` 数据驱动:
+
+- ``PhaseSpec`` 描述每阶段的 ``(name, node_cls, build_cfg, log_summary)``
+- 增 / 删 / 调序节点 = 改 ``PIPELINE_SPEC`` 列表 (单点)
+- ``run()`` 主循环 ~10 行
+
+Phase R2 (2026-06-19): 从 pipeline_runner.py 抽出, 单一职责.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable, Optional
+
+from QuantNodes.research.factor_test.config import SingleFactorTestConfig
+from QuantNodes.research.factor_test.nodes.adjust_date_node import AdjustDateNode
+from QuantNodes.research.factor_test.nodes.factor_neutralize_node import FactorNeutralizeNode
+from QuantNodes.research.factor_test.nodes.factor_preprocess_node import FactorPreprocessNode
+from QuantNodes.research.factor_test.nodes.factor_score_node import FactorScoreNode
+from QuantNodes.research.factor_test.nodes.factor_test_report_node import FactorTestReportNode
+from QuantNodes.research.factor_test.nodes.group_analyzer_node import GroupAnalyzerNode
+from QuantNodes.research.factor_test.nodes.ic_analyzer_node import ICAnalyzerNode
+from QuantNodes.research.factor_test.nodes.load_data_node import LoadDataNode
+from QuantNodes.research.factor_test.nodes.long_short_node import LongShortNode
+from QuantNodes.research.factor_test.nodes.risk_correlation_node import RiskCorrelationNode
+from QuantNodes.research.factor_test.nodes.sample_pool_filter_node import SamplePoolFilterNode
+from QuantNodes.research.factor_test.nodes.tradability_filter_node import TradabilityFilterNode
+
+
+@dataclass(frozen=True)
+class PhaseSpec:
+    """单个 Pipeline 阶段描述.
+
+    Attributes:
+        name: 节点名 (用作 ``ctx[name]`` 键)
+        phase_no: 1-12 阶段编号 (仅显示)
+        title: 阶段中文标题 (打印 banner 用)
+        node_cls: 节点类 (``BaseNode`` 子类)
+        build_cfg: ``cfg -> dict`` 构造节点 config
+        skip_if_in_ctx: True 时若 ``name in ctx`` 则跳过 (LoadData 注入场景)
+        log_summary: ``(cfg, output) -> str`` 阶段成功后的额外日志, 可为 None
+    """
+    name: str
+    phase_no: int
+    title: str
+    node_cls: type
+    build_cfg: Callable[[SingleFactorTestConfig], dict]
+    skip_if_in_ctx: bool = False
+    log_summary: Optional[Callable[[SingleFactorTestConfig, Any], str]] = None
+
+
+# ── 12 节点 config builder ────────────────────────────────────
+
+def _cfg_load(cfg: SingleFactorTestConfig) -> dict:
+    return {
+        "factor": cfg.factor.model_dump(),
+        "data_path": cfg.data_path,
+        "load_keys": cfg.load_keys,
+    }
+
+
+def _cfg_sample(cfg: SingleFactorTestConfig) -> dict:
+    return {
+        "sample_index": cfg.preprocess.sample_index,
+        "sample_industry": cfg.preprocess.sample_industry,
+        "sample_index_customdir": cfg.preprocess.sample_index_customdir,
+    }
+
+
+def _cfg_trad(cfg: SingleFactorTestConfig) -> dict:
+    return {"tradable": cfg.preprocess.tradable.model_dump()}
+
+
+def _cfg_adj(cfg: SingleFactorTestConfig) -> dict:
+    return {
+        "adj_date_beg": cfg.preprocess.adj_date_beg,
+        "adj_date_end": cfg.preprocess.adj_date_end,
+        "adj_mode": cfg.preprocess.adj_mode,
+    }
+
+
+def _cfg_preprocess(cfg: SingleFactorTestConfig) -> dict:
+    return {
+        "missing": cfg.preprocess.missing,
+        "extreme": cfg.preprocess.extreme,
+        "norm": cfg.preprocess.norm,
+    }
+
+
+def _cfg_neutralize(cfg: SingleFactorTestConfig) -> dict:
+    return {
+        "industry_neutral": cfg.preprocess.industry_neutral,
+        "risk_neutral": cfg.preprocess.risk_neutral,
+        "risk_factors": cfg.preprocess.risk_factors,
+    }
+
+
+def _cfg_ic(cfg: SingleFactorTestConfig) -> dict:
+    return {"min_group_size": cfg.analysis.ic.min_group_size}
+
+
+def _cfg_group(cfg: SingleFactorTestConfig) -> dict:
+    return {
+        "groups": cfg.analysis.group.groups,
+        "factor_direction": cfg.analysis.group.factor_direction,
+        "floor_mode": cfg.analysis.group.floor_mode,
+        "hedge": cfg.analysis.group.hedge,
+        "hedge_path": cfg.analysis.group.hedge_path,
+    }
+
+
+def _cfg_longshort(cfg: SingleFactorTestConfig) -> dict:
+    return {"factor_direction": cfg.analysis.longshort.factor_direction}
+
+
+def _cfg_score(cfg: SingleFactorTestConfig) -> dict:
+    return {"enabled": cfg.analysis.score.enabled}
+
+
+def _cfg_risk_corr(cfg: SingleFactorTestConfig) -> dict:
+    return {"factors": cfg.analysis.risk_corr.factors}
+
+
+def _cfg_report(cfg: SingleFactorTestConfig) -> dict:
+    return {"dir": cfg.output.dir, "format": cfg.output.format}
+
+
+# ── log_summary 辅助 ──────────────────────────────────────────
+
+def _log_adj(cfg, out) -> str:
+    return f"  调仓日数: {len(out)}"
+
+
+def _log_preprocess(cfg, out) -> str:
+    shape = getattr(out, "shape", "?")
+    return f"  预处理后因子形状: {shape}"
+
+
+def _log_ic(cfg, out) -> str:
+    if not isinstance(out, dict):
+        return ""
+    ic_result = out.get("ic_result")
+    if not isinstance(ic_result, dict):
+        return ""
+    parts = []
+    if ic_result.get("IC均值") is not None:
+        parts.append(f"IC均值: {ic_result['IC均值']:.4f}")
+    if ic_result.get("ICIR") is not None:
+        parts.append(f"ICIR: {ic_result['ICIR']:.4f}")
+    return "  " + " | ".join(parts) if parts else ""
+
+
+def _log_group(cfg, out) -> str:
+    return f"  分组数: {cfg.analysis.group.groups}"
+
+
+# ── 12 节点 Pipeline 声明 ─────────────────────────────────────
+
+PIPELINE_SPEC: list[PhaseSpec] = [
+    PhaseSpec(
+        name="LoadData", phase_no=1, title="数据加载",
+        node_cls=LoadDataNode, build_cfg=_cfg_load,
+        skip_if_in_ctx=True,
+    ),
+    PhaseSpec(
+        name="SamplePoolFilter", phase_no=2, title="样本池筛选",
+        node_cls=SamplePoolFilterNode, build_cfg=_cfg_sample,
+    ),
+    PhaseSpec(
+        name="TradabilityFilter", phase_no=3, title="可交易性筛选",
+        node_cls=TradabilityFilterNode, build_cfg=_cfg_trad,
+    ),
+    PhaseSpec(
+        name="AdjustDate", phase_no=4, title="调仓日生成",
+        node_cls=AdjustDateNode, build_cfg=_cfg_adj,
+        log_summary=_log_adj,
+    ),
+    PhaseSpec(
+        name="FactorPreprocess", phase_no=5, title="因子预处理",
+        node_cls=FactorPreprocessNode, build_cfg=_cfg_preprocess,
+        log_summary=_log_preprocess,
+    ),
+    PhaseSpec(
+        name="FactorNeutralize", phase_no=6, title="因子中性化",
+        node_cls=FactorNeutralizeNode, build_cfg=_cfg_neutralize,
+    ),
+    PhaseSpec(
+        name="ICAnalyzer", phase_no=7, title="IC 分析",
+        node_cls=ICAnalyzerNode, build_cfg=_cfg_ic,
+        log_summary=_log_ic,
+    ),
+    PhaseSpec(
+        name="GroupAnalyzer", phase_no=8, title="分组分析",
+        node_cls=GroupAnalyzerNode, build_cfg=_cfg_group,
+        log_summary=_log_group,
+    ),
+    PhaseSpec(
+        name="LongShort", phase_no=9, title="多空组合",
+        node_cls=LongShortNode, build_cfg=_cfg_longshort,
+    ),
+    PhaseSpec(
+        name="FactorScore", phase_no=10, title="市值行业分层打分",
+        node_cls=FactorScoreNode, build_cfg=_cfg_score,
+    ),
+    PhaseSpec(
+        name="RiskCorrelation", phase_no=11, title="风险因子相关性",
+        node_cls=RiskCorrelationNode, build_cfg=_cfg_risk_corr,
+    ),
+    PhaseSpec(
+        name="FactorTestReport", phase_no=12, title="生成报告",
+        node_cls=FactorTestReportNode, build_cfg=_cfg_report,
+    ),
+]

QuantNodes/research/factor_test/utils/__init__.py

@@ -0,0 +1,26 @@
+# coding: utf-8
+from .data_loader import DataLoader
+from .date_utils import (
+    valid_date, datenum_to_datetime, datetime_to_datenum,
+    chg_idx_to_datestr, resample_trade_date, get_adjust_date, offset_date,
+)
+from .performance_metrics import calc_max_drawdown, evaluation, cal_net_simple
+from .constants import INDEX_MAPPING, INDEX_CP_MAPPING, INDUSTRY_MAPPING, ANNUAL_DAYS
+
+__all__ = [
+    "DataLoader",
+    "valid_date",
+    "datenum_to_datetime",
+    "datetime_to_datenum",
+    "chg_idx_to_datestr",
+    "resample_trade_date",
+    "get_adjust_date",
+    "offset_date",
+    "calc_max_drawdown",
+    "evaluation",
+    "cal_net_simple",
+    "INDEX_MAPPING",
+    "INDEX_CP_MAPPING",
+    "INDUSTRY_MAPPING",
+    "ANNUAL_DAYS",
+]

QuantNodes/research/factor_test/utils/constants.py

@@ -0,0 +1,86 @@
+# coding: utf-8
+"""常量定义 / Constants
+
+H13-H16: 行业/指数/天数支持外部 JSON 覆盖 (默认内置)。
+用法:
+    from QuantNodes.research.factor_test.utils.constants import load_overrides
+    overrides = load_overrides(Path("./my_industry_map.json"))
+    ind_map = overrides.get("INDUSTRY_MAP", DEFAULT_INDUSTRY_MAP)
+"""
+
+from pathlib import Path
+from typing import Any, Optional
+
+import json
+
+# 指数映射 (默认; SZ50 id_50 路由不在 ifind_database 中, 仅作占位)
+INDEX_MAPPING = {
+    'HS300': ('stk_daily.h5', 'id_300'),
+    'ZZ500': ('stk_daily.h5', 'id_500'),
+}
+
+# 指数收盘价映射
+INDEX_CP_MAPPING = {
+    'HS300': '000300.SH',
+    'ZZ500': '000905.SH',
+}
+
+# 中信行业映射
+INDUSTRY_MAPPING = {
+    'id_citic1A': 'ind_name_CITIC_1A',
+    'id_citic1': 'ind_name_CITIC_1',
+}
+
+# 年化天数 (A 股 250; 美股/港股 252; 24h 市场 365)
+ANNUAL_DAYS = 250
+
+
+def load_overrides(path: Optional[Path | str] = None) -> dict[str, Any]:
+    """加载外部 JSON 覆盖 (H13-H16)。
+
+    支持覆盖字段:
+        - INDUSTRY_MAP: dict[行业 key, 显示名 key]
+        - INDEX_MAPPING: dict[指数名, (h5, key)]
+        - INDEX_CP_MAPPING: dict[指数名, 代码]
+        - ANNUAL_DAYS: int
+
+    Args:
+        path: JSON 路径, None 或文件不存在 → 返回空 dict (用全部默认)
+
+    Returns:
+        dict: 覆盖项 (子集, 只含实际有 override 的字段)
+    """
+    if path is None:
+        return {}
+    path = Path(path)
+    if not path.exists():
+        return {}
+    try:
+        with path.open("r", encoding="utf-8") as f:
+            return json.load(f)
+    except Exception:
+        return {}
+
+
+def resolve_industry_map(overrides: dict[str, Any] | None = None) -> dict[str, str]:
+    """解析 INDUSTRY_MAP (含 override 合并)。"""
+    base = dict(INDUSTRY_MAPPING)
+    if overrides and "INDUSTRY_MAP" in overrides:
+        base.update(overrides["INDUSTRY_MAP"])
+    return base
+
+
+def resolve_index_mapping(overrides: dict[str, Any] | None = None) -> dict[str, tuple]:
+    """解析 INDEX_MAPPING (含 override 合并)。"""
+    base = {k: tuple(v) for k, v in INDEX_MAPPING.items()}
+    if overrides and "INDEX_MAPPING" in overrides:
+        for k, v in overrides["INDEX_MAPPING"].items():
+            base[k] = tuple(v)
+    return base
+
+
+def resolve_annual_days(overrides: dict[str, Any] | None = None) -> int:
+    """解析 ANNUAL_DAYS (含 override)。"""
+    if overrides and "ANNUAL_DAYS" in overrides:
+        return int(overrides["ANNUAL_DAYS"])
+    return ANNUAL_DAYS