powerquant-cli 0.2.6__py3-none-any.whl

quant_core/app/portfolio/domain/position_entity.py

@@ -0,0 +1,165 @@
+"""持仓与持仓批次内部实体。"""
+
+from datetime import date, datetime
+from decimal import Decimal
+
+
+class Position:
+    """单标的可变持仓，只能由 Portfolio 聚合修改。"""
+
+    __slots__ = (
+        "available_quantity",
+        "average_cost",
+        "last_price",
+        "pending_settlement_quantity",
+        "quantity",
+        "realized_pnl",
+    )
+
+    def __init__(self, quantity: int, price: Decimal, fee_total: Decimal) -> None:
+        self.quantity = quantity
+        self.available_quantity = 0
+        self.pending_settlement_quantity = quantity
+        self.average_cost = (Decimal(quantity) * price + fee_total) / Decimal(quantity)
+        self.last_price = price
+        self.realized_pnl = Decimal("0")
+
+    def unrealized_pnl(self) -> Decimal:
+        return Decimal(self.quantity) * (self.last_price - self.average_cost)
+
+    def apply_buy(self, quantity: int, price: Decimal, total_cost: Decimal) -> None:
+        """增加当日待结算持仓并按总成本重算均价。"""
+        existing_cost = Decimal(self.quantity) * self.average_cost
+        self.quantity += quantity
+        self.pending_settlement_quantity += quantity
+        self.average_cost = (existing_cost + total_cost) / Decimal(self.quantity)
+        self.last_price = price
+
+    def apply_sell(self, quantity: int, price: Decimal, realized_pnl: Decimal) -> None:
+        """应用已通过 Portfolio 资金和批次校验的卖出结果。"""
+        if quantity > self.available_quantity:
+            raise ValueError(
+                f"卖出被拒绝：数量 {quantity} 超过可卖 {self.available_quantity}（T+1）"
+            )
+        self.quantity -= quantity
+        self.available_quantity -= quantity
+        self.realized_pnl += realized_pnl
+        self.last_price = price
+
+    def apply_bonus(self, quantity: int) -> None:
+        """除权日计入红股总持仓，但保持待上市不可卖。"""
+        old_cost = Decimal(self.quantity) * self.average_cost
+        self.quantity += quantity
+        self.pending_settlement_quantity += quantity
+        self.average_cost = old_cost / Decimal(self.quantity)
+
+    def release_bonus(self, quantity: int) -> None:
+        """红股上市日将指定数量从待结算转为可卖。"""
+        if quantity > self.pending_settlement_quantity:
+            raise ValueError("红股数量超过持仓待结算数量")
+        self.pending_settlement_quantity -= quantity
+        self.available_quantity += quantity
+
+    def settle(self, locked_quantity: int) -> None:
+        """释放普通 T+1 待结算数量，保留未上市红股锁定。"""
+        releasable = self.pending_settlement_quantity - locked_quantity
+        if releasable < 0:
+            raise ValueError("红股锁定数量超过待结算数量")
+        self.available_quantity += releasable
+        self.pending_settlement_quantity = locked_quantity
+
+    def mark(self, price: Decimal) -> None:
+        self.last_price = price
+
+
+class PositionLot:
+    """拥有独立 lot_id、成本、持有期和可卖时间的持仓批次。"""
+
+    __slots__ = (
+        "_available_on",
+        "_available_quantity",
+        "_remaining_quantity",
+        "_unit_cost",
+        "acquired_at",
+        "instrument_id",
+        "lot_id",
+        "original_quantity",
+        "source_id",
+    )
+
+    def __init__(
+        self,
+        *,
+        lot_id: str,
+        instrument_id: str,
+        source_id: str,
+        acquired_at: datetime,
+        quantity: int,
+        unit_cost: Decimal,
+        available_quantity: int = 0,
+        available_on: date | None = None,
+    ) -> None:
+        if not lot_id or not instrument_id or not source_id:
+            raise ValueError("持仓批次必须包含 lot_id、instrument_id 和 source_id")
+        if acquired_at.tzinfo is None:
+            raise ValueError("持仓批次 acquired_at 必须 timezone-aware")
+        if quantity <= 0:
+            raise ValueError("持仓批次数量必须 > 0")
+        if available_quantity < 0 or available_quantity > quantity:
+            raise ValueError("持仓批次可卖数量必须在总数量范围内")
+        if not unit_cost.is_finite() or unit_cost < 0:
+            raise ValueError("持仓批次单位成本必须是有限非负 Decimal")
+        self.lot_id = lot_id
+        self.instrument_id = instrument_id
+        self.source_id = source_id
+        self.acquired_at = acquired_at
+        self._available_on = available_on
+        self.original_quantity = quantity
+        self._remaining_quantity = quantity
+        self._available_quantity = available_quantity
+        self._unit_cost = unit_cost
+
+    @property
+    def remaining_quantity(self) -> int:
+        return self._remaining_quantity
+
+    @property
+    def available_quantity(self) -> int:
+        return self._available_quantity
+
+    @property
+    def available_on(self) -> date | None:
+        return self._available_on
+
+    @property
+    def unit_cost(self) -> Decimal:
+        return self._unit_cost
+
+    def close(self, quantity: int) -> None:
+        """关闭可卖批次数量，禁止超卖或产生负状态。"""
+        if quantity <= 0 or quantity > self.available_quantity:
+            raise ValueError("关闭数量超过持仓批次可卖数量")
+        self._remaining_quantity -= quantity
+        self._available_quantity -= quantity
+
+    def release(self, available_on: date) -> None:
+        """将批次全部剩余数量置为可卖。"""
+        if self.remaining_quantity <= 0:
+            raise ValueError("已耗尽持仓批次不能释放")
+        if self.available_quantity == self.remaining_quantity:
+            return
+        if self.available_on is not None and available_on < self.available_on:
+            raise ValueError("持仓批次可卖日期不允许回退")
+        self._available_quantity = self.remaining_quantity
+        self._available_on = available_on
+
+    def apply_bonus_cost(self, bonus_quantity: int) -> Decimal:
+        """按送转后总数量摊薄原批次成本，返回红股批次单位成本。"""
+        if bonus_quantity <= 0:
+            raise ValueError("红股批次数量必须 > 0")
+        adjusted_quantity = self.remaining_quantity + bonus_quantity
+        adjusted_cost = (
+            self.unit_cost * Decimal(self.remaining_quantity) / Decimal(adjusted_quantity)
+        )
+        self._unit_cost = adjusted_cost
+        return adjusted_cost

quant_core/app/portfolio/domain/reservation_entity.py

@@ -0,0 +1,69 @@
+"""订单资源冻结的内部实体。"""
+
+from decimal import Decimal
+
+from quant_core.app.order_execution.constants import OrderSide
+
+
+class OrderReservation:
+    """以 order_id 为身份，跟踪尚未消耗的冻结现金或证券。"""
+
+    __slots__ = (
+        "_remaining_cash",
+        "_remaining_quantity",
+        "instrument_id",
+        "order_id",
+        "side",
+    )
+
+    def __init__(
+        self,
+        *,
+        order_id: str,
+        instrument_id: str,
+        side: OrderSide,
+        remaining_quantity: int,
+        remaining_cash: Decimal,
+    ) -> None:
+        if not order_id or not instrument_id:
+            raise ValueError("订单冻结必须关联 order_id 和 instrument_id")
+        if remaining_quantity <= 0:
+            raise ValueError("订单冻结数量必须 > 0")
+        if not remaining_cash.is_finite() or remaining_cash < 0:
+            raise ValueError("订单冻结现金必须是有限非负 Decimal")
+        if side is OrderSide.BUY and remaining_cash <= 0:
+            raise ValueError("买单必须冻结正数现金")
+        if side is OrderSide.SELL and remaining_cash != 0:
+            raise ValueError("卖单不得冻结现金")
+        self.order_id = order_id
+        self.instrument_id = instrument_id
+        self.side = side
+        self._remaining_quantity = remaining_quantity
+        self._remaining_cash = remaining_cash
+
+    @property
+    def remaining_quantity(self) -> int:
+        return self._remaining_quantity
+
+    @property
+    def remaining_cash(self) -> Decimal:
+        return self._remaining_cash
+
+    def ensure_matches(self, instrument_id: str, side: OrderSide) -> None:
+        """保证成交只能消耗自身订单方向和标的对应的冻结资源。"""
+        if instrument_id != self.instrument_id or side is not self.side:
+            raise ValueError("成交标的或方向与订单冻结资源不一致")
+
+    def consume(self, quantity: int, cash: Decimal = Decimal("0")) -> None:
+        """成交时消耗冻结资源，并保护订单冻结不被透支。"""
+        if quantity <= 0 or quantity > self.remaining_quantity:
+            raise ValueError("成交数量超过订单剩余冻结数量")
+        if not cash.is_finite() or cash < 0:
+            raise ValueError("冻结现金消耗必须是有限非负 Decimal")
+        if self.side is OrderSide.BUY:
+            if cash <= 0 or cash > self.remaining_cash:
+                raise ValueError("成交金额超过订单剩余冻结现金")
+        elif cash != 0:
+            raise ValueError("卖单不得消耗冻结现金")
+        self._remaining_quantity -= quantity
+        self._remaining_cash -= cash

quant_core/app/portfolio/interface/public/portfolio.py

@@ -0,0 +1,77 @@
+"""
+Portfolio Protocol - Trading Runtime / Order Planning 消费的组合 Port
+
+依赖方向：Portfolio 消费 Order Execution 的 Fill（Fill Rule）；Runtime 与
+Strategy 只依赖本 Protocol 与只读 Snapshot。实现（T3 Simulated Portfolio）
+结构满足即可，跨域不得依赖实现内部。
+"""
+
+from collections.abc import Mapping
+from datetime import date, datetime
+from decimal import Decimal
+from typing import Protocol, runtime_checkable
+
+from quant_core.app.data.schema.corporate_action_schema import CorporateActionEventPayload
+from quant_core.app.order_execution.domain.order_event import Fill
+from quant_core.app.portfolio.ledger_schema import (
+    CashLedgerEntry,
+    ClosedTrade,
+    OrderReservationLedgerEntry,
+    PositionLotSnapshot,
+)
+from quant_core.app.portfolio.portfolio_schema import (
+    CashSnapshot,
+    PortfolioSnapshot,
+    PositionSnapshot,
+)
+
+
+@runtime_checkable
+class IPortfolioUpdate(Protocol):
+    """组合变更能力：唯一交易输入是 Fill"""
+
+    def apply_fill(self, fill: Fill) -> None:
+        """应用一次已确认成交（现金/持仓/成本/已实现盈亏）"""
+        ...
+
+    def apply_corporate_action(self, event: CorporateActionEventPayload, at: datetime) -> None:
+        """按阶段应用公司行动权益事件。"""
+        ...
+
+    def mark_to_market(self, prices: Mapping[str, Decimal], at: datetime) -> None:
+        """按片内收盘价估值并刷新未实现盈亏（价格缺失标的保持上次估值）"""
+        ...
+
+    def settle_trading_day(self, trading_day: date) -> None:
+        """交易日边界结算（如新交易日首片释放 T+1 available）"""
+        ...
+
+    def snapshot(self) -> PortfolioSnapshot:
+        """当前 point-in-time 只读投影"""
+        ...
+
+
+@runtime_checkable
+class IPortfolioReader(Protocol):
+    """组合只读能力（Strategy / Order Planning 的最小依赖面）"""
+
+    def get_cash(self) -> CashSnapshot:
+        """读取可用/冻结/合计资金"""
+        ...
+
+    def get_position(self, instrument_id: str) -> PositionSnapshot | None:
+        """读取单标的持仓投影；无持仓返回 None"""
+        ...
+
+
+@runtime_checkable
+class IPortfolioLedger(Protocol):
+    """Backtest 只读消费的账本事实能力面。"""
+
+    def position_lots(self) -> tuple[PositionLotSnapshot, ...]: ...
+
+    def cash_ledger_entries(self) -> tuple[CashLedgerEntry, ...]: ...
+
+    def closed_trades(self) -> tuple[ClosedTrade, ...]: ...
+
+    def reservation_ledger_entries(self) -> tuple[OrderReservationLedgerEntry, ...]: ...

quant_core/app/portfolio/interface/public/simulation_account.py

@@ -0,0 +1,16 @@
+"""运行账户组合既有更新、读取、预占与账本契约，不公开实现。"""
+
+from typing import Protocol
+
+from quant_core.app.order_execution.interface.public.execution_account import IExecutionReservation
+from quant_core.app.portfolio.interface.public.portfolio import (
+    IPortfolioLedger,
+    IPortfolioReader,
+    IPortfolioUpdate,
+)
+
+
+class ISimulationAccount(
+    IPortfolioUpdate, IPortfolioReader, IPortfolioLedger, IExecutionReservation, Protocol
+):
+    pass

quant_core/app/portfolio/ledger_schema.py

@@ -0,0 +1,130 @@
+"""Portfolio 不可变账本事实与持仓批次投影。"""
+
+from datetime import date, datetime
+from decimal import Decimal
+from enum import Enum
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from quant_core.app.data.schema.trading_state_schema import validate_canonical_instrument_id
+from quant_core.app.order_execution.validators import reject_float_amount, validate_identifier
+
+
+class CashLedgerAccount(str, Enum):
+    CASH = "cash"
+    FROZEN_CASH = "frozen_cash"
+    DIVIDEND_RECEIVABLE = "dividend_receivable"
+
+
+class CashLedgerEntryType(str, Enum):
+    INITIAL_BALANCE = "initial_balance"
+    TRADE_GROSS = "trade_gross"
+    TRADE_FEE = "trade_fee"
+    DIVIDEND_RECEIVABLE = "dividend_receivable"
+    DIVIDEND_PAYMENT = "dividend_payment"
+    DIVIDEND_TAX = "dividend_tax"
+    ORDER_RESERVE = "order_reserve"
+    ORDER_RELEASE = "order_release"
+
+
+class ReservationLedgerAction(str, Enum):
+    RESERVE = "reserve"
+    CONSUME = "consume"
+    RELEASE = "release"
+
+
+class OrderReservationLedgerEntry(BaseModel):
+    """订单冻结资源的 append-only 事实；按 order_id 求和可重建当前冻结。"""
+
+    model_config = ConfigDict(frozen=True)
+
+    entry_id: str
+    order_id: str
+    instrument_id: str
+    side: str
+    action: ReservationLedgerAction
+    cash_delta: Decimal
+    quantity_delta: int
+    event_time: datetime
+
+    _validate_entry_id = field_validator("entry_id")(
+        classmethod(lambda cls, value: validate_identifier(value, "entry_id"))
+    )
+    _validate_order_id = field_validator("order_id")(
+        classmethod(lambda cls, value: validate_identifier(value, "order_id"))
+    )
+    _validate_instrument = field_validator("instrument_id")(
+        classmethod(lambda cls, value: validate_canonical_instrument_id(value))
+    )
+    _validate_cash = field_validator("cash_delta", mode="before")(
+        classmethod(lambda cls, value: reject_float_amount(value, "cash_delta"))
+    )
+
+
+class PositionLotSnapshot(BaseModel):
+    """一笔买入或送股形成的持仓批次当前投影。"""
+
+    model_config = ConfigDict(frozen=True)
+
+    lot_id: str
+    instrument_id: str
+    source_id: str
+    acquired_at: datetime
+    available_on: date | None
+    original_quantity: int = Field(..., gt=0)
+    remaining_quantity: int = Field(..., ge=0)
+    available_quantity: int = Field(..., ge=0)
+    unit_cost: Decimal = Field(..., ge=0)
+
+    _validate_lot_id = field_validator("lot_id")(
+        classmethod(lambda cls, value: validate_identifier(value, "lot_id"))
+    )
+    _validate_instrument = field_validator("instrument_id")(
+        classmethod(lambda cls, value: validate_canonical_instrument_id(value))
+    )
+    _validate_cost = field_validator("unit_cost", mode="before")(
+        classmethod(lambda cls, value: reject_float_amount(value, "unit_cost"))
+    )
+
+
+class CashLedgerEntry(BaseModel):
+    """现金或应收股息账户的 append-only 变动事实。"""
+
+    model_config = ConfigDict(frozen=True)
+
+    entry_id: str
+    account_id: str
+    account: CashLedgerAccount
+    entry_type: CashLedgerEntryType
+    amount: Decimal
+    event_time: datetime
+    source_key: str
+    instrument_id: str | None = None
+
+    _validate_amount = field_validator("amount", mode="before")(
+        classmethod(lambda cls, value: reject_float_amount(value, "amount"))
+    )
+
+
+class ClosedTrade(BaseModel):
+    """FIFO 买入批次与卖出 Fill 的不可变平仓配对事实。"""
+
+    model_config = ConfigDict(frozen=True)
+
+    trade_id: str
+    instrument_id: str
+    position_lot_id: str
+    buy_source_id: str
+    sell_fill_id: str
+    quantity: int = Field(..., gt=0)
+    opened_at: datetime
+    closed_at: datetime
+    cost_basis: Decimal = Field(..., ge=0)
+    proceeds: Decimal = Field(..., ge=0)
+    sell_fees: Decimal = Field(..., ge=0)
+    realized_pnl: Decimal
+    holding_days: int = Field(..., ge=0)
+
+    _validate_amounts = field_validator(
+        "cost_basis", "proceeds", "sell_fees", "realized_pnl", mode="before"
+    )(classmethod(lambda cls, value: reject_float_amount(value, "closed_trade amount")))

quant_core/app/portfolio/order_account_listener.py

@@ -0,0 +1,36 @@
+"""账户订阅订单与成交事件；资源冻结和入账统一由 Portfolio 拥有。"""
+
+from decimal import Decimal
+
+from quant_core.app.order_execution.constants import OrderStatus
+from quant_core.app.order_execution.domain.order_event import Fill, OrderTransition
+from quant_core.app.order_execution.domain.order_value import OrderIntent
+from quant_core.app.portfolio.interface.public.simulation_account import ISimulationAccount
+
+
+class OrderAccountListener:
+    """在 Broker 返回前同步更新账户，不经 Runtime 二次应用成交。"""
+
+    def __init__(self, account: ISimulationAccount) -> None:
+        self._account = account
+
+    def on_order_pending_new(self, order_id: str, intent: OrderIntent, cash: Decimal) -> bool:
+        return self._account.reserve_order(
+            order_id,
+            intent.instrument_id,
+            intent.side,
+            intent.quantity,
+            cash,
+            intent.creation_event_time,
+        )
+
+    def on_trade(self, fill: Fill) -> None:
+        self._account.apply_fill(fill)
+
+    def on_order_update(self, update: OrderTransition) -> None:
+        if update.current_status in {
+            OrderStatus.FILLED,
+            OrderStatus.CANCELLED,
+            OrderStatus.EXPIRED,
+        }:
+            self._account.release_order_reservation(update.order_id, update.event_time)

quant_core/app/portfolio/portfolio_dependency.py

@@ -0,0 +1,21 @@
+"""Portfolio 所属域的模拟账户组装入口。"""
+
+from datetime import datetime
+from decimal import Decimal
+
+from quant_core.app.order_execution.interface.public.order_events import IOrderEventListener
+from quant_core.app.portfolio.interface.public.simulation_account import ISimulationAccount
+from quant_core.app.portfolio.order_account_listener import OrderAccountListener
+from quant_core.app.portfolio.simulated_portfolio import SimulatedPortfolio
+
+
+def build_simulation_account(
+    account_id: str, initial_cash: Decimal, start: datetime
+) -> ISimulationAccount:
+    """返回组合账户能力，不向应用服务暴露 SimulatedPortfolio。"""
+    return SimulatedPortfolio(account_id, initial_cash, start)
+
+
+def build_order_account_listener(account: ISimulationAccount) -> IOrderEventListener:
+    """向订单事件总线提供账户监听能力。"""
+    return OrderAccountListener(account)