powerquant-cli 0.2.6__py3-none-any.whl

quant_core/app/strategy/service/strategy_runtime_service.py

@@ -0,0 +1,319 @@
+"""策略生命周期调度与 PIT 数据装配；交易调用同步交给注入的公开 API。"""
+
+from collections.abc import AsyncIterator, Iterable, Mapping
+from datetime import date, datetime
+from typing import Any
+from zoneinfo import ZoneInfo
+
+from quant_core.app.data.constants import BarFrequency, MarketEventType
+from quant_core.app.data.interface.market_data_query import IMarketDataQuery
+from quant_core.app.data.schema.adjustment_schema import (
+    AdjustmentAnchorMode,
+    AdjustmentType,
+    BarViewRequest,
+)
+from quant_core.app.data.schema.event_schema import (
+    BarEvent,
+    MarketTimeSlice,
+    TradingSessionEvent,
+    market_event_order_key,
+)
+from quant_core.app.factor.interface.public.factor_exposure_query import IFactorExposureQuery
+from quant_core.app.factor.interface.public.factor_selection import IFactorSelection
+from quant_core.app.order_execution.interface.public.order_submission import IOrderSubmission
+from quant_core.app.strategy.interface.public.portfolio_construction import IPortfolioConstruction
+from quant_core.app.strategy.interface.public.strategy import IStrategy
+from quant_core.app.strategy.interface.public.strategy_portfolio_reader import (
+    IStrategyPortfolioReader,
+)
+from quant_core.app.strategy.interface.strategy_factor_reader import IStrategyFactorReader
+from quant_core.app.strategy.interface.strategy_order_reader import IStrategyOrderReader
+from quant_core.app.strategy.schema.portfolio_target import PortfolioDecision
+from quant_core.app.strategy.schema.signal_schema import Signal
+from quant_core.app.strategy.service.strategy_market_view import StrategyMarketView
+from quant_core.app.strategy.service.strategy_scheduler import StrategyScheduler
+from quant_core.app.strategy.strategy_context import StrategyContext
+
+
+async def _aiter(items: list):
+    """list → async iterator（时间片同步列表与异步流统一消费）"""
+    for item in items:
+        yield item
+
+
+class StrategyRuntimeService:
+    """策略运行时：以时间片为调度边界消费市场事件流，装配上下文并调度策略回调"""
+
+    def __init__(
+        self,
+        strategy: IStrategy,
+        market: IMarketDataQuery,
+        factor_reader: IStrategyFactorReader,
+        portfolio: IStrategyPortfolioReader | None = None,
+        order_reader: IStrategyOrderReader | None = None,
+        order_api: IOrderSubmission | None = None,
+        adjustment_type: AdjustmentType = AdjustmentType.NONE,
+        observation_frequency: BarFrequency | None = None,
+        listing_dates: Mapping[str, date] | None = None,
+        factor_selection: IFactorSelection | None = None,
+        exposure_query: IFactorExposureQuery | None = None,
+        portfolio_construction: IPortfolioConstruction | None = None,
+    ) -> None:
+        self.strategy = strategy
+        self.market = market
+        self.factor_reader = factor_reader
+        self.portfolio = portfolio  # 只读视图；修改持仓归属 Backtest/Execution
+        self.order_reader = order_reader
+        self._order_api = order_api
+        self.decisions: tuple[PortfolioDecision, ...] = ()
+        self.adjustment_type = adjustment_type
+        self.observation_frequency = observation_frequency
+        self._listing_dates = dict(listing_dates or {})
+        self._factor_selection = factor_selection
+        self._exposure_query = exposure_query
+        self._portfolio_construction = portfolio_construction
+        self.state: dict[str, Any] = {}  # strategy-local state，禁存 cash/position
+        self._scheduler = StrategyScheduler()
+        self._active_universe: tuple[str, ...] | None = None
+        self._active_day = None
+        self._initialized = False
+        self._after_trading_days: set = set()
+
+    async def run_slice(self, time_slice: MarketTimeSlice) -> list[Signal]:
+        """单时间片执行入口（Backtest 逐片编排的边界）：执行一个时间片并立即返回该片 Signal
+
+        对 MarketTimeSlice：
+        1. 以 slice.event_time 为上界装配全部 universe 窗口与 Canonical FactorValue
+          （完整信息集，先于任何策略回调）；
+        2. 校验片内每个 BarEvent 的标的窗口包含当根 Bar（数据截断/排序异常
+          显式失败，不静默算陈旧数据）；
+        3. 按时间片内的稳定顺序（边界优先级 + 标的字典序，仅确定性语义）
+          逐事件调度策略回调；
+        4. 该时间片产生的 Signal 整批收齐返回；交易 API 可在回调内产生订单与成交，
+           账户由事件监听器更新。
+
+        返回后调用方（Backtest）可执行撮合并更新 Portfolio，再处理下一时间片；
+        下一片的 StrategyContext 经只读 IStrategyPortfolioReader 读到新状态。
+        """
+        slice_frequency = self._slice_frequency(time_slice)
+        frequency = (
+            self.observation_frequency.value
+            if self.observation_frequency is not None
+            else slice_frequency
+        )
+        context, windows = await self._prepare(time_slice.event_time, frequency)
+        # 按稳定技术顺序调度（边界优先级 + 标的字典序，仅确定性语义），
+        # 输入排列不影响策略调用顺序与 Signal 输出顺序
+        ordered = sorted(time_slice.events, key=market_event_order_key)
+        signals: list[Signal] = []
+        day = time_slice.event_time.date()
+        if not self._initialized:
+            context._orders_allowed = False
+            signals.extend(await self._invoke_optional("init", context))
+            self._initialized = True
+            context._orders_allowed = True
+        if self._active_day != day:
+            self._active_day = day
+            context._orders_allowed = False
+            signals.extend(await self._invoke_optional("before_trading", context))
+            context._orders_allowed = True
+        for callback in self._scheduler.due(time_slice.event_time):
+            signals.extend(await self._invoke_optional(callback.callback_name, context))
+        for event in ordered:
+            if isinstance(event, BarEvent):
+                if (
+                    self.observation_frequency is not None
+                    and event.payload.frequency != self.observation_frequency.value
+                    and not self._has_observation_bar(
+                        windows, event.payload.instrument_id, time_slice.event_time
+                    )
+                ):
+                    continue
+                self._require_event_bar(windows, event.payload.instrument_id, time_slice.event_time)
+                event = event.model_copy(
+                    update={"payload": windows[event.payload.instrument_id][-1]}
+                )
+            signals.extend(await self._dispatch(event, context))
+        slice_callback = getattr(self.strategy, "on_slice", None)
+        if slice_callback is not None:
+            signals.extend(await slice_callback(time_slice, context) or ())
+        if day not in self._after_trading_days and self._has_session_close(time_slice):
+            context._orders_allowed = False
+            signals.extend(await self._invoke_optional("after_trading", context))
+            self._after_trading_days.add(day)
+        self.decisions = tuple(context.decisions)
+        return signals
+
+    async def run_slices(
+        self, slices: Iterable[MarketTimeSlice] | AsyncIterator[MarketTimeSlice]
+    ) -> list[Signal]:
+        """批量便利入口：逐时间片调用 run_slice（复用同一调度逻辑，不复制业务路径）。
+
+        仅适合一次性回放到结束的场景；需要在时间片之间撮合/更新 Portfolio 的
+        Backtest 必须自己逐片调用 run_slice。
+        """
+        stream = slices if isinstance(slices, AsyncIterator) else _aiter(list(slices))
+        signals: list[Signal] = []
+        async for time_slice in stream:
+            signals.extend(await self.run_slice(time_slice))
+        return signals
+
+    async def run(self, events) -> list[Signal]:
+        """按市场时间顺序消费原子事件流直到结束（单事件入口，复用同一调度逻辑）"""
+        signals: list[Signal] = []
+        async for event in events:
+            signals.extend(await self.handle(event))
+        return signals
+
+    async def handle(self, event) -> list[Signal]:
+        """处理单个事件：装配 StrategyContext → 调度策略回调"""
+        if isinstance(event, (BarEvent, TradingSessionEvent)):
+            return await self.run_slice(
+                MarketTimeSlice(event_time=event.event_time, events=[event])
+            )
+        return []  # 未知事件按契约忽略（Runtime 不做 Bar-centric 假设）
+
+    async def _dispatch(self, event, context: StrategyContext) -> list[Signal]:
+        """单事件 → 策略回调分发（原子流与时间片流共用，不复制业务逻辑）"""
+        if isinstance(event, BarEvent):
+            return await self.strategy.on_bar(event, context)
+        if isinstance(event, TradingSessionEvent):
+            return await self.strategy.on_session(event, context)
+        return []
+
+    async def _invoke_optional(self, callback_name: str, context: StrategyContext) -> list[Signal]:
+        callback = getattr(self.strategy, callback_name, None)
+        if callback is None:
+            return []
+        result = await callback(context)
+        return list(result or ())
+
+    @staticmethod
+    def _has_session_close(time_slice: MarketTimeSlice) -> bool:
+        return any(
+            isinstance(event, TradingSessionEvent)
+            and event.payload.session is MarketEventType.SESSION_CLOSE
+            for event in time_slice.events
+        )
+
+    def _set_universe(self, universe: tuple[str, ...]) -> None:
+        self._active_universe = universe
+
+    async def _prepare(
+        self, event_time: datetime, frequency: str = "1d"
+    ) -> tuple[StrategyContext, dict[str, list]]:
+        """装配完整上下文：每个 universe 标的截至 event_time（含）的窗口 + Canonical FactorValue
+
+        返回 (context, windows)；因子历史与发布状态归 Factor Store。
+        windows 供调用方做事件标的数据一致性防御校验
+        （窗口末根晚于/缺于事件时间 = 查询异常）。窗口上界永远 ≤ event_time，
+        Strategy 不可能读到未来数据。
+        """
+        definition = self.strategy.definition()
+        windows: dict[str, list] = {}
+        factors: dict[str, dict] = {}
+        universe = self._active_universe or tuple(self._universe(definition))
+        self._active_universe = universe
+        visible_universe = tuple(
+            instrument_id
+            for instrument_id in universe
+            if self._listing_dates.get(instrument_id) is None
+            or self._listing_dates[instrument_id] <= event_time.date()
+        )
+        for instrument_id in visible_universe:
+            listed_date = self._listing_dates.get(instrument_id)
+            if (
+                listed_date == event_time.date()
+                and frequency == BarFrequency.D1.value
+                and event_time.astimezone(ZoneInfo("Asia/Shanghai")).hour < 15
+            ):
+                windows[instrument_id] = []
+                continue
+            window = await self._bar_window(instrument_id, frequency, event_time)
+            windows[instrument_id] = window
+            if not window:
+                continue  # 停牌/未同步标的当天无 Bar 属正常语义
+        if definition.required_factors and visible_universe:
+            factors = await self.factor_reader.read_many(
+                tuple(definition.required_factors), visible_universe, event_time
+            )
+            for rows in factors.values():
+                if any(result.available_at > event_time for result in rows.values()):
+                    raise ValueError("Factor Reader 返回未来可见值，拒绝注入策略")
+        context = StrategyContext(
+            event_time=event_time,
+            market=StrategyMarketView(self.market, event_time, self.adjustment_type),
+            factors=factors,
+            parameters=definition.parameters,
+            state=self.state,
+            portfolio=self.portfolio,
+            strategy_id=definition.strategy_id,
+            order_reader=self.order_reader,
+            order_api=self._order_api,
+            current_data={key: value[-1] for key, value in windows.items() if value},
+            universe=visible_universe,
+            universe_setter=self._set_universe,
+            run_daily=self._scheduler.run_daily,
+            run_weekly=self._scheduler.run_weekly,
+            factor_selection=self._factor_selection,
+            exposure_query=self._exposure_query,
+            portfolio_construction=self._portfolio_construction,
+        )
+        return context, windows
+
+    @staticmethod
+    def _has_observation_bar(
+        windows: dict[str, list], instrument_id: str, event_time: datetime
+    ) -> bool:
+        window = windows.get(instrument_id, [])
+        return bool(window and window[-1].timestamp == event_time)
+
+    @staticmethod
+    def _require_event_bar(windows: dict[str, list], instrument_id: str, event_time) -> None:
+        """事件标的的窗口必须包含 event_time 当根 Bar（Replay 事件来自 DB Bar）"""
+        window = windows.get(instrument_id, [])
+        if not window or window[-1].timestamp != event_time:
+            actual = window[-1].timestamp if window else "无数据"
+            raise ValueError(
+                f"Bar 窗口末根 {actual} 与事件时间 {event_time} 不一致"
+                f"（instrument={instrument_id}），疑似查询截断/排序异常"
+            )
+
+    @staticmethod
+    def _slice_frequency(time_slice: MarketTimeSlice) -> str:
+        """时间片 Bar 频率取片内 BarEvent 的 frequency（无 Bar 默认日线）"""
+        for event in time_slice.events:
+            if isinstance(event, BarEvent):
+                return event.payload.frequency
+        return "1d"
+
+    async def _bar_window(self, instrument_id: str, frequency: str, event_time, limit: int = 100):
+        """截至 event_time（含）的 Canonical Bar 窗口（旧→新；上界不含未来数据）"""
+        if self.adjustment_type is AdjustmentType.NONE:
+            return await self.market.get_bars(
+                instrument_id,
+                frequency,
+                None,
+                event_time,
+                limit,
+            )
+        result = await self.market.get_adjusted_bars(
+            instrument_id,
+            frequency,
+            BarViewRequest(
+                adjustment_type=self.adjustment_type,
+                anchor_mode=AdjustmentAnchorMode.DECISION_TIME,
+                decision_time=event_time,
+            ),
+            None,
+            event_time,
+            limit,
+        )
+        return result.bars
+
+    @staticmethod
+    def _universe(definition) -> list[str]:
+        universe = list(definition.universe)
+        if not universe:
+            raise ValueError("StrategyDefinition.universe 为空且未外部指定标的池")
+        return universe

quant_core/app/strategy/service/strategy_scheduler.py

@@ -0,0 +1,50 @@
+"""Deterministic strategy callback schedules driven only by market time."""
+
+from dataclasses import dataclass
+from datetime import date, datetime, time
+
+
+@dataclass(frozen=True, slots=True)
+class ScheduledCallback:
+    callback_name: str
+    target_time: time
+    weekday: int | None = None
+
+    def __post_init__(self) -> None:
+        if not self.callback_name.strip():
+            raise ValueError("callback_name 不能为空")
+        if self.weekday is not None and self.weekday not in range(7):
+            raise ValueError("weekday 必须位于 [0, 6]")
+
+
+class StrategyScheduler:
+    """Registry and once-per-trading-day trigger state."""
+
+    def __init__(self) -> None:
+        self._callbacks: list[ScheduledCallback] = []
+        self._fired: set[tuple[date, ScheduledCallback]] = set()
+
+    def run_daily(self, callback_name: str, target_time: time) -> None:
+        self._register(ScheduledCallback(callback_name, target_time))
+
+    def run_weekly(self, callback_name: str, weekday: int, target_time: time) -> None:
+        self._register(ScheduledCallback(callback_name, target_time, weekday))
+
+    def due(self, event_time: datetime) -> tuple[ScheduledCallback, ...]:
+        day = event_time.date()
+        due: list[ScheduledCallback] = []
+        for callback in self._callbacks:
+            key = (day, callback)
+            if key in self._fired:
+                continue
+            if callback.weekday is not None and day.weekday() != callback.weekday:
+                continue
+            if event_time.timetz().replace(tzinfo=None) < callback.target_time:
+                continue
+            self._fired.add(key)
+            due.append(callback)
+        return tuple(due)
+
+    def _register(self, callback: ScheduledCallback) -> None:
+        if callback not in self._callbacks:
+            self._callbacks.append(callback)

quant_core/app/strategy/strategies/__init__.py

@@ -0,0 +1,7 @@
+"""内置策略（Python Native Demo；作者ing 入口之一，最终都编译为 Canonical Definition）"""
+
+from quant_core.app.strategy.strategies.momentum_volume_breakout import (
+    MomentumVolumeBreakoutStrategy,
+)
+
+__all__ = ["MomentumVolumeBreakoutStrategy"]

quant_core/app/strategy/strategies/momentum_volume_breakout.py

@@ -0,0 +1,157 @@
+"""
+Momentum Volume Breakout - P1 Demo Strategy（Python Native）
+
+规则（目标不是盈利，是验证 Market → Factor → Strategy → Signal 边界正确）：
+- Entry：momentum_20d > 阈值 AND volume_ratio_5d > 1.5 → ENTER LONG
+- Exit：close 跌破 ma_close_10 → EXIT
+
+边界收口：
+- 全部数值判断消费 Canonical FactorValue（因子计算只发生在 Factor 模块，Strategy
+  不重复计算任何因子，包括 MA）；
+- 持仓经 context.portfolio 只读获取（get_position），不维护 cash/position；
+  context.state 只允许策略内部状态（如 last_signal_time）；
+- 公式逻辑移植自 FactorHub（pct_change 动量 + 量比），按本项目规范以
+  Canonical Definition + StrategyProtocol 实现，不复用其 pandas 向量化引擎。
+"""
+
+from decimal import Decimal
+
+from quant_core.app.data.schema.event_schema import BarEvent, TradingSessionEvent
+from quant_core.app.factor.constants import (
+    FACTOR_MA_CLOSE_10,
+    FACTOR_MOMENTUM_20D,
+    FACTOR_VOLUME_RATIO_5D,
+)
+from quant_core.app.strategy.constants import (
+    AuthoringSource,
+    SignalSide,
+    SignalType,
+    StrategyStatus,
+    StrategyStyle,
+    StrategyType,
+)
+from quant_core.app.strategy.schema.signal_schema import Signal
+from quant_core.app.strategy.schema.strategy_schema import RuleCondition, StrategyDefinition
+from quant_core.app.strategy.strategy_context import StrategyContext
+
+_IMPLEMENTATION_REF = (
+    "quant_core.app.strategy.strategies.momentum_volume_breakout.MomentumVolumeBreakoutStrategy"
+)
+
+
+class MomentumVolumeBreakoutStrategy:
+    """放量突破短线策略（long_only，A股 V1 语义）"""
+
+    def __init__(
+        self,
+        universe: list[str],
+        momentum_threshold: float = 0.05,
+        volume_ratio_threshold: float = 1.5,
+        strategy_id: str = "momentum_volume_breakout",
+        version: str = "1",
+    ) -> None:
+        self._universe = universe
+        self._momentum_threshold = Decimal(str(momentum_threshold))
+        self._volume_ratio_threshold = Decimal(str(volume_ratio_threshold))
+        self._definition = StrategyDefinition(
+            strategy_id=strategy_id,
+            version=version,
+            name="放量突破短线",
+            description="20 日动量突破且放量入场；跌破 10 日均线出场",
+            strategy_type=StrategyType.TIMING,
+            styles=[StrategyStyle.MOMENTUM.value, StrategyStyle.BREAKOUT.value],
+            universe=universe,
+            required_factors=[FACTOR_MOMENTUM_20D, FACTOR_VOLUME_RATIO_5D, FACTOR_MA_CLOSE_10],
+            entry_rules=[
+                RuleCondition(left=FACTOR_MOMENTUM_20D, operator="gt", right=momentum_threshold),
+                RuleCondition(
+                    left=FACTOR_VOLUME_RATIO_5D, operator="gt", right=volume_ratio_threshold
+                ),
+            ],
+            exit_rules=[
+                RuleCondition(left="close", operator="cross_below", right=FACTOR_MA_CLOSE_10),
+            ],
+            holding_rules=["long_only；单标的全仓进出（V1 demo，不含仓位管理）"],
+            screening_rules=None,
+            position_intent="long_only",
+            parameters={
+                "momentum_threshold": momentum_threshold,
+                "volume_ratio_threshold": volume_ratio_threshold,
+            },
+            status=StrategyStatus.DRAFT,
+            authoring_source=AuthoringSource.PYTHON,
+            created_by="p1-demo",
+            parent_version=None,
+            implementation_ref=_IMPLEMENTATION_REF,
+        )
+
+    def definition(self) -> StrategyDefinition:
+        return self._definition
+
+    async def on_bar(self, event: BarEvent, context: StrategyContext) -> list[Signal]:
+        instrument_id = event.payload.instrument_id
+        momentum = context.factor_value(FACTOR_MOMENTUM_20D, instrument_id)
+        volume_ratio = context.factor_value(FACTOR_VOLUME_RATIO_5D, instrument_id)
+        ma = context.factor_value(FACTOR_MA_CLOSE_10, instrument_id)
+        position = (
+            await context.portfolio.get_position(instrument_id)
+            if context.portfolio is not None
+            else None
+        )
+        held = position is not None and position.quantity > 0
+
+        entry_ok = (
+            not held
+            and momentum is not None
+            and volume_ratio is not None
+            and momentum > self._momentum_threshold
+            and volume_ratio > self._volume_ratio_threshold
+        )
+        if entry_ok:
+            return [
+                self._signal(
+                    SignalType.ENTER,
+                    instrument_id,
+                    event.event_time,
+                    reason=f"momentum={momentum} > {self._momentum_threshold} "
+                    f"且 volume_ratio={volume_ratio} > {self._volume_ratio_threshold}",
+                    factor_refs=[FACTOR_MOMENTUM_20D, FACTOR_VOLUME_RATIO_5D],
+                )
+            ]
+        if held and ma is not None and event.payload.close < ma:
+            return [
+                self._signal(
+                    SignalType.EXIT,
+                    instrument_id,
+                    event.event_time,
+                    reason=f"close={event.payload.close} 跌破 {FACTOR_MA_CLOSE_10}={ma}",
+                    factor_refs=[FACTOR_MA_CLOSE_10],
+                )
+            ]
+        return []
+
+    async def on_session(
+        self, event: TradingSessionEvent, context: StrategyContext
+    ) -> list[Signal]:
+        return []  # V1 demo 不使用 Session 事件决策
+
+    def _signal(
+        self,
+        signal_type: SignalType,
+        instrument_id: str,
+        event_time,
+        reason: str,
+        factor_refs: list[str],
+    ) -> Signal:
+        side = SignalSide.LONG if signal_type == SignalType.ENTER else SignalSide.NONE
+        return Signal(
+            strategy_id=self._definition.strategy_id,
+            strategy_version=self._definition.version,
+            instrument_id=instrument_id,
+            event_time=event_time,
+            signal_type=signal_type,
+            side=side,
+            score=None,
+            reason=reason,
+            factor_refs=factor_refs,
+        )