powerquant-cli 0.2.6__py3-none-any.whl

quant_core/app/data/schema/trading_state_schema.py

@@ -0,0 +1,211 @@
+"""
+Market Runtime Schema - 市场交易状态事实契约
+
+定义两类客观市场事实（SSOT 见 DECISIONS.md 2026-09-04「市场状态采用增量事实投影」）：
+
+- TradingStateEvent：通用交易状态事实（TRADING/SUSPENDED/HALTED/AUCTION/CLOSED），
+  任何市场均可提供；不依赖 A 股规则。
+- PriceLimitEvent：可选事实。没有价格限制的市场可以完全不提供该事件；
+  提供时表达上下限价与买/卖流动性锁定状态。
+
+语义边界：
+- 两类事件只表达客观市场事实，不输出订单的 ALLOW / DEFER / REJECT——
+  该决策属于 Order Execution 的 TradabilityPolicy。
+- 状态是增量事实：从 event_time 生效并持续到后续事实显式覆盖；
+  事件缺席不表示恢复交易（投影见 MarketStateResolver）。
+- Bar 只表达 OHLCV，禁止从 Bar 推断停牌、涨停封板或跌停封板。
+"""
+
+from dataclasses import dataclass
+from datetime import datetime
+from decimal import Decimal
+from enum import Enum
+
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+from quant_core.app.data.constants import CANONICAL_INSTRUMENT_ID_PATTERN
+
+
+def validate_canonical_instrument_id(instrument_id: str) -> str:
+    """Canonical Instrument ID 唯一校验入口（复用 constants 的唯一格式规则）
+
+    拒绝空白值与非 Canonical 格式；域内事实 payload 统一走本函数，
+    不各自复制正则。
+    """
+    if not instrument_id.strip():
+        raise ValueError("instrument_id 不允许为空或纯空白")
+    if not CANONICAL_INSTRUMENT_ID_PATTERN.match(instrument_id):
+        raise ValueError(f"非法 Canonical instrument_id: {instrument_id!r}")
+    return instrument_id
+
+
+class TradingState(str, Enum):
+    """通用交易状态（市场无关）
+
+    UNKNOWN 不是可被事件显式声明的状态：它只表达「尚无任何状态事实」，
+    由 MarketStateResolver 投影产生；TradingStateEvent 声明 UNKNOWN 属于矛盾输入。
+    """
+
+    TRADING = "trading"
+    SUSPENDED = "suspended"
+    HALTED = "halted"
+    AUCTION = "auction"
+    CLOSED = "closed"
+    UNKNOWN = "unknown"
+
+
+class TradingStateEventPayload(BaseModel):
+    """TradingStateEvent 载荷：单标的一次客观交易状态事实"""
+
+    instrument_id: str = Field(..., description="Canonical 标识（CN.XSHE.000001）")
+    state: TradingState = Field(..., description="生效交易状态")
+
+    _validate_id = field_validator("instrument_id")(
+        classmethod(lambda cls, value: validate_canonical_instrument_id(value))
+    )
+
+    @model_validator(mode="after")
+    def _reject_contradictory_state(self) -> "TradingStateEventPayload":
+        if self.state is TradingState.UNKNOWN:
+            raise ValueError(
+                "TradingStateEvent 不允许声明 UNKNOWN：UNKNOWN 只表示尚无状态事实，"
+                "只能由 MarketStateResolver 投影产生，不是客观市场事实"
+            )
+        return self
+
+
+class PriceLimitEventPayload(BaseModel):
+    """PriceLimitEvent 载荷：单标的一次价格限制事实（可选市场提供）"""
+
+    instrument_id: str = Field(..., description="Canonical 标识（CN.XSHE.000001）")
+    limit_up: Decimal = Field(..., gt=0, description="涨停价（> 0）")
+    limit_down: Decimal = Field(..., gt=0, description="跌停价（> 0）")
+    buy_side_locked: bool = Field(False, description="买方向流动性锁定（涨停封板）")
+    sell_side_locked: bool = Field(False, description="卖方向流动性锁定（跌停封板）")
+
+    _validate_id = field_validator("instrument_id")(
+        classmethod(lambda cls, value: validate_canonical_instrument_id(value))
+    )
+
+    @model_validator(mode="after")
+    def _check_price_bounds(self) -> "PriceLimitEventPayload":
+        if self.limit_up <= self.limit_down:
+            raise ValueError(
+                f"价格限制边界非法：limit_up {self.limit_up} 必须严格大于 "
+                f"limit_down {self.limit_down}"
+            )
+        return self
+
+    @model_validator(mode="after")
+    def _reject_contradictory_locks(self) -> "PriceLimitEventPayload":
+        if self.buy_side_locked and self.sell_side_locked:
+            raise ValueError(
+                "买/卖方向不允许同时锁定：双向无流动性等价于停牌，"
+                "属于 TradingStateEvent 的表达范围，不是价格限制事实"
+            )
+        return self
+
+
+class DailyStateSnapshotEventPayload(BaseModel):
+    """DailyStateSnapshotEvent 载荷：单标的单日完整状态快照
+
+    与增量事实事件的语义边界（DECISIONS 2026-09-06「日级回放状态采用完整快照事件」）：
+    - trading_state 允许显式 UNKNOWN（表达「当日无官方事实」），这是快照独有的
+      表达能力；增量 TradingStateEvent 仍拒绝 UNKNOWN；
+    - limit_up/limit_dn 同时为 None = 显式清除当日价格限制（不依赖事件缺席）；
+      同时出现时必须满足 limit_up > limit_dn > 0；单边出现属矛盾输入。
+    """
+
+    instrument_id: str = Field(..., description="Canonical 标识（CN.XSHE.000001）")
+    trading_state: TradingState = Field(..., description="当日完整交易状态（允许 UNKNOWN）")
+    limit_up: Decimal | None = Field(None, gt=0, description="当日涨停价；None=无价格限制")
+    limit_dn: Decimal | None = Field(None, gt=0, description="当日跌停价；None=无价格限制")
+
+    _validate_id = field_validator("instrument_id")(
+        classmethod(lambda cls, value: validate_canonical_instrument_id(value))
+    )
+
+    @model_validator(mode="after")
+    def _check_limit_pair(self) -> "DailyStateSnapshotEventPayload":
+        if (self.limit_up is None) != (self.limit_dn is None):
+            raise ValueError(
+                "快照价格限制必须成对出现：limit_up/limit_dn 只允许同时为 None "
+                "（显式无限制）或同时给出（官方边界），单边出现属矛盾输入"
+            )
+        if (
+            self.limit_up is not None
+            and self.limit_dn is not None
+            and self.limit_up <= self.limit_dn
+        ):
+            raise ValueError(
+                f"快照价格限制边界非法：limit_up {self.limit_up} 必须严格大于 "
+                f"limit_dn {self.limit_dn}"
+            )
+        return self
+
+
+def _check_optional_event_id(value: str | None, field: str) -> str | None:
+    """可空事实来源标识校验：None 合法（非事件来源/默认态）；非 None 必须是非空、非纯空白标识
+
+    Market 域自持校验，不 import order_execution validator。
+    """
+    if value is None:
+        return None
+    if (
+        not isinstance(value, str)
+        or not value
+        or value.strip() != value
+        or any(ch.isspace() for ch in value)
+    ):
+        raise ValueError(f"{field} 必须是 None 或非空、不含空白字符的事件标识：{value!r}")
+    return value
+
+
+@dataclass(frozen=True)
+class PriceLimitState:
+    """某标的 point-in-time 价格限制投影（不可变只读）
+
+    source_event_id：最近一次生效的价格限制来源事件的 event_id（provenance）；
+    来源事件允许是增量 PriceLimitEvent 或日级 DailyStateSnapshotEvent（Q1-A）。
+    None 表示投影并非来自事件事实（兼容手工构造），下游不得伪造引用。
+    """
+
+    limit_up: Decimal
+    limit_down: Decimal
+    buy_side_locked: bool
+    sell_side_locked: bool
+    as_of: datetime
+    source_event_id: str | None = None
+
+    def __post_init__(self) -> None:
+        _check_optional_event_id(self.source_event_id, "source_event_id")
+
+
+@dataclass(frozen=True)
+class InstrumentMarketState:
+    """某标的 point-in-time 市场状态只读投影（InstrumentMarketState@T）
+
+    由 MarketStateResolver 从状态事实投影而来（状态来源事件允许是增量
+    TradingStateEvent 或日级 DailyStateSnapshotEvent，Q1-A；价格限制来源
+    事件允许是增量 PriceLimitEvent 或 DailyStateSnapshotEvent）：
+    - trading_state 为最近一次生效状态来源事件声明的状态；从未有任何状态
+      事件时为 UNKNOWN（默认态）；
+    - trading_state_as_of 为该状态事实的 event_time；从未有状态事实时为 None
+      （即使已有价格限制事实也是 None——价格限制不改变交易状态语义）；
+    - price_limit 为最近一次生效价格限制事实声明的边界，其生效时间独立记录
+      在 PriceLimitState.as_of；从未有价格限制事实时为 None。
+    - trading_state_event_id 为最近一次生效状态来源事件的 event_id
+      （provenance）：增量 TradingStateEvent 或 DailyStateSnapshotEvent
+      （含显式 UNKNOWN 的快照——快照是事实来源，拥有 provenance）；
+      仅 UNKNOWN 默认态（从未收到任何状态事件）或非事件来源为 None，
+      不伪造来源标识。
+    """
+
+    instrument_id: str
+    trading_state_as_of: datetime | None
+    trading_state: TradingState
+    price_limit: PriceLimitState | None = None
+    trading_state_event_id: str | None = None
+
+    def __post_init__(self) -> None:
+        _check_optional_event_id(self.trading_state_event_id, "trading_state_event_id")

quant_core/app/data/service/calendar_coverage_service.py

@@ -0,0 +1,63 @@
+"""CalendarCoverage - 交易所交易日历覆盖判定（T4R AC-7 三入口统一）
+
+「返回行非空」≠「日历已完整同步」：请求涉及的每个自然日都必须有一行日历事实，
+缺行是数据缺口（结构化失败），与休市（is_open=False，显式声明）严格区分。
+
+三入口共享同一判定：
+- sync_bars（写入前基线校验）
+- verify_bars（数据集健康检查）
+- Replay（回放窗口 open days 校验）
+"""
+
+from dataclasses import dataclass
+from datetime import date
+
+from quant_core.app.data.exceptions import MarketDataNotSyncedException
+
+
+@dataclass(frozen=True)
+class CalendarCoverage:
+    """一个交易所在 [start, end] 内的日历覆盖事实"""
+
+    exchange: str
+    start: date
+    end: date
+    open_days: tuple[date, ...]
+    missing_days: tuple[date, ...]
+
+    @property
+    def complete(self) -> bool:
+        """每个自然日都有日历行（is_open 与否均可）"""
+        return not self.missing_days
+
+    @property
+    def open_day_set(self) -> frozenset[date]:
+        return frozenset(self.open_days)
+
+    def require_complete(self) -> "CalendarCoverage":
+        """日历不完整 → 结构化失败（绝不静默当作空/休市区间）"""
+        if not self.complete:
+            raise MarketDataNotSyncedException(
+                f"交易日历未同步（{self.exchange} {self.start}~{self.end}），"
+                f"缺少 {len(self.missing_days)} 个自然日的日历行"
+                f"（如 {self.missing_days[0]}），请先 sync calendar"
+            )
+        return self
+
+
+def build_calendar_coverage(exchange: str, start: date, end: date, rows: list) -> CalendarCoverage:
+    """由日历行构建覆盖判定；rows 需带 trade_date / is_open 字段"""
+    row_dates = {r.trade_date for r in rows}
+    missing = tuple(d for d in _daterange(start, end) if d not in row_dates)
+    open_days = tuple(sorted(r.trade_date for r in rows if r.is_open))
+    return CalendarCoverage(
+        exchange=exchange,
+        start=start,
+        end=end,
+        open_days=open_days,
+        missing_days=missing,
+    )
+
+
+def _daterange(start: date, end: date) -> list[date]:
+    return [date.fromordinal(o) for o in range(start.toordinal(), end.toordinal() + 1)]

quant_core/app/data/service/prepared_data_verification_service.py

@@ -0,0 +1,40 @@
+"""固定下载批次的验证证据；回放不再读取远端可变状态。"""
+
+from quant_core.app.data.schema.reliability_schema import DatasetHealth, DatasetHealthResult
+
+
+class PreparedDataVerification:
+    def __init__(self) -> None:
+        self.results: dict[tuple, DatasetHealthResult] = {}
+
+    def add(self, dataset: str, instrument_id, frequency, start, end, result) -> None:
+        self.results[(dataset, instrument_id, frequency, start, end)] = (
+            DatasetHealthResult.model_validate(result.model_dump())
+        )
+
+    async def verify_bars(self, instrument_id, frequency, start, end):
+        return self._covering("bar", instrument_id, frequency, start, end)
+
+    async def verify_adjustment_factors(self, instrument_id, frequency, start, end):
+        return self._covering("adjustment_factor", instrument_id, frequency, start, end)
+
+    async def verify_corporate_actions(self, instrument_id, start, end):
+        return self._covering("corporate_action", instrument_id, "1d", start, end)
+
+    def _covering(self, dataset, instrument_id, frequency, start, end) -> DatasetHealthResult:
+        """完整大区间证明可用于子区间；保留原验证范围与计数，不伪造裁剪统计。"""
+        exact = self.results.get((dataset, instrument_id, frequency, start, end))
+        if exact is not None:
+            return exact
+        candidates = [
+            result
+            for (kind, instrument, freq, lower, upper), result in self.results.items()
+            if kind == dataset
+            and instrument == instrument_id
+            and freq == frequency
+            and lower <= start <= end <= upper
+            and result.health in (DatasetHealth.HEALTHY, DatasetHealth.STALE)
+        ]
+        if not candidates:
+            raise ValueError("本地快照没有覆盖请求范围的完整验证证据，请重新准备数据")
+        return min(candidates, key=lambda result: result.requested_end - result.requested_start)

quant_core/app/data/service/prepared_market_service.py

@@ -0,0 +1,189 @@
+"""回测运行内的只读市场数据集；时间片推进期间不访问网络。"""
+
+from bisect import bisect_left, bisect_right
+from datetime import date, datetime
+
+from quant_core.app.data.exceptions import MarketDataNotSyncedException
+from quant_core.app.data.schema.adjustment_schema import BarViewRequest
+from quant_core.app.data.schema.corporate_action_schema import CorporateActionResponse
+from quant_core.app.data.schema.history_schema import HistoryFacts
+from quant_core.app.data.schema.market_schema import (
+    BarResponse,
+    InstrumentResponse,
+    TradingCalendarDayResponse,
+    TradingRuleResponse,
+)
+from quant_core.app.data.schema.pit_daily_window import PITDailyWindow
+from quant_core.app.data.schema.quote_schema import DailyBasicResponse
+from quant_core.app.data.service.price_adjustment_service import PriceAdjustmentService
+
+
+class PreparedMarketData:
+    """用已准备的事实提供范围查询与复权计算，不含数据库或 SDK 连接。"""
+
+    def __init__(self, start: datetime, end: datetime, revision: str) -> None:
+        self.start = start
+        self.end = end
+        self.revision = revision
+        self.facts: dict[str, HistoryFacts] = {}
+        self.bars: dict[tuple[str, str], list[BarResponse]] = {}
+        self.timestamps: dict[tuple[str, str], list[datetime]] = {}
+        self.instruments: list[InstrumentResponse] = []
+
+    def add_bars(self, instrument_id: str, frequency: str, bars: list[BarResponse]) -> None:
+        key = (instrument_id, frequency)
+        self.bars[key] = bars
+        self.timestamps[key] = [bar.timestamp for bar in bars]
+
+    async def get_instrument(self, instrument_id: str) -> InstrumentResponse:
+        for row in self.instruments:
+            if row.instrument_id == instrument_id:
+                return row
+        raise MarketDataNotSyncedException(f"数据集不包含标的 {instrument_id}")
+
+    async def search_instruments(
+        self, keyword=None, instrument_type=None, exchange=None, limit=100
+    ):
+        return [
+            row
+            for row in self.instruments
+            if (keyword is None or keyword in row.name or keyword in row.symbol)
+            and (instrument_type is None or row.instrument_type == instrument_type)
+            and (exchange is None or row.exchange == exchange)
+        ][:limit]
+
+    async def list_instruments_on(self, on_date: date, limit=10000):
+        rows = [
+            row
+            for row in self.instruments
+            if row.listed_date is not None
+            and row.listed_date <= on_date
+            and (row.delisted_date is None or row.delisted_date >= on_date)
+        ]
+        if len(rows) > limit:
+            raise ValueError("股票池超出上限，拒绝截断")
+        return rows
+
+    async def list_trading_rules(self, instrument_ids: list[str], start: date, end: date):
+        return [
+            TradingRuleResponse.model_validate(rule)
+            for instrument_id in instrument_ids
+            for rule in self.facts[instrument_id].trading_rules
+            if rule.effective_from <= end
+            and (rule.effective_to is None or rule.effective_to >= start)
+        ]
+
+    async def list_bars(self, instrument_id, frequency, start=None, end=None, limit=1000):
+        if (start is not None and start < self.start) or (end is not None and end > self.end):
+            raise ValueError("行情请求超出已准备时间范围，请扩大数据准备窗口")
+        key = (instrument_id, frequency)
+        if key not in self.bars:
+            raise MarketDataNotSyncedException(f"数据集未准备 {key}")
+        timestamps = self.timestamps[key]
+        left = bisect_left(timestamps, start) if start else 0
+        right = bisect_right(timestamps, end) if end else len(timestamps)
+        return self.bars[key][max(left, right - limit) : right]
+
+    async def get_bars(self, instrument_id, frequency, start=None, end=None, limit=1000):
+        rows = await self.list_bars(instrument_id, frequency, start, end, limit)
+        if not rows:
+            raise MarketDataNotSyncedException(f"数据集中没有 {instrument_id} 的请求行情")
+        return rows
+
+    async def get_adjusted_bars(
+        self, instrument_id, frequency, view: BarViewRequest, start=None, end=None, limit=1000
+    ):
+        rows = await self.get_bars(instrument_id, frequency, start, end, limit)
+        return await PriceAdjustmentService(self).adjust(rows, view)
+
+    async def get_pit_daily_windows(
+        self,
+        instrument_id: str,
+        days: list[date],
+        next_days: list[date],
+        lookback: int,
+    ) -> tuple[PITDailyWindow, ...]:
+        """让已有 Alpha 输入适配器复用本地原始行情与复权事实，不发起 HTTP。"""
+        if not days or len(days) != len(next_days) or lookback < 1:
+            raise ValueError("PIT 窗口请求非法")
+        if min(days) < self.start.date() or max(next_days) > self.end.date():
+            raise ValueError("PIT 窗口超出本地数据范围，请扩展准备范围")
+        if instrument_id not in self.facts or (instrument_id, "1d") not in self.bars:
+            raise MarketDataNotSyncedException("本地数据缺少行情或复权事实")
+        factors = await self.list_adjustment_factors(
+            instrument_id, self.start.date(), max(next_days)
+        )
+        return PriceAdjustmentService.pit_daily_windows(
+            self.bars[(instrument_id, "1d")], factors, days, next_days, lookback
+        )
+
+    async def list_calendar_days(self, exchange: str, start: date, end: date, only_open=False):
+        if start < self.start.date() or end > self.end.date():
+            raise ValueError("日历请求超出已准备时间范围")
+        facts = next(
+            (item for item in self.facts.values() if item.instrument.exchange == exchange), None
+        )
+        if facts is None:
+            raise MarketDataNotSyncedException(f"数据集未准备 {exchange} 日历")
+        return [
+            TradingCalendarDayResponse.model_validate(row)
+            for row in facts.calendar
+            if start <= row.trade_date <= end and (not only_open or row.is_open)
+        ]
+
+    async def list_trading_days(self, exchange: str, start: date, end: date):
+        return await self.list_calendar_days(exchange, start, end, only_open=True)
+
+    async def is_trading_day(self, exchange: str, trade_date: date) -> bool:
+        rows = await self.list_calendar_days(exchange, trade_date, trade_date)
+        if not rows:
+            raise MarketDataNotSyncedException(f"日历缺少 {trade_date}")
+        return rows[0].is_open
+
+    async def list_daily_facts(self, instrument_id: str, start: date, end: date):
+        return [
+            row for row in self.facts[instrument_id].daily_facts if start <= row.trade_date <= end
+        ]
+
+    async def list_corporate_actions(
+        self, instrument_ids: list[str], start: date, end: date, known_at=None
+    ):
+        if known_at is not None:
+            raise ValueError("当前公司行动快照未包含历史知识时间修订，不能执行 known_at 查询")
+        return [
+            CorporateActionResponse.model_validate(row)
+            for instrument_id in instrument_ids
+            for row in self.facts[instrument_id].corporate_actions
+            if any(
+                day is not None and start <= day <= end
+                for day in (row.record_date, row.ex_date, row.pay_date, row.listing_date)
+            )
+        ]
+
+    async def list_adjustment_factors(
+        self, instrument_id: str, start: date, end: date, known_at=None
+    ):
+        latest = {}
+        for row in self.facts[instrument_id].adjustment_factors:
+            if start <= row.trade_date <= end and (known_at is None or row.recorded_at <= known_at):
+                old = latest.get(row.trade_date)
+                if old is None or row.recorded_at > old.recorded_at:
+                    latest[row.trade_date] = row
+        return [latest[day] for day in sorted(latest)]
+
+    async def get_adjustment_factor_on_or_before(
+        self, instrument_id, on_or_before=None, known_at=None
+    ):
+        rows = await self.list_adjustment_factors(
+            instrument_id,
+            self.start.date(),
+            on_or_before or self.end.date(),
+            known_at,
+        )
+        return rows[-1] if rows else None
+
+    async def list_daily_basic_at(
+        self, decision_time: datetime, limit: int = 10000
+    ) -> list[DailyBasicResponse]:
+        """当前快照不含每日估值指标；明确缺少输入，不能隐式联网补数。"""
+        raise MarketDataNotSyncedException("本地数据快照未准备每日估值指标")