feat: batch portfolio summary

.planning/ROADMAP.md

@@ -45,6 +45,7 @@
 - [x] `check_portfolio_constraints()` 已提供组合级保证金占用与回撤门控。
 - [x] `financing_cost_estimate()` 已支持保证金资金成本估算。
 - [x] `position_pnl_estimate()` 已输出扣减资金成本后的净 P&L。
+- [x] `summarize_batch_portfolio()` 已提供批量持仓高层汇总。
 - [ ] 在完整组合资金引擎中接入融资/资金费率与更多组合约束。
 - [x] T+1 close 执行近似已加入 `backtest --t1-close`（仍非 open/settle，真实缺口待合约数据接入）。
 - [x] `summarize_roll_costs()` 已提供合约级可量化换月 gap 成本统计。
@@ -75,4 +76,4 @@
 
 当前测试：`PYTHONPATH=src python3 -m unittest discover -s tests -v`
 
-当前通过：105 tests OK。
+当前通过：106 tests OK。

CHANGELOG.md

@@ -51,7 +51,8 @@
 - `portfolio_daily_margin()`：多笔持仓逐日合并盯市与保证金监控；
 - `check_portfolio_constraints()`：组合级保证金占用与回撤风控门控；
 - `financing_cost_estimate()`：保证金资金成本估算；
-- `position_pnl_estimate()` 增加资金成本与净 P&L 估算。
+- `position_pnl_estimate()` 增加资金成本与净 P&L 估算；
+- `summarize_batch_portfolio()`：批量 episode → 持仓模拟 → 资金/保证金高层汇总。
 
 ## [0.1.0-rc1] - 2026-09-02
 

src/goratio/margin.py

@@ -411,3 +411,32 @@ def financing_cost_estimate(
     if margin_estimate < 0 or holding_days < 0:
         raise ValueError("保证金与持有天数不能为负")
     return margin_estimate * annual_rate * holding_days / 365.0
+
+
+def summarize_batch_portfolio(
+    records,
+    episodes,
+    *,
+    instrument: str = "gold",
+    direction: int = 1,
+    lots: int = 1,
+    initial_capital: float = 100000.0,
+) -> dict:
+    """批量 episode → 持仓模拟 → 资金曲线/保证金占用的高层汇总。"""
+    simulation = run_position_simulation(
+        records,
+        episodes,
+        instrument=instrument,
+        direction=direction,
+        lots=lots,
+    )
+    equity = batch_equity_summary(simulation, initial_capital=initial_capital)
+    utilization = margin_utilization_summary(
+        simulation, initial_capital=initial_capital
+    )
+    return {
+        "simulation": simulation,
+        "equity": equity,
+        "margin_utilization": utilization,
+        "note": "高层研究汇总，不构成交易建议",
+    }

tests/test_margin.py

@@ -262,5 +262,47 @@ def test_financing_cost_estimate(self) -> None:
         self.assertAlmostEqual(cost, 500.0)
 
 
+    def test_summarize_batch_portfolio(self) -> None:
+        from goratio.episodes import Episode
+        from goratio.margin import summarize_batch_portfolio
+
+        records = [
+            ContractRecord(
+                date=date(2024, 1, 2), instrument="gold", symbol="GC",
+                contract_month="2024-02", close=2000.0,
+                volume=100, open_interest=50,
+            ),
+            ContractRecord(
+                date=date(2024, 1, 3), instrument="gold", symbol="GC",
+                contract_month="2024-02", close=2010.0,
+                volume=80, open_interest=40,
+            ),
+            ContractRecord(
+                date=date(2024, 1, 3), instrument="gold", symbol="GC",
+                contract_month="2024-04", close=2020.0,
+                volume=200, open_interest=300,
+            ),
+            ContractRecord(
+                date=date(2024, 1, 4), instrument="gold", symbol="GC",
+                contract_month="2024-04", close=2030.0,
+                volume=250, open_interest=400,
+            ),
+        ]
+        episode = Episode(
+            date=date(2024, 1, 2),
+            outcome_date=date(2024, 1, 4),
+            forward_return=0.0,
+            percentile=0.1,
+            history_count=300,
+            low_state_days=3,
+        )
+
+        summary = summarize_batch_portfolio(records, [episode])
+
+        self.assertIn("simulation", summary)
+        self.assertIn("equity", summary)
+        self.assertIn("margin_utilization", summary)
+
+
 if __name__ == "__main__":
     unittest.main()