powerquant-cli 0.2.6__py3-none-any.whl

quant_core/app/backtest/backtest_run.py

@@ -0,0 +1,393 @@
+"""Backtest Run - 历史回测环境驱动、生命周期与结果聚合（T7）
+
+SSOT：`app/backtest/SPEC.md`、T7 Task/Plan、DECISIONS.md 2026-09-04。
+
+Backtest 只负责：历史环境组装输入、Replay 驱动、生命周期与结果聚合。
+单时间片业务循环由 RuntimeSession 唯一拥有；Backtest 的循环仅为：
+
+    Data Guard → Historical MarketTimeSlice Source
+        → HistoricalClock.set(T) → await RuntimeSession.step(slice@T)
+        → 成功后聚合 StepResult → 下一个 Slice
+
+硬边界：
+- 不复制 Market → Execution → Fill → Portfolio → Snapshot → Strategy →
+  Planning → submit 的 Runtime 单片内部顺序；
+- 每个 MarketTimeSlice 恰好 step 一次；Clock 时间与 slice.event_time 相等；
+- 只有完整成功返回的 RuntimeStepResult 才进入聚合；step 异常时该片不
+  提交 Equity/Trace/Fill/Attempt，BacktestRun 进入 FAILED 并停止；
+- SETTLING 只聚合、算指标、冻结 Result——不合成 SESSION_CLOSE/Bar、
+  不生成 Fill、不强平、不撤销/过期订单、不修改 Portfolio 业务状态；
+  数据结束时仍存在的订单/持仓如实保留并披露；
+- 全程不读 wall clock，无 sleep，无随机业务排序。
+"""
+
+from collections.abc import AsyncIterator, Mapping
+from datetime import date, datetime, time
+from typing import Protocol, runtime_checkable
+
+from quant_core.app.backtest.data_guard import (
+    ensure_backtest_data_ready,
+    ensure_backtest_dependencies_ready,
+)
+from quant_core.app.backtest.historical_clock import HistoricalClock
+from quant_core.app.backtest.metrics import compute_metrics
+from quant_core.app.backtest.schema import (
+    BacktestConfig,
+    BacktestDataRevision,
+    BacktestMetrics,
+    BacktestResult,
+    BacktestStatus,
+    DecisionTrace,
+    EquityCurve,
+    EquityPoint,
+    ResultLimitation,
+)
+from quant_core.app.data.constants import BarFrequency, MarketStreamMode
+from quant_core.app.data.interface.market_data_verification import IMarketDataVerification
+from quant_core.app.data.interface.market_time_slice_source import IMarketTimeSliceSource
+from quant_core.app.data.schema.adjustment_schema import AdjustmentType
+from quant_core.app.data.schema.event_schema import MarketStreamRequest, MarketTimeSlice
+from quant_core.app.order_execution.interface.public.order_execution import IOrderExecution
+from quant_core.app.portfolio.interface.public.portfolio import IPortfolioLedger
+from quant_core.app.strategy.schema.portfolio_target import PortfolioDecision
+from quant_core.app.trading_runtime.runtime_schema import RuntimeStepResult, TraceEntry
+
+
+@runtime_checkable
+class RuntimeSessionProtocol(Protocol):
+    """RuntimeSession 的消费方最小 Port（Backtest 只调用 step）"""
+
+    async def step(self, time_slice: MarketTimeSlice) -> RuntimeStepResult:
+        """严格执行一个时间片（固定因果顺序；失败即异常）"""
+        ...
+
+
+class BacktestRun:
+    """一次历史回测的运行实例（状态机；单线程/单事件循环使用）
+
+    构造注入已组装的历史环境（具体 Simulated 实现由组装点装配）：
+
+    - config：不可变 BacktestConfig；
+    - runtime_session：组装完成的 RuntimeSession；
+    - clock：组装点创建的唯一 HistoricalClock（同一实例必须已注入
+      RuntimeSession；BacktestRun 只负责在每个片 step 前推进它，不创建
+      第二个 Clock，也不读 Session 私有状态）；
+    - order_execution：仅用于终态读取公开 ``order_snapshots()``；
+    - slice_source：IMarketTimeSliceSource（历史 Replay 语义 Port）；
+    - verification：IMarketDataVerification（先 verify 后运行）。
+    """
+
+    def __init__(
+        self,
+        config: BacktestConfig,
+        runtime_session: RuntimeSessionProtocol,
+        order_execution: IOrderExecution,
+        slice_source: IMarketTimeSliceSource,
+        verification: IMarketDataVerification,
+        clock: HistoricalClock,
+        ledger: IPortfolioLedger | None = None,
+        input_revisions: tuple[BacktestDataRevision, ...] = (),
+        listing_dates: Mapping[str, date] | None = None,
+    ) -> None:
+        self._config = config
+        self._session = runtime_session
+        self._execution = order_execution
+        self._slice_source = slice_source
+        self._verification = verification
+        self._listing_dates = dict(listing_dates or {})
+        # Clock ownership 归组装点（T8）：先创建唯一 HistoricalClock，再以
+        # 同一实例显式注入 RuntimeSession 与本 Run（遗漏注入无法构造）
+        self.clock = clock
+        self._ledger = ledger
+        self._status = BacktestStatus.CREATED
+        self._result: BacktestResult | None = None
+
+        # 成功片聚合累积器（仅完整成功的 StepResult 才写入）。
+        # Trace 采用运行内增量积累：逐批校验与历史尾部的衔接后 append，
+        # 最终在 _build_result 一次性冻结为不可变 DecisionTrace（避免每片
+        # 复制并全量重校验历史序列的 O(n²) 开销）
+        self._equity_points: list[EquityPoint] = []
+        self._portfolio_decisions: list[PortfolioDecision] = []
+        self._fills: list = []
+        self._attempts: list = []
+        self._trace_entries: list = []
+        self._trace_last_event_time: datetime | None = None
+        self._started_event_time: datetime | None = None
+        self._ended_event_time: datetime | None = None
+        self._final_snapshot = None
+        self._last_slice_time: datetime | None = None
+        self._data_revisions: list[BacktestDataRevision] = list(input_revisions)
+
+    # ------------------------------------------------------------------
+    # 公开状态
+    # ------------------------------------------------------------------
+
+    @property
+    def status(self) -> BacktestStatus:
+        return self._status
+
+    @property
+    def result(self) -> BacktestResult:
+        """最终结果（只有 COMPLETED 后可读；幂等且全等）"""
+        if self._status is not BacktestStatus.COMPLETED or self._result is None:
+            raise RuntimeError(
+                f"BacktestResult 仅在 COMPLETED 后可读，当前状态 {self._status.value}"
+            )
+        return self._result
+
+    # ------------------------------------------------------------------
+    # 运行
+    # ------------------------------------------------------------------
+
+    async def run(self) -> BacktestResult:
+        """执行回测直到完成；任一阶段异常 → FAILED 并原样传播"""
+        if self._status is not BacktestStatus.CREATED:
+            raise RuntimeError(
+                f"BacktestRun 只能从 CREATED 运行一次，当前状态 {self._status.value}"
+            )
+        try:
+            await self._run()
+        except BaseException:
+            self._status = BacktestStatus.FAILED
+            raise
+        return self._require_result()
+
+    async def _run(self) -> None:
+        # DATA_CHECK：先 verify 后运行（不可用时抛领域异常）
+        self._status = BacktestStatus.DATA_CHECK
+        execution_frequency = self._config.execution_frequency or self._config.frequency
+        for instrument_id in self._config.instrument_ids:
+            listed_date = self._listing_dates.get(instrument_id)
+            verification_start = self._config.start
+            if listed_date is not None and listed_date > verification_start.date():
+                verification_start = datetime.combine(
+                    listed_date, time(9, 30), tzinfo=self._config.start.tzinfo
+                )
+            if verification_start > self._config.end:
+                continue
+            bar_result = await ensure_backtest_data_ready(
+                self._verification,
+                instrument_id,
+                execution_frequency.value,
+                verification_start,
+                self._config.end,
+            )
+            if bar_result.dataset_revision is not None:
+                self._data_revisions.append(
+                    BacktestDataRevision(
+                        dataset=bar_result.dataset,
+                        instrument_id=instrument_id,
+                        frequency=execution_frequency.value,
+                        revision=bar_result.dataset_revision,
+                    )
+                )
+            if execution_frequency is not self._config.frequency:
+                observation_result = await ensure_backtest_data_ready(
+                    self._verification,
+                    instrument_id,
+                    self._config.frequency.value,
+                    verification_start,
+                    self._config.end,
+                )
+                if observation_result.dataset_revision is not None:
+                    self._data_revisions.append(
+                        BacktestDataRevision(
+                            dataset=observation_result.dataset,
+                            instrument_id=instrument_id,
+                            frequency=self._config.frequency.value,
+                            revision=observation_result.dataset_revision,
+                        )
+                    )
+            dependency_results = await ensure_backtest_dependencies_ready(
+                self._verification,
+                instrument_id,
+                self._config.frequency.value,
+                verification_start,
+                self._config.end,
+                require_adjustment_factors=(
+                    self._config.strategy_adjustment_type is not AdjustmentType.NONE
+                ),
+            )
+            self._data_revisions.extend(
+                BacktestDataRevision(
+                    dataset=result.dataset,
+                    instrument_id=instrument_id,
+                    frequency=(
+                        self._config.frequency.value
+                        if result.dataset != "corporate_action"
+                        else None
+                    ),
+                    revision=result.dataset_revision,
+                )
+                for result in dependency_results
+                if result.dataset_revision is not None
+            )
+
+        # RUNNING：逐片驱动 RuntimeSession（Backtest 不复制单片业务顺序）
+        self._status = BacktestStatus.RUNNING
+        request = MarketStreamRequest(
+            mode=MarketStreamMode.REPLAY,
+            speed=0.0,
+            instrument_ids=list(self._config.instrument_ids),
+            frequency=execution_frequency,
+            # 所有日线回放都需要显式开盘边界来完成 T+1 结算；
+            # 撮合价格仍由 execution_policy 独立决定。
+            coarse_open_decisions=execution_frequency in {BarFrequency.D1, BarFrequency.W1},
+            start=self._config.start,
+            end=self._config.end,
+        )
+        slices: AsyncIterator[MarketTimeSlice] = self._slice_source.stream_slices(request)
+        async for time_slice in slices:
+            self._check_slice_monotonic(time_slice)
+            self.clock.set(time_slice.event_time)
+            step_result = await self._session.step(time_slice)
+            # 错片防线：Runtime 输出必须仍属于本次输入时间片（早片/晚片
+            # 均属 Runtime 矛盾输出），任何聚合写入前校验
+            if step_result.slice_time != time_slice.event_time:
+                raise ValueError(
+                    f"RuntimeStepResult.slice_time {step_result.slice_time} 与输入时间片 "
+                    f"{time_slice.event_time} 不一致（错片输出，拒绝聚合）"
+                )
+            self._aggregate(step_result)
+
+        # SETTLING：只聚合已发生结果、算指标、冻结 Result
+        # （不合成事件/成交、不强平、不改 Portfolio 状态）。
+        # R3 finding 2（方案 C 兜底，用户裁定）：数据结束时仍 PENDING 的
+        # **coarse DAY 单**结构化 EXPIRED（一次终态迁移，经 Execution 公开
+        # 方法产生 OrderUpdate 并反映在 order_snapshots）；日内订单维持
+        # 「如实保留」语义不变。
+        # R4 finding 4：产生的 OrderUpdate 必须进入最终可审计结果——
+        # 作为独立 settling 生命周期迁移披露（BacktestResult.
+        # settling_order_updates）并追加为 DecisionTrace 条目（时间 =
+        # ended_event_time，不倒退），不伪造成市场事件或成交。
+        # 原子性：settle 迁移在 Result 冻结前完成；任一失败 → Run FAILED
+        # 并终止（无跨域回滚与既有失败语义一致），不产出半提交 Result。
+        self._status = BacktestStatus.SETTLING
+        settling_updates: tuple = ()
+        if self._ended_event_time is not None:
+            settling_updates = self._execution.expire_pending_day_orders(self._ended_event_time)
+        self._result = self._build_result(settling_updates)
+        self._status = BacktestStatus.COMPLETED
+
+    # ------------------------------------------------------------------
+
+    def _check_slice_monotonic(self, time_slice: MarketTimeSlice) -> None:
+        """Replay 驱动的调度边界：时间片必须严格递增（倒流/重复即失败）"""
+        if self._last_slice_time is not None and time_slice.event_time <= self._last_slice_time:
+            raise ValueError(
+                f"Replay 时间片必须严格递增：{time_slice.event_time} 不晚于已消费 "
+                f"{self._last_slice_time}（倒流/重复时间片属 Source 矛盾输出）"
+            )
+
+    def _aggregate(self, step_result: RuntimeStepResult) -> None:
+        """聚合一个完整成功的 StepResult（失败片根本不会进入本方法）"""
+        t = step_result.slice_time
+        self._equity_points.append(
+            EquityPoint(time=t, total_value=step_result.portfolio_snapshot.total_value)
+        )
+        self._fills.extend(step_result.fills)
+        self._portfolio_decisions.extend(step_result.portfolio_decisions)
+        self._attempts.extend(step_result.execution_attempts)
+        self._extend_trace(step_result.trace_entries)
+        if self._started_event_time is None:
+            self._started_event_time = t
+        self._ended_event_time = t
+        self._final_snapshot = step_result.portfolio_snapshot
+        self._last_slice_time = t
+
+    def _extend_trace(self, entries: tuple) -> None:
+        """增量追加一批 TraceEntry：只校验新增批次及与历史尾部的衔接
+        （时间不得倒退；同一时间片多条合法）。完整序列校验仍由
+        DecisionTrace 构造边界在最终冻结时执行，双保险不削弱。"""
+        if not entries:
+            return
+        if (
+            self._trace_last_event_time is not None
+            and entries[0].event_time < self._trace_last_event_time
+        ):
+            raise ValueError(
+                f"DecisionTrace 时间不得倒退：新增批次首条 {entries[0].event_time} 早于"
+                f"已聚合尾部 {self._trace_last_event_time}（成功片时间严格递增，"
+                f"属 Runtime 矛盾输出）"
+            )
+        self._trace_entries.extend(entries)
+        self._trace_last_event_time = entries[-1].event_time
+
+    def _build_result(self, settling_updates: tuple = ()) -> BacktestResult:
+        curve = EquityCurve(points=tuple(self._equity_points))
+        position_lots = self._ledger.position_lots() if self._ledger is not None else ()
+        cash_entries = self._ledger.cash_ledger_entries() if self._ledger is not None else ()
+        reservation_entries = (
+            getattr(self._ledger, "reservation_ledger_entries", lambda: ())()
+            if self._ledger is not None
+            else ()
+        )
+        closed_trades = self._ledger.closed_trades() if self._ledger is not None else None
+        metrics: BacktestMetrics = compute_metrics(
+            curve,
+            initial_cash=self._config.initial_cash,
+            fill_count=len(self._fills),
+            trading_days_per_year=self._config.trading_days_per_year,
+            annual_risk_free_rate=self._config.annual_risk_free_rate,
+            closed_trades=closed_trades,
+            fills=tuple(self._fills),
+        )
+        # SETTLING 结构化迁移追加为 trace 条目（kind=order_update；时间 =
+        # ended_event_time == 最后成功片时间，满足 trace 不倒退）
+        settling_traces = tuple(
+            TraceEntry(
+                event_time=update.event_time,
+                kind="order_update",
+                detail=(
+                    f"order_id={update.order_id} status={update.current_status.value} "
+                    f"reason={update.reason_code.value} phase=settling"
+                ),
+            )
+            for update in settling_updates
+        )
+        return BacktestResult(
+            status=BacktestStatus.COMPLETED,
+            config=self._config,
+            data_revisions=tuple(
+                sorted(
+                    self._data_revisions,
+                    key=lambda item: (
+                        item.dataset,
+                        item.instrument_id,
+                        item.frequency or "event",
+                        item.revision,
+                    ),
+                )
+            ),
+            started_event_time=self._started_event_time,
+            ended_event_time=self._ended_event_time,
+            final_portfolio_snapshot=self._final_snapshot,
+            # 终态订单来自 Order Execution 公开投影；数据结束时仍 PENDING 的
+            # 日内订单如实保留（SETTLING 只对 coarse DAY 单结构化到期）
+            order_snapshots=self._execution.order_snapshots(),
+            settling_order_updates=settling_updates,
+            fills=tuple(self._fills),
+            portfolio_decisions=tuple(self._portfolio_decisions),
+            position_lots=position_lots,
+            cash_ledger_entries=cash_entries,
+            reservation_ledger_entries=reservation_entries,
+            closed_trades=closed_trades or (),
+            execution_attempts=tuple(self._attempts),
+            equity_curve=curve,
+            metrics=metrics,
+            decision_trace=DecisionTrace(entries=tuple(self._trace_entries) + settling_traces),
+            limitations=(
+                ()
+                if self._ledger is not None
+                else (
+                    ResultLimitation.TRADE_COUNT_UNAVAILABLE,
+                    ResultLimitation.WIN_RATE_UNAVAILABLE,
+                    ResultLimitation.PRE_TAX_DIVIDEND,
+                )
+            ),
+        )
+
+    def _require_result(self) -> BacktestResult:
+        if self._result is None or self._status is not BacktestStatus.COMPLETED:
+            raise RuntimeError("BacktestRun 未正常完成：无最终结果")
+        return self._result

quant_core/app/backtest/data_guard.py

@@ -0,0 +1,77 @@
+"""
+Backtest Data Guard - 回测启动前的数据前置检查。
+
+边界：
+- 不找 Provider、不同步数据、不修复数据；
+- 只依赖 Market 跨域稳定 Port；
+- STALE 不拒绝，因为历史完整区间通常不要求接近当前时间。
+"""
+
+from datetime import datetime
+
+from quant_core.app.data.exceptions import MarketDataIncompleteException, MarketDataInvalidException
+from quant_core.app.data.interface.market_data_verification import IMarketDataVerification
+from quant_core.app.data.schema.reliability_schema import DatasetHealth, DatasetHealthResult
+
+
+async def ensure_backtest_data_ready(
+    verification: IMarketDataVerification,
+    instrument_id: str,
+    frequency: str,
+    start: datetime,
+    end: datetime,
+) -> DatasetHealthResult:
+    """校验 Historical Backtest 所需 Bar 数据，不可用时抛出领域异常。"""
+    result = await verification.verify_bars(instrument_id, frequency, start, end)
+    if result.health in (DatasetHealth.HEALTHY, DatasetHealth.STALE):
+        return result
+    reason = f"health={result.health.value}"
+    if result.missing_count:
+        samples = ", ".join(i.timestamp.isoformat() for i in result.issues if i.timestamp)
+        reason += f"; missing {result.missing_count} bars (samples: {samples})"
+    if result.invalid_count:
+        reason += f"; invalid {result.invalid_count} bars"
+    if result.health is DatasetHealth.INVALID:
+        raise MarketDataInvalidException(
+            dataset=result.dataset,
+            instrument_id=instrument_id,
+            start=start.isoformat(),
+            end=end.isoformat(),
+            reason=reason,
+        )
+    raise MarketDataIncompleteException(
+        dataset=result.dataset,
+        instrument_id=instrument_id,
+        start=start.isoformat(),
+        end=end.isoformat(),
+        reason=reason,
+    )
+
+
+async def ensure_backtest_dependencies_ready(
+    verification: IMarketDataVerification,
+    instrument_id: str,
+    frequency: str,
+    start: datetime,
+    end: datetime,
+    require_adjustment_factors: bool,
+) -> tuple[DatasetHealthResult, ...]:
+    """校验复权与公司行动依赖；任何缺失都在消费首片前 fail closed。"""
+    results = []
+    if require_adjustment_factors:
+        results.append(
+            await verification.verify_adjustment_factors(instrument_id, frequency, start, end)
+        )
+    results.append(await verification.verify_corporate_actions(instrument_id, start, end))
+    for result in results:
+        if result.health in (DatasetHealth.HEALTHY, DatasetHealth.STALE):
+            continue
+        reason = f"health={result.health.value}; missing={result.missing_count}"
+        raise MarketDataIncompleteException(
+            dataset=result.dataset,
+            instrument_id=instrument_id,
+            start=start.isoformat(),
+            end=end.isoformat(),
+            reason=reason,
+        )
+    return tuple(results)

quant_core/app/backtest/historical_clock.py

@@ -0,0 +1,26 @@
+"""Historical Clock - Backtest 拥有的场景时钟（T7）
+
+ClockProtocol 的历史回放实现：当前市场时间由 BacktestRun 在调用
+``RuntimeSession.step(slice@T)`` 前显式设置为 T，绝不读 wall clock。
+"""
+
+from datetime import datetime
+
+
+class HistoricalClock:
+    """历史回放时钟（结构化满足 ClockProtocol）"""
+
+    def __init__(self) -> None:
+        self._now: datetime | None = None
+
+    def set(self, now: datetime) -> None:
+        """由 BacktestRun 在每个时间片 step 前调用（必须 timezone-aware）"""
+        if not isinstance(now, datetime) or now.tzinfo is None:
+            raise ValueError("HistoricalClock.set 必须 timezone-aware datetime")
+        self._now = now
+
+    def now(self) -> datetime:
+        """返回当前回放市场时间（尚未设置时失败，不伪造时间）"""
+        if self._now is None:
+            raise ValueError("HistoricalClock 尚未设置：回放开始前没有当前市场时间")
+        return self._now

quant_core/app/backtest/legacy_result_schema.py

@@ -0,0 +1,34 @@
+"""旧回测结果的只读调仓投影；仅用于历史 JSON 反序列化。"""
+
+from decimal import Decimal
+from enum import Enum
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from quant_core.app.strategy.schema.portfolio_target import PortfolioDecision
+
+
+class RebalancePhase(str, Enum):
+    SELLING = "selling"
+    BUYING = "buying"
+    COMPLETED = "completed"
+    CONSTRAINED = "constrained"
+    SUPERSEDED = "superseded"
+
+
+class RebalanceMode(str, Enum):
+    COMPLETE = "complete"
+    PARTIAL = "partial"
+
+
+class RebalancePlanSnapshot(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    plan_id: str
+    phase: RebalancePhase
+    target_weights: tuple[tuple[str, Decimal], ...]
+    remaining_cash: Decimal = Field(..., ge=0)
+    target_value_error: tuple[tuple[str, Decimal], ...] = ()
+    reasons: tuple[str, ...] = ()
+    mode: RebalanceMode = RebalanceMode.COMPLETE
+    decision: PortfolioDecision | None = None