powerquant-cli 0.2.6__py3-none-any.whl

quant_core/app/trading_runtime/runtime_session.py

@@ -0,0 +1,361 @@
+"""共享市场事件循环；策略在回调内同步下单，Runtime 不计算或推进调仓计划。"""
+
+from datetime import datetime
+from decimal import Decimal
+from enum import Enum
+
+from quant_core.app.data.constants import MarketEventType
+from quant_core.app.data.schema.event_schema import (
+    BarEvent,
+    CorporateActionEvent,
+    MarketTimeSlice,
+    TradingSessionEvent,
+)
+from quant_core.app.order_execution.constants import ExecutionAttemptOutcome
+from quant_core.app.order_execution.domain.order_event import (
+    ExecutionAttempt,
+    Fill,
+    OrderTransition,
+)
+from quant_core.app.order_execution.domain.order_value import OrderAck, OrderIntent
+from quant_core.app.order_execution.interface.public.order_execution import IOrderExecution
+from quant_core.app.order_execution.interface.public.order_runtime import IOrderRuntime
+from quant_core.app.order_execution.schema.order_request_schema import OrderRequest
+from quant_core.app.trading_runtime.runtime_ports import (
+    ExchangeStateProjectionProtocol,
+    MarketStateProjectionProtocol,
+    RuntimePortfolioProtocol,
+    StrategyRuntimeProtocol,
+)
+from quant_core.app.trading_runtime.runtime_schema import (
+    ClockProtocol,
+    RuntimeStepResult,
+    TraceEntry,
+)
+
+
+class RuntimeSessionState(str, Enum):
+    """Session 生命周期状态机：READY → STEPPING → READY；任一异常 → FAILED"""
+
+    READY = "ready"
+    STEPPING = "stepping"
+    FAILED = "failed"
+
+
+class RuntimeSession:
+    """单时间片编排器（Backtest / Paper / Live 共享同一因果顺序）
+
+    构造注入全部协作 Port（具体实现只在组合点装配）：
+
+    - clock：场景无关时钟（clock.now() 必须等于本片时间）；
+    - market_state_resolver：Market 域增量投影 Port；
+    - order_execution：Order Execution Port；
+    - portfolio：组合聚合（RuntimePortfolioProtocol：组合更新 + 执行期
+      只读账户视图，同一对象两个能力面）；
+    - strategy_runtime：StrategyRuntimeProtocol（现有 StrategyRuntimeService
+      零修改即满足）；
+    - order_api：同步交易环境及审计读取能力。
+    """
+
+    def __init__(
+        self,
+        clock: ClockProtocol,
+        market_state_resolver: MarketStateProjectionProtocol,
+        exchange_state_resolver: ExchangeStateProjectionProtocol,
+        order_execution: IOrderExecution,
+        portfolio: RuntimePortfolioProtocol,
+        strategy_runtime: StrategyRuntimeProtocol,
+        order_api: IOrderRuntime,
+    ) -> None:
+        self._clock = clock
+        self._resolver = market_state_resolver
+        self._exchange_resolver = exchange_state_resolver
+        self._execution = order_execution
+        self._portfolio = portfolio
+        self._strategy_runtime = strategy_runtime
+        self._order_api = order_api
+        self._state = RuntimeSessionState.READY
+        self._last_slice_time: datetime | None = None
+
+    # ------------------------------------------------------------------
+    # 公开状态
+    # ------------------------------------------------------------------
+
+    @property
+    def state(self) -> RuntimeSessionState:
+        return self._state
+
+    @property
+    def last_slice_time(self) -> datetime | None:
+        """上一个成功 step 的时间片时间（尚未成功 step 时为 None）"""
+        return self._last_slice_time
+
+    # ------------------------------------------------------------------
+    # 单时间片编排
+    # ------------------------------------------------------------------
+
+    async def step(self, time_slice: MarketTimeSlice) -> RuntimeStepResult:
+        """严格执行一个 MarketTimeSlice（固定因果顺序；任一异常即 FAILED）"""
+        if self._state is RuntimeSessionState.FAILED:
+            raise RuntimeError(
+                "RuntimeSession 已处于 FAILED 状态：写阶段可能已部分完成，"
+                "禁止在同一 Session 继续运行（由上层 BacktestRun 终止整个 run）"
+            )
+        if self._state is RuntimeSessionState.STEPPING:
+            raise RuntimeError("RuntimeSession.step 不允许重入")
+        self._state = RuntimeSessionState.STEPPING
+        try:
+            return await self._step(time_slice)
+        except BaseException:
+            # fail-fast：任一阶段失败后 Session 不可继续（无跨域事务回滚）
+            self._state = RuntimeSessionState.FAILED
+            raise
+
+    # ------------------------------------------------------------------
+
+    def _validate_time(self, slice_time: datetime) -> None:
+        """step 前时间边界：全部失败路径零下游调用"""
+        if slice_time.tzinfo is None:
+            raise ValueError("MarketTimeSlice.event_time 必须 timezone-aware")
+        now = self._clock.now()
+        if not isinstance(now, datetime) or now.tzinfo is None:
+            raise ValueError("Clock.now() 必须返回 timezone-aware datetime")
+        if now != slice_time:
+            raise ValueError(f"clock.now() {now} 必须等于 slice_time {slice_time}")
+        if self._last_slice_time is not None and slice_time <= self._last_slice_time:
+            raise ValueError(
+                f"时间片必须严格递增：{slice_time} 不晚于上一个成功片 "
+                f"{self._last_slice_time}（重复/倒流 slice 拒绝）"
+            )
+
+    def _has_session_open(self, time_slice: MarketTimeSlice) -> bool:
+        """新交易日结算的唯一触发边界：显式 TradingSessionEvent(SESSION_OPEN)"""
+        return any(
+            isinstance(event, TradingSessionEvent)
+            and event.payload.session is MarketEventType.SESSION_OPEN
+            for event in time_slice.events
+        )
+
+    def _settle_if_new_trading_day(self, time_slice: MarketTimeSlice) -> None:
+        """显式 SESSION_OPEN 才结算；账户级一次（同片多 Exchange OPEN 去重）"""
+        if self._has_session_open(time_slice):
+            self._portfolio.settle_trading_day(time_slice.event_time.date())
+
+    def _bar_close_prices(self, time_slice: MarketTimeSlice) -> dict[str, Decimal]:
+        """本片每标的一根 Bar 的 close（稳定构造；矛盾重复 Bar 即失败）"""
+        prices: dict[str, Decimal] = {}
+        for event in time_slice.events:
+            if isinstance(event, BarEvent):
+                bar = event.payload
+                if bar.instrument_id in prices:
+                    raise ValueError(f"同一时间片出现多根 {bar.instrument_id} Bar，属矛盾输入")
+                prices[bar.instrument_id] = bar.close
+        return prices
+
+    def _apply_corporate_actions(self, time_slice: MarketTimeSlice) -> None:
+        """Fill 后、估值前应用权益事件；登记日收盘成交可获得当日权益。"""
+        actions = sorted(
+            (event for event in time_slice.events if isinstance(event, CorporateActionEvent)),
+            key=lambda event: (event.payload.action.action_id, event.payload.phase.value),
+        )
+        for event in actions:
+            self._portfolio.apply_corporate_action(event.payload, time_slice.event_time)
+
+    def _validate_signal_times(self, signals: list, slice_time: datetime) -> tuple:
+        for signal in signals:
+            if signal.event_time != slice_time:
+                raise ValueError(
+                    f"Signal.event_time {signal.event_time} 必须等于 slice_time "
+                    f"{slice_time}（signal_id={signal.signal_id}）"
+                )
+        return tuple(signals)
+
+    def _validate_intent_times(self, intents: tuple, slice_time: datetime) -> tuple:
+        for intent in intents:
+            if intent.creation_event_time != slice_time:
+                raise ValueError(
+                    f"OrderIntent.creation_event_time {intent.creation_event_time} "
+                    f"必须等于 slice_time {slice_time}"
+                    f"（intent_id={intent.intent_id}）；不 submit"
+                )
+        return intents
+
+    def _validate_ack_times(self, acks: tuple, slice_time: datetime) -> tuple:
+        for ack in acks:
+            if ack.event_time != slice_time:
+                raise ValueError(
+                    f"OrderAck.event_time {ack.event_time} 必须等于 slice_time "
+                    f"{slice_time}（intent_id={ack.intent_id}）"
+                )
+        return acks
+
+    def _build_trace_entries(
+        self,
+        slice_time: datetime,
+        fills: tuple[Fill, ...],
+        attempts: tuple[ExecutionAttempt, ...],
+        order_updates: tuple[OrderTransition, ...],
+        signals: tuple,
+        requests: tuple[OrderRequest, ...],
+        intents: tuple[OrderIntent, ...],
+        acks: tuple[OrderAck, ...],
+    ) -> tuple[TraceEntry, ...]:
+        """确定性顺序的审计条目（分类固定；detail 仅人类可读，不驱动行为）"""
+        entries: list[TraceEntry] = []
+        for fill in fills:
+            entries.append(
+                TraceEntry(
+                    event_time=slice_time,
+                    kind="fill",
+                    detail=(
+                        f"fill_id={fill.fill_id} order_id={fill.order_id} "
+                        f"{fill.instrument_id} {fill.side.value} "
+                        f"{fill.quantity}@{fill.price}"
+                    ),
+                )
+            )
+        for attempt in attempts:
+            if attempt.outcome is ExecutionAttemptOutcome.DEFERRED:
+                entries.append(
+                    TraceEntry(
+                        event_time=slice_time,
+                        kind="execution_deferred",
+                        detail=(
+                            f"attempt_id={attempt.attempt_id} order_id={attempt.order_id} "
+                            f"reason={attempt.defer_reason.value if attempt.defer_reason else None}"
+                        ),
+                    )
+                )
+        for update in order_updates:
+            entries.append(
+                TraceEntry(
+                    event_time=slice_time,
+                    kind="order_update",
+                    detail=(
+                        f"order_id={update.order_id} status={update.current_status.value} "
+                        f"reason={update.reason_code.value}"
+                    ),
+                )
+            )
+        for signal in signals:
+            entries.append(
+                TraceEntry(
+                    event_time=slice_time,
+                    kind="signal",
+                    detail=(
+                        f"signal_id={signal.signal_id} {signal.instrument_id} "
+                        f"{signal.signal_type.value} {signal.side.value}"
+                    ),
+                )
+            )
+        for request in requests:
+            entries.append(
+                TraceEntry(
+                    event_time=slice_time,
+                    kind="strategy_order_request",
+                    detail=(
+                        f"request_id={request.request_id} strategy_id={request.strategy_id} "
+                        f"{request.instrument_id} {request.request_type.value}"
+                    ),
+                )
+            )
+        for intent in intents:
+            entries.append(
+                TraceEntry(
+                    event_time=slice_time,
+                    kind="order_intent",
+                    detail=(
+                        f"intent_id={intent.intent_id} {intent.instrument_id} "
+                        f"{intent.side.value} {intent.quantity}"
+                    ),
+                )
+            )
+        for ack in acks:
+            reason = ack.rejection_reason.value if ack.rejection_reason else None
+            entries.append(
+                TraceEntry(
+                    event_time=slice_time,
+                    kind="order_ack",
+                    detail=(
+                        f"intent_id={ack.intent_id} status={ack.status.value} "
+                        f"order_id={ack.order_id} rejection_reason={reason}"
+                    ),
+                )
+            )
+        return tuple(entries)
+
+    async def _step(self, time_slice: MarketTimeSlice) -> RuntimeStepResult:
+        # 1. 时间边界（失败零下游调用）
+        self._validate_time(time_slice.event_time)
+        t = time_slice.event_time
+
+        # 2. 市场状态投影（先于撮合）；交易所运行状态投影（T4R 唯一 SSOT）
+        market_states = self._resolver.apply_slice(time_slice)
+        exchange_states = self._exchange_resolver.apply_slice(time_slice)
+
+        # 3. 新交易日结算（显式 SESSION_OPEN；先于旧单撮合）
+        self._settle_if_new_trading_day(time_slice)
+
+        # 4. 旧订单撮合（本片新单绝不参与；account view 即同一 Portfolio；
+        # 交易所运行状态由 Resolver 投影注入，Execution 不自行解释 Session 事件）
+        processing_result = self._execution.process_market_slice(
+            time_slice,
+            market_states,
+            exchange_states,
+            self._portfolio,
+        )
+
+        # 6. 公司行动：登记日权益基于本片成交后的持仓；除权/到账在估值前生效。
+        self._apply_corporate_actions(time_slice)
+
+        # 7. 本片 Bar Close 估值（空映射仍调用，使 snapshot.as_of 推进到 T）
+        prices = self._bar_close_prices(time_slice)
+        self._portfolio.mark_to_market(prices, t)
+
+        self._order_api.begin_slice(time_slice, prices, exchange_states)
+        signals = await self._strategy_runtime.run_slice(time_slice)
+        signal_batch = self._validate_signal_times(signals, t)
+        requests = tuple(self._order_api.requests)
+        intent_batch = self._validate_intent_times(tuple(self._order_api.intents), t)
+        ack_batch = self._validate_ack_times(tuple(self._order_api.acks), t)
+        order_updates = processing_result.order_updates + tuple(self._order_api.cancellations)
+        matches = self._order_api.matches
+        fills = processing_result.fills + tuple(fill for batch in matches for fill in batch.fills)
+        attempts = processing_result.execution_attempts + tuple(
+            attempt for batch in matches for attempt in batch.execution_attempts
+        )
+        order_updates += tuple(update for batch in matches for update in batch.order_updates)
+        order_updates += self._execution.finish_slice(time_slice)
+        self._portfolio.mark_to_market(prices, t)
+        snapshot = self._portfolio.snapshot()
+
+        # 15-16. 组装 trace 与 StepResult@T（构造失败即 step 失败）
+        trace_entries = self._build_trace_entries(
+            t,
+            fills,
+            attempts,
+            order_updates,
+            signal_batch,
+            requests,
+            intent_batch,
+            ack_batch,
+        )
+        result = RuntimeStepResult(
+            slice_time=t,
+            fills=fills,
+            execution_attempts=attempts,
+            order_acks=ack_batch,
+            order_updates=order_updates,
+            signals=signal_batch,
+            portfolio_decisions=self._strategy_runtime.decisions,
+            strategy_order_requests=requests,
+            order_intents=intent_batch,
+            portfolio_snapshot=snapshot,
+            exchange_states=tuple(exchange_states[k] for k in sorted(exchange_states)),
+            trace_entries=trace_entries,
+        )
+
+        # 17. 提交 last successful slice time（仅在完整 StepResult 构造成功后）
+        self._state = RuntimeSessionState.READY
+        self._last_slice_time = t
+        return result

quant_core/app/trading_runtime/strategy_portfolio_adapter.py

@@ -0,0 +1,58 @@
+"""Portfolio 同步只读能力到 Strategy 异步查询的适配。
+
+每次委托当前账户，确保策略读取的是本片成交和估值后的真实状态。
+既有 CashView/PositionView 保持原语义；组合构建另通过公开快照与持仓批次
+读取市值、取得时间和剩余数量。适配器不缓存、推断或修改资产事实。
+"""
+
+from typing import Protocol
+
+from quant_core.app.portfolio.interface.public.portfolio import IPortfolioReader
+from quant_core.app.portfolio.ledger_schema import PositionLotSnapshot
+from quant_core.app.portfolio.portfolio_schema import PortfolioSnapshot
+from quant_core.app.strategy.interface.public.strategy_portfolio_reader import (
+    IStrategyPortfolioReader,
+)
+from quant_core.app.strategy.schema.portfolio_schema import CashView, PositionView
+
+
+class StrategyPortfolioSource(IPortfolioReader, Protocol):
+    """适配器只依赖账户读取和成交批次事实。"""
+
+    def snapshot(self) -> PortfolioSnapshot:
+        """读取当前真实估值快照。"""
+        ...
+
+    def position_lots(self) -> tuple[PositionLotSnapshot, ...]:
+        """读取成交形成的持仓批次。"""
+        ...
+
+
+class StrategyPortfolioReaderAdapter(IStrategyPortfolioReader):
+    """Portfolio 同步只读 Protocol → Strategy async 只读 Protocol 的桥
+
+    显式继承 Strategy 域 Protocol（不重新定义第二套形状）。
+    """
+
+    def __init__(self, portfolio: StrategyPortfolioSource) -> None:
+        self._portfolio = portfolio
+
+    async def get_position(self, instrument_id: str) -> PositionView | None:
+        """实时读取当前持仓并翻译为 PositionView（无持仓返回 None）"""
+        position = self._portfolio.get_position(instrument_id)
+        if position is None:
+            return None
+        return PositionView(instrument_id=position.instrument_id, quantity=position.quantity)
+
+    async def get_cash(self) -> CashView:
+        """实时读取当前资金并翻译为 CashView（available_cash → cash）"""
+        cash = self._portfolio.get_cash()
+        return CashView(cash=cash.available_cash)
+
+    async def get_snapshot(self) -> PortfolioSnapshot:
+        """读取账户估值，不缓存或修改资产事实。"""
+        return self._portfolio.snapshot()
+
+    async def get_position_lots(self) -> tuple[PositionLotSnapshot, ...]:
+        """读取真实持仓批次，供持有期约束使用。"""
+        return self._portfolio.position_lots()

quant_core/app/trading_runtime/trading_rule_book.py

@@ -0,0 +1,37 @@
+"""交易规则的时间有效性解析。"""
+
+from collections.abc import Iterable
+from datetime import date, datetime
+
+from quant_core.app.data.schema.market_schema import TradingRuleResponse
+
+
+class EffectiveTradingRuleBook:
+    """不可变规则簿；缺失或重叠均失败关闭。"""
+
+    def __init__(self, rules: Iterable[TradingRuleResponse]) -> None:
+        grouped: dict[str, list[TradingRuleResponse]] = {}
+        for rule in rules:
+            grouped.setdefault(rule.instrument_id, []).append(rule)
+        normalized: dict[str, tuple[TradingRuleResponse, ...]] = {}
+        for instrument_id, rows in grouped.items():
+            ordered = tuple(sorted(rows, key=lambda item: item.effective_from))
+            for previous, current in zip(ordered, ordered[1:], strict=False):
+                if previous.effective_to is None or previous.effective_to >= current.effective_from:
+                    raise ValueError(f"{instrument_id} TradingRule 有重叠有效期")
+            normalized[instrument_id] = ordered
+        self._rules = normalized
+
+    def resolve(self, instrument_id: str, at: date | datetime) -> TradingRuleResponse:
+        business_date = at.date() if isinstance(at, datetime) else at
+        matches = tuple(
+            rule
+            for rule in self._rules.get(instrument_id, ())
+            if rule.effective_from <= business_date
+            and (rule.effective_to is None or business_date <= rule.effective_to)
+        )
+        if len(matches) != 1:
+            raise ValueError(
+                f"{instrument_id} 在 {business_date} 必须恰有一条 TradingRule，实际 {len(matches)}"
+            )
+        return matches[0]

quant_core/app/trading_runtime/trading_rule_query.py

@@ -0,0 +1,12 @@
+"""订单规划消费的最小交易规则接口。"""
+
+from datetime import date, datetime
+from typing import Protocol
+
+from quant_core.app.data.schema.market_schema import TradingRuleResponse
+
+
+class ITradingRuleQuery(Protocol):
+    def resolve(self, instrument_id: str, at: date | datetime) -> TradingRuleResponse:
+        """返回业务时点唯一有效的交易规则，缺失或重叠应失败。"""
+        ...

quant_core/common/exceptions/base.py

@@ -0,0 +1,89 @@
+"""
+通用异常机制基类 - Common owns mechanism, Domain owns semantics
+
+本模块只定义机制:AppException 基类 + 通用抽象子类（不存在/冲突/未认证等）。
+具体 Domain 的业务错误（OrderNotFound / UserDisabled 等）由各 Domain 的
+app/{module}/exceptions.py 自定义并继承这里的基类，common 不存放业务语义。
+
+设计约束:本模块不得 import fastapi。Service 层只依赖异常基类,
+协议层(HTTP / WebSocket / CLI / Task Worker)各自负责翻译。
+
+命名约定:
+- error_code: 业务语义错误码字符串,跨入口复用,供 WS / MQ / 前端编程判断。
+- http_status: HTTP 协议状态码,仅 HTTP 入口翻译使用。
+
+两个入口完全分离:HTTP 响应体放 http_status,WS 响应放 error_code,
+不要让两者共用一个名叫 code 的字段。
+
+新增异常类型:继承 AppException 或其子类,声明 error_code / http_status 两个类属性即可,
+无需修改构造签名。
+"""
+
+from typing import ClassVar
+
+
+class AppException(Exception):
+    """应用业务异常基类。
+
+    Attributes:
+        message: 面向用户的错误描述(默认中文)。
+        error_code:   稳定的业务错误码字符串,跨入口复用,供 WS / MQ / 前端编程判断。
+        http_status:  建议的 HTTP 状态码,供 HTTP handler 翻译;默认 400。
+    """
+
+    error_code: ClassVar[str] = "APP_ERROR"
+    http_status: ClassVar[int] = 400
+
+    def __init__(self, message: str = "业务处理失败"):
+        self.message = message
+        super().__init__(self.message)
+
+
+class NotFoundException(AppException):
+    """资源不存在"""
+
+    error_code = "NOT_FOUND"
+    http_status = 404
+
+    def __init__(self, message: str = "资源不存在"):
+        super().__init__(message)
+
+
+class UnauthorizedException(AppException):
+    """未认证或认证失败(凭证无效、账户禁用等)"""
+
+    error_code = "UNAUTHORIZED"
+    http_status = 401
+
+    def __init__(self, message: str = "认证失败"):
+        super().__init__(message)
+
+
+class PermissionDeniedException(AppException):
+    """无权限访问"""
+
+    error_code = "PERMISSION_DENIED"
+    http_status = 403
+
+    def __init__(self, message: str = "无权访问"):
+        super().__init__(message)
+
+
+class ConflictException(AppException):
+    """资源冲突,例如唯一约束冲突、状态非法变更"""
+
+    error_code = "CONFLICT"
+    http_status = 409
+
+    def __init__(self, message: str = "资源冲突"):
+        super().__init__(message)
+
+
+class ValidationException(AppException):
+    """业务规则校验失败(区别于 FastAPI 的请求体格式校验)"""
+
+    error_code = "VALIDATION_ERROR"
+    http_status = 422
+
+    def __init__(self, message: str = "请求参数校验失败"):
+        super().__init__(message)

quant_core/common/local_run.py

@@ -0,0 +1,45 @@
+"""本地执行记录的协议无关信封，不包含领域结果模型。"""
+
+import hashlib
+import json
+from datetime import UTC, datetime
+from enum import Enum
+from typing import Any
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, Field, model_validator
+
+
+class RunStatus(str, Enum):
+    COMPLETED = "completed"
+    FAILED = "failed"
+
+
+class LocalRunRecord(BaseModel):
+    """执行来源与结果索引；领域结果由所属模块解释。"""
+
+    uuid: UUID = Field(default_factory=uuid4)
+    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    status: RunStatus = RunStatus.COMPLETED
+    request: dict[str, Any]
+    provenance: dict[str, Any] = Field(default_factory=dict)
+    result: dict[str, Any] = Field(default_factory=dict)
+    error: str | None = None
+
+    @model_validator(mode="after")
+    def validate_record(self) -> "LocalRunRecord":
+        if self.created_at.utcoffset() is None:
+            raise ValueError("运行记录创建时间必须带时区")
+        if (self.status == RunStatus.FAILED) != (self.error is not None):
+            raise ValueError("运行状态与错误信息不一致")
+        return self
+
+
+def content_digest(value: str) -> str:
+    """稳定内容摘要，不用于身份认证。"""
+    return hashlib.sha256(value.encode("utf-8")).hexdigest()
+
+
+def json_value(value: Any) -> Any:
+    """将数值与日期保留为精确文本，供 JSON 产物使用。"""
+    return json.loads(json.dumps(value, default=str, ensure_ascii=False, allow_nan=False))