powerquant-cli 0.2.6__py3-none-any.whl

quant_core/app/order_execution/slippage_model.py

@@ -0,0 +1,40 @@
+"""Slippage Model - 可注入滑点模型（T5）
+
+SSOT：T5 Task「Mock Fee / Slippage 参数（2026-09-04 用户确认）」。
+
+- SlippageModelProtocol 是 order_execution 消费方拥有的最小消费面。
+- FixedBpsSlippageModel：固定 bps 滑点——BUY = Open × (1 + bps/10000)；
+  SELL = Open × (1 - bps/10000)。只消费 Open，不读取 High/Low/Close。
+- 全部 Decimal、不 quantize、无状态、相同输入结果一致。
+"""
+
+from decimal import Decimal
+from typing import cast
+
+from quant_core.app.order_execution.constants import OrderSide
+from quant_core.app.order_execution.validators import reject_float_amount
+
+
+class FixedBpsSlippageModel:
+    """固定 bps 滑点模型（Mock 确定性配置）"""
+
+    def __init__(self, fixed_slippage_bps: Decimal) -> None:
+        checked = reject_float_amount(fixed_slippage_bps, "fixed_slippage_bps")
+        bps = checked if isinstance(checked, Decimal) else Decimal(cast(int | str, checked))
+        if not bps.is_finite():
+            raise ValueError(
+                "fixed_slippage_bps 必须是有限 Decimal，禁止字符串形式的 NaN / Infinity / sNaN"
+            )
+        if bps < 0:
+            raise ValueError(f"fixed_slippage_bps 必须 >= 0，实际 {bps}")
+        self.ratio = bps / Decimal("10000")
+
+    def apply(self, side: OrderSide, bar_open: Decimal) -> Decimal:
+        reject_float_amount(bar_open, "bar_open")
+        if side is OrderSide.BUY:
+            price = bar_open * (Decimal("1") + self.ratio)
+        else:
+            price = bar_open * (Decimal("1") - self.ratio)
+        if price <= 0:
+            raise ValueError(f"滑点后成交价必须 > 0，实际 {price}")
+        return price

quant_core/app/order_execution/tradability_policy.py

@@ -0,0 +1,174 @@
+"""Tradability Policy - 纯决策、可注入的市场可交易性判断（T4）
+
+语义 SSOT 见 `app/order_execution/SPEC.md`、DECISIONS.md 2026-09-04
+「回测撮合以通用市场交易事实和可替换 Policy 表达市场限制」、T4 Task 及用户裁定：
+
+    Market Facts + Order
+              |
+              v
+      TradabilityPolicy
+              |
+              +── ALLOW
+              |
+              +── DEFER(reason)
+
+边界：
+- Policy 是纯函数式决策：只消费 OrderSnapshot 最小读取面与 InstrumentMarketState，
+  返回结构化 TradabilityDecisionRecord；不修改 Order / Portfolio，不产生
+  Fill / OrderUpdate / OrderAck；DEFER 只表达「本次市场暂不可成交」，
+  Order 保持 PENDING，状态恢复后可继续参与后续撮合。
+- 静态非法输入（非法 id / quantity / order type / execution policy）属于
+  submit 阶段 REJECT，与本 Policy 无关；Policy 不返回 REJECT。
+- 不读取 wall clock / Runtime mode，不知道 Backtest/Paper/Live；
+  相同输入返回逐字段相同结果。
+- TradingState 的禁止交易优先级高于 PriceLimitState；原因码与实际阻塞
+  条件一一对应（显式决策表，无嵌套分支、无字符串 reason）。
+- 价格限制语义以 PriceLimitEvent 事实为准；Policy 不从 Bar OHLC 推断
+  封板，不计算涨跌停价格，不读 ST / 板块 / 交易所涨跌幅规则。
+"""
+
+from quant_core.app.data.schema.trading_state_schema import (
+    InstrumentMarketState,
+    PriceLimitState,
+    TradingState,
+)
+from quant_core.app.order_execution.constants import (
+    ExecutionDeferReason,
+    OrderSide,
+    TradabilityDecision,
+)
+from quant_core.app.order_execution.domain.order_value import (
+    OrderSnapshot,
+)
+from quant_core.app.order_execution.domain.order_value import (
+    TradabilityDecision as TradabilityDecisionRecord,
+)
+
+# TradingState 显式决策表（禁止交易状态 → 一一对应的原因码）。
+# TradingState 的禁止优先级高于 PriceLimitState：表内命中即 DEFER，
+# 不再检查价格限制。TRADING 不在表内，进入价格限制检查。
+_BLOCKED_TRADING_STATE: dict[TradingState, ExecutionDeferReason] = {
+    TradingState.SUSPENDED: ExecutionDeferReason.SUSPENDED,
+    TradingState.HALTED: ExecutionDeferReason.HALTED,
+    # AUCTION / CLOSED：非连续交易时段，保守 DEFER（T1 枚举复用，不新增同义状态）
+    TradingState.AUCTION: ExecutionDeferReason.SESSION_NOT_TRADABLE,
+    TradingState.CLOSED: ExecutionDeferReason.SESSION_NOT_TRADABLE,
+    TradingState.UNKNOWN: ExecutionDeferReason.TRADING_STATE_UNKNOWN,
+}
+
+
+def _state_evidence(market_state: InstrumentMarketState) -> tuple[str, ...]:
+    """本次通用 TradingState 检查实际消费的事实引用
+
+    provenance 来自投影携带的最近生效 TradingStateEvent ID；
+    UNKNOWN 默认态 / 非事件来源为 None——不伪造引用。
+    """
+    if market_state.trading_state_event_id is None:
+        return ()
+    return (market_state.trading_state_event_id,)
+
+
+def _price_limit_evidence(price_limit: PriceLimitState) -> tuple[str, ...]:
+    """本次 PriceLimit 检查实际消费的事实引用（None 来源不伪造）"""
+    if price_limit.source_event_id is None:
+        return ()
+    return (price_limit.source_event_id,)
+
+
+def _merge_evidence(*parts: tuple[str, ...]) -> tuple[str, ...]:
+    """合并各检查阶段的事实引用，去重且保序
+
+    同一物理事件可为多个检查消费同一引用：真实日级事实以单条
+    DAILY_STATE_SNAPSHOT 同时承载交易状态与涨跌停（T5 真实数据回放发现），
+    两类 evidence 的 source_event_id 相同——事件引用一次即可，模型边界
+    禁止重复引用（TradabilityDecisionRecord validator）。
+    """
+    return tuple(dict.fromkeys(ref for part in parts for ref in part))
+
+
+def _blocked_trading_state_reason(
+    order: OrderSnapshot, market_state: InstrumentMarketState
+) -> ExecutionDeferReason | None:
+    """两个 Policy 共用的通用交易状态检查（TradingState 优先级高于 PriceLimitState）
+
+    标的不一致属于矛盾输入，立即抛错；命中禁止状态返回一一对应的原因码，
+    否则返回 None（TRADING，进入各自的市场特定判断）。
+    """
+    if order.intent.instrument_id != market_state.instrument_id:
+        raise ValueError(
+            f"订单标的 {order.intent.instrument_id} 与市场投影标的 "
+            f"{market_state.instrument_id} 不一致"
+        )
+    return _BLOCKED_TRADING_STATE.get(market_state.trading_state)
+
+
+class NoPriceLimitTradabilityPolicy:
+    """无价格限制市场的通用 Policy（用户裁定 2026-09-04：「无价格限制 ≠ 无视交易状态」）
+
+    精确语义：
+    - 非 TRADING 状态（SUSPENDED/HALTED/AUCTION/CLOSED/UNKNOWN）按通用矩阵 DEFER；
+    - TRADING 时**始终 ALLOW**——即使投影意外携带涨跌停锁定也 ALLOW，
+      证明价格限制由可替换 Policy 拥有，而非引擎内置。
+    无状态、纯决策，不读取 wall clock / Runtime mode / 市场字符串 / Provider。
+    """
+
+    def decide(
+        self, order: OrderSnapshot, market_state: InstrumentMarketState
+    ) -> TradabilityDecisionRecord:
+        blocked = _blocked_trading_state_reason(order, market_state)
+        evidence = _state_evidence(market_state)
+        if blocked is not None:
+            return TradabilityDecisionRecord(
+                decision=TradabilityDecision.DEFER,
+                defer_reason=blocked,
+                evidence_event_refs=evidence,
+            )
+        # 明确忽略 PriceLimit：其 evidence 即使存在也不进入引用
+        return TradabilityDecisionRecord(
+            decision=TradabilityDecision.ALLOW, defer_reason=None, evidence_event_refs=evidence
+        )
+
+
+class ChinaEquityTradabilityPolicy:
+    """A 股市场规则 Policy：停牌/集合竞价等禁止 + 涨跌停方向锁单
+
+    决策矩阵（用户裁定 2026-09-04）：
+    - SUSPENDED / HALTED / CLOSED / UNKNOWN / AUCTION × BUY/SELL → DEFER；
+    - TRADING + 涨停封板（buy_side_locked）→ BUY DEFER / SELL ALLOW；
+    - TRADING + 跌停封板（sell_side_locked）→ BUY ALLOW / SELL DEFER；
+    - TRADING + 未锁定 / 无 PriceLimitEvent → ALLOW。
+    无状态：不缓存历史 MarketState（历史投影由 T1 MarketStateResolver 负责）。
+    """
+
+    def decide(
+        self, order: OrderSnapshot, market_state: InstrumentMarketState
+    ) -> TradabilityDecisionRecord:
+        blocked = _blocked_trading_state_reason(order, market_state)
+        if blocked is not None:
+            # 状态已先行阻塞：只引用实际消费的状态事实，不追加未消费的 PriceLimit
+            return TradabilityDecisionRecord(
+                decision=TradabilityDecision.DEFER,
+                defer_reason=blocked,
+                evidence_event_refs=_state_evidence(market_state),
+            )
+
+        price_limit = market_state.price_limit
+        evidence = _state_evidence(market_state)
+        if price_limit is not None:
+            # TRADING 且携带 PriceLimit：Policy 实际检查了状态与价格限制两类事实
+            evidence = _merge_evidence(evidence, _price_limit_evidence(price_limit))
+            if order.intent.side is OrderSide.BUY and price_limit.buy_side_locked:
+                return TradabilityDecisionRecord(
+                    decision=TradabilityDecision.DEFER,
+                    defer_reason=ExecutionDeferReason.PRICE_LIMIT_BUY_BLOCKED,
+                    evidence_event_refs=evidence,
+                )
+            if order.intent.side is OrderSide.SELL and price_limit.sell_side_locked:
+                return TradabilityDecisionRecord(
+                    decision=TradabilityDecision.DEFER,
+                    defer_reason=ExecutionDeferReason.PRICE_LIMIT_SELL_BLOCKED,
+                    evidence_event_refs=evidence,
+                )
+        return TradabilityDecisionRecord(
+            decision=TradabilityDecision.ALLOW, defer_reason=None, evidence_event_refs=evidence
+        )

quant_core/app/order_execution/validators.py

@@ -0,0 +1,40 @@
+"""Order Execution 领域内共享校验器（不放 common：仅本域复用）"""
+
+from decimal import Decimal
+
+
+def validate_identifier(value: object, field: str) -> str:
+    """业务标识（intent_id / order_id / ack_id / fill_id / attempt_id / strategy_id）
+
+    至少拒绝：非字符串、空串、纯空白、含任何空白字符。
+    """
+    if not isinstance(value, str):
+        raise ValueError(f"{field} 必须是非空字符串标识")
+    if not value or value.strip() != value or any(ch.isspace() for ch in value):
+        raise ValueError(f"{field} 不允许为空或包含空白字符：{value!r}")
+    return value
+
+
+def reject_float_amount(value: object, field: str) -> object:
+    """金额/价格字段严格拒绝 float 与非有限 Decimal（禁止浮点/Inf 进入资金计算）
+
+    接受 Decimal（以及 Pydantic 默认可无损转换的 int 字面量）。
+    统一规则：value.is_finite() 必须为 True（拒绝 NaN / ±Infinity / sNaN）。
+    """
+    if isinstance(value, float):
+        raise ValueError(f"{field} 必须使用 Decimal，禁止 float（避免二进制浮点误差）")
+    if isinstance(value, Decimal) and not value.is_finite():
+        raise ValueError(f"{field} 必须是有限 Decimal，禁止 NaN / Infinity / sNaN")
+    return value
+
+
+def ensure_finite_amounts(model: object, fields: tuple[str, ...]) -> None:
+    """Decimal 解析完成后的二次统一 finite 校验（mode="after"）
+
+    字符串 "NaN" / "Infinity" 等在 before 阶段还不是 Decimal，会在
+    Pydantic 解析后变成非有限 Decimal；此处在解析后统一收口拒绝。
+    """
+    for name in fields:
+        value = getattr(model, name)
+        if isinstance(value, Decimal) and not value.is_finite():
+            raise ValueError(f"{name} 必须是有限 Decimal，禁止字符串形式的 NaN / Infinity / sNaN")

quant_core/app/portfolio/SPEC.md

@@ -0,0 +1,69 @@
+# Portfolio SPEC
+
+## 1. Domain Purpose
+
+`portfolio` 负责维护特定运行账户的资金、持仓、成本、估值、损益和风险状态，并向 Strategy 和 Trading Runtime 提供只读 PortfolioSnapshot。
+
+## 2. Responsibilities
+
+- 应用 Order Execution 产生的 Fill。
+- 更新 Cash、Position、CostBasis 和 RealizedPnL。
+- 使用当前可用市场价格计算估值、UnrealizedPnL 与 Exposure。
+- 提供 point-in-time `PortfolioSnapshot`。
+- 隔离 Backtest、Paper 和 Live 的账户状态。
+- 为 Order Planning 提供仓位计算、交易约束与下单前风险检查所需状态。
+
+## 3. Non-Responsibilities
+
+- 不产生 Strategy Signal。
+- 不创建、撮合或路由 Order。
+- 不推进 Runtime Clock。
+- 不维护 Opportunity 或 Watchlist。
+- 不直接读取 Provider 或 Broker-specific 类型。
+
+## 4. Main Concepts
+
+```text
+Fill + Market Valuation Facts
+              ↓
+Portfolio
+├── Cash
+├── Position
+├── CostBasis
+├── RealizedPnL
+├── UnrealizedPnL
+└── Exposure
+              ↓
+PortfolioSnapshot
+```
+
+`PortfolioSnapshot` 是某一市场时刻的只读组合视图。Strategy 可以读取它，但不能修改 Portfolio。
+
+## 5. Fill Rule
+
+Fill 是确认成交的事实，也是 Portfolio 因交易而改变资金和持仓的唯一输入。OrderIntent、Order Accepted 或 Signal 均不能直接修改 Portfolio。
+
+## 6. Runtime Isolation
+
+```text
+Backtest Account State  ─┐
+Paper Account State     ─┼── 相同 Portfolio 语义，不共享可变状态
+Live Account State      ─┘
+```
+
+不同运行环境可以使用不同存储或同步机制，但 Cash、Position、PnL、Exposure 与 Snapshot 的 Canonical 语义保持一致。
+
+## 7. Cross-Domain Dependencies
+
+- 消费 Order Execution 的 Fill。
+- 消费 Market 的估值事实。
+- 向 Strategy 和 Trading Runtime 提供只读 Snapshot 契约。
+- Backtest 负责创建和隔离其运行账户，本域不依赖 Backtest。
+
+## 8. Aggregate Boundary
+
+`Portfolio` 是资金、持仓、冻结、结算和公司行动状态的唯一聚合根。`Position`、`PositionLot`、`OrderReservation` 与 `DividendEntitlement` 是聚合内部实体，只能经 Portfolio 应用 Fill、结算或公司行动时改变。
+
+内部实体保护自身局部不变量，例如批次不可超卖、冻结资源不可透支、分红权益不可超额消耗；Portfolio 负责跨实体的原子校验和编排。Snapshot、账本 Schema 与 ORM Model 位于领域边界之外，不得持有另一套可变业务规则。
+
+`app/portfolio/domain/` 保持零入口框架、零 ORM、零外部数据 SDK 依赖。当前不存在从 ORM 恢复完整聚合的需求，因此不预建 Mapper。

quant_core/app/portfolio/domain/__init__.py

@@ -0,0 +1,32 @@
+"""Portfolio 纯领域模型。"""
+
+from quant_core.app.portfolio.domain.entitlement_entity import DividendEntitlement
+from quant_core.app.portfolio.domain.portfolio_entity import Portfolio
+from quant_core.app.portfolio.domain.portfolio_event import (
+    ClosedLot,
+    CorporateActionApplied,
+    FillApplied,
+    ReservationAction,
+    ReservationChanged,
+)
+from quant_core.app.portfolio.domain.portfolio_value import (
+    CorporateActionInstruction,
+    CorporateActionPhase,
+)
+from quant_core.app.portfolio.domain.position_entity import Position, PositionLot
+from quant_core.app.portfolio.domain.reservation_entity import OrderReservation
+
+__all__ = [
+    "DividendEntitlement",
+    "ClosedLot",
+    "CorporateActionApplied",
+    "CorporateActionInstruction",
+    "CorporateActionPhase",
+    "FillApplied",
+    "OrderReservation",
+    "Portfolio",
+    "Position",
+    "PositionLot",
+    "ReservationAction",
+    "ReservationChanged",
+]

quant_core/app/portfolio/domain/entitlement_entity.py

@@ -0,0 +1,45 @@
+"""公司行动权益的内部实体。"""
+
+from decimal import Decimal
+
+
+class DividendEntitlement:
+    """关联 action/lot 的分红权益及尚未处置数量。"""
+
+    __slots__ = ("_remaining_quantity", "action_id", "cash_per_share", "lot_id")
+
+    def __init__(
+        self,
+        action_id: str,
+        lot_id: str,
+        quantity: int,
+        cash_per_share: Decimal,
+    ) -> None:
+        if not action_id or not lot_id:
+            raise ValueError("分红权益必须关联 action_id 和 lot_id")
+        if quantity <= 0:
+            raise ValueError("分红权益数量必须 > 0")
+        if not cash_per_share.is_finite() or cash_per_share < 0:
+            raise ValueError("每股现金分红必须是有限非负 Decimal")
+        self.action_id = action_id
+        self.lot_id = lot_id
+        self._remaining_quantity = quantity
+        self.cash_per_share = cash_per_share
+
+    @property
+    def remaining_quantity(self) -> int:
+        return self._remaining_quantity
+
+    def consume(self, quantity: int) -> None:
+        """卖出关联批次时消耗权益，禁止超额或反向修改。"""
+        if quantity <= 0:
+            raise ValueError("分红权益消耗数量必须 > 0")
+        if quantity > self.remaining_quantity:
+            raise ValueError("分红权益消耗数量超过剩余数量")
+        self._remaining_quantity -= quantity
+
+    def gross_cash_for(self, quantity: int) -> Decimal:
+        """返回指定剩余权益数量对应的税前现金基数。"""
+        if quantity <= 0 or quantity > self.remaining_quantity:
+            raise ValueError("分红权益计税数量必须在剩余数量范围内")
+        return Decimal(quantity) * self.cash_per_share