基金量化定投选基系统

---

## 下级目录

[[CR-002-M3a里程碑交付物语义变更]] 

[[CR-003-多窗口特征列名规范化]]

---

## 全量数据基准预览（仅作审计与特征字典参考）

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

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

| **W4** | **S3-01** | **基础滚动特征引擎（A/B/C类）**<br>实现均值回归、波动、趋势动量类特征的 Polars 向量化计算。 | 规约 4.1 (A/B/C类)；FW-3 (按年串行)；CR-003 (`_w` 命名) | ① 产出约 20 维基础特征（如 `momentum_w4`, `max_drawdown_w26`）；<br>② **强制隔离**：滚动计算必须按 `group_by(['fund_id', 'segment_id'])` 隔离，严禁跨段计算；<br>③ 所有窗口参数从 `config.yaml` 读取；<br>④ 单测验证特定 Mock 数据下的滚动值精确度。 | 1.5天 |

| **W4** | **S3-02** | **定投特有与风险调整特征引擎（D/E类）**<br>实现 DCA 特征与 Sharpe/Sortino，包含 OLS 线性回归斜率计算。 | 规约 4.1 (D/E类)；规约 4.2 (min_valid_ratio)；规约 4.1E (weekly_rf 公式) | ① 产出约 20 维高阶特征（如 `dca_return_w12`, `rolling_sharpe_w26`）；<br>② **有效值判定**：所有滚动特征必须实现 `min_valid_ratio=0.20` 卡控，不足时输出 NULL；<br>③ `weekly_rf` 计算公式必须严格为 `(1 + 0.02)^(1/52) - 1`，严禁硬编码数值；<br>④ OLS 回归单测验证斜率与 R² 极限情况。 | 1天 |

| **W4** | **S3-03** | **标准化与共线性工具函数（纯逻辑抽离）**<br>实现 T-1 截面标准化与共线性剔除的**纯函数**，并在全量数据上跑一遍产出预览文件。 | 规约 4.3 (T-1模式/MAD边界3.0)；规约 4.4 (IC计算/阈值0.90)；CR-002 (函数级单测) | ① 暴露 `calculate_stats()`, `apply_standardization()`, `remove_collinear_features()` 三个公开函数，**带完整 Type Hints**；<br>② **单测强卡点**：构造 2 天数据的 DataFrame，调用 `apply_standardization()`，断言第 1 天所有特征输出 NULL；<br>③ 产出 `standardization_params.parquet`（标记为预览）与 `final_feature_list.json`。 | 1.5天 |

| **W4** | **S3-04** | **特征落盘、血缘与双轨制文档**<br>按年分区写长表特征 Parquet，更新 Hash 与数据契约文档。 | 规约 7.4 (严禁Pivot宽表)；FW-4 (按年覆盖写回)；架构基线 3 | ① `data/features/features_YYYY.parquet` 产出，Schema 为长表：`fund_id`, `net_value_date`, `segment_id`, `feature_1`, ..., `feature_K`；<br>② PyArrow 写入指定 `row_group_size=100000`；<br>③ 产出 `data/metadata/features_hash.json`；<br>④ `docs/data_contract.md` 同步更新特征字典（含 `_w` 命名示例）。 | 1天 |

---

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

### 1. 滚动窗口的“有效值判定”通用包装器（复用级）

规约 4.2 要求每个滚动特征都要判断 `min_valid_ratio`。如果在 40 个特征里各自写一遍 `.is_not_null().sum()` 逻辑，代码极度冗余且易错。

**建议实现**：在 `feature_engineering.py` 内部实现一个高阶函数或装饰器：

```python

def with_validity_check(df: pl.Expr, window_size: int, min_ratio: float) -> pl.Expr:

    # 统一包装：先算 rolling，再算窗口内非空数，不足比例则返回 NULL

    ...

```

所有特征计算只需调用此包装器，保证全项目有效值判定逻辑绝对一致。

### 2. OLS 回归的 NumPy 向量化加速

规约要求计算 `trend_slope` 和 `trend_r_squared`。Polars 原生不支持直接在 `group_by` 内做复杂的 OLS 矩阵运算。

**建议实现**：提取每只基金（每段）的窗口数据为极小的 NumPy 数组（最大 52x2 矩阵），使用 `np.linalg.lstsq` 批量求解。这不仅规避了 Polars 的限制，还能通过 `map_elements` 在底层实现极高的向量化性能。

---

## 新增/修改文件清单

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

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

| **新增** | `src/feature_engineering.py` | **核心模块**。包含 3 个层级：<br>① `calculate_raw_features(df)` — 按年调用，产出 A~E 类原始特征；<br>② `calculate_stats(df)`, `apply_standardization(df, stats)` — 标准化纯函数；<br>③ `remove_collinear_features(df, labels)` — 共线性剔除纯函数。严禁出现魔法数字。 |

| **新增** | `tests/test_feature_engineering.py` | **防线级单测**。必含：<br>① OLS 斜率精度测试；<br>② `min_valid_ratio` NULL 化测试；<br>③ **T-1 标准化首日 NULL 测试**（构造 2 天数据，验证函数输出）。 |

| **修改** | `docs/data_contract.md` | 新增《特征矩阵接口契约单》：<br>① 明确 `features_YYYY.parquet` 的 Schema（重点标注含 `segment_id` 且特征为原始值）；<br>② 列出完整的特征字典（采用 `_w` 风格 2 命名，约 40+ 行）；<br>③ 标注 `standardization_params.parquet` 的“预览”语义。 |

| **修改** | `docs/architecture_baseline.md` | 更新数据流图：明确 `feature_engineering.py` 向 `trainer.py` 暴露标准化“纯函数”的虚线依赖关系。 |

| **修改** | `.gitea/workflows/ci.yml` | 增加 `pytest tests/test_feature_engineering.py -v` 步骤，纳入 CI 强阻断。 |

| **产出** | `data/features/features_YYYY.parquet` | 运行时产物。长表形态，包含原始特征值。 |

| **产出** | `data/models/standardization_params.parquet` | 运行时产物（全量基准预览）。Schema 符合规约 4.3，但增加审计备注。 |

| **产出** | `data/models/final_feature_list.json` | 运行时产物（预览列表）。格式：`["price_vs_ma_ratio_w12", ..., "rolling_sharpe_w52"]`。 |

| **产出** | `data/metadata/features_hash.json` | 运行时产物。基于 `src/utils/hash.py` 计算。 |

---