powerquant-cli 0.2.6__py3-none-any.whl

quant_core/app/portfolio/portfolio_schema.py

@@ -0,0 +1,204 @@
+"""
+Portfolio Schema - 组合只读投影契约（CashSnapshot / PositionSnapshot / PortfolioSnapshot）
+
+语义 SSOT 见 `app/portfolio/SPEC.md`（Fill Rule §5、Runtime Isolation §6）。
+
+不变量（构造边界自维护，不依赖调用者自律）：
+- 全部金额/价格严格 Decimal（mode="before" 拒绝 float，不静默转换）。
+- 数量非负；available + pending_settlement 不超过 quantity。
+- Cash：total == available + frozen，分项均 >= 0。
+- Position：Canonical instrument_id；market_value == quantity * last_price。
+- PortfolioSnapshot：positions 按 instrument_id 稳定排序且不重复；
+  exposure == Σ market_value；total_value == total_cash + exposure；
+  unrealized_pnl == Σ position.unrealized_pnl（realized 可含已平仓历史，
+  不强制等于当前 positions 之和）。
+- Snapshot 深度不可变（frozen + tuple）。本轮不修改 Strategy 的 PositionView。
+"""
+
+from datetime import datetime
+from decimal import Decimal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+from quant_core.app.data.schema.trading_state_schema import validate_canonical_instrument_id
+
+
+def _check_tz_aware(value: datetime, field: str) -> datetime:
+    if value.tzinfo is None:
+        raise ValueError(f"{field} 必须 timezone-aware（Canonical 市场时间带时区）")
+    return value
+
+
+def _reject_float(value: object, field: str) -> object:
+    """组合域内金额/价格共享校验：严格拒绝 float 与非有限 Decimal
+
+    int 字面量可无损转 Decimal，允许；统一规则 value.is_finite() 必须为 True
+    （拒绝 NaN / ±Infinity / sNaN，含无范围约束的 PnL 字段）。
+    """
+    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 _validate_identifier(value: object, field: str) -> str:
+    """组合域内标识校验：拒绝非字符串、空串、纯空白、含任何空白字符"""
+    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 _ensure_finite(model: object, fields: tuple[str, ...]) -> None:
+    """Decimal 解析完成后的二次统一 finite 校验（mode="after"）。
+
+    字符串 "NaN" / "Infinity" 在 before 阶段还不是 Decimal，会在
+    Pydantic 解析后变成非有限 Decimal；此处在解析后统一收口拒绝，
+    与 before 阶段 `_reject_float` 使用同一条 is_finite() 规则。
+    """
+    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")
+
+
+class CashSnapshot(BaseModel):
+    """资金只读投影（分项均 >= 0 且与 total 一致）"""
+
+    model_config = ConfigDict(frozen=True)
+
+    available_cash: Decimal = Field(..., ge=0, description="可用资金（Decimal，>= 0）")
+    frozen_cash: Decimal = Field(..., ge=0, description="冻结资金（Decimal，>= 0）")
+    dividend_receivable: Decimal = Field(
+        Decimal("0"), ge=0, description="已除权但尚未到账的应收股息"
+    )
+    total_cash: Decimal = Field(
+        ..., ge=0, description="资金合计（= available + frozen + receivable，>= 0）"
+    )
+
+    @field_validator(
+        "available_cash", "frozen_cash", "dividend_receivable", "total_cash", mode="before"
+    )
+    @classmethod
+    def _reject_float_amounts(cls, value: object) -> object:
+        return _reject_float(value, "资金字段")
+
+    @model_validator(mode="after")
+    def _check_total_cash(self) -> "CashSnapshot":
+        _ensure_finite(self, ("available_cash", "frozen_cash", "dividend_receivable", "total_cash"))
+        expected = self.available_cash + self.frozen_cash + self.dividend_receivable
+        if self.total_cash != expected:
+            raise ValueError(
+                f"total_cash {self.total_cash} 必须等于 available + frozen + receivable {expected}"
+            )
+        return self
+
+
+class PositionSnapshot(BaseModel):
+    """单持仓只读投影（数量/市值不变量在构造边界自维护）"""
+
+    model_config = ConfigDict(frozen=True)
+
+    instrument_id: str = Field(..., description="Canonical 标识（CN.XSHE.000001）")
+    quantity: int = Field(..., ge=0, description="总持仓（share，>= 0）")
+    available_quantity: int = Field(..., ge=0, description="可卖数量（T+1，>= 0）")
+    pending_settlement_quantity: int = Field(..., ge=0, description="待结算数量（>= 0）")
+    average_cost: Decimal = Field(..., ge=0, description="持仓均价（Decimal，>= 0）")
+    last_price: Decimal = Field(..., gt=0, description="最新价（Decimal，> 0）")
+    market_value: Decimal = Field(..., description="市值（= quantity * last_price）")
+    realized_pnl: Decimal = Field(..., description="已实现盈亏（Decimal）")
+    unrealized_pnl: Decimal = Field(..., description="未实现盈亏（Decimal）")
+
+    _validate_id = field_validator("instrument_id")(
+        classmethod(lambda cls, value: validate_canonical_instrument_id(value))
+    )
+    _validate_amounts = field_validator(
+        "average_cost",
+        "last_price",
+        "market_value",
+        "realized_pnl",
+        "unrealized_pnl",
+        mode="before",
+    )(classmethod(lambda cls, value: _reject_float(value, "持仓金额字段")))
+
+    @model_validator(mode="after")
+    def _check_quantity_invariants(self) -> "PositionSnapshot":
+        _ensure_finite(
+            self,
+            ("average_cost", "last_price", "market_value", "realized_pnl", "unrealized_pnl"),
+        )
+        if self.available_quantity + self.pending_settlement_quantity > self.quantity:
+            raise ValueError(
+                f"available {self.available_quantity} + pending_settlement "
+                f"{self.pending_settlement_quantity} 不得超过总持仓 {self.quantity}"
+            )
+        expected_value = Decimal(self.quantity) * self.last_price
+        if self.market_value != expected_value:
+            raise ValueError(
+                f"market_value {self.market_value} 必须等于 quantity * last_price {expected_value}"
+            )
+        return self
+
+
+class PortfolioSnapshot(BaseModel):
+    """组合 point-in-time 只读投影（跨域唯一读取形态；Strategy 只读）"""
+
+    model_config = ConfigDict(frozen=True)
+
+    account_id: str = Field(..., description="运行账户标识（Backtest/Paper/Live 隔离）")
+
+    _validate_account_id = field_validator("account_id")(
+        classmethod(lambda cls, value: _validate_identifier(value, "account_id"))
+    )
+
+    as_of: datetime = Field(..., description="估值市场时间（timezone-aware）")
+    cash: CashSnapshot = Field(..., description="资金投影")
+    positions: tuple[PositionSnapshot, ...] = Field(
+        ..., description="持仓投影（按 instrument_id 稳定排序，无重复）"
+    )
+    total_value: Decimal = Field(..., description="组合总值（= total_cash + exposure）")
+    realized_pnl: Decimal = Field(..., description="已实现盈亏合计（可含已平仓历史）")
+    unrealized_pnl: Decimal = Field(..., description="未实现盈亏合计（= Σ position）")
+    exposure: Decimal = Field(..., ge=0, description="持仓敞口（= Σ market_value，>= 0）")
+
+    _validate_time = field_validator("as_of")(
+        classmethod(lambda cls, value: _check_tz_aware(value, "as_of"))
+    )
+    _validate_amounts = field_validator(
+        "total_value", "realized_pnl", "unrealized_pnl", "exposure", mode="before"
+    )(classmethod(lambda cls, value: _reject_float(value, "组合金额字段")))
+
+    @field_validator("positions")
+    @classmethod
+    def _stably_sort_positions(
+        cls, positions: tuple[PositionSnapshot, ...]
+    ) -> tuple[PositionSnapshot, ...]:
+        """构造期按 instrument_id 稳定排序，并拒绝重复持仓"""
+        ids = [p.instrument_id for p in positions]
+        if len(ids) != len(set(ids)):
+            raise ValueError(f"同一 instrument_id 不允许重复 position：{ids}")
+        return tuple(sorted(positions, key=lambda p: p.instrument_id))
+
+    @model_validator(mode="after")
+    def _check_aggregate_invariants(self) -> "PortfolioSnapshot":
+        _ensure_finite(self, ("total_value", "realized_pnl", "unrealized_pnl", "exposure"))
+        expected_exposure = sum((p.market_value for p in self.positions), Decimal("0"))
+        if self.exposure != expected_exposure:
+            raise ValueError(
+                f"exposure {self.exposure} 必须等于 Σ position.market_value {expected_exposure}"
+            )
+        expected_total = self.cash.total_cash + self.exposure
+        if self.total_value != expected_total:
+            raise ValueError(
+                f"total_value {self.total_value} 必须等于 "
+                f"cash.total_cash + exposure {expected_total}"
+            )
+        expected_unrealized = sum((p.unrealized_pnl for p in self.positions), Decimal("0"))
+        if self.unrealized_pnl != expected_unrealized:
+            raise ValueError(
+                f"unrealized_pnl {self.unrealized_pnl} 必须等于 Σ position.unrealized_pnl "
+                f"{expected_unrealized}"
+            )
+        return self

quant_core/app/portfolio/simulated_portfolio.py

@@ -0,0 +1,427 @@
+"""Simulated Portfolio - 内存模拟组合（T3，确定性可回放）
+
+语义 SSOT 见 `app/portfolio/SPEC.md` §5 Fill Rule、T3 Task 及用户裁定
+2026-09-04：
+- BUY Fill 的全部 ``FeeBreakdown.total`` 计入 CostBasis；
+- SELL Fill 的费用在计算已实现盈亏时扣除；
+- 清仓（quantity == 0）后删除 active Position，已实现盈亏保留在账户级累计；
+- Portfolio 不做任何货币舍入（费用精度由 FeeModel 产出的 FeeBreakdown 负责）。
+
+核心不变量：
+- 唯一交易输入是 Fill（Fill Rule）；只有 apply_fill 改变现金/持仓状态。
+- BUY：现金减少 ``q*P + F``；数量与 pending_settlement 增加 q；当日不可卖。
+- SELL：不允许超过 available；数量与 available 同步减少 q；
+  现金增加 ``q*P - F``；已实现 ``q*P - F - q*C``（卖出费用计入已实现）。
+- settle_trading_day：新交易日首片前只释放普通买入 pending；红股锁定数量
+  必须等待 listing_date 事件，禁止被普通 T+1 提前释放；
+  同日重复调用幂等；交易日显式注入，不读墙钟。
+- mark_to_market 只更新估值（last_price/market_value/unrealized），
+  不改数量；接受市场价格超集（用户裁定 2026-09-06）：先校验全部输入，
+  只更新与持仓的交集；缺价持仓延续上次估值；交集为空仍推进 as_of。
+- 全程 Decimal 精确计算，无 float / 非有限值（含字符串形式的 "NaN"/"Infinity"）。
+- 同一 fill_id 只能成功应用一次；失败的 Fill 不占用该 ID。
+- SELL 记账后现金必须 >= 0（MVP 不允许账户现金为负）。
+- apply_fill 失败原子：先完整校验，任一失败即抛出且不产生部分状态。
+"""
+
+from datetime import datetime
+from decimal import Decimal
+
+from quant_core.app.data.schema.corporate_action_schema import (
+    CorporateActionEventPayload,
+)
+from quant_core.app.data.schema.trading_state_schema import validate_canonical_instrument_id
+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.portfolio_entity import Portfolio, finite_decimal
+from quant_core.app.portfolio.domain.portfolio_value import (
+    CorporateActionInstruction,
+)
+from quant_core.app.portfolio.domain.portfolio_value import (
+    CorporateActionPhase as PortfolioCorporateActionPhase,
+)
+from quant_core.app.portfolio.domain.reservation_entity import OrderReservation
+from quant_core.app.portfolio.ledger_schema import (
+    CashLedgerAccount,
+    CashLedgerEntry,
+    CashLedgerEntryType,
+    ClosedTrade,
+    OrderReservationLedgerEntry,
+    PositionLotSnapshot,
+    ReservationLedgerAction,
+)
+from quant_core.app.portfolio.portfolio_schema import (
+    CashSnapshot,
+    PortfolioSnapshot,
+    PositionSnapshot,
+)
+
+
+def _check_finite_decimal(value: object, field: str) -> Decimal:
+    """组合域共享金额校验：拒绝 float；转换后统一 is_finite() 收口
+
+    字符串 "NaN" / "Infinity" / "sNaN" 等在转换前不是 Decimal，必须在
+    Decimal 转换完成后再次检查 is_finite()，不允许任何非有限值进入内部状态。
+    """
+    return finite_decimal(value, field)
+
+
+class SimulatedPortfolio(Portfolio):
+    """确定性可回放的内存组合；结构化满足：
+
+    - IPortfolioUpdate（apply_fill / mark_to_market / settle_trading_day / snapshot）
+    - IPortfolioReader（get_cash / get_position）
+    - IExecutionAccountView（available_cash / available_quantity，只读视图）
+    """
+
+    def __init__(
+        self, account_id: str, initial_cash: Decimal, initial_market_time: datetime
+    ) -> None:
+        super().__init__(account_id, initial_cash, initial_market_time)
+        cash = self._cash
+        self._cash_ledger: list[CashLedgerEntry] = []
+        self._closed_trades: list[ClosedTrade] = []
+        self._cash_source_keys: set[str] = set()
+        self._reservation_ledger: list[OrderReservationLedgerEntry] = []
+        self._append_cash_entry(
+            account=CashLedgerAccount.CASH,
+            entry_type=CashLedgerEntryType.INITIAL_BALANCE,
+            amount=cash,
+            event_time=initial_market_time,
+            source_key=f"initial:{self._account_id}",
+        )
+
+    # ------------------------------------------------------------------
+    # IPortfolioUpdate
+    # ------------------------------------------------------------------
+
+    def apply_fill(self, fill: Fill) -> None:
+        """由聚合应用成交；本适配层只生成账本投影。"""
+        reservation = self._order_reservations.get(fill.order_id)
+        result = super().apply_fill(fill)
+        if reservation is not None and (
+            result.reservation_cash_delta or result.reservation_quantity_delta
+        ):
+            self._append_reservation_entry(
+                reservation,
+                ReservationLedgerAction.CONSUME,
+                result.reservation_cash_delta,
+                result.reservation_quantity_delta,
+                fill.fill_time,
+            )
+        if result.reservation_cash_delta:
+            released = -result.reservation_cash_delta
+            for account, amount, suffix in (
+                (CashLedgerAccount.CASH, released, "cash"),
+                (CashLedgerAccount.FROZEN_CASH, -released, "frozen"),
+            ):
+                self._append_cash_entry(
+                    account=account,
+                    entry_type=CashLedgerEntryType.ORDER_RELEASE,
+                    amount=amount,
+                    event_time=fill.fill_time,
+                    source_key=f"fill:{fill.fill_id}:release:{suffix}",
+                    instrument_id=fill.instrument_id,
+                )
+        self._append_trade_cash_entries(fill, result.gross)
+        projected = [
+            ClosedTrade(
+                trade_id=trade.trade_id,
+                instrument_id=trade.instrument_id,
+                position_lot_id=trade.position_lot_id,
+                buy_source_id=trade.buy_source_id,
+                sell_fill_id=trade.sell_fill_id,
+                quantity=trade.quantity,
+                opened_at=trade.opened_at,
+                closed_at=trade.closed_at,
+                cost_basis=trade.cost_basis,
+                proceeds=trade.proceeds,
+                sell_fees=trade.sell_fees,
+                realized_pnl=trade.realized_pnl,
+                holding_days=trade.holding_days,
+            )
+            for trade in result.closed_lots
+        ]
+        self._closed_trades.extend(projected)
+        if result.dividend_tax:
+            self._append_cash_entry(
+                account=CashLedgerAccount.CASH,
+                entry_type=CashLedgerEntryType.DIVIDEND_TAX,
+                amount=-result.dividend_tax,
+                event_time=fill.fill_time,
+                source_key=f"dividend-tax:{fill.fill_id}",
+                instrument_id=fill.instrument_id,
+            )
+
+    def apply_corporate_action(self, event: CorporateActionEventPayload, at: datetime) -> None:
+        """按登记/除权/红股上市/到账阶段处理权益，重复阶段幂等。"""
+        action = event.action
+        applied = super().apply_corporate_action(
+            CorporateActionInstruction(
+                action_id=action.action_id,
+                instrument_id=action.instrument_id,
+                phase=PortfolioCorporateActionPhase(event.phase.value),
+                cash_per_share=action.cash_per_share,
+                stock_ratio=action.stock_ratio,
+            ),
+            at,
+        )
+        if applied is None:
+            return
+        if applied.receivable_delta > 0:
+            self._append_cash_entry(
+                account=CashLedgerAccount.DIVIDEND_RECEIVABLE,
+                entry_type=CashLedgerEntryType.DIVIDEND_RECEIVABLE,
+                amount=applied.receivable_delta,
+                event_time=at,
+                source_key=f"corporate-action:{action.action_id}:receivable",
+                instrument_id=action.instrument_id,
+            )
+        elif applied.receivable_delta < 0:
+            self._append_cash_entry(
+                account=CashLedgerAccount.DIVIDEND_RECEIVABLE,
+                entry_type=CashLedgerEntryType.DIVIDEND_PAYMENT,
+                amount=applied.receivable_delta,
+                event_time=at,
+                source_key=f"corporate-action:{action.action_id}:receivable-paid",
+                instrument_id=action.instrument_id,
+            )
+        if applied.cash_delta:
+            self._append_cash_entry(
+                account=CashLedgerAccount.CASH,
+                entry_type=CashLedgerEntryType.DIVIDEND_PAYMENT,
+                amount=applied.cash_delta,
+                event_time=at,
+                source_key=f"corporate-action:{action.action_id}:cash-paid",
+                instrument_id=action.instrument_id,
+            )
+
+    def snapshot(self) -> PortfolioSnapshot:
+        """当前 point-in-time 只读投影（持仓按 instrument_id 稳定排序）"""
+        position_snapshots = tuple(
+            PositionSnapshot(
+                instrument_id=instrument_id,
+                quantity=position.quantity,
+                available_quantity=position.available_quantity,
+                pending_settlement_quantity=position.pending_settlement_quantity,
+                average_cost=position.average_cost,
+                last_price=position.last_price,
+                market_value=Decimal(position.quantity) * position.last_price,
+                realized_pnl=position.realized_pnl,
+                unrealized_pnl=position.unrealized_pnl(),
+            )
+            for instrument_id, position in sorted(self._positions.items())
+        )
+        exposure = sum((p.market_value for p in position_snapshots), Decimal("0"))
+        total_cash = self._cash + self._frozen_cash + self._dividend_receivable
+        unrealized = sum((p.unrealized_pnl for p in position_snapshots), Decimal("0"))
+        return PortfolioSnapshot(
+            account_id=self._account_id,
+            as_of=self._state_time,
+            cash=CashSnapshot(
+                available_cash=self._cash,
+                frozen_cash=self._frozen_cash,
+                dividend_receivable=self._dividend_receivable,
+                total_cash=total_cash,
+            ),
+            positions=position_snapshots,
+            total_value=total_cash + exposure,
+            realized_pnl=self._realized_pnl,
+            unrealized_pnl=unrealized,
+            exposure=exposure,
+        )
+
+    # ------------------------------------------------------------------
+    # IPortfolioReader
+    # ------------------------------------------------------------------
+
+    def get_cash(self) -> CashSnapshot:
+        return self.snapshot().cash
+
+    def get_position(self, instrument_id: str) -> PositionSnapshot | None:
+        canonical = validate_canonical_instrument_id(instrument_id)
+        position = self._positions.get(canonical)
+        if position is None:
+            return None
+        return next(p for p in self.snapshot().positions if p.instrument_id == canonical)
+
+    # ------------------------------------------------------------------
+    # IExecutionAccountView（执行期只读视图）
+    # ------------------------------------------------------------------
+
+    def reserve_order(
+        self,
+        order_id: str,
+        instrument_id: str,
+        side: OrderSide,
+        quantity: int,
+        cash_amount: Decimal,
+        event_time: datetime,
+    ) -> bool:
+        """由聚合冻结资源，并把领域事实投影到账本。"""
+        event = self.reserve_order_resources(
+            order_id, instrument_id, side, quantity, cash_amount, event_time
+        )
+        if event is None:
+            return False
+        reservation = self._order_reservations[order_id]
+        self._append_reservation_entry(
+            reservation,
+            ReservationLedgerAction.RESERVE,
+            event.cash_delta,
+            quantity,
+            event_time,
+        )
+        if event.cash_delta:
+            self._append_reservation_cash_transfer(
+                order_id,
+                event.cash_delta,
+                event_time,
+                event.instrument_id,
+                release=False,
+            )
+        return True
+
+    def release_order_reservation(self, order_id: str, event_time: datetime) -> None:
+        reservation = self._order_reservations.get(order_id)
+        event = self.release_order_resources(order_id, event_time)
+        if event is None or reservation is None:
+            return
+        self._append_reservation_entry(
+            reservation,
+            ReservationLedgerAction.RELEASE,
+            event.cash_delta,
+            event.quantity_delta,
+            event_time,
+        )
+        if event.cash_delta:
+            self._append_reservation_cash_transfer(
+                order_id,
+                -event.cash_delta,
+                event_time,
+                reservation.instrument_id,
+                release=True,
+            )
+
+    def _append_reservation_entry(
+        self,
+        reservation: OrderReservation,
+        action: ReservationLedgerAction,
+        cash_delta: Decimal,
+        quantity_delta: int,
+        event_time: datetime,
+    ) -> None:
+        self._reservation_ledger.append(
+            OrderReservationLedgerEntry(
+                entry_id=f"reservation:{len(self._reservation_ledger)}",
+                order_id=reservation.order_id,
+                instrument_id=reservation.instrument_id,
+                side=reservation.side.value,
+                action=action,
+                cash_delta=cash_delta,
+                quantity_delta=quantity_delta,
+                event_time=event_time,
+            )
+        )
+
+    def _append_reservation_cash_transfer(
+        self,
+        order_id: str,
+        amount: Decimal,
+        event_time: datetime,
+        instrument_id: str,
+        *,
+        release: bool,
+    ) -> None:
+        entry_type = (
+            CashLedgerEntryType.ORDER_RELEASE if release else CashLedgerEntryType.ORDER_RESERVE
+        )
+        direction = Decimal("1") if release else Decimal("-1")
+        suffix = "release" if release else "reserve"
+        self._append_cash_entry(
+            account=CashLedgerAccount.CASH,
+            entry_type=entry_type,
+            amount=direction * amount,
+            event_time=event_time,
+            source_key=f"order:{order_id}:{suffix}:cash",
+            instrument_id=instrument_id,
+        )
+        self._append_cash_entry(
+            account=CashLedgerAccount.FROZEN_CASH,
+            entry_type=entry_type,
+            amount=-direction * amount,
+            event_time=event_time,
+            source_key=f"order:{order_id}:{suffix}:frozen",
+            instrument_id=instrument_id,
+        )
+
+    def position_lots(self) -> tuple[PositionLotSnapshot, ...]:
+        """返回包含已耗尽批次的稳定持仓批次投影。"""
+        return tuple(
+            PositionLotSnapshot(
+                lot_id=lot.lot_id,
+                instrument_id=lot.instrument_id,
+                source_id=lot.source_id,
+                acquired_at=lot.acquired_at,
+                available_on=lot.available_on,
+                original_quantity=lot.original_quantity,
+                remaining_quantity=lot.remaining_quantity,
+                available_quantity=lot.available_quantity,
+                unit_cost=lot.unit_cost,
+            )
+            for lot in self._position_lots
+        )
+
+    def cash_ledger_entries(self) -> tuple[CashLedgerEntry, ...]:
+        return tuple(self._cash_ledger)
+
+    def closed_trades(self) -> tuple[ClosedTrade, ...]:
+        return tuple(self._closed_trades)
+
+    def reservation_ledger_entries(self) -> tuple[OrderReservationLedgerEntry, ...]:
+        return tuple(self._reservation_ledger)
+
+    def _append_trade_cash_entries(self, fill: Fill, gross: Decimal) -> None:
+        direction = Decimal("-1") if fill.side is OrderSide.BUY else Decimal("1")
+        self._append_cash_entry(
+            account=CashLedgerAccount.CASH,
+            entry_type=CashLedgerEntryType.TRADE_GROSS,
+            amount=direction * gross,
+            event_time=fill.fill_time,
+            source_key=f"fill:{fill.fill_id}:gross",
+            instrument_id=fill.instrument_id,
+        )
+        self._append_cash_entry(
+            account=CashLedgerAccount.CASH,
+            entry_type=CashLedgerEntryType.TRADE_FEE,
+            amount=-fill.fees.total,
+            event_time=fill.fill_time,
+            source_key=f"fill:{fill.fill_id}:fee",
+            instrument_id=fill.instrument_id,
+        )
+
+    def _append_cash_entry(
+        self,
+        *,
+        account: CashLedgerAccount,
+        entry_type: CashLedgerEntryType,
+        amount: Decimal,
+        event_time: datetime,
+        source_key: str,
+        instrument_id: str | None = None,
+    ) -> None:
+        if source_key in self._cash_source_keys:
+            raise ValueError(f"重复现金账来源：{source_key}")
+        self._cash_ledger.append(
+            CashLedgerEntry(
+                entry_id=f"cash:{source_key}",
+                account_id=self._account_id,
+                account=account,
+                entry_type=entry_type,
+                amount=amount,
+                event_time=event_time,
+                source_key=source_key,
+                instrument_id=instrument_id,
+            )
+        )
+        self._cash_source_keys.add(source_key)

quant_core/app/research/SPEC.md

@@ -0,0 +1,57 @@
+# Research SPEC
+
+## 1. Domain Purpose
+
+`research` 负责把交易想法转化为可复现、可比较、可追溯的历史证据，为 Strategy Candidate 的形成和调整提供依据。
+
+## 2. Responsibilities
+
+- 将 Trading Idea 结构化为可验证的 TradingHypothesis。
+- 定义并运行 Historical Experiment。
+- 研究因子、形态、事件和市场环境。
+- 统计样本结果、稳健性、局限与反例。
+- 比较假设、参数和 Strategy Candidate。
+- 产出结构化 ResearchEvidence。
+
+## 3. Non-Responsibilities
+
+- 不定义最终可执行 Strategy Contract。
+- 不运行完整账户级历史回测。
+- 不撮合订单或维护 Portfolio。
+- 不参与实时事件循环。
+- 不直接调用通知渠道。
+
+## 4. Main Concepts
+
+```text
+Trading Idea
+     ↓
+TradingHypothesis
+     ↓
+ResearchExperiment
+     ↓
+ResearchEvidence
+     ↓
+Strategy Candidate
+```
+
+- `TradingHypothesis`：观察条件、预期结果、观察窗口、股票范围与关键假设。
+- `ResearchExperiment`：数据范围、参数、样本定义、分组和可复现配置。
+- `ResearchEvidence`：样本量、收益分布、胜率、MFE/MAE、稳定性、局限和数据来源。
+- `Comparison`：跨参数、时期、股票范围或市场环境比较实验结果。
+
+## 5. Research 与 Backtest
+
+```text
+Research  研究“这个现象是否存在、证据是否稳健”
+Backtest  验证“完整策略考虑时间、成交、费用和资金后是否可交易”
+```
+
+Research 可以比较 Strategy Candidate，但账户级执行对象是 Backtest 中的可执行 StrategyDefinition。
+
+## 6. Cross-Domain Dependencies
+
+- 通过 Market 的公开查询契约读取 point-in-time 正确的历史数据。
+- 可以读取 Strategy Candidate 定义与 BacktestResult 做比较，但不得复制其逻辑。
+- Notification 可以消费 ResearchEvidence 或研究报告，本域不得直接调用渠道 SDK。
+- Agent/LLM 是研究执行能力之一，必须输出结构化、可追溯结果，不能成为自由文本旁路。