feature: Implement rolling training logic with state management

Author: Tonny@Home

README.md

@@ -29,7 +29,7 @@ The system strictly decouples the **Engine (Code)** from the **Workspace (Config
 
 ```text
 QuantPits/
-├── docs/                   # Detailed system manuals (00-08)
+├── docs/                   # Detailed system manuals (00-08, 30+, 70)
 ├── ui/                     # Streamlit interactive dashboards
 │   ├── dashboard.py        # Macro performance app
 │   └── rolling_dashboard.py# Temporal strategy health app
@@ -143,6 +143,7 @@ For a deep dive into each module, refer to the documentation in `docs/`:
 - `01_TRAINING_GUIDE.md`
 - `02_BRUTE_FORCE_GUIDE.md`
 - `03_ENSEMBLE_FUSION_GUIDE.md`
+- `30_ROLLING_TRAINING_GUIDE.md` (Rolling Training: Sliding Window Training)
 - ...and more.
 
 All documentation is available in both Chinese and English (`docs/en/`).

README_zh.md

@@ -29,7 +29,7 @@
 
 ```text
 QuantPits/
-├── docs/                   # 详细的系统开发及应用操作手册（00-08）
+├── docs/                   # 详细的系统开发及应用操作手册（00-08, 30+, 70）
 ├── ui/                     # 交互式数据图表面板
 │   ├── dashboard.py        # 宏观资管业绩评估 Streamlit 面板
 │   └── rolling_dashboard.py# 时序策略执行健康监测 Streamlit 面板
@@ -143,6 +143,7 @@ python -m quantpits.scripts.init_workspace \
 - `01_TRAINING_GUIDE.md` (全量训练及模型配置向导)
 - `02_BRUTE_FORCE_GUIDE.md` (穷举回测及GPU加速矩阵操作向导)
 - `03_ENSEMBLE_FUSION_GUIDE.md` ...以此类推。
+- `30_ROLLING_TRAINING_GUIDE.md` (滚动训练：滑动窗口训练、冷启动、断点恢复)
 
 所有文档均已提供中文与纯正的英文(`en/`)双语版本支持。
 

docs/00_SYSTEM_OVERVIEW.md

@@ -50,6 +50,10 @@ flowchart TB
         IT["incremental_train.py<br/>增量训练"]
     end
 
+    subgraph ROLLING["⑨ 滚动训练（按需）"]
+        RT["rolling_train.py<br/>冷启动/日常/预测"]
+    end
+
     subgraph PREDICT["② 预测（每次）"]
         PO["prod_predict_only.py<br/>仅预测"]
     end
@@ -81,15 +85,20 @@ flowchart TB
 
     REG["model_registry.yaml<br/>模型注册表"]
     LTR["latest_train_records.json<br/>训练记录"]
+    LRR["latest_rolling_records.json<br/>滚动训练记录"]
     PRED_CSV["output/predictions/<br/>预测 CSV"]
     WC["prod_config.json<br/>持仓/现金"]
 
     REG --> TRAIN
     REG --> PREDICT
+    REG --> ROLLING
     TRAIN --> LTR
     PREDICT --> LTR
+    ROLLING --> LRR
     LTR --> BRUTEFORCE
     LTR --> FUSION
+    LRR -.->|--record-file| BRUTEFORCE
+    LRR -.->|--record-file| FUSION
     FUSION --> PRED_CSV
     PREDICT --> PRED_CSV
     PRED_CSV --> ORDERGEN
@@ -198,6 +207,24 @@ python quantpits/scripts/ensemble_fusion.py \
 # ⑤⑥ 同上
 ```
 
+### 场景 E：滚动训练（适应市场风格漂移）
+
+当静态模型预测质量因市场风格变化而衰减时，使用滚动训练让模型持续适应。
+
+```bash
+# ⑨ 冷启动：首次滚动训练
+python quantpits/scripts/rolling_train.py --cold-start --all-enabled
+
+# ③④ 穷举 + 融合（使用滚动预测）
+python quantpits/scripts/brute_force_fast.py --record-file latest_rolling_records.json
+python quantpits/scripts/ensemble_fusion.py \
+  --from-config --record-file latest_rolling_records.json
+
+# ⑤⑥ Post-Trade + 订单生成（同其他场景）
+```
+
+> 日常运行只需：`python quantpits/scripts/rolling_train.py --all-enabled`（自动判断训练/预测）
+
 ---
 
 ## 模块速查
@@ -217,6 +244,19 @@ python quantpits/scripts/ensemble_fusion.py \
 - 训练记录修改前自动备份到 `data/history/`
 - 增量训练支持 `--resume`（断点续训）和 `--dry-run`（预览）
 
+### ⑨ 滚动训练模块
+
+> 详见 [30_ROLLING_TRAINING_GUIDE.md](30_ROLLING_TRAINING_GUIDE.md)
+
+| 脚本 | 用途 | 保存语义 |
+|------|------|----------|
+| `rolling_train.py` | 滑动窗口训练 + 预测拼接 | **独立** `latest_rolling_records.json` |
+
+- 与静态训练完全独立，共存于同一 Workspace
+- 支持冷启动、日常模式（自动判断训练/预测）、仅预测、断点恢复
+- 下游通过 `--record-file latest_rolling_records.json` 无缝切换数据源
+- 配置文件：`config/rolling_config.yaml`（起点、训练年数、验证年数、步长）
+
 ### ② 预测模块
 
 > 详见 [05_PREDICT_ONLY_GUIDE.md](05_PREDICT_ONLY_GUIDE.md)
@@ -350,13 +390,15 @@ python quantpits/scripts/ensemble_fusion.py \
 | `prod_config.json` | 实盘与状态层：持仓、现金、处理时间 | Post-Trade、订单生成 |
 | `cashflow.json` | 出入金记录：按日期的出入金 | Post-Trade |
 | `ensemble_config.json` | 多组合融合配置：combo 定义、权重、default | 融合预测、订单生成、信号排名 |
+| `rolling_config.yaml` | 滚动训练参数：起点、训练/验证年数、步长 | 滚动训练 |
 | `workflow_config_*.yaml` | Qlib 工作流：各模型的训练配置 | 训练 |
 
 ### 输出文件 (`output/`)
 
 | 目录/文件 | 用途 |
 |-----------|------|
 | `predictions/*.csv` | 各模型和 ensemble 的预测结果（多 combo 带组合名） |
+| `predictions/rolling/` | 滚动训练预测（per-window CSV + 拼接 CSV） |
 | `brute_force/` | 暴力穷举精确回测结果和分析报告 |
 | `brute_force_fast/` | 快速穷举结果 |
 | `ensemble/` | 融合配置、排行榜、图表、跨组合对比 |
@@ -373,6 +415,8 @@ python quantpits/scripts/ensemble_fusion.py \
 | `history/` | 自动备份的历史文件 |
 | `order_history/` | 历史订单建议、交易明细、交易软件导出表（由归档脚本管理） |
 | `run_state.json` | 增量训练运行状态（支持断点续跑） |
+| `rolling_state.json` | 滚动训练状态（断点恢复用） |
+| `latest_rolling_records.json` | 滚动训练记录（下游 `--record-file` 使用） |
 | `trade_log_full.csv` | 累计交易日志（含买入和卖出） |
 | `holding_log_full.csv` | 累计持仓日志 |
 | `daily_amount_log_full.csv` | 每日资金汇总 |
@@ -398,6 +442,7 @@ python quantpits/scripts/ensemble_fusion.py \
 | 06 | [ORDER_GEN_GUIDE](06_ORDER_GEN_GUIDE.md) | 订单生成、买卖建议输出 |
 | 07 | [SIGNAL_RANKING_GUIDE](07_SIGNAL_RANKING_GUIDE.md) | 信号排名 Top N 推荐 |
 | 08 | [ANALYSIS_GUIDE](08_ANALYSIS_GUIDE.md) | 单模型质量、融合相关性、执行滑点成本及多维组合风险综合评测 |
+| **30** | **[ROLLING_TRAINING_GUIDE](30_ROLLING_TRAINING_GUIDE.md)** | **滚动训练：时间窗口滑动训练、冷启动、断点恢复** |
 | 70 | [WALKTHROUGH](70_WALKTHROUGH.md) | **端到端实战操作手册（从这里开始！）** |
 
 ---

docs/30_ROLLING_TRAINING_GUIDE.md

@@ -0,0 +1,235 @@
+# 滚动训练指南 (Rolling Training)
+
+> 30 系列文档专注于**非静态训练**逻辑——即训练窗口随时间推进而滚动的训练范式。
+
+---
+
+## 概述
+
+传统静态训练（`prod_train_predict.py`、`incremental_train.py`）使用**固定的日期区间**训练模型。当市场风格发生漂移时，静态模型的预测质量会逐渐衰减。
+
+**滚动训练 (Rolling Training)** 通过将时间轴切分为多个滑动窗口，在每个窗口上独立训练模型，从而使模型始终适应最新的市场状态。
+
+### 静态 vs. 滚动
+
+| 特性 | 静态训练 | 滚动训练 |
+|------|---------|---------|
+| 训练区间 | 固定（如 2015–2022） | 滑动窗口（每窗口独立训练） |
+| 模型数量 | 每模型 1 个 | 每模型 × N 个窗口 |
+| 适应性 | 低（依赖长期统计特征） | 高（随市场风格滑动更新） |
+| 预测输出 | 单段连续预测 | 多段拼接（自动拼接为连续文件） |
+| 下游兼容性 | `latest_train_records.json` | `latest_rolling_records.json`（通过 `--record-file` 切换） |
+
+### 共存架构
+
+滚动训练与静态训练**完全独立**，共存于同一 Workspace：
+
+```text
+output/
+├── predictions/               # 静态训练预测
+│   └── rolling/               # 滚动训练预测（per-window CSV + 拼接 CSV）
+data/
+├── latest_train_records.json  # 静态训练记录
+├── latest_rolling_records.json# 滚动训练记录
+└── rolling_state.json         # 滚动训练运行状态（中间态，断点恢复用）
+```
+
+---
+
+## 核心脚本
+
+| 脚本 | 用途 |
+|------|------|
+| `rolling_train.py` | 滚动训练主脚本：冷启动、日常模式、仅预测、断点恢复 |
+
+---
+
+## 时间窗口划分
+
+### 配置参数
+
+在 `config/rolling_config.yaml` 中配置：
+
+```yaml
+rolling_start: "2020-01-01"   # T: 起始日期
+train_years: 3                # X: 训练区间（整数年）
+valid_years: 1                # Y: 验证区间（整数年）
+test_step: "3M"               # Z: 测试步长（nM 或 nY）
+```
+
+### 划分公式
+
+对于第 `n` 个窗口（从 0 开始）：
+
+```
+Train: [T + nZ,       T + X + nZ − 1d]
+Valid: [T + X + nZ,   T + X + Y + nZ − 1d]
+Test:  [T + X + Y + nZ, T + X + Y + (n+1)Z − 1d]
+```
+
+> [!IMPORTANT]
+> **绝对不重叠**：训练、验证、测试三段之间没有任何日期重叠，包括端点。`train_end + 1d = valid_start`，`valid_end + 1d = test_start`。
+
+### 示例
+
+`T=2020-01-01, X=3年, Y=1年, Z=3M`：
+
+| 窗口 | 训练区间 | 验证区间 | 测试区间 |
+|:---:|---------|---------|---------|
+| W0 | 2020-01-01 ~ 2022-12-31 | 2023-01-01 ~ 2023-12-31 | 2024-01-01 ~ 2024-03-31 |
+| W1 | 2020-04-01 ~ 2023-03-31 | 2023-04-01 ~ 2024-03-31 | 2024-04-01 ~ 2024-06-30 |
+| W2 | 2020-07-01 ~ 2023-06-30 | 2023-07-01 ~ 2024-06-30 | 2024-07-01 ~ 2024-09-30 |
+| W3 | 2020-10-01 ~ 2023-09-30 | 2023-10-01 ~ 2024-09-30 | 2024-10-01 ~ 2024-12-31 |
+
+最后一个窗口的 `test_end` 自动截断至 `anchor_date`（Qlib 最新交易日）。
+
+---
+
+## 运行模式
+
+### 模式一：冷启动
+
+**首次运行必须执行冷启动。** 生成所有 windows 并逐个训练。
+
+```bash
+# 全量冷启动
+python quantpits/scripts/rolling_train.py --cold-start --all-enabled
+
+# 指定模型
+python quantpits/scripts/rolling_train.py --cold-start --models linear_Alpha158
+
+# Dry-run: 仅查看窗口划分
+python quantpits/scripts/rolling_train.py --cold-start --dry-run --all-enabled
+```
+
+冷启动流程：
+1. 从 `rolling_config.yaml` 读取参数
+2. 生成所有 rolling windows（到 anchor_date 为止）
+3. 对每个 window × 每个模型执行训练 + 预测
+4. 拼接所有 windows 的预测为连续时间序列
+5. 保存 `latest_rolling_records.json`
+
+### 模式二：日常模式
+
+自动检测是否有新 window 需要训练：
+- **有新 window** → 训练新 window + 重新拼接
+- **无新 window** → 使用最近模型执行预测
+
+```bash
+python quantpits/scripts/rolling_train.py --all-enabled
+```
+
+### 模式三：仅预测
+
+使用最近一个 window 训练的模型对最新数据预测：
+
+```bash
+python quantpits/scripts/rolling_train.py --predict-only --all-enabled
+```
+
+### 断点恢复
+
+训练中断时，自动跳过已完成的 window × model：
+
+```bash
+python quantpits/scripts/rolling_train.py --resume
+```
+
+### 状态查看
+
+```bash
+# 查看当前状态
+python quantpits/scripts/rolling_train.py --show-state
+
+# 清除状态（重新开始）
+python quantpits/scripts/rolling_train.py --clear-state
+```
+
+---
+
+## 模型选择
+
+与静态训练一致，支持所有模型筛选方式：
+
+| 参数 | 说明 |
+|------|------|
+| `--models m1,m2` | 按名称指定 |
+| `--algorithm alg` | 按算法筛选 |
+| `--dataset ds` | 按数据集筛选 |
+| `--tag tag` | 按标签筛选 |
+| `--all-enabled` | 所有 enabled 模型 |
+| `--skip m1,m2` | 排除指定模型 |
+
+---
+
+## 下游衔接
+
+滚动训练的预测结果通过 `--record-file` 参数无缝衔接下游脚本：
+
+```bash
+# 穷举
+python quantpits/scripts/brute_force_fast.py \
+  --record-file latest_rolling_records.json
+
+# 融合
+python quantpits/scripts/ensemble_fusion.py \
+  --from-config --record-file latest_rolling_records.json
+```
+
+> [!TIP]
+> 静态和滚动训练的下游流程完全相同，仅通过 `--record-file` 切换数据来源。默认值为 `latest_train_records.json`（静态），指定 `latest_rolling_records.json` 即切换到滚动。
+
+---
+
+## 状态管理与断点恢复
+
+`rolling_state.json` 记录训练进度，结构如下：
+
+```json
+{
+    "started_at": "2025-03-14 10:00:00",
+    "rolling_config": {"test_step": "3M", ...},
+    "anchor_date": "2025-03-14",
+    "total_windows": 4,
+    "completed_windows": {
+        "0": {"linear_Alpha158": "rec_001", "gru_Alpha158": "rec_002"},
+        "1": {"linear_Alpha158": "rec_003"}
+    }
+}
+```
+
+- 每完成一个 window × model，立即保存状态
+- 中断后使用 `--resume` 恢复，自动跳过已完成项
+- `--clear-state` 清除状态重新开始（旧状态自动备份到 `data/history/`）
+
+---
+
+## MLflow 实验命名
+
+| 实验名 | 内容 |
+|--------|------|
+| `Rolling_Windows_{FREQ}` | 各 window 的单独训练记录 |
+| `Rolling_Combined_{FREQ}` | 拼接后的完整预测记录 |
+
+其中 `{FREQ}` 为交易频率（如 `WEEK`、`DAY`）。
+
+---
+
+## 配置文件参考
+
+`config/rolling_config.yaml` 完整示例：
+
+```yaml
+# Rolling Training Configuration
+# 滚动训练配置
+
+rolling_start: "2020-01-01"   # T: 起始日期
+train_years: 3                # X: 训练区间长度（整数年）
+valid_years: 1                # Y: 验证区间长度（整数年）
+test_step: "3M"               # Z: 测试步长
+                              #   - nM: n 个月 (如 3M, 6M)
+                              #   - nY: n 年 (如 1Y)
+```
+
+> [!CAUTION]
+> `train_years` 和 `valid_years` 必须为**整数年**。`test_step` 必须为 `nM`（整数月）或 `nY`（整数年），不支持小数。