document_id: SPEC-FUND-DCA-001
version: 1.0.0
status: Frozen (Baseline)
created_date: 2026-04-11
approved_by: Henry Lin
redmine_link: https://redmine.persys.top/projects/fund-selection-system

基金量化定投选基系统 — 最终设计规约 (v1.0)¶

⚠️ 机器与人工强制红线声明
本文档为系统的唯一业务与技术真相源。AI 必须严格按此执行，研发人员任何代码实现若与本文档冲突，一律以本文档为准。严禁擅自修改任何参数、公式或逻辑。

变更日志¶

〇、决策确认总表¶

一、数据基础¶

1.1 数据源 Schema¶

净值表 fund_net_info（主表）：

1.2 数据处理规则¶

1.3 存储方案¶

• 按年份分区存储：data/processed/net_value_YYYY.parquet
• Parquet row_group_size = 100,000
• 每次全量刷新时覆盖写入，不追加

二、计算引擎架构¶

2.1 DuckDB ↔ Polars 职责防火墙¶

2.2 防火墙规则（铁律）¶

三、标签系统¶

3.1 标签定义¶

3.2 标签计算算法¶

核心约束：不使用全局 Python for 循环，采用 Polars group_by + NumPy 向量化并行策略。

对每只基金（单次处理约 300-500 周的极小数组）：
nav_array = [nav_0, nav_1, ..., nav_T]
对每个时间点 t（作为"开始定投"的候选时刻）：
    ① 有效窗口 = nav_array[t+1 : t+151] （numpy 切片自动截断于数据末尾）
    ② 若有效窗口长度 < 2 → label = 0（数据不足以定投）
    ③ 累计成本序列：cum_cost = np.cumsum(有效窗口) / np.arange(1, len+1)
    ④ 当前净值序列：current = 有效窗口
    ⑤ DCA 收益率序列：dca_ret = (current - cum_cost) / cum_cost
    ⑥ 首次达标检测：mask = dca_ret >= 0.20
       - any(mask) 为 True → weeks = np.argmax(mask) + 1 → label = 150 - weeks
       - any(mask) 为 False → label = 0

清盘基金处理：NumPy 切片在数组越界时自动截断。清盘基金的有效窗口短于 150 周，若截断前未触发止盈则 any(mask) 为 False，标签自动为 0。无需额外逻辑。

3.3 样本平衡机制¶

四、特征系统¶

4.1 特征目录（共约 40+ 维）¶

A. 均值回归类¶

B. 波动类¶

C. 趋势与动量类¶

D. 定投特有类¶

E. 风险调整类¶

4.2 窗口有效值判定¶

• 对每个滚动窗口特征，计算窗口内非 NULL 值的数量
• 有效值 < window_size × min_valid_ratio（默认 0.20） → 特征值输出 NULL
• 示例：52 周窗口至少需要 11 个有效值（52 × 0.2 = 10.4，向上取整）

4.3 截面标准化（T-1 严格模式）¶

分四步严格执行：

1. 计算统计量：计算每个日期截面的均值、标准差、中位数、MAD。
2. 时间对齐：将统计量整体 shift(1)，即 T 日的标准化参数使用 T-1 日截面的统计量。首日（数据集第一天）无 T-1 可用，该日所有标准化特征输出 NULL。
3. Z-Score：将 shifted 统计量 Join 回主表，执行 z_score = (raw_feature - T1_mean) / T1_std。
4. MAD 去极值：
   median = T1 截面中位数
mad = median(|x - median|) × 1.4826
clip z_score to [median - 3×mad, median + 3×mad]
   持久化：每个时间截面的标准化参数独立保存为 standardization_params.parquet：
   | 字段 | 类型 | 说明 |
   |------|------|------|
   | date | Date | 截面日期（即统计量的来源日期） |
   | feature_name | String | 特征名 |
   | mean | Float64 | 截面均值 |
   | std | Float64 | 截面标准差 |
   | median | Float64 | 截面中位数 |
   | mad | Float64 | 截面 MAD |
   推理时加载该文件的最新行，对输入特征做同样的 Z-Score + MAD clip。

4.4 特征共线性剔除¶

五、模型训练¶

5.1 训练数据流¶

features.parquet (按年分区)
       │ Polars: 读取并合并
       ▼
labels.parquet
       │ Polars: LEFT JOIN (on fund_id + date)
       ▼
train_dataset.parquet
schema: fund_id | date | feature_1 | ... | feature_K | label

缺失值处理：特征 NULL 在 LightGBM 内部自动处理（设为缺失值，树模型原生支持），不做预填充。

5.2 交叉验证¶

• 使用 TimeSeriesSplit(n_splits=5)
• 严禁 随机 K-Fold
• 每一折的训练集内部独立执行：截面标准化 → 共线性筛选
• 验证集仅使用对应训练折产出的标准化参数

5.3 Optuna 超参搜索¶

5.4 评估指标体系¶

模型层：

1. 用模型对所有候选基金打分
2. 按得分分四桶：Top 20 / Top 21-50 / Top 51-100 / 其余
3. 每桶模拟等权周定投组合（每周投入 20 元均分到该桶基金）
4. 追踪组合净值，计算：
   | 回测指标 | 说明 |
   |----------|------|
   | 年化收益率 | 定投组合的实际年化回报 |
   | 最大回撤 | 组合净值的最大峰谷跌幅 |
   | Sharpe Ratio | 风险调整后收益 |
   | Calmar Ratio | 年化收益 / 最大回撤 |
   | 止盈成功率 | 150 周内达到 20% 定投收益率的比例 |
5. 基准对照：全标的池等权随机组合的相同指标

5.5 MLflow 实验记录¶

每次训练自动记录：

• Optuna 最优超参数
• 模型层指标（AUC、NDCG）+ 业务层回测指标
• LightGBM 模型文件（.txt）
• config.yaml 快照
• final_feature_list.json
• standardization_params.parquet
• SHAP summary plot（图片）
• 各分桶回测净值曲线（图片）
  模型通过 MLflow Model Registry 管理，新模型打 Production 标签后直接替换推理服务加载的模型版本，旧版本归档至 Archived。

六、推理服务¶

6.1 输入输出¶

6.2 推理流程¶

输入净值 → Polars 读入
       ▼
特征计算（复用 Module3 逻辑，单基金精简版）
       ▼
加载 standardization_params.parquet（最新一周参数）
       ▼
T-1 参数做 Z-Score + MAD clip
       ▼
加载 LightGBM Production 模型 → 预测概率
       ▼
score = round(概率 × 100) → 0-100 整数分
       ▼
SHAP TreeExplainer → 单样本特征归因
       ▼
输出：得分 + Top5正向特征 + Top5负向特征 + 决策建议文本

6.3 决策建议文本生成规则¶

七、工程质量规范¶

7.1 目录结构¶

project-root/
├── pyproject.toml
├── config/
│   └── config.yaml
├── data/
│   ├── raw/                # 原始 CSV / Parquet
│   ├── processed/          # 清洗后 Parquet（按年分区）
│   ├── features/           # 特征矩阵 Parquet（按年分区）
│   ├── models/             # 模型文件 & 标准化参数
│   └── metadata/           # SHA-256 hash 校验文件
├── src/
│   ├── __init__.py
│   ├── utils/
│   │   ├── __init__.py
│   │   ├── config.py       # YAML 配置加载器
│   │   ├── logging.py      # 结构化日志配置
│   │   └── hash.py         # SHA-256 数据血缘校验
│   ├── data_loader.py      # 数据清洗与入库
│   ├── feature_engineering.py # 特征计算引擎
│   ├── label_generator.py  # 标签生成器
│   ├── trainer.py          # 模型训练与评估
│   └── inference.py        # 推理服务
├── tests/
│   ├── test_label_generator.py
│   └── test_feature_engineering.py
├── mlruns/                 # MLflow 实验追踪
└── logs/                   # 运行日志

7.2 配置与代码分离¶

所有硬参数集中在 config.yaml，代码中严禁魔法数字。核心参数分区如下：

# === 标签参数 ===
label:
  target_return: 0.20
  max_weeks: 150
  deduction_method: "simple_avg" # 预留: "irr"
  deduct_fee: false
  purchase_fee_rate: 0.0012
# === 数据过滤 ===
filter:
  fund_type_whitelist:
    - "股票型"
    - "混合型-偏股"
    - "混合型-灵活"
    - "QDII-普通股票"
    - "QDII-混合偏股"
    - "QDII-混合灵活"
  min_net_value_weeks: 52
  building_period_weeks: 12
  max_gap_weeks: 4
  single_week_change_limit: 0.50
# === 特征参数 ===
feature:
  windows:
    mean_reversion: [12, 26, 52]
    volatility: [12, 26, 52]
    momentum: [4, 12, 26, 52]
    trend: [26, 52]
    dca_specific: [12, 26, 52]
    risk_adjusted: [26, 52]
  min_valid_ratio: 0.20
  outlier_method: "mad"
  outlier_bound: 3.0
# === 截面标准化 ===
standardization:
  method: "zscore"
  use_shift_1: true # 使用 T-1 截面统计量
# === 样本平衡 ===
sample_balance:
  max_samples_per_fund: 50
  zero_label_ratio: 0.3 # label=0 的上限比例
# === 模型训练 ===
model:
  time_series_n_splits: 5
  optuna_budget: 200
  optuna_timeout_hours: 1
# === 风险 ===
risk_free_rate:
  annual: 0.02

7.3 数据血缘¶

7.4 工程约束¶

八、实施路线图¶

按以下 6 个 Step 逐步交付，每步确认后再推进：

注：Step 3 和 Step 4 无相互依赖，可并行开发。但在流水线执行中，Step 4 的标签需要 Join 到 Step 3 的特征表，所以最终训练集的生成依赖两者都完成。

九、单元测试必覆盖场景¶

tests/test_label_generator.py 必须完整覆盖以下 7 个场景：