first commit

backend/app/domain.py

@@ -0,0 +1,77 @@
+"""领域模型契约（单一事实源的载体）。
+
+MVP 第一周必须定稿的核心类型。回测引擎、指标、API、(未来的)前端类型化客户端
+都基于这些契约——保证"图表/回测/实盘"用同一套语义。
+
+注意：回测/图表的指标值由后端唯一计算（app.indicators），前端不另算。
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from enum import Enum
+
+
+class Side(str, Enum):
+    BUY = "buy"
+    SELL = "sell"
+
+
+class Timeframe(str, Enum):
+    """K 线周期。分钟级已预留（用户选了分钟级回测）。"""
+    M1 = "1m"
+    M5 = "5m"
+    M15 = "15m"
+    M30 = "30m"
+    H1 = "1h"
+    D1 = "1d"
+    W1 = "1w"
+
+
+@dataclass(frozen=True)
+class Bar:
+    """一根 K 线（OHLCV + 时间戳）。复权标识后续扩展。"""
+    ts: datetime
+    open: float
+    high: float
+    low: float
+    close: float
+    volume: float
+
+
+@dataclass(frozen=True)
+class Signal:
+    """策略产生的交易信号（用于在图上标注买卖点）。"""
+    ts: datetime
+    side: Side
+    price: float
+    strength: float = 1.0
+
+
+@dataclass(frozen=True)
+class Fill:
+    """一笔成交（含费用明细）。回测中由 PaperBroker 产生。"""
+    ts: datetime
+    side: Side
+    price: float
+    qty: float
+    commission: float = 0.0
+    stamp_duty: float = 0.0   # 印花税（仅卖出）
+    transfer_fee: float = 0.0  # 过户费（双边）
+
+    @property
+    def total_cost(self) -> float:
+        return self.commission + self.stamp_duty + self.transfer_fee
+
+
+@dataclass
+class Position:
+    """持仓状态。T+1：locked_qty 为当日买入、次日才可卖的部分。"""
+    symbol: str = ""
+    holdings: float = 0.0   # 可卖数量
+    locked: float = 0.0     # 当日买入（T+1 锁定）
+    avg_price: float = 0.0
+
+    @property
+    def qty(self) -> float:
+        return self.holdings + self.locked