feat: margin utilization summary

.planning/ROADMAP.md

@@ -39,6 +39,7 @@
 - [x] `position_pnl_estimate()` 已提供真实主力链持仓保证金与 P&L 估算。
 - [x] `run_position_simulation()` 已支持对一组 episode 批量运行持仓估算。
 - [x] `batch_equity_summary()` 已提供简单资金曲线摘要。
+- [x] `margin_utilization_summary()` 已提供批量持仓保证金占用率统计。
 - [ ] 在完整组合持仓/资金引擎中接入逐日保证金监控。
 - [x] T+1 close 执行近似已加入 `backtest --t1-close`（仍非 open/settle，真实缺口待合约数据接入）。
 - [x] `summarize_roll_costs()` 已提供合约级可量化换月 gap 成本统计。
@@ -68,4 +69,4 @@
 
 当前测试：`PYTHONPATH=src python3 -m unittest discover -s tests -v`
 
-当前通过：99 tests OK。
+当前通过：100 tests OK。

CHANGELOG.md

@@ -44,7 +44,8 @@
 - `position_pnl_estimate()`：真实主力链持仓保证金与换月 P&L 估算；
 - `run_position_simulation()`：对一组 episode 批量运行真实主力链持仓估算；
 - `batch_equity_summary()`：基于批量模拟生成简单资金曲线摘要；
-- `formal_v2.generate_v2_formal_report()`：协议 v2 正式验收前的可审计报告入口。
+- `formal_v2.generate_v2_formal_report()`：协议 v2 正式验收前的可审计报告入口；
+- `margin_utilization_summary()`：批量持仓保证金占用率统计。
 
 ## [0.1.0-rc1] - 2026-09-02
 

src/goratio/margin.py

@@ -193,3 +193,24 @@ def batch_equity_summary(sim: dict, *, initial_capital: float = 100000.0) -> dic
         "valid_pnl_count": row_count,
         "note": "简单逐笔资金曲线摘要，不包含重叠持仓、融资与提现",
     }
+
+
+def margin_utilization_summary(sim: dict, *, initial_capital: float = 100000.0) -> dict:
+    """从批量持仓模拟中统计保证金占用率（逐笔近似）。"""
+    if initial_capital <= 0:
+        raise ValueError("initial_capital 必须为正")
+    utilizations = []
+    for row in sim.get("rows", []):
+        margin = row.get("margin_estimate")
+        if margin is None:
+            continue
+        utilizations.append(margin / initial_capital)
+    return {
+        "initial_capital": initial_capital,
+        "valid_margin_count": len(utilizations),
+        "mean_margin_utilization": (
+            sum(utilizations) / len(utilizations) if utilizations else None
+        ),
+        "max_margin_utilization": max(utilizations) if utilizations else None,
+        "note": "逐笔近似保证金占用，不包含重叠持仓的逐日合并监控",
+    }

tests/test_margin.py

@@ -133,5 +133,22 @@ def test_batch_equity_summary(self) -> None:
         self.assertEqual(summary["valid_pnl_count"], 3)
 
 
+    def test_margin_utilization_summary(self) -> None:
+        from goratio.margin import margin_utilization_summary
+
+        sim = {
+            "rows": [
+                {"margin_estimate": 1000.0},
+                {"margin_estimate": 2000.0},
+            ]
+        }
+
+        summary = margin_utilization_summary(sim, initial_capital=10000.0)
+
+        self.assertEqual(summary["valid_margin_count"], 2)
+        self.assertAlmostEqual(summary["mean_margin_utilization"], 0.15)
+        self.assertAlmostEqual(summary["max_margin_utilization"], 0.2)
+
+
 if __name__ == "__main__":
     unittest.main()