Simon
75c5472c31
- quant/selection.run_condition_selection：结构化条件 AND 求值 —— 字段域 static.*（行业/市场…）、技术列与派生量（close/volume/ma20/ma60）、已注册因子 （momentum_60 等）、fundamental.*（announce_date<=as_of 的最新已公告财务值）； 条件支持 value 字面量与 ref 字段比较（如 close > ma60）；结果带 filter_status/reason - SelectionQuery 校验调整：condition 模式为纯过滤（不再强制 top_n/top_pct） - FinancialRepository 新增 list_announced_many（批量防未来函数读取）+ SQLAlchemy 实现； SelectionService 注入 financial_repo 并按 announce_date 取每股最新一版 - tests/test_selection_condition.py：8 例（行业 in/ne、动量>0、close>ma60 ref、阈值、 ROE 过滤且未来公告不可见、缺财务 repo 报错、更早 as_of 排除）；全量 pytest 通过
127 lines
5.6 KiB
Python
127 lines
5.6 KiB
Python
"""选股系统领域对象（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":
|
||
if not self.factors:
|
||
raise ValueError("method=score 需要至少一个 factors")
|
||
if self.top_n is None and self.top_pct is None:
|
||
raise ValueError("method=score 需要 top_n 与 top_pct 至少提供一个")
|
||
if self.method == "condition" and not self.conditions:
|
||
raise ValueError("method=condition 需要至少一个 conditions")
|
||
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()
|