feat: implement disk cache flushing in strategy backtest for improved data integrity

Author: Grefer

.gitignore

@@ -29,6 +29,8 @@ data/announcement_pdfs/
 data/batch_pricing_cache.json
 data/watchlist.json
 
-# 策略回测结果快照 (GUI 运行态产物, 随回测增删/prune, 不入版本库)
+# 策略回测运行态产物 (结果快照 + 跨运行磁盘缓存), 随回测增删/prune, 不入版本库
 data/strategy_backtest_snapshot.json
+data/strategy_backtest_snapshot.bak.json
 data/strategy_backtest_snapshots/
+data/strategy_backtest_cache/

convertible_bond/gui/controllers/strategy_backtest.py

@@ -26,13 +26,15 @@
     build_batch_provider,
     parse_bond_codes,
 )
+from ...backtest_disk_cache import DiskCacheProvider
 from ...cb_events import CBEventStore, project_events_path
 from ...data_providers import WindDataProvider
 from ...historical_terms import (
     HistoricalBondDataProvider,
     TermsPatchStore,
     project_terms_patches_path,
 )
+from ...paths import data_dir
 from ...strategy_backtest import (
     ScoreStrategyConfig,
     _funding_legacy_alias,
@@ -690,20 +692,26 @@ def _update():
                         self.strategy_bt_progress.set(pct)
                 self.after(0, _update)
 
-            result = backtest_score_strategy(
-                provider,
-                codes,
-                start_date=start,
-                end_date=end,
-                config=config,
-                terms_cache=None,
-                admission_config=admission_config,
-                pricing_snapshot_cache=getattr(self, "_strategy_pricing_cache", None),
-                progress_cb=progress,
-                stage_cb=stage_progress,
-                cancel_cb=cancel_check,
-                **params,
-            )
+            try:
+                result = backtest_score_strategy(
+                    provider,
+                    codes,
+                    start_date=start,
+                    end_date=end,
+                    config=config,
+                    terms_cache=None,
+                    admission_config=admission_config,
+                    pricing_snapshot_cache=getattr(self, "_strategy_pricing_cache", None),
+                    progress_cb=progress,
+                    stage_cb=stage_progress,
+                    cancel_cb=cancel_check,
+                    **params,
+                )
+            finally:
+                # 跨运行磁盘缓存: 中途取消/异常也落盘已拉取的昂贵数据 (与 CLI 同口径)
+                flush = getattr(provider, "flush", None)
+                if callable(flush):
+                    flush()
             result_config = dict(result.get("config") or {})
             result_config["history_mode"] = history_mode
             result["config"] = result_config
@@ -766,7 +774,7 @@ def _build_strategy_provider(self, source):
             # 而是 strip 掉 Wind 泄漏的当前状态、改由 cb_events 按 event_date 重建。
             # 这些状态本就是离散公告事件 (cb_events 已覆盖 18 类), 事件重建既防未来
             # 函数又把每债 Wind 调用压到 ~2 次 (条款批量 wss + close wsd)。
-            return HistoricalBondDataProvider(
+            provider = HistoricalBondDataProvider(
                 WindDataProvider(),
                 history_store=None,
                 patch_store=TermsPatchStore(project_terms_patches_path()),
@@ -775,6 +783,9 @@ def _build_strategy_provider(self, source):
                 merge_admission_status=False,
                 provider_history_terms=True,
             )
+            # 跨运行磁盘缓存 (与 CLI --cache-dir 同机制): 高保真逐债拉取的 point-in-time
+            # 条款/历史价落盘复用, 复跑从数小时降到定价时间; 补丁/事件文件一变自动失效。
+            return DiskCacheProvider(provider, data_dir("strategy_backtest_cache"))
 
         base_provider = build_batch_provider(
             source,
@@ -1354,6 +1365,17 @@ def _render_strategy_insight(self, result):
             verdict = "暂无足够收益数据"
         quality = "高" if fallback_ratio <= 0 else ("中" if fallback_ratio <= 0.2 else "低")
 
+        hints = {
+            "结论": "解读铁律: 一切对照「等权基准」——跑不赢基准 = 这套规则没有超额,\n"
+                    "哪怕绝对收益为正。机会分是复核标记、不是收益预测;\n"
+                    "单一市场周期的回测不构成策略承诺 (详见 USAGE 4.2 与 README 模型边界)。",
+            "最大回撤": "净值从峰值到谷底的最大跌幅 = 历史上最深要忍受的亏损。\n"
+                       "对照基准回撤判断风险是否换来了收益; 与持仓集中度、现金缓冲相关。",
+            "主要贡献": "收益贡献最大的单券。若总收益高度依赖个别券 (尤其强赎/退市收敛券),\n"
+                       "说明结果偏尾部运气而非系统性能力, 复现性存疑——去「归因」页核对。",
+            "数据质量": "条款回退占比 = 用当前条款顶替历史条款的样本比例, >0 有未来信息渗入风险。\n"
+                       "下结论前先看「数据」子页的补丁覆盖率与缺价跳过数。",
+        }
         items = [
             ("结论", verdict),
             ("最大回撤", (
@@ -1380,6 +1402,10 @@ def _render_strategy_insight(self, result):
                 font=(FONT_FAMILY, 13, "bold"), wraplength=260,
                 justify="left")
             value_label.pack(anchor="w")
+            hint = hints.get(title)
+            if hint:
+                Tooltip(cell, hint)
+                Tooltip(value_label, hint)
 
             def _update_wrap(event, label=value_label):
                 label.configure(wraplength=max(180, event.width - 24))

convertible_bond/strategy_backtest.py

@@ -764,6 +764,11 @@ def backtest_score_strategy(
         pricer_overrides=pricer_overrides,
     )
 
+    # 跨运行磁盘缓存 (DiskCacheProvider, 经 _BacktestCacheProvider.__getattr__ 链可达)
+    # 的阶段性落盘句柄: 多小时高保真拉取中途进程被杀也只丢当期数据。
+    # flush 为原子写且无脏数据时零成本; 链上无 flush 能力时为 None, 安全跳过。
+    provider_flush = getattr(provider, "flush", None)
+
     for idx, period_start in enumerate(schedule[:-1]):
         period_end = schedule[idx + 1]
         res = _run_rebalance_period(
@@ -791,6 +796,8 @@ def backtest_score_strategy(
         periods.append(res.period)
         if progress_cb:
             progress_cb(idx + 1, total_periods)
+        if callable(provider_flush):
+            provider_flush()
 
     summary = _summarize_strategy(
         equity_curve,

tests/test_strategy_backtest.py

@@ -1761,3 +1761,49 @@ def fake_batch_price(provider_arg, codes, *, valuation_date, **kwargs):
             break
         period_rows.append(r)
     assert len(period_rows) == len(result["periods"]) == 3
+
+
+def test_score_strategy_flushes_provider_disk_cache_each_period(monkeypatch):
+    """逐期 flush: provider 链上有 flush 能力 (DiskCacheProvider) 时每个调仓期落盘一次。
+
+    同时守护委托链: 回测内部把 provider 包成 _BacktestCacheProvider, flush 须经
+    __getattr__ 透传到内层; 多小时高保真拉取中途进程被杀也只丢当期数据。
+    """
+    class FlushingProvider(StrategyFakeProvider):
+        def __init__(self):
+            super().__init__()
+            self.flush_calls = 0
+
+        def flush(self):
+            self.flush_calls += 1
+
+    provider = FlushingProvider()
+
+    def fake_batch_price(provider_arg, codes, *, valuation_date, **kwargs):
+        return [
+            {
+                "bond_code": code,
+                "status": "ok",
+                "S0": 100.0, "K": 100.0, "sigma": 0.30,
+                "theoretical_price": 110.0, "market_price": 100.0,
+                "deviation": -10.0 / 110.0,
+                "credit_rating": "AA+", "outstanding_balance": 10.0, "T": 3.0,
+            }
+            for code in codes
+        ]
+
+    monkeypatch.setattr(
+        "convertible_bond.strategy_backtest.batch_price_from_provider_threaded",
+        fake_batch_price,
+    )
+
+    backtest_score_strategy(
+        provider,
+        ["113001.SH", "113002.SH", "113003.SH"],
+        start_date=date(2025, 1, 2),
+        end_date=date(2025, 3, 31),
+        config=ScoreStrategyConfig(top_n=1, rebalance_freq="M"),
+    )
+
+    # 2025-01-02 → 2025-03-31 月频共 3 个调仓期, 每期 flush 一次
+    assert provider.flush_calls == 3