基金量化定投选基系统

数据基建¶

data_audit.json 标准 Schema 定义

此文件为 M2 验收的机器可解析审计凭证，S2-04 必须严格按此 Schema 输出：

{
  "pipeline": {
    "step": "step2_data_loading",
    "run_time": "2026-04-11T10:00:00+08:00",
    "python_version": "3.12.x"
  },
  "input": {
    "fund_net_info": {
      "file_path": "data/raw/fund_net_info.csv",
      "sha256": "a1b2c3d4...",
      "total_rows": 23000000,
      "date_range": ["2015-12-07", "2026-03-28"]
    },
    "fund_basic_info": {
      "file_path": "data/raw/fund_basic_info.csv",
      "sha256": "e5f6g7h8...",
      "total_records": 26000,
      "columns_actually_read": ["fund_id", "fund_name", "fund_type", "create_date"],
      "columns_discarded": ["insert_datetime", "update_datetime", "insert_operator", "update_operator"]
    }
  },
  "filtering": {
    "whitelist_total_funds": 26000,
    "whitelist_retained_funds": 8000,
    "whitelist_filtered_funds": 18000,
    "whitelist_retention_rate": 0.3077
  },
  "cleaning": {
    "weekly_aggregation_dedup_rows": 500000,
    "nav_le_zero_removed_rows": 1200,
    "weekly_change_over_limit_nullified": 3500,
    "building_period_dropped_rows": 96000,
    "truncated_rows_by_gap": 42000,
    "survival_filtered_funds": 1500,
    "survival_filtered_rows": 78000
  },
  "output": {
    "parquet_files": [
      {"filename": "net_value_2016.parquet", "sha256": "...", "rows": 450000},
      {"filename": "net_value_2017.parquet", "sha256": "...", "rows": 480000}
    ],
    "total_rows_after_cleaning": 8500000,
    "total_funds_after_cleaning": 6500,
    "date_range": ["2016-01-04", "2026-03-28"],
    "schema": ["fund_id:String", "net_value_date:Date", "cumulative_net_value:Float64", "segment_id:UInt32"],
    "peak_memory_gb": 35.2,
    "duckdb_view_name": "v_net_value_processed"
  }
}

PM 卡控说明：上述数值为占位示例，研发必须使用 settings.filter.fund_type_whitelist 等配置参数驱动计算，严禁硬编码。whitelist_retention_rate 的分母必须是 fund_basic_info 的原始总行数。

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

1. ffill + 截断的 Polars 向量化实现（复用级）¶

# 推荐实现思路（伪代码，非最终交付）
# 先按 fund_id 排序，再用 Polars 原生 forward fill
df = df.sort(["fund_id", "net_value_date"])
df = df.with_columns(
    pl.col("cumulative_net_value").forward_fill().over("fund_id")
)
# 然后 Polars 原生检测连续 NULL（即原始缺失超过 max_gap_weeks 的位置）
# 利用 diff 计算相邻日期间隔，间隔 > (max_gap_weeks+1)*7 天即为截断点

2. DuckDB memory_limit 应从配置读取¶

S2-01 中 DuckDB 连接应设置 memory_limit=str(settings.duckdb_memory_limit)，建议在 config.yaml 中新增：

duckdb:
  memory_limit: "40GB"

这样后续压测时可通过环境变量 DUCKDB__MEMORY_LIMIT=20GB 快速模拟低内存环境。

3. 审计日志的"率"统一精度¶

建议在 src/utils/config.py 中新增一个审计工具函数：

def calc_rate(numerator: int, denominator: int, decimals: int = 4) -> float:
    """通用比率计算，分母为 0 时返回 0.0"""

供 data_loader.py 调用，保证全项目比率计算逻辑一致。

新增/修改文件清单¶

下级目录¶

CR-001-M2里程碑_Parquet_Schema_变更¶

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

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

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

规约 4.2 要求每个滚动特征都要判断 min_valid_ratio。如果在 40 个特征里各自写一遍 .is_not_null().sum() 逻辑，代码极度冗余且易错。
建议实现：在 feature_engineering.py 内部实现一个高阶函数或装饰器：

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 在底层实现极高的向量化性能。

新增/修改文件清单¶

下级目录¶

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

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

标签生成器¶

由于 Step 4 业务逻辑高度内聚且规约给出了标准伪代码，一周时间安排相对紧凑，核心攻坚集中在向量化实现与边界防御。

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

1. “有效窗口长度 < 2” 的防御性考量¶

规约伪代码写道：“若有效窗口长度 < 2 → label = 0”。
在实际工程中，如果由于 Step 2 的截断导致某个时间点 t 之后只剩下 1 周的数据（即 t+1 存在，但 t+2 不存在），np.cumsum 依然可以运行（长度为 1 的数组），但这不符合“定投”的语义（至少要投入 2 期才能算成本）。因此，强制拦截 < 2 是极其正确的防御，单测场景 7（建仓期后首周）刚好能覆盖此边界。研发在实现时切勿将判断条件放宽为 < 1。

2. np.argmax(mask) 的陷阱防御¶

NumPy 的 argmax 在 mask 全为 False 时会返回 0。虽然伪代码中用了 any(mask) 做前置判断，但在向量化实现（如使用 np.where 或底层 NumPy 循环）时，极易引入隐式 Bug。
建议实现：不要过度追求炫技的纯矩阵运算，规约已允许“对每只基金处理极小数组”，直接在 map_elements 或 Python UDF 中使用规约给定的标准 if-else 伪代码逻辑是最安全的，性能瓶颈不在 Python 层，而在 Polars 的 group_by 调度。

新增/修改文件清单¶

下级目录¶

模型训练与评估¶

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

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 日之后没有新数据来给新基金打分）。这是一个极易踩坑的业务边界。

新增/修改文件清单¶

下级目录¶

CR-004-回测评估执行策略与空桶防御机制修正
CR-005-MLflow_归档标准化参数语义变更

推理收口¶

作为项目收官之周，Step 6 的重心不再是算法攻坚，而是工程闭环、接口防穿透与双轨制收尾。

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

1. 特征计算“精简版”的接口复用（防笨重化）¶

Step 3 的 calculate_raw_features 是针对按年分区大表设计的，内部包含了 segment_id 的复杂隔离逻辑与按年循环。
但在 Step 6 推理时，输入的永远是单只基金的小 DataFrame（通常 < 500 行），且 segment_id 必然只有 0 这一个值。
建议实现：在 feature_engineering.py 中暴露一个轻量级包装器 calculate_raw_features_inference(df_single_fund: pl.DataFrame)，内部直接调用核心滚动逻辑，但跳过按年循环与 segment 隔离的开销。这能将单基金特征计算耗时从秒级压榨到毫秒级。

2. MLflow 模型加载的“防穿透”硬编码¶

规约 5.5 提到“新模型打 Production 标签后直接替换”。
防坑点：MLflow 的 mlflow.lightgbm.load_model("models:/model_name/latest") 中的 latest 指的是最后运行的一次 Experiment，而不是打了 Production 标签的版本。如果在一次失败的训练后没有打标，latest 会指向垃圾模型。
强制要求：inference.py 加载模型必须使用如下严格语法：

model_uri = "models:/fund_dca_model/production"
# 禁止使用 "latest"
model = mlflow.lightgbm.load_model(model_uri)

3. “得分区间文案”的逻辑外置¶

规约 6.3 的四段文案极易在后续业务迭代中被修改。建议将这四个模板（包含占位符 {top_feature}）统一定义在 config/config.yaml 的 inference.recommendation_templates 节点下，inference.py 仅负责读取配置并 format()，严禁在代码中硬编码大段中文文案。

新增/修改文件清单¶

下级目录¶

CR-006-批量推荐接口_SHAP_归因性能降级策略