feat(selection): M6.0 选股契约与评分引擎（SelectionQuery/Result + select(as_of)）

- domain/entities/selection.py：SelectionQuery（universe+method+factors+top_n/top_pct/ min_score+as_of+预热）与 SelectionResult/Candidate/Statistics（v2 §14.2/§21.1 DTO）； ConditionSpec 字段就位供 M6.2 条件选股 - quant/selection.py：Selection Engine method=score —— 复合分（zscore×权重×方向） → TopN/Top% 截断；observation_date=<=as_of 最近交易日（防未来函数，v2 §9）；候选带 factor_values 与 selection_reason（可解释） - application/services/selection_service.py：选股用例（universe 过滤 → 装配 → 引擎） - quant/service.py：抽取公共 load_daily_df 供研究/选股共用（行为不变） - tests/test_selection.py：11 例 —— TopN/排序/理由、as_of 防未来函数、ST/上市天数/ 退市过滤、top_pct/min_score、空数据与查询校验；全量 pytest 通过
2026-09-09 00:12:28 +08:00
parent 697ffc767b
commit f3586adb25
5 changed files with 606 additions and 21 deletions
@@ -0,0 +1,125 @@
+"""选股系统领域对象（ARCHITECTURE_v2 §14 Selection Engine）。
+
+回答两个核心问题（v2 §8）：
+- 「某历史日（as_of）为什么选出这些股票？」→ SelectionResult 带 factor_values / selection_reason
+- 「当前（as_of）有哪些股票满足策略？」→ 同一条查询对当前日期执行
+
+设计：
+- SelectionQuery = v2 §14.2 的 Selection 输入（universe 范围 + 评分因子 + TopN 截断 + as_of）。
+- method=score：按因子加权复合分取 TopN（复用现有 9 个内置因子）；
+  method=condition：结构化条件选股（M6.2 加入 ConditionSpec）。
+- 结果不落库由本实体负责（落库表在 M6.3）；本实体是前后端/Agent 的统一 DTO（v2 §21.1）。
+- 所有查询天然带 as_of 语义：只允许使用 <= as_of 的数据（v2 §9 防未来函数）。
+"""
+
+from __future__ import annotations
+
+from datetime import date
+
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+from app.domain.entities.research import FactorSpec, UniverseSpec
+
+
+class SelectionQuery(BaseModel):
+    """一次选股查询（v2 §14.2 Selection 输入）。"""
+
+    universe: UniverseSpec = UniverseSpec()
+    # 研究时点：None → 引擎用 <= 今天最近可用交易日；显式给历史日期即做历史选股
+    as_of: date | None = Field(
+        default=None, description="选股时点；历史回测/解释用具体日期，当前选股可留空"
+    )
+    method: str = Field(default="score", pattern="^(score|condition)$")
+    # method=score：因子 + 权重（至少 1 个；方向由因子元数据决定）
+    factors: list[FactorSpec] = Field(default_factory=list)
+    # method=condition：结构化条件（M6.2 引入 ConditionSpec 后启用）
+    conditions: list[ConditionSpec] = Field(default_factory=list)
+    # 截断：top_n（绝对数量）与 top_pct（占可评分股票比例）二选一；可选 min_score 下限
+    top_n: int | None = Field(default=None, ge=1, le=2000)
+    top_pct: float | None = Field(default=None, gt=0, le=1)
+    min_score: float | None = None
+    # 因子预热窗口（自然日）：覆盖 lookback 前导数据，Lookback 放大时需同步加大
+    warmup_days: int = Field(default=300, ge=0)
+
+    @model_validator(mode="after")
+    def _check_method_args(self) -> SelectionQuery:
+        if self.method == "score" and not self.factors:
+            raise ValueError("method=score 需要至少一个 factors")
+        if self.method == "condition" and not self.conditions:
+            raise ValueError("method=condition 需要至少一个 conditions")
+        if self.top_n is None and self.top_pct is None:
+            raise ValueError("top_n 与 top_pct 至少提供一个")
+        return self
+
+    @model_validator(mode="after")
+    def _no_duplicate_factors(self) -> SelectionQuery:
+        names = [f.name for f in self.factors]
+        if len(set(names)) != len(names):
+            raise ValueError("factors 存在重复因子名")
+        return self
+
+
+class ConditionSpec(BaseModel):
+    """结构化选股条件（M6.2 使用）。
+
+    field 域：
+    - static.*：股票基础字段（industry / market / area / exchange / status…）
+    - 行情/技术字段：close / ma20 / ma60 / volume 及全部已注册因子名（momentum_60 等）
+    - fundamental.*：财务字段（eps / roe / total_revenue / net_profit / gross_margin），
+      仅取 announce_date <= as_of 的最新已公告值（防未来函数）
+    右操作数取 value（字面量）或 ref（另一字段名），二者二选一。
+    """
+
+    field: str
+    op: str = Field(pattern="^(gt|gte|lt|lte|eq|ne|in|not_in)$")
+    value: float | int | str | list | None = None
+    ref: str | None = None  # 与另一字段比较（如 close vs ma60）
+
+    @model_validator(mode="after")
+    def _require_operand(self) -> ConditionSpec:
+        if self.value is None and self.ref is None:
+            raise ValueError("value 与 ref 必须提供一个")
+        if self.value is not None and self.ref is not None:
+            raise ValueError("value 与 ref 只能提供一个")
+        if self.op in ("in", "not_in") and not isinstance(self.value, list):
+            raise ValueError("in/not_in 的 value 必须是列表")
+        return self
+
+
+class SelectionCandidate(BaseModel):
+    """单只候选股（v2 §14.3/§21.1）。"""
+
+    symbol: str
+    rank: int
+    score: float
+    factor_values: dict[str, float] = Field(default_factory=dict)
+    filter_status: list[str] = Field(default_factory=list, description="各条件通过/未通过")
+    selection_reason: list[str] = Field(default_factory=list, description="为什么选它（可解释）")
+
+
+class SelectionStatistics(BaseModel):
+    universe_size: int = 0  # 股票池过滤后数量
+    evaluated: int = 0  # 有有效分数的股票数量
+    selected: int = 0  # 最终选出数量
+
+
+class SelectionResult(BaseModel):
+    """选股结果（v2 §21.1）。前端 / Agent 只依赖该结构。"""
+
+    as_of_date: date
+    method: str
+    statistics: SelectionStatistics
+    candidates: list[SelectionCandidate] = Field(default_factory=list)
+    unimplemented: list[str] = Field(
+        default_factory=list,
+        description="本结果中未建模的约束（如 exclude_suspended 依赖停牌数据未实现）",
+    )
+    config_snapshot: dict = Field(default_factory=dict, description="复现用查询快照")
+
+    @field_validator("candidates")
+    @classmethod
+    def _rank_sorted(cls, candidates: list[SelectionCandidate]) -> list[SelectionCandidate]:
+        return sorted(candidates, key=lambda c: c.rank)
+
+
+SelectionQuery.model_rebuild()