powerquant-cli 0.2.6__py3-none-any.whl

quant_core/app/order_execution/schema/order_request_schema.py

@@ -0,0 +1,88 @@
+"""策略订单请求契约：表达策略想交易什么，不承载撮合结果。"""
+
+from datetime import datetime
+from decimal import Decimal
+from enum import Enum
+from uuid import uuid4
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_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 OrderRequestType(str, Enum):
+    QUANTITY = "quantity"
+    VALUE = "value"
+    TARGET_QUANTITY = "target_quantity"
+    TARGET_VALUE = "target_value"
+    TARGET_PERCENT = "target_percent"
+
+
+class OrderRequest(BaseModel):
+    """交易 API 的校验输入；同步处理，不进入延迟请求队列。"""
+
+    model_config = ConfigDict(frozen=True)
+
+    request_id: str = Field(default_factory=lambda: str(uuid4()))
+    strategy_id: str
+    instrument_id: str
+    request_type: OrderRequestType
+    quantity: int | None = None
+    value: Decimal | None = None
+    target_percent: Decimal | None = None
+    limit_price: Decimal | None = Field(default=None, gt=0)
+    event_time: datetime
+    signal_refs: tuple[str, ...] = ()
+
+    _request_id = field_validator("request_id")(
+        classmethod(lambda cls, value: validate_identifier(value, "request_id"))
+    )
+    _strategy_id = field_validator("strategy_id")(
+        classmethod(lambda cls, value: validate_identifier(value, "strategy_id"))
+    )
+    _instrument_id = field_validator("instrument_id")(
+        classmethod(lambda cls, value: validate_canonical_instrument_id(value))
+    )
+
+    @field_validator("value", "target_percent", "limit_price", mode="before")
+    @classmethod
+    def _decimal_only(cls, value: object, info):
+        return None if value is None else reject_float_amount(value, info.field_name)
+
+    @field_validator("event_time")
+    @classmethod
+    def _aware_time(cls, value: datetime) -> datetime:
+        if value.tzinfo is None:
+            raise ValueError("event_time 必须 timezone-aware")
+        return value
+
+    @model_validator(mode="after")
+    def _one_payload(self) -> "OrderRequest":
+        supplied = sum(
+            item is not None for item in (self.quantity, self.value, self.target_percent)
+        )
+        if supplied != 1:
+            raise ValueError("策略订单请求必须且只能提供一种数量/金额/比例")
+        if self.request_type in {
+            OrderRequestType.QUANTITY,
+            OrderRequestType.TARGET_QUANTITY,
+        }:
+            if self.quantity is None:
+                raise ValueError("数量请求必须提供 quantity")
+            if self.request_type is OrderRequestType.TARGET_QUANTITY and self.quantity < 0:
+                raise ValueError("目标 quantity 不允许为负")
+        elif self.request_type in {
+            OrderRequestType.VALUE,
+            OrderRequestType.TARGET_VALUE,
+        }:
+            if self.value is None:
+                raise ValueError("金额请求必须提供 value")
+            if self.request_type is OrderRequestType.TARGET_VALUE and self.value < 0:
+                raise ValueError("目标 value 不允许为负")
+        else:
+            if self.target_percent is None:
+                raise ValueError("目标比例请求必须提供 target_percent")
+            if not Decimal("0") <= self.target_percent <= Decimal("1"):
+                raise ValueError("target_percent 必须位于 [0, 1]")
+        return self