# quant_engine

> 量化研究引擎 —— alpha 因子库 + 执行仿真 + 技术指标 + 数据适配 + 回测工具

**从 `research_results` 抽出的纯回测能力库**（v1.2.0 重构）。

## 角色

`quant_engine` 是 researchhub_workspace 的**引擎层**：

| 仓库 | 角色 |
|---|---|
| `quant_engine` | **纯回测核心**（alpha + execution + indicators + data_adapter + backtest + metrics） |
| `research_results` | 业务集成（47 个 proj 调度 + 注册 + 平台对接） |
| `tushare2db_pro_aoge` | 数据层（行情 ELT） |
| `research_platform` | 展示层（FastAPI + Next.js） |
| `edb_data_core` | 数据层（经济数据） |

## 模块

- `alpha_factors` — 158 alpha 公式 + 24 基础算子（移植自 qlib alpha158）
- `execution` — A 股长仓执行仿真（成本/滑点/现金约束）+ 稀疏调仓/完整交易日 Ledger + 可投影成交与 NAV 审计；T+1、涨跌停、成交量与价差提供独立约束函数
- `indicators` — 50+ 技术指标（MACD / KDJ / 布林 / ATR / ADX / 等）
- `data_adapter` — 桥接 qtdb_pro 长表与新模块（rename / long-wide / 复权 / vwap 代理）
- `backtest` — weight-based 多日仿真（rebalance_table / compute_nav / compare_to_benchmark）
- `portfolio_construction` — 多期因子分数 → Top-K → 等权目标权重表
- `research_pipeline` — 因子日 → 下一真实交易日 → 显式执行价 → 日末估值 → 成本后绩效（防前视编排）
- `metrics` — 绩效（年化收益 / 波动率 / Sharpe / 最大回撤 / Calmar）
- `factor_library` — 通用方法（turnover / winsorize / IC / OLS / jb_test）
- `portfolio_decomp` — 组合分解（risk_parity / mean_variance / 因子归因）
- `risk` — 风险指标（边际 / 风险贡献）
- `perf_stats` — 详细绩效（与 metrics 并存）
- `logging` — 统一 logger（标准库 + 可选 loguru）

## 依赖

- 必需：numpy / pandas / scipy（标准量化栈）
- 可选：loguru（logback，标准库 logging 兜底）

**零重型依赖** —— 不引入 torch / lightgbm / hikyuu 等。

## 安装

```bash
cd quant_engine
pip install -e ".[dev]"
```

## 测试

```bash
pytest                    # 单元测试
pytest --cov=src          # 覆盖率
mypy --strict src/        # 类型检查
ruff check src/ tests/    # lint
```

## 使用

```python
from quant_engine.alpha_factors import alpha_001, alpha_005, ALPHA158_REGISTRY
from quant_engine.execution import (
    ExecutionConfig, simulate_daily_ledger_with_audit,
    simulate_multi_day_with_audit, simulate_with_daily_data,
)
from quant_engine.research_pipeline import (
    run_factor_backtest_research, run_factor_execution_research,
)
from quant_engine.backtest import run_weight_backtest
from quant_engine.indicators import macd, bollinger, kdj
from quant_engine.data_adapter import (
    long_to_wide, wide_to_long, rename_tushare_columns,
    add_vwap_proxy, apply_adj_factor,
    prepare_stock_series, prepare_execution_inputs,
    load_qtdb_daily,
)

# 端到端：qtdb_pro 长表 → 适配 → alpha158 → execution
df = load_qtdb_daily(["000001.SZ"], "2024-01-01", with_adj=True)
close_prices, volumes = prepare_execution_inputs(df)
open_prices, _ = prepare_execution_inputs(df, price_col="open")
result = simulate_with_daily_data(close_prices, initial_cash=1_000_000.0)

# 已正确滞后的目标权重 → 现金约束执行 → 唯一来源的成交/拒绝/日末持仓/NAV
execution = simulate_multi_day_with_audit(
    target_weights_history=[
        ("2024-01-02", {"000001.SZ": 1.0}),
        ("2024-01-03", {"000001.SZ": 1.0}),
    ],
    price_history=[
        ("2024-01-02", {"000001.SZ": 10.0}),
        ("2024-01-03", {"000001.SZ": 10.5}),
    ],
    initial_cash=1_000_000.0,
    config=ExecutionConfig(),
)
print(execution.nav_series)
print(execution.daily_executions)

# 多期因子分数（必须是 point-in-time 数据）→ Top-K → 下一交易日 open 执行
factor_execution = run_factor_execution_research(
    factor_scores,
    top_k=20,
    execution_prices=open_prices,
    execution_price_field="open",
    initial_cash=1_000_000.0,
)

# 推荐研究入口：同一交易日历上显式区分 open 成交和 close 估值。
# 因子日保持现金，下一交易日成交后的真实持仓才参与当日收盘收益。
factor_backtest = run_factor_backtest_research(
    factor_scores,
    top_k=20,
    execution_prices=open_prices,
    valuation_prices=close_prices,
    execution_price_field="open",
    valuation_price_field="close",
    initial_cash=1_000_000.0,
    config=ExecutionConfig(),
)
print(factor_backtest.nav)
print(factor_backtest.returns)
print(factor_backtest.stats())
print(factor_backtest.execution.ledger_frame)
print(factor_backtest.execution.trades_frame)

# run_weight_backtest 是低层算子：只接受收益区间开始前已经生效的持仓权重。
# 不要把 signal-date 的 factor_scores/decision_weights 直接传给它。
backtest = run_weight_backtest(
    weights=effective_holding_weights,
    stock_returns=daily_returns,
    initial_capital=1_000_000.0,
    benchmark_nav=benchmark_nav,
)
print(factor_execution.schedule.signal_to_execution)
print(factor_execution.execution.daily_executions)
print(backtest.stats())
print(backtest.benchmark_report())
```

## 与 research_results 的关系

`research_results` 依赖 `quant_engine`（通过 re-export 保持向后兼容）：

```python
# research_results/src/shared/alpha_factors.py 现在是：
from quant_engine.alpha_factors import *  # re-export
```

47 个 proj 的 import 路径**暂时不变**（`from src.shared.alpha_factors import ...` 仍可用）——后续逐步迁移到 `from quant_engine.alpha_factors import ...`。