量化研究手册 (Quantitative Research Handbook)

专业量化投研与工程实战体系
从数据工程、因子挖掘、机器学习到指增实盘闭环

《量化研究手册》是一套面向专业量化投研与工业级工程实现教程。全套教程涵盖 8 大核心模块、31 讲深度专题，配备完整的交互式网页文档，以及 31 个开箱即用的独立 Python 实战脚本与全套离线单元测试。

本项目面向具备 Python 编程基础、渴望系统建立买方/私募机构级量化投资与全流程工程闭环的研究员与开发者，彻底打通“数据清洗 $\rightarrow$ PIT 治理 $\rightarrow$ 特征工程 $\rightarrow$ 因子评估 $\rightarrow$ 机器学习 $\rightarrow$ 风险模型 $\rightarrow$ 组合优化 $\rightarrow$ 全真撮合 $\rightarrow$ 归因监控”的完整链路。

flowchart LR
    A["01 认知与基础设施\n(A股规则与现代栈)"] --> B["02 数据工程与防泄漏\n(PIT财报与动态Universe)"]
    B --> C["03 特征与高频低频化\n(价量/基本面/微观OFI)"]
    C --> D["04 工业级因子评价\n(IC/IR/单调性/正交化)"]
    D --> E["05 截面与时序 ML\n(Purged CV/LightGBM)"]
    E --> F["06 Barra与组合优化\n(风险模型/cvxpy约束)"]
    F --> G["07 全真回测与交易摩擦\n(涨跌停限制/冲击成本)"]
    G --> H["08 归因监控与实盘落地\n(归因/风险控制/恢复演练)"]

1. 立足 A 股微观制度与实盘约束
   • 深入建模 A 股特有的 T+1 机制、涨跌停板（±10% / ±20% / ±30%）限制与不可成交逻辑、停牌与退市处理、红利送转与除权除息四时点账本，以及印花税与市场冲击成本，拒绝脱离实盘的“玩具回测”。
2. 严密的 Point-in-Time (PIT) 数据治理架构
   • 严格区分信息的生效时间（effective_date）与策略可见时刻（available_at），支持财务报告多次更正历史回溯，从数据根源彻底消除前瞻偏差（Lookahead Bias）与幸存者偏差（Survivorship Bias）。
3. 拥抱现代高性能量化工程栈
   • 全面采用 Polars（向量化表达式与高速并行）与 DuckDB（极速嵌入式分析）替代传统低效的 Pandas 单线程计算，支持千万级高频与截面数据秒级聚合。
4. 买方级量化机器学习与凸优化组合构建
   • 严格落实 Purged / Embargo K-Fold 时序交叉验证；基于 RankReturnCalibrator 校准收益预测；构建 Barra 多因子结构化风险模型；使用 cvxpy 实施年化跟踪误差（TE）硬上限与换手冲击惩罚的凸优化求解。
5. 100% 离线自包含可复现验证
   • 31 讲全部具备独立可执行源码及合成测试夹具（fixtures.py、common.py），无需购买商业数据即可一键执行全套自动化回归测试（npm run test:examples）。

本课程包含 8 大模块、31 讲，每讲均配套独立 Python 源码与契约验证：

• Python：>= 3.11, < 3.14
• Node.js：>= 18
• 包管理器推荐：uv（现代极速 Python 包管理工具）与 npm

# 1. 安装前端文档依赖
npm ci

# 2. 启动本地开发服务 (支持热更新，默认访问 http://localhost:5173)
npm run dev

# 3. 构建静态站点产物
npm run build

# 4. 本地预览构建产物
npm run preview

本项目推荐使用 uv 进行可复现的环境锁管理（依赖已完全锁定于 uv.lock）。

# 基础依赖同步 (涵盖 25 个核心讲次)
uv sync --locked

# 全量依赖同步 (包含机器学习、深度学习与凸优化求解器)
uv sync --locked --extra ml --extra deep --extra optimization

运行单个实战示例模块（必须在项目根目录下以 -m 模块模式运行）：

# 运行基础示例（如第 8 讲：手写 A 股 PIT 检索引擎）
uv run --locked python -m examples.lecture_08_pit_engine_practice

# 运行机器学习选股流水线（第 22 讲，需 --extra ml）
uv run --locked --extra ml python -m examples.lecture_22_ml_stock_selection_pipeline

# 运行组合换手约束与凸优化（第 25 讲，需 --extra optimization）
uv run --locked --extra optimization python -m examples.lecture_25_turnover_constraints_and_costs

# 运行全真事件驱动回测引擎（第 27 讲）
uv run --locked python -m examples.lecture_27_vectorized_vs_event_driven_backtest

# 运行实盘监控看板与熔断预警（第 31 讲）
uv run --locked python -m examples.lecture_31_live_monitoring_risk_dashboard

uv sync --locked --extra data
uv run --locked --extra data python -m examples.lecture_04_industrial_data_pipeline --fetch

项目配备了完整的契约与数学逻辑单元测试，所有测试均使用内建合成数据，无需联网：

# 执行全套回归测试
npm run test:examples

# 或直接调用 uv 执行 unittest：
uv run --locked --extra ml --extra deep --extra optimization python -m unittest discover -s tests -v

测试套件分类说明：

• tests/test_tutorial.py：覆盖模块 01–02（数据湖原子写盘、前瞻偏差诊断、PIT 历史多版本检索与动态 Universe）。
• tests/test_factor_modules.py：覆盖模块 03–04（量价微观 OFI、WLS 加权正交、共线性拦截、IC/IR 统计、单调性与未成交现金排查）。
• tests/test_ml_risk_modules.py：覆盖模块 05–06（Purged CV 时间隔离、SHAP 贡献加和、Barra 风险模型、TE 约束凸优化求解）。
• tests/test_execution_monitoring.py：覆盖模块 07–08（复式记账守恒、开盘不可成交限制、红利送转四时点演化、Brinson 归因闭合与风控滞回熔断）。

在模块 02（第 4–8 讲）中，项目定义了标准的工业级共享数据契约。后续所有特征挖掘、模型训练及回测撮合均严格遵照此契约执行：

• 日期字段：统一采用 pl.Date。
• 高频与事件时间戳：必须统一采用 Asia/Shanghai 本地无时区 pl.Datetime。外部带时区时间必须先转换为上海时间再剔除时区，严禁直接丢弃 UTC 时区标识。
• 数值与状态：价格、成交量为非负浮点或整型，状态一律采用布尔值 Boolean。

• effective_date vs available_at：
  • effective_date 为状态在现实中实际生效的业务日期。
  • available_at 为该信息经由上游数据源处理后、量化系统真正可知并可下单的客观物理时间。二者决不可混同。
• 上市交易天数规则：
  • 上市交易天数按交易所开市日逐日计数，包含停牌期间，绝对不等于已下载行情记录行数。日历缺失立即报错。
• 动态池候选资格 (in_universe)：
  • 仅表示该标的在此截面具备选股候选资格，不代表持仓被剔除后可以立即按最新价变现。
• 收盘截面 15:00 假设：
  • PIT 引擎模拟盘后选股，假定 15:00 日线行情已形成。实际生产环境应计入数据入库延迟，所生成的信号最早于次日开盘时段执行。

• 版本选择规则：财报查询时先按指定时刻过滤 available_at <= query_time，再取每个报告期当前可见的最新更正版本。更新历史年报不会导致当前季度财务指标退回旧期。
• 行情文件存储：按 (symbol, trade_date) 保证主键唯一，写盘前严格检查有限值与 $Low \le Open, Close \le High$ 关系；年度 Parquet 文件采用临时文件原子替换（Atomic Rename），避免写入中断损坏数据。

• 收益率口径：计算跨日收益必须使用后复权价格 close_hfq。财务同比增速不应冒充超预期 SUE 指标。
• 高频微观结构：第 11 讲 OFI 严格采用本地无时区时间戳，不支持跨交易日平滑衔接；定时快照（Snapshot）不等于逐笔委托事件（Tick by Tick）。
• 正交化与中性化：第 12 讲使用 NumPy 求解加权最小二乘（WLS），验证残差与约束向量的加权正交；第 13 讲正交化前对常数列与共线输入显式报错，杜绝虚假独立因子。
• 评估隔离：第 14–15 讲标签必须由调用方按实际信号产生与成交时点对齐；第 17 讲排查伪 Alpha 时，未成交委托必须保留为现金，杜绝“一字涨停虚构暴利”。

• 时间隔离：训练集与测试集必须施加 Purged 与 Embargo 机制；严禁使用未来信息拟合数据预处理变换器（如 Scaler/Imputer）。
• 收益校准：树模型的排序输出（LambdaRank 分数）不能直接作为预期收益率输入给优化器，必须通过 RankReturnCalibrator 拟合成熟历史样本外的持有期超额收益。
• Barra 与优化求解：
  • 风险模型接收 $(T, N, K)$ 历史期初暴露面板与独立的当前期初暴露。
  • 优化器使用 Clarabel 凸优化求解器处理年化跟踪误差（TE）二次硬约束，求解后自动校验对偶残差与可行性。
• 进程隔离注意事项：

  [!WARNING] 在已训练 LightGBM 的同一 Python 进程中执行 PyTorch 深度学习模型可能引发底层 OpenMP / 卷积线程池阻塞。第 21 讲与深度模型测试建议在独立进程中调用。

• 撮合纪律：次日开盘撮合严禁读取当日最高价、最低价或收盘价。成交数量受当日成交量占比上限（ADV Limit）硬约束，未成交订单继续保留于持仓或资金中，当日成交股份严格受 T+1 锁定。
• 红利送转四时点演化：股权登记日收盘锁定权益，除权除息日确认应收红利与锁定送股，红利发放日与送股上市日分别释放可用资金与可用股份，实现账本幂等。
• 归因闭合与风控滞回：第 30 讲归因显式纳入现金留存与交易手续费，确保组合收益与归因分项严格等式闭合；第 31 讲风控监控实行滞回熔断机制，触发三级最高预警后禁止新开买单，且必须经显式条件复位并记录审批引用。

quant-handbook/
├── .vitepress/              # VitePress 站点配置、Mermaid 插件与课程目录定义
│   ├── config.mts           # 站点全局配置与导航
│   └── curriculum.ts        # 8 大模块 31 讲大纲数据源
├── examples/                # 31 讲独立 Python 源码与公共工具库
│   ├── common.py            # 数据契约核验与通用断言
│   ├── fixtures.py          # 离线合成数据集生成器
│   ├── factor_utils.py      # 因子计算与加权中性化工具
│   ├── ml_utils.py          # 机器学习验证与收益校准工具
│   ├── portfolio_utils.py   # 组合优化与风险归因工具
│   ├── lecture_01_*.py      # 第 1 讲配套可运行示例
│   └── ...                  # 第 2 ~ 31 讲对应示例源码
├── module_01/ ~ module_08/  # 31 讲详细教程 Markdown 正文
├── tests/                   # 自动化回归测试套件 (100% 离线通过)
│   ├── test_tutorial.py             # 模块 01–02 单元测试
│   ├── test_factor_modules.py       # 模块 03–04 单元测试
│   ├── test_ml_risk_modules.py      # 模块 05–06 单元测试
│   └── test_execution_monitoring.py # 模块 07–08 单元测试
├── index.md                 # 网站主页
├── learning_path.md         # 学习路径、入门自测与逐章掌握标准
├── resources.md             # 公开权威书目、大学课程与官方规则导读
├── syllabus.md              # 完整课程体系全景大纲
├── package.json             # 前端与全局测试脚本定义
├── pyproject.toml           # Python 项目依赖与 Extras 配置
└── uv.lock                  # 依赖精确锁定文件

• 学习路径与逐章掌握标准：提供量化六大基础入门自测题、三条并行学习线以及逐讲交付证据核验清单。
• 公开资源与权威书目导读：收录 MIT 18.06（线性代数）、Boyd 凸优化、上交所最新交易规则、AKShare 接口规范等核验清单。
• 课程全景体系大纲：31 讲完整知识图谱、各讲设计思路与进阶目标。

• 现代工程栈：Polars 官方文档 · DuckDB 官方文档 · uv 包管理器
• 优化与建模：CVXPY 凸优化库 · LightGBM 文档 · SHAP 可解释性
• 市场制度与基准：上交所交易规则 · 中证指数计算与维护细则 · AKShare 开源财经数据

量化研究求真务实 · 严谨敬畏市场 · 构建稳健复利