release: v1.17.13 — 修复多策略组合回测最大回撤虚高（分母误用初始值而非峰值）

用户反馈：3 个策略各自最大回撤仅 45.53%/40.16%/16.89%，组合却显示 83.76%。
根因：_build_combined_equity 的 drawdown_pct 分母误用 initial（固定初始资金），
净值大涨后（总收益 545%，峰值≈6.45×初始）绝对回撤额除以小初始值被等比放大。
改为 drawdown / peak（相对当时峰值，0~1），与单标的 PortfolioTracker 一致。
连带修复卡玛比率（年化/最大回撤）。其余指标经核对均正确。加回归守卫。

CHANGELOG.md

@@ -2,6 +2,15 @@
 
 本文件记录 easy-tdx 的版本变更。格式遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/)。
 
+## [1.17.13] — 2026-07-04
+
+**修复多策略组合回测「最大回撤」严重虚高** —— 用户反馈：3 个策略各自最大回撤仅 45.53%/40.16%/16.89%，组合在一起却显示 **83.76%**。根因是 `MultiStrategyEngine._build_combined_equity` 计算 `drawdown_pct` 时**分母误用初始资金（`initial`）而非逐点峰值（`peak`）**：净值大涨后峰值是初始值的好几倍（本例总收益 545%，峰值≈6.45×初始），同样的绝对回撤额除以小的初始值，百分比被等比放大。正确公式应为 `drawdown / peak`（相对当时峰值的回撤，0~1），与单标的 `PortfolioTracker.equity_curve` 的 `drawdown_pct` 定义一致。修复后最大回撤回到合理区间（≤ 各策略最大回撤的加权，不可能超过 100%）。**连带修复**：卡玛比率（`年化收益 / 最大回撤`）此前因 max_drawdown 虚高而被压低，修复后恢复正常。其余指标（总收益/年化/夏普/索提诺/波动率/交易数/胜率/盈亏比）经逐一核对**均正确**，不受此 bug 影响。
+
+### 修复
+
+- **`drawdown_pct` 分母改用逐点峰值**（`src/easy_tdx/backtest/multi_strategy_engine.py` `_build_combined_equity`）—— `drawdown / initial` → `drawdown / peak`（`peak_safe = peak.where(peak != 0, 1.0)` 防除零）。这同时修复 `EquityChart` 回撤曲线显示（前端读 `drawdown_pct` 取负向下画）。
+- **回归守卫**（`tests/unit/test_multi_strategy.py::test_max_drawdown_relative_to_peak_not_initial`）—— 构造「净值 1→6→4」的大涨后回撤场景，断言 `max_drawdown ≈ 33%`（旧逻辑会算成 200%，必 >1，断言 `≤1.0` 抓住回归）。
+
 ## [1.17.12] — 2026-07-04
 
 **修复 CI 在新版 FastAPI 上路由注册失败** —— v1.17.11 的 `DELETE /api/v1/strategies/{id}` 用 `status_code=204`，较新 FastAPI/Starlette 在路由注册阶段（`add_api_route`）就抛 `AssertionError: Status code 204 must not have a response body`，导致 CI 的 ubuntu 矩阵（py3.10/3.12/3.13）整片 ERROR（21 个 web 测试因 fixture 导入 router 而连带失败）。改为返回 `200 + {"deleted": id}` 确认体，既消除注册期断言又给前端明确反馈。

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "easy-tdx"
-version = "1.17.12"
+version = "1.17.13"
 description = "通达信 TCP 协议行情数据客户端，支持在线行情、离线数据读取与写入同步"
 readme = "README.md"
 requires-python = ">=3.10"

src/easy_tdx/backtest/multi_strategy_engine.py

@@ -228,12 +228,16 @@ class MultiStrategyEngine:
         aligned = aligned.ffill().fillna(0)
         total = aligned.sum(axis=1)
 
-        # 回撤：用正值约定（peak - total），与单标的 PortfolioTracker.equity_curve
-        # 及 PerformanceAnalyzer 一致；EquityChart 也按正值展示（前端取负向下画）。
+        # 回撤：drawdown 为绝对回撤额（峰值-当前，正值），drawdown_pct 为相对当时
+        # 峰值的回撤比例（drawdown / peak，0~1）。分母必须用逐点 peak 而非固定初始值：
+        # 净值大涨后 peak 是初始值的好几倍，若除以 initial 会把回撤百分比严重放大
+        # （如峰值 6.45x 初始时，45% 的真实回撤会被算成 293%）。与单标的
+        # PortfolioTracker.equity_curve 的 drawdown/drawdown_pct 定义保持一致，
+        # PerformanceAnalyzer 直接读 drawdown_pct 列算 max_drawdown。
         peak = total.cummax()
         drawdown = peak - total
-        initial = peak.iloc[0] if len(peak) > 0 and peak.iloc[0] != 0 else 1.0
-        drawdown_pct = drawdown / initial
+        peak_safe = peak.where(peak != 0, 1.0)
+        drawdown_pct = drawdown / peak_safe
 
         return pd.DataFrame(
             {

tests/unit/test_multi_strategy.py

@@ -119,6 +119,53 @@ class TestMultiStrategyEngine:
         result = MultiStrategyEngine(slots, total_cash=1_000_000).run()
         assert (result.combined_equity["drawdown"] >= 0).all()
 
+    def test_max_drawdown_relative_to_peak_not_initial(self) -> None:
+        """最大回撤必须相对「当时峰值」而非「初始资金」。
+
+        回归 v1.17.11/v1.17.12 的 bug：drawdown_pct 分母误用 initial（固定初始值），
+        导致净值大涨后回撤被严重放大（如峰值 6x 初始时，真实 45% 回撤被算成 290%）。
+        构造一个大涨后回撤的场景：净值为 1→6→4（即从峰值回撤 33%），验证 max_drawdown
+        ≈ 33%（旧逻辑会算成 200%，超出 1.0）。
+        """
+        # 构造单标的净值序列：前 50 根 close 线性涨到 6 倍，后 50 根跌到 4 倍。
+        # 用从不交易的 HoldStrategy，使 total ≈ initial_cash（曲线不随 close 变）……
+        # 不行——HoldStrategy 净值恒为初始资金，无法制造涨跌。改用直接断言合并曲线
+        # 的 drawdown_pct 计算逻辑：构造两段净值的合成 df 喂给 _build_combined_equity。
+        from easy_tdx.backtest.types import BacktestResult
+
+        # 两根等长净值曲线：均从 1.0 涨到 6.0 再跌到 4.0（各 50 根，峰值在第 50 根）
+        dates = pd.date_range("2024-01-01", periods=100, freq="D")
+        up = np.linspace(1.0, 6.0, 50)  # 0→50: 1→6
+        down = np.linspace(6.0, 4.0, 50)  # 50→100: 6→4
+        totals = np.concatenate([up, down])  # 峰值 6.0 在第 50 根，谷底 4.0 在末尾
+        ec = pd.DataFrame(
+            {
+                "datetime": dates,
+                "total": totals * 100_000,  # 缩放到资金量级
+                "drawdown": np.zeros(100),
+                "drawdown_pct": np.zeros(100),
+            }
+        )
+        # 造一个空 trades/positions 的 BacktestResult 占位
+        empty_df = pd.DataFrame()
+        fake = BacktestResult(
+            performance={"total_return": 3.0},
+            equity_curve=ec,
+            trades=empty_df,
+            positions=empty_df,
+            config={},
+        )
+        engine = MultiStrategyEngine.__new__(MultiStrategyEngine)
+        combined = engine._build_combined_equity(  # noqa: SLF001 — 直接测内部算法
+            {"A@SZ:000001": fake}, {"A@SZ:000001": 100_000.0}
+        )
+        # 真实最大回撤（相对峰值）：峰值 600000，谷底 400000，回撤 = 200000/600000 ≈ 33.3%
+        dd_pct = combined["drawdown_pct"].to_numpy()
+        max_dd = float(np.max(dd_pct))
+        assert 0.30 <= max_dd <= 0.36, f"max_drawdown 应≈33%，实际 {max_dd:.4f}"
+        # 旧 bug（除以 initial=100000）会算成 200%（200000/100000），必然 >1
+        assert max_dd <= 1.0, "drawdown_pct 相对峰值，绝不可能超过 100%"
+
     def test_capital_split_equal(self) -> None:
         """资金按策略数均分：每个槽位 1/N。"""
         slots = [