Simon
92627f5b6b
- 后端业务 API：GET /api/stocks(搜索/分页)、GET /api/factors（因子目录）、POST /api/factor-tests 与 /api/backtests（Research Spec 驱动同步执行）、GET /api/backtests/last；Annotated 依赖注入 + CORS(dev) - Repository 批量查询 get_range_many（研究装配一次查询，避免逐只拉取） - 前端 frontend/web：Next.js 15(TS) + ECharts —— 总览 / 股票池 / 因子研究(IC·RankIC·分层展示) / 回测（净值·回撤·月度·持仓·未建模标注） - 前端只消费业务 API 与标准化 BacktestResult，无 Qlib/SQL 概念泄漏 - 真实数据：同步 20 只权重股 2023-2024 日线（9680 根）支撑截面研究 - 验证：API 集成测试 8 项（DTO 校验/装配/引擎/标准结果，内存 repo 全链路）+ 全量 pytest 68 passed；前端 tsc + next build 通过；无头浏览器端到端（factors/backtest 页面渲染后端数据） - ruff clean
340 lines
12 KiB
Python
340 lines
12 KiB
Python
"""LocalEngine —— 默认研究引擎（纯 pandas，AGENT.md §40 简单可替换优先）。
|
||
|
||
无未来函数纪律：
|
||
- 调仓日 t 的选股只使用 <=t 的因子值与收盘价
|
||
- 成交发生在 t 收盘（价格 = close[t] ± 滑点）；t 当日组合收益用 t-1 收盘持仓结算，
|
||
调仓在 t 收盘生效、自 t+1 起计收益 —— 不存在「当日买入当日计收益」的未来函数
|
||
- 涨跌停 / 停牌约束按可达信息近似建模，未建模部分显式写入结果 unimplemented
|
||
"""
|
||
|
||
from __future__ import annotations
|
||
|
||
import math
|
||
from dataclasses import dataclass
|
||
from datetime import date
|
||
|
||
import pandas as pd
|
||
|
||
from app.domain.entities.research import (
|
||
BacktestResult,
|
||
BacktestSummary,
|
||
CurvePoint,
|
||
FactorTestReport,
|
||
MonthlyReturn,
|
||
Position,
|
||
ResearchSpec,
|
||
Trade,
|
||
YearlyReturn,
|
||
)
|
||
from app.quant.evaluation import run_factor_test
|
||
from app.quant.factors import FactorDef, compute_factor
|
||
|
||
TRADING_DAYS = 252
|
||
_DEFAULT_UNIMPLEMENTED = [
|
||
"涨跌停按收盘价相对上一有效收盘近似判定（未建模开盘一字 / 集合竞价路径）",
|
||
"成交假设发生在调仓日收盘（未建模盘中价格路径与流动性冲击）",
|
||
]
|
||
|
||
|
||
def _limit_up_ratio(symbol: str) -> float:
|
||
"""按板块近似涨跌停幅度。"""
|
||
code = symbol[:3]
|
||
if code in {"300", "301", "688"}:
|
||
return 1.199
|
||
if code.startswith(("8", "4", "92")):
|
||
return 1.299
|
||
return 1.099
|
||
|
||
|
||
def cross_sectional_zscore(panel: pd.DataFrame) -> pd.DataFrame:
|
||
"""截面 z-score。
|
||
|
||
候选不足 2 只（如单股票池）时退化为 0：无比较基准，但保留为可候选值；
|
||
全列缺失才为 NaN（该日不可选股）。
|
||
"""
|
||
|
||
def _row_z(row: pd.Series) -> pd.Series:
|
||
valid = row.dropna()
|
||
if len(valid) == 0:
|
||
return pd.Series(float("nan"), index=row.index)
|
||
if len(valid) == 1:
|
||
return pd.Series(0.0, index=row.index)
|
||
mu, sd = valid.mean(), valid.std()
|
||
if sd == 0 or math.isnan(sd):
|
||
return pd.Series(0.0, index=row.index)
|
||
return (row - mu) / sd
|
||
|
||
return panel.apply(_row_z, axis=1)
|
||
|
||
|
||
def composite_score(
|
||
panels: list[tuple[str, pd.DataFrame, float, str]],
|
||
) -> pd.DataFrame:
|
||
"""按 (name, panel, weight, direction) 计算加权复合 zscore。
|
||
|
||
direction="lower_is_better" 的因子取负号后相加（统一为「得分高者优先」）。
|
||
"""
|
||
total = None
|
||
for _name, panel, weight, direction in panels:
|
||
z = cross_sectional_zscore(panel)
|
||
if direction == "lower_is_better":
|
||
z = -z
|
||
contribution = z * weight
|
||
total = contribution if total is None else total.add(contribution, fill_value=0)
|
||
assert total is not None
|
||
return total
|
||
|
||
|
||
def rebalance_dates(index: pd.Index, rebalance: str, start: date) -> list[pd.Timestamp]:
|
||
"""按频率取首个交易日（>= start）。"""
|
||
periods = index.to_period("M" if rebalance == "monthly" else "W")
|
||
seen: dict = {}
|
||
order: list[pd.Timestamp] = []
|
||
for ts, per in zip(index, periods, strict=True):
|
||
if per not in seen:
|
||
seen[per] = ts
|
||
order.append(ts)
|
||
return [ts for ts in order if ts.date() >= start]
|
||
|
||
|
||
@dataclass
|
||
class EngineResult:
|
||
equity: pd.Series # index=date -> equity
|
||
trades: list[Trade]
|
||
positions: list[Position]
|
||
rebalance_notional: list[float]
|
||
|
||
|
||
class TopKBacktestRunner:
|
||
"""TopK 等权、固定调仓频率的低频回测。"""
|
||
|
||
def __init__(self, spec: ResearchSpec, score: pd.DataFrame, close: pd.DataFrame) -> None:
|
||
self.spec = spec
|
||
close = close.copy()
|
||
close.index = pd.to_datetime(close.index)
|
||
self.close = close.sort_index()
|
||
self.score = score.reindex(self.close.index).sort_index()
|
||
self.costs = spec.costs
|
||
# 上一有效收盘（用于涨跌停与收益结算，处理停牌日）
|
||
self.prev_close = self.close.ffill().shift(1)
|
||
|
||
def run(self) -> BacktestResult:
|
||
end_date = self.spec.period[1]
|
||
dates = [d for d in self.close.index if self.spec.period[0] <= d.date() <= end_date]
|
||
rebal = {
|
||
d
|
||
for d in rebalance_dates(self.close.index, self.spec.rebalance, self.spec.period[0])
|
||
if d.date() <= end_date
|
||
}
|
||
cash = float(self.spec.initial_capital)
|
||
shares: dict[str, float] = {}
|
||
entry_date: dict[str, date] = {}
|
||
entry_price: dict[str, float] = {}
|
||
equity_rows: dict[pd.Timestamp, float] = {}
|
||
trades: list[Trade] = []
|
||
positions: list[Position] = []
|
||
notional: list[float] = []
|
||
|
||
def _value(d: pd.Timestamp) -> float:
|
||
total = cash
|
||
for s, qty in shares.items():
|
||
if qty <= 0:
|
||
continue
|
||
px = self.close.at[d, s] if d in self.close.index else None
|
||
if px is None or (isinstance(px, float) and math.isnan(px)):
|
||
continue # 无行情日不计该仓（停牌近似，见 unimplemented）
|
||
total += float(qty * px)
|
||
return total
|
||
|
||
for d in dates:
|
||
if d in rebal:
|
||
cash = self._rebalance(
|
||
d, cash, shares, entry_date, entry_price, trades, positions, notional
|
||
)
|
||
equity_rows[d] = _value(d)
|
||
|
||
equity = pd.Series(equity_rows).sort_index()
|
||
return self._to_result(equity, trades, positions, notional)
|
||
|
||
# ---- 调仓（t 收盘执行，自 t+1 生效） ----
|
||
|
||
def _rebalance(self, d, cash, shares, entry_date, entry_price, trades, positions, notional):
|
||
close_d = self.close.loc[d]
|
||
prev_d = self.prev_close.loc[d]
|
||
sold_notional = 0.0
|
||
|
||
# 1) 卖出：跌停或无价（停牌）持仓保留，其余卖出
|
||
for s in [s for s in shares if shares[s] > 0]:
|
||
c, p = close_d[s], prev_d[s]
|
||
if _nan(c):
|
||
continue # 停牌无价：保留
|
||
if not _nan(p) and p > 0 and c / p <= 1.0 - (_limit_up_ratio(s) - 1.0):
|
||
continue # 跌停无法卖出：保留到下一调仓
|
||
qty = shares[s]
|
||
proceeds = qty * float(c) * (1 - self.costs.slippage_rate)
|
||
fee = proceeds * (self.costs.commission_rate + self.costs.stamp_tax_rate)
|
||
cash += proceeds - fee
|
||
sold_notional += proceeds
|
||
trades.append(
|
||
Trade(
|
||
entry_date=entry_date[s],
|
||
exit_date=d.date(),
|
||
symbol=s,
|
||
entry_price=entry_price[s],
|
||
exit_price=float(c),
|
||
return_pct=(float(c) / entry_price[s] - 1.0) * 100,
|
||
)
|
||
)
|
||
shares[s] = 0.0
|
||
entry_date.pop(s, None)
|
||
entry_price.pop(s, None)
|
||
|
||
# 2) 买入：取得分最高且可买的 TopN（涨停 / 无价剔除）
|
||
score_d = self.score.loc[d].dropna()
|
||
top = score_d.sort_values(ascending=False).index.tolist()
|
||
targets: list[str] = []
|
||
for s in top:
|
||
if len(targets) >= self.spec.selection.top_n:
|
||
break
|
||
c, p = close_d[s], prev_d[s]
|
||
if _nan(c) or _nan(p) or p <= 0:
|
||
continue
|
||
if c / p >= _limit_up_ratio(s):
|
||
continue # 涨停不可追买
|
||
targets.append(s)
|
||
|
||
if targets:
|
||
budget = cash / len(targets)
|
||
for s in targets:
|
||
c = float(close_d[s])
|
||
price_in = c * (1 + self.costs.slippage_rate)
|
||
invest = budget * (1 - self.costs.commission_rate)
|
||
shares[s] = invest / price_in
|
||
entry_date[s] = d.date()
|
||
entry_price[s] = price_in
|
||
notional.append(budget)
|
||
cash -= budget * len(targets)
|
||
|
||
# 3) 记录调仓后仓位
|
||
total = cash + sum(
|
||
float(self.close.at[d, s] * qty)
|
||
for s, qty in shares.items()
|
||
if qty > 0 and not _nan(self.close.at[d, s])
|
||
)
|
||
if total > 0:
|
||
for s, qty in shares.items():
|
||
if qty > 0 and not _nan(self.close.at[d, s]):
|
||
positions.append(
|
||
Position(
|
||
date=d.date(), symbol=s, weight=float(qty * self.close.at[d, s] / total)
|
||
)
|
||
)
|
||
return cash
|
||
|
||
# ---- 指标 ----
|
||
|
||
def _to_result(self, equity, trades, positions, notional) -> BacktestResult:
|
||
start, end = equity.index[0].date(), equity.index[-1].date()
|
||
init = float(self.spec.initial_capital)
|
||
final = float(equity.iloc[-1])
|
||
rets = equity.pct_change().dropna()
|
||
n = len(rets)
|
||
total_ret = (final / init - 1.0) * 100 if init else 0.0
|
||
annual = (
|
||
((final / init) ** (TRADING_DAYS / max(n, 1)) - 1.0) * 100
|
||
if final > 0 and init > 0
|
||
else -100.0
|
||
)
|
||
mean_r, std_r = (float(rets.mean()), float(rets.std(ddof=1))) if n else (0.0, 0.0)
|
||
sharpe = mean_r / std_r * math.sqrt(TRADING_DAYS) if std_r and mean_r else 0.0
|
||
vol = std_r * math.sqrt(TRADING_DAYS) * 100
|
||
dd = (equity / equity.cummax() - 1.0).min() * 100
|
||
wins = [t for t in trades if t.return_pct > 0]
|
||
win_rate = len(wins) / len(trades) * 100 if trades else 0.0
|
||
avg_turn = (sum(notional) / len(notional) / ((init + final) / 2)) * 100 if notional else 0.0
|
||
|
||
eq_pts = [CurvePoint(date=d.date(), value=round(float(v), 2)) for d, v in equity.items()]
|
||
dd_series = (equity / equity.cummax() - 1.0) * 100
|
||
drawdown = [
|
||
CurvePoint(date=d.date(), value=round(float(v), 3)) for d, v in dd_series.items()
|
||
]
|
||
|
||
monthly: list[MonthlyReturn] = []
|
||
yearly: list[YearlyReturn] = []
|
||
if len(equity) > 1:
|
||
m = equity.resample("ME").last().pct_change().dropna()
|
||
monthly = [
|
||
MonthlyReturn(
|
||
year=int(d.year), month=int(d.month), return_pct=round(float(v) * 100, 3)
|
||
)
|
||
for d, v in m.items()
|
||
]
|
||
y = equity.resample("YE").last().pct_change().dropna()
|
||
yearly = [
|
||
YearlyReturn(year=int(d.year), return_pct=round(float(v) * 100, 3))
|
||
for d, v in y.items()
|
||
]
|
||
|
||
summary = BacktestSummary(
|
||
start=start,
|
||
end=end,
|
||
initial_capital=round(init, 2),
|
||
final_equity=round(final, 2),
|
||
total_return_pct=round(total_ret, 3),
|
||
annual_return_pct=round(annual, 3),
|
||
sharpe=round(sharpe, 3),
|
||
max_drawdown_pct=round(float(dd), 3),
|
||
volatility_pct=round(vol, 3),
|
||
win_rate_pct=round(win_rate, 2),
|
||
total_trades=len(trades),
|
||
avg_turnover_pct=round(avg_turn, 2),
|
||
)
|
||
return BacktestResult(
|
||
summary=summary,
|
||
equity_curve=eq_pts,
|
||
drawdown=drawdown,
|
||
monthly_returns=monthly,
|
||
yearly_returns=yearly,
|
||
positions=positions,
|
||
trades=trades,
|
||
turnover_pct=round(sum(notional) / max(init, 1) * 100, 2),
|
||
unimplemented=list(_DEFAULT_UNIMPLEMENTED),
|
||
config_snapshot=self.spec.model_dump(mode="json"),
|
||
)
|
||
|
||
|
||
def build_factor_panels(
|
||
daily: pd.DataFrame, factor_specs
|
||
) -> list[tuple[str, pd.DataFrame, float, str]]:
|
||
"""按 spec.factors 计算面板与权重（因子不存在即报错）。"""
|
||
panels: list[tuple[str, pd.DataFrame, float, str]] = []
|
||
for fs in factor_specs:
|
||
defn: FactorDef
|
||
defn, panel = compute_factor(fs.name, daily)
|
||
panels.append((fs.name, panel, fs.weight, defn.direction))
|
||
return panels
|
||
|
||
|
||
def run_spec_factor_test(
|
||
daily: pd.DataFrame,
|
||
spec: ResearchSpec,
|
||
horizon_days: int = 21,
|
||
) -> tuple[FactorTestReport, dict[str, pd.DataFrame]]:
|
||
"""单因子测试：因子面板 + 未来 horizon 收益 → FactorTestReport。"""
|
||
assert spec.type == "factor_test"
|
||
factor_name = spec.factors[0].name
|
||
panels = build_factor_panels(daily, spec.factors)
|
||
panel = panels[0][1]
|
||
close = daily.pivot(index="trade_date", columns="symbol", values="close").sort_index()
|
||
close.index = pd.to_datetime(close.index)
|
||
forward = close.shift(-horizon_days) / close - 1.0
|
||
report = run_factor_test(panel, forward, factor_name=factor_name)
|
||
return report, {factor_name: panel}
|
||
|
||
|
||
def _nan(v) -> bool:
|
||
try:
|
||
return bool(math.isnan(float(v)))
|
||
except (TypeError, ValueError):
|
||
return False
|