基金量化定投选基系统

## 模型训练与评估

| 周次 | Story ID | Story 描述 | 规约硬性映射 | 验收标准 | 工时 |

|:---:|:---|:---|:---|:---:|:---:|

| **W6** | **S5-01** | **时序切分基座与特征标签对齐**<br>读取按年 Parquet，执行 LEFT JOIN 产出未标准化的 `train_dataset.parquet`，实现 TimeSeriesSplit 索引划分。 | 规约 5.1 (训练数据流)；规约 5.2 (严禁随机 K-Fold) | ① 产出 `train_dataset.parquet`，Schema 为长表且特征均为**原始值**；<br>② 实现严格的 `TimeSeriesSplit(n_splits=5)` 索引生成器，按时间排序切分，严禁打乱；<br>③ 单测验证各折的 Train/Val 时间范围无重叠且无未来穿越。 | 1天 |

| **W6** | **S5-02** | **逐折闭环引擎（标准化+共线性+训练+评估）**<br>实现单折内部的时序隔离计算流，复用 Step 3 纯函数。 | 规约 5.2 (每折独立执行)；CR-002 (复用Step3函数)；规约 4.4 (严禁跨时间窗口IC计算) | ① 调用 `feature_engineering.calculate_stats()` **仅基于 Train 折数据**计算统计量；<br>② 调用 `apply_standardization()` 应用 T-1 参数，Val 折**严格借用**对应 Train 折参数；<br>③ 调用 `remove_collinear_features()` 时，计算 Spearman IC **仅使用 Train 折标签**；<br>④ 产出每折的 AUC、NDCG 指标。 | 2天 |

| **W6** | **S5-03** | **Optuna 单折搜索与 1 小时硬限拦截**<br>在最后一个折上配置 Optuna 搜索空间与超时机制。 | 章程第八章 (1小时硬限)；规约 5.3 (参数范围/停止条件) | ① Optuna 目标函数配置 `early_stopping_rounds=50`；<br>② 调用 `study.optimize(timeout=3600)` 实现强制截断，到达 1 小时无论是否收敛必须停止并取当前最优；<br>③ 搜索范围 8 个超参数严格对齐规约 5.3 表格，严禁自行添加。 | 1天 |

| **W7** | **S5-04** | **四桶回测引擎（单点快照+绝对截断）**<br>在最后折的 Val 集最后一个截面，实现绝对分桶与 DCA 组合净值模拟。 | CR-004 (单点快照/绝对截断/空桶保留)；规约 5.4 (回测指标) | ① 仅取最后折 Val 集的**最后一个日期截面**进行打分；<br>② 严格按绝对数量分桶（Top20 取 1~20 名），空桶净值曲线输出为 `None`；<br>③ 实现周定投组合净值追踪：每周投入 20 元均分，计算年化收益率、最大回撤、Sharpe、止盈成功率；<br>④ 计算全标的池等权基准的相同指标。 | 2天 |

| **W7** | **S5-05** | **全量参数重算与 MLflow 归档闭环**<br>产出最终推理级参数，执行 SHAP 归因，完成 MLflow Production 打标。 | CR-005 (全量重算参数)；规约 5.5 (MLflow 记录)；规约 7.3 (config.yaml Hash) | ① 全量加载 `features.parquet`，重新跑一遍标准化，产出**全局基准** `standardization_params.parquet` 存入 MLflow；<br>② 使用最优参数在所有折上重训最终模型，产出 `.txt` 文件；<br>③ 产出 SHAP summary plot 与四桶回测净值曲线图；<br>④ 在 MLflow Model Registry 将新模型打上 `Production` 标签，旧模型归档至 `Archived`。 | 2天 |

---

## 可优化与可复用逻辑提示

### 1. 【高优提醒】LightGBM 目标函数的对齐缺失

规约 5.4 要求评估 `NDCG@20`（排序质量指标），但规约 5.3 未明确 LightGBM 的 `objective`（目标函数）。

- 如果使用 `binary:logloss`，模型输出的是概率，无法直接完美对齐 NDCG。

- **建议实现**：在 S5-03 的 Optuna 定义中，建议研发使用 `lambdarank` 目标函数，或至少在评估阶段将模型概率输出转化为分位数后计算 NDCG。**此细节无需 PM 拍板，但请研发在 Review 时重点关注，避免 NDCG 指标失真。**

### 2. LightGBM 特征名与共线性剔除后列表的严格对齐

在 S5-02 逐折循环中，共线性剔除会丢弃部分特征。在将 Polars DataFrame 转换为 LightGBM Dataset 时，**必须显式传入 `feature_names=final_feature_list`**。如果不传，LightGBM 会按内部索引（0, 1, 2...）生成特征名，后续导出的 SHAP 归因图将变成无意义的 `Feature_0`，直接导致 M4 验收失败。

### 3. 回测 DCA 净值模拟的“快照隔离”

规约要求模拟“等权周定投组合”。在单点快照（假设 T 日为 2025-12-31）下，组合从 T+1 日开始买入，但买入的标的必须是 T 日排名分桶后的基金池。**严禁**在回测的 150 周内允许新基金加入组合（因为 T 日之后没有新数据来给新基金打分）。这是一个极易踩坑的业务边界。

---

## 新增/修改文件清单

| 操作 | 文件路径 | 简介与企业级约束 |

|:---:|:---|:---|

| **新增** | `src/trainer.py` | **核心模块**。包含主入口 `run_training_pipeline()`，以及内部函数 `_train_single_fold()`、`_evaluate_single_fold()`、`_run_optuna()`、`_backtest_single_point()`。严禁出现任何硬编码超参数。 |

| **新增** | `src/utils/backtest.py` | **回测工具模块**。包含 `_simulate_dca_portfolio()`（给定基金池，按周均分资金模拟定投净值）和 `_calculate_portfolio_metrics()`（计算年化、最大回撤、Sharpe等）。从 `trainer.py` 中剥离，保持单一职责。 |

| **修改** | `docs/architecture_baseline.md` | 新增《Step 5 时序隔离防泄露架构图》：明确展示 Train 折计算 Stats -> Val 折使用 Shifted Stats 的虚线依赖关系，以及全量重算参数的旁路流程。 |

| **修改** | `.gitea/workflows/ci.yml` | 增加 Step 5 所需系统依赖的安装检查（如 `lightgbm`, `optuna`, `shap`, `scikit-learn`, `matplotlib`），防止流水线在拉取代码后因缺包报错。 |

| **产出** | `data/models/model_final.txt` | 运行时产物。使用最优参数在全量 5 折上重训的最终 LightGBM 模型文件。 |

| **产出** | `data/models/standardization_params.parquet` | 运行时产物（CR-005 定义的全局基准版）。Schema 严格符合规约 4.3 节，供 Step 6 推理服务直读。 |

| **产出** | `data/models/final_feature_list.json` | 运行时产物。最后一次重训时保留的特征名列表（可能因逐折 IC 剔除而与 Step 3 预览版不同）。 |

| **产出** | `mlruns/.../artifacts/shap_summary.png` | 运行时产物。SHAP 特征重要性摘要图，用于解释模型决策依据。 |

| **产出** | `mlruns/.../artifacts/backtest_curves.png` | 运行时产物。包含 Top20、Top21-50、Top51-100、其余 四条净值曲线与等权基准曲线的对比图。 |

---

## 子目录

[[CR-004-回测评估执行策略与空桶防御机制修正]] 

[[CR-005-MLflow_归档标准化参数语义变更]]