powerquant-cli 0.2.6__py3-none-any.whl

quant_core/app/portfolio/domain/portfolio_entity.py

@@ -0,0 +1,511 @@
+"""Portfolio 聚合根：拥有账户可变状态和内部实体集合。"""
+
+from collections.abc import Mapping
+from datetime import date, datetime
+from decimal import ROUND_FLOOR, Decimal
+
+from quant_core.app.order_execution.constants import OrderSide
+from quant_core.app.order_execution.domain.order_event import Fill
+from quant_core.app.portfolio.domain.entitlement_entity import DividendEntitlement
+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
+
+
+def finite_decimal(value: object, field: str) -> Decimal:
+    """领域金额边界：禁止 float 和非有限 Decimal。"""
+    if isinstance(value, float):
+        raise ValueError(f"{field} 必须使用 Decimal，禁止 float（避免二进制浮点误差）")
+    if not isinstance(value, (Decimal, int, str)):
+        raise ValueError(f"{field} 必须是 Decimal、整数或数字字符串")
+    converted = value if isinstance(value, Decimal) else Decimal(value)
+    if not converted.is_finite():
+        raise ValueError(f"{field} 必须是有限 Decimal，禁止 NaN / Infinity")
+    return converted
+
+
+class Portfolio:
+    """资金、持仓、冻结、结算与公司行动状态的唯一聚合根。"""
+
+    def __init__(
+        self,
+        account_id: str,
+        initial_cash: Decimal,
+        initial_market_time: datetime,
+    ) -> None:
+        if (
+            not account_id
+            or account_id.strip() != account_id
+            or any(char.isspace() for char in account_id)
+        ):
+            raise ValueError("account_id 不允许为空或包含空白字符")
+        if initial_market_time.tzinfo is None:
+            raise ValueError("initial_market_time 必须 timezone-aware")
+        cash = finite_decimal(initial_cash, "initial_cash")
+        if cash < 0:
+            raise ValueError(f"initial_cash 必须 >= 0，实际 {cash}")
+        self._account_id = account_id
+        self._cash = cash
+        self._frozen_cash = Decimal("0")
+        self._dividend_receivable = Decimal("0")
+        self._positions: dict[str, Position] = {}
+        self._realized_pnl = Decimal("0")
+        self._applied_fill_ids: set[str] = set()
+        self._position_lots: list[PositionLot] = []
+        self._order_reservations: dict[str, OrderReservation] = {}
+        self._dividend_entitlements: list[DividendEntitlement] = []
+        self._state_time = initial_market_time
+        self._last_settled_day: date | None = None
+        self._corporate_action_entitlements: dict[str, int] = {}
+        self._corporate_action_receivables: dict[str, Decimal] = {}
+        self._corporate_action_bonuses: dict[str, int] = {}
+        self._corporate_action_bonus_lots: dict[str, tuple[str, ...]] = {}
+        self._locked_bonus_by_instrument: dict[str, int] = {}
+        self._applied_corporate_action_phases: set[tuple[str, str]] = set()
+
+    def apply_fill(self, fill: Fill) -> FillApplied:
+        """原子应用成交到现金、持仓、批次、冻结与股息税状态。"""
+        if fill.fill_id in self._applied_fill_ids:
+            raise ValueError(f"重复 Fill 被拒绝：fill_id {fill.fill_id} 已成功应用过一次")
+        self._check_event_time(fill.fill_time, "fill_time")
+        fee_total = finite_decimal(fill.fees.total, "fees.total")
+        gross = finite_decimal(fill.price, "price") * Decimal(fill.quantity)
+        reservation = self._order_reservations.get(fill.order_id)
+        if reservation is not None:
+            reservation.ensure_matches(fill.instrument_id, fill.side)
+        reservation_cash_delta = Decimal("0")
+        reservation_quantity_delta = 0
+
+        if fill.side is OrderSide.BUY:
+            cost = gross + fee_total
+            released_cash = (
+                (
+                    reservation.remaining_cash
+                    * Decimal(fill.quantity)
+                    / Decimal(reservation.remaining_quantity)
+                )
+                if reservation is not None
+                else Decimal(0)
+            )
+            spendable = self._cash + released_cash
+            if cost > spendable:
+                raise ValueError(f"可用资金不足以买入：需要 {cost}，可用 {spendable}")
+            if reservation is None:
+                self._cash -= cost
+            else:
+                reservation.consume(fill.quantity, released_cash)
+                self._frozen_cash -= released_cash
+                self._cash += released_cash - cost
+                reservation_cash_delta = -released_cash
+                reservation_quantity_delta = -fill.quantity
+            unit_cost = cost / Decimal(fill.quantity)
+            self._position_lots.append(
+                PositionLot(
+                    lot_id=f"lot:{fill.fill_id}",
+                    instrument_id=fill.instrument_id,
+                    source_id=fill.fill_id,
+                    acquired_at=fill.fill_time,
+                    quantity=fill.quantity,
+                    unit_cost=unit_cost,
+                )
+            )
+            position = self._positions.get(fill.instrument_id)
+            if position is None:
+                self._positions[fill.instrument_id] = Position(fill.quantity, fill.price, fee_total)
+            else:
+                position.apply_buy(fill.quantity, fill.price, cost)
+            closed_lots: tuple[ClosedLot, ...] = ()
+            dividend_tax = Decimal("0")
+        else:
+            position = self._positions.get(fill.instrument_id)
+            if position is None:
+                raise ValueError(f"卖出被拒绝：{fill.instrument_id} 无持仓")
+            if fill.quantity > position.available_quantity:
+                raise ValueError(
+                    f"卖出被拒绝：数量 {fill.quantity} 超过可卖 "
+                    f"{position.available_quantity}（T+1）"
+                )
+            cash_after = self._cash + gross - fee_total
+            if cash_after < 0:
+                raise ValueError(f"卖出被拒绝：记账后现金 {cash_after} 为负")
+            planned = self._plan_closed_lots(fill, gross, fee_total)
+            if reservation is not None and fill.quantity > reservation.remaining_quantity:
+                raise ValueError("卖出 Fill 超过订单冻结证券数量")
+            dividend_tax, consumptions = self._plan_dividend_tax(planned)
+            cash_after -= dividend_tax
+            if cash_after < 0:
+                raise ValueError(f"卖出及股息税记账后现金 {cash_after} 为负")
+            self._cash = cash_after
+            if reservation is not None:
+                reservation.consume(fill.quantity)
+                reservation_quantity_delta = -fill.quantity
+            realized = sum((trade.realized_pnl for trade in planned), Decimal("0"))
+            position.apply_sell(fill.quantity, fill.price, realized)
+            self._realized_pnl += realized
+            for trade in planned:
+                lot = self._lot_by_id(trade.position_lot_id)
+                lot.close(trade.quantity)
+            for entitlement, quantity in consumptions:
+                entitlement.consume(quantity)
+            if position.quantity == 0:
+                del self._positions[fill.instrument_id]
+            closed_lots = tuple(planned)
+
+        self._state_time = fill.fill_time
+        self._applied_fill_ids.add(fill.fill_id)
+        return FillApplied(
+            gross=gross,
+            closed_lots=closed_lots,
+            dividend_tax=dividend_tax,
+            reservation_cash_delta=reservation_cash_delta,
+            reservation_quantity_delta=reservation_quantity_delta,
+        )
+
+    def apply_corporate_action(
+        self, instruction: CorporateActionInstruction, at: datetime
+    ) -> CorporateActionApplied | None:
+        """按登记、除权、红股上市和派息阶段推进公司行动状态机。"""
+        self._check_event_time(at, "corporate_action_time")
+        key = (instruction.action_id, instruction.phase.value)
+        if key in self._applied_corporate_action_phases:
+            return None
+        action_id = instruction.action_id
+        instrument_id = instruction.instrument_id
+        position = self._positions.get(instrument_id)
+        receivable_delta = Decimal("0")
+        cash_delta = Decimal("0")
+
+        if instruction.phase is CorporateActionPhase.RECORD:
+            self._corporate_action_entitlements[action_id] = (
+                0 if position is None else position.quantity
+            )
+            for lot in self._open_lots(instrument_id):
+                self._dividend_entitlements.append(
+                    DividendEntitlement(
+                        action_id,
+                        lot.lot_id,
+                        lot.remaining_quantity,
+                        instruction.cash_per_share,
+                    )
+                )
+        else:
+            if action_id not in self._corporate_action_entitlements:
+                raise ValueError(f"公司行动 {action_id} 缺少股权登记阶段，禁止推断权益")
+            entitled = self._corporate_action_entitlements[action_id]
+            if instruction.phase is CorporateActionPhase.EX_DATE:
+                receivable = Decimal(entitled) * instruction.cash_per_share
+                bonus_decimal = Decimal(entitled) * instruction.stock_ratio
+                bonus = int(bonus_decimal)
+                if Decimal(bonus) != bonus_decimal:
+                    raise ValueError(
+                        f"公司行动 {action_id} 产生非整数送转股 {bonus_decimal}，MVP 禁止静默取整"
+                    )
+                if bonus and position is None:
+                    raise ValueError("登记日有权益但除权日持仓缺失，状态矛盾")
+                if instruction.cash_per_share:
+                    self._dividend_receivable += receivable
+                    self._corporate_action_receivables[action_id] = receivable
+                    receivable_delta = receivable
+                if bonus:
+                    assert position is not None
+                    entitlements = [
+                        item for item in self._dividend_entitlements if item.action_id == action_id
+                    ]
+                    exact = [
+                        Decimal(item.remaining_quantity) * instruction.stock_ratio
+                        for item in entitlements
+                    ]
+                    allocations = [int(v.to_integral_value(rounding=ROUND_FLOOR)) for v in exact]
+                    remainder = bonus - sum(allocations)
+                    order = sorted(
+                        range(len(entitlements)),
+                        key=lambda index: (exact[index] - Decimal(allocations[index]), -index),
+                        reverse=True,
+                    )
+                    for index in order[:remainder]:
+                        allocations[index] += 1
+                    bonus_lot_ids: list[str] = []
+                    for entitlement, allocated in zip(entitlements, allocations, strict=True):
+                        if not allocated:
+                            continue
+                        original = self._lot_by_id(entitlement.lot_id)
+                        adjusted_cost = original.apply_bonus_cost(allocated)
+                        lot_id = f"lot:{action_id}:bonus:{original.lot_id}"
+                        self._position_lots.append(
+                            PositionLot(
+                                lot_id=lot_id,
+                                instrument_id=instrument_id,
+                                source_id=action_id,
+                                acquired_at=original.acquired_at,
+                                quantity=allocated,
+                                unit_cost=adjusted_cost,
+                            )
+                        )
+                        bonus_lot_ids.append(lot_id)
+                    position.apply_bonus(bonus)
+                    self._corporate_action_bonus_lots[action_id] = tuple(bonus_lot_ids)
+                if instruction.stock_ratio:
+                    self._corporate_action_bonuses[action_id] = bonus
+                    self._locked_bonus_by_instrument[instrument_id] = (
+                        self._locked_bonus_by_instrument.get(instrument_id, 0) + bonus
+                    )
+            elif instruction.phase is CorporateActionPhase.LISTING_DATE:
+                bonus = self._corporate_action_bonuses.pop(action_id, None)
+                if bonus is None:
+                    raise ValueError(f"公司行动 {action_id} 缺少除权阶段送转股")
+                if bonus:
+                    if position is None:
+                        raise ValueError("红股上市日持仓缺失，状态矛盾")
+                    locked = self._locked_bonus_by_instrument.get(instrument_id, 0)
+                    if locked < bonus or position.pending_settlement_quantity < bonus:
+                        raise ValueError("红股锁定数量与持仓待结算数量矛盾")
+                    position.release_bonus(bonus)
+                    for lot_id in self._corporate_action_bonus_lots.pop(action_id, ()):
+                        lot = self._lot_by_id(lot_id)
+                        lot.release(at.date())
+                    remaining = locked - bonus
+                    if remaining:
+                        self._locked_bonus_by_instrument[instrument_id] = remaining
+                    else:
+                        self._locked_bonus_by_instrument.pop(instrument_id, None)
+            elif instruction.phase is CorporateActionPhase.PAY_DATE:
+                receivable = self._corporate_action_receivables.pop(action_id, None)
+                if receivable is None:
+                    raise ValueError(f"公司行动 {action_id} 缺少除权阶段应收股息")
+                self._dividend_receivable -= receivable
+                self._cash += receivable
+                receivable_delta = -receivable
+                cash_delta = receivable
+        self._state_time = at
+        self._applied_corporate_action_phases.add(key)
+        return CorporateActionApplied(
+            action_id, instrument_id, instruction.phase.value, receivable_delta, cash_delta
+        )
+
+    def mark_to_market(self, prices: Mapping[str, Decimal], at: datetime) -> None:
+        """原子校验估值输入后，只更新当前持仓并推进组合时间。"""
+        self._check_event_time(at, "at")
+        normalized: dict[str, Decimal] = {}
+        for instrument_id, price in prices.items():
+            canonical = _canonical_instrument_id(instrument_id)
+            checked = finite_decimal(price, f"price[{instrument_id}]")
+            if checked <= 0:
+                raise ValueError(f"估值价格必须 > 0，实际 {checked}")
+            normalized[canonical] = checked
+        for canonical, price in normalized.items():
+            position = self._positions.get(canonical)
+            if position is not None:
+                position.mark(price)
+        self._state_time = at
+
+    def settle_trading_day(self, trading_day: date) -> None:
+        """释放普通 T+1 持仓；红股继续锁定到上市阶段。"""
+        if self._last_settled_day is not None and trading_day < self._last_settled_day:
+            raise ValueError(f"交易日不允许回退：{trading_day} < 已结算 {self._last_settled_day}")
+        if self._last_settled_day == trading_day:
+            return
+        for instrument_id, position in self._positions.items():
+            position.settle(self._locked_bonus_by_instrument.get(instrument_id, 0))
+        locked_bonus_lot_ids = {
+            lot_id for lot_ids in self._corporate_action_bonus_lots.values() for lot_id in lot_ids
+        }
+        for lot in self._position_lots:
+            if (
+                lot.remaining_quantity
+                and lot.available_quantity < lot.remaining_quantity
+                and lot.lot_id not in locked_bonus_lot_ids
+            ):
+                lot.release(trading_day)
+        self._last_settled_day = trading_day
+
+    def available_cash(self) -> Decimal:
+        return self._cash
+
+    def available_quantity(self, instrument_id: str) -> int:
+        canonical = _canonical_instrument_id(instrument_id)
+        position = self._positions.get(canonical)
+        if position is None:
+            return 0
+        frozen = sum(
+            reservation.remaining_quantity
+            for reservation in self._order_reservations.values()
+            if reservation.instrument_id == canonical and reservation.side is OrderSide.SELL
+        )
+        return position.available_quantity - frozen
+
+    def reserved_cash(self, order_id: str) -> Decimal:
+        reservation = self._order_reservations.get(order_id)
+        return Decimal("0") if reservation is None else reservation.remaining_cash
+
+    def reserved_quantity(self, order_id: str) -> int:
+        reservation = self._order_reservations.get(order_id)
+        return 0 if reservation is None else reservation.remaining_quantity
+
+    def reserve_order_resources(
+        self,
+        order_id: str,
+        instrument_id: str,
+        side: OrderSide,
+        quantity: int,
+        cash_amount: Decimal,
+        event_time: datetime,
+    ) -> ReservationChanged | None:
+        """原子冻结订单资源；失败不改变聚合。"""
+        self._check_event_time(event_time, "reservation_time")
+        canonical = _canonical_instrument_id(instrument_id)
+        amount = finite_decimal(cash_amount, "cash_amount")
+        if quantity <= 0 or order_id in self._order_reservations:
+            return None
+        if side is OrderSide.BUY:
+            if amount <= 0 or amount > self._cash:
+                return None
+        elif side is OrderSide.SELL:
+            if amount != 0 or quantity > self.available_quantity(canonical):
+                return None
+        else:
+            raise ValueError("side 必须是 OrderSide")
+        reservation = OrderReservation(
+            order_id=order_id,
+            instrument_id=canonical,
+            side=side,
+            remaining_quantity=quantity,
+            remaining_cash=amount,
+        )
+        self._order_reservations[order_id] = reservation
+        if amount:
+            self._cash -= amount
+            self._frozen_cash += amount
+        return ReservationChanged(
+            order_id,
+            canonical,
+            side,
+            ReservationAction.RESERVE,
+            amount,
+            quantity,
+            event_time,
+        )
+
+    def release_order_resources(
+        self, order_id: str, event_time: datetime
+    ) -> ReservationChanged | None:
+        """释放订单剩余冻结资源；不存在时幂等返回 None。"""
+        self._check_event_time(event_time, "reservation_release_time")
+        reservation = self._order_reservations.pop(order_id, None)
+        if reservation is None:
+            return None
+        cash = reservation.remaining_cash
+        quantity = reservation.remaining_quantity
+        if cash:
+            self._frozen_cash -= cash
+            self._cash += cash
+        return ReservationChanged(
+            reservation.order_id,
+            reservation.instrument_id,
+            reservation.side,
+            ReservationAction.RELEASE,
+            -cash,
+            -quantity,
+            event_time,
+        )
+
+    def _open_lots(self, instrument_id: str) -> list[PositionLot]:
+        return [
+            lot
+            for lot in self._position_lots
+            if lot.instrument_id == instrument_id and lot.remaining_quantity > 0
+        ]
+
+    def _lot_by_id(self, lot_id: str) -> PositionLot:
+        return next(lot for lot in self._position_lots if lot.lot_id == lot_id)
+
+    def _plan_closed_lots(self, fill: Fill, gross: Decimal, fee_total: Decimal) -> list[ClosedLot]:
+        remaining = fill.quantity
+        planned: list[ClosedLot] = []
+        for lot in self._open_lots(fill.instrument_id):
+            if remaining == 0:
+                break
+            quantity = min(remaining, lot.available_quantity)
+            if quantity == 0:
+                continue
+            ratio = Decimal(quantity) / Decimal(fill.quantity)
+            proceeds = gross * ratio
+            sell_fees = fee_total * ratio
+            cost_basis = lot.unit_cost * Decimal(quantity)
+            planned.append(
+                ClosedLot(
+                    trade_id=f"trade:{fill.fill_id}:{lot.lot_id}",
+                    instrument_id=fill.instrument_id,
+                    position_lot_id=lot.lot_id,
+                    buy_source_id=lot.source_id,
+                    sell_fill_id=fill.fill_id,
+                    quantity=quantity,
+                    opened_at=lot.acquired_at,
+                    closed_at=fill.fill_time,
+                    cost_basis=cost_basis,
+                    proceeds=proceeds,
+                    sell_fees=sell_fees,
+                    realized_pnl=proceeds - sell_fees - cost_basis,
+                    holding_days=(fill.fill_time.date() - lot.acquired_at.date()).days,
+                )
+            )
+            remaining -= quantity
+        if remaining:
+            raise ValueError(f"可用 PositionLot 不足：尚缺 {remaining}")
+        return planned
+
+    def _plan_dividend_tax(
+        self, closed_lots: list[ClosedLot]
+    ) -> tuple[Decimal, list[tuple[DividendEntitlement, int]]]:
+        tax = Decimal("0")
+        consumptions: list[tuple[DividendEntitlement, int]] = []
+        planned_by_entitlement: dict[int, int] = {}
+        for trade in closed_lots:
+            for entitlement in self._dividend_entitlements:
+                if entitlement.lot_id != trade.position_lot_id:
+                    continue
+                already_planned = planned_by_entitlement.get(id(entitlement), 0)
+                quantity = min(
+                    entitlement.remaining_quantity - already_planned,
+                    trade.quantity,
+                )
+                if quantity == 0:
+                    continue
+                rate = (
+                    Decimal("0.20")
+                    if trade.holding_days <= 30
+                    else Decimal("0.10")
+                    if trade.holding_days <= 365
+                    else Decimal("0")
+                )
+                tax += entitlement.gross_cash_for(quantity) * rate
+                planned_by_entitlement[id(entitlement)] = already_planned + quantity
+                consumptions.append((entitlement, quantity))
+        return tax, consumptions
+
+    def _check_event_time(self, event_time: datetime, field: str) -> None:
+        if event_time.tzinfo is None:
+            raise ValueError(f"{field} 必须 timezone-aware")
+        if event_time < self._state_time:
+            raise ValueError(f"{field} {event_time} 不允许早于当前状态时间 {self._state_time}")
+
+
+def _canonical_instrument_id(value: str) -> str:
+    parts = value.split(".")
+    if (
+        len(parts) != 3
+        or any(not part for part in parts)
+        or parts[0] != parts[0].upper()
+        or parts[1] != parts[1].upper()
+    ):
+        raise ValueError(f"非法 Canonical instrument_id：{value!r}")
+    return value

quant_core/app/portfolio/domain/portfolio_event.py

@@ -0,0 +1,59 @@
+"""Portfolio 聚合产生的不可变领域事实。"""
+
+from dataclasses import dataclass
+from datetime import datetime
+from decimal import Decimal
+from enum import Enum
+
+from quant_core.app.order_execution.constants import OrderSide
+
+
+class ReservationAction(str, Enum):
+    RESERVE = "reserve"
+    RELEASE = "release"
+
+
+@dataclass(frozen=True, slots=True)
+class ReservationChanged:
+    order_id: str
+    instrument_id: str
+    side: OrderSide
+    action: ReservationAction
+    cash_delta: Decimal
+    quantity_delta: int
+    event_time: datetime
+
+
+@dataclass(frozen=True, slots=True)
+class ClosedLot:
+    trade_id: str
+    instrument_id: str
+    position_lot_id: str
+    buy_source_id: str
+    sell_fill_id: str
+    quantity: int
+    opened_at: datetime
+    closed_at: datetime
+    cost_basis: Decimal
+    proceeds: Decimal
+    sell_fees: Decimal
+    realized_pnl: Decimal
+    holding_days: int
+
+
+@dataclass(frozen=True, slots=True)
+class FillApplied:
+    gross: Decimal
+    closed_lots: tuple[ClosedLot, ...] = ()
+    dividend_tax: Decimal = Decimal("0")
+    reservation_cash_delta: Decimal = Decimal("0")
+    reservation_quantity_delta: int = 0
+
+
+@dataclass(frozen=True, slots=True)
+class CorporateActionApplied:
+    action_id: str
+    instrument_id: str
+    phase: str
+    receivable_delta: Decimal = Decimal("0")
+    cash_delta: Decimal = Decimal("0")

quant_core/app/portfolio/domain/portfolio_value.py

@@ -0,0 +1,21 @@
+"""Portfolio 领域的不可变输入值。"""
+
+from dataclasses import dataclass
+from decimal import Decimal
+from enum import Enum
+
+
+class CorporateActionPhase(str, Enum):
+    RECORD = "record"
+    EX_DATE = "ex_date"
+    LISTING_DATE = "listing_date"
+    PAY_DATE = "pay_date"
+
+
+@dataclass(frozen=True, slots=True)
+class CorporateActionInstruction:
+    action_id: str
+    instrument_id: str
+    phase: CorporateActionPhase
+    cash_per_share: Decimal
+    stock_ratio: Decimal