qlib/backend/app/application/services/selection_service.py

"""选股用例入口（ARCHITECTURE_v2 §14 Selection Engine · 业务层）。

- 输入：SelectionQuery（universe + method + factors/conditions + top_n/pct + as_of）
- 装配：股票池（universe 过滤）→ 行情长表（含预热窗口）→ Selection Engine
  （method=score 因子评分 / method=condition 结构化条件）
- 输出：SelectionResult（可解释：factor_values / filter_status / selection_reason）
- 未来函数红线：行情只取 <= as_of；财务条件只取 announce_date <= as_of 的已公告值（v2 §9）

MVP 为同步执行（单日全市场因子/条件计算量轻）；如需异步可复用 Job 链路。
"""

from __future__ import annotations

from datetime import date, timedelta

import pandas as pd

from app.domain.entities.market import FinancialIndicator
from app.domain.entities.selection import SelectionQuery, SelectionResult
from app.domain.repositories.market import (
    DailyBarRepository,
    FinancialRepository,
    StockRepository,
)
from app.quant.selection import (
    condition_needed_columns,
    factor_columns,
    run_condition_selection,
    run_score_selection,
)
from app.quant.service import (
    load_basic_df,
    load_daily_df,
    merge_basic_into_daily,
    split_factor_columns,
)
from app.quant.universe import filter_stocks, names_as_of, resolve_members

_FUNDAMENTAL_PREFIX = "fundamental."


def fill_candidate_names(result: SelectionResult, stocks: list) -> SelectionResult:
    """把股票池的 `symbol → name` 回填进候选股（展示增强，未命中保持 None）。

    为什么在业务层做：名称是展示数据而非选股语义，引擎（quant/selection.py）
    只做纯数值计算，不应感知名称；而本用例的 `stocks` 已是 universe 过滤后的
    股票实体列表（天然带 name），在这里一次性建立映射即可，不必在各出口各自查库。
    查不到名称的候选保持 None —— 前端按「名称未知」渲染，不伪造也不报错。
    """
    if not result.candidates or not stocks:
        return result
    name_map = {s.symbol: s.name for s in stocks if getattr(s, "name", None)}
    if not name_map:
        return result
    for cand in result.candidates:
        if cand.name is None:
            cand.name = name_map.get(cand.symbol)
    return result


class SelectionService:
    """选股用例入口：select(query) → SelectionResult（当前或历史 as_of）。"""

    def __init__(
        self,
        stock_repo: StockRepository,
        daily_repo: DailyBarRepository,
        financial_repo: FinancialRepository | None = None,
        index_repo=None,
        basic_repo=None,
        name_repo=None,
    ) -> None:
        self._stock_repo = stock_repo
        self._daily_repo = daily_repo
        self._financial_repo = financial_repo
        self._index_repo = index_repo
        # 每日指标仓储（daily_basic）：score 因子/条件引用 dv_ratio 等列时使用
        self._basic_repo = basic_repo
        # 名称变更历史仓储：exclude_st 的时点口径（与回测口径一致，v2 §25）
        self._name_repo = name_repo

    def select(self, query: SelectionQuery) -> SelectionResult:
        as_of = query.as_of or date.today()
        all_stocks = self._stock_repo.list()
        name_at, _applied = names_as_of(all_stocks, as_of, self._name_repo)
        stocks = filter_stocks(
            all_stocks, query.universe, as_of=as_of,
            members=resolve_members(self._index_repo, query.universe, as_of),
            name_at=name_at,
        )
        if not stocks:
            return self._run(query, pd.DataFrame(), stocks, as_of, financial={})
        symbols = [s.symbol for s in stocks]
        if query.method == "score":
            columns = sorted(factor_columns(query))
        else:
            columns = sorted(condition_needed_columns(query))
        bar_cols, basic_cols = split_factor_columns(columns)
        data_start = as_of - timedelta(days=query.warmup_days)
        daily = load_daily_df(
            self._daily_repo,
            symbols,
            data_start,
            as_of,
            sorted(bar_cols),
            adjust="none",
            price_adjust=query.price_adjustment,
        )
        if basic_cols:
            daily = self._attach_basic(daily, symbols, data_start, as_of, sorted(basic_cols))
        financial: dict[str, FinancialIndicator] = {}
        if query.method == "condition" and self._uses_fundamental(query):
            financial = self._load_financial(symbols, as_of)
        return self._run(query, daily, stocks, as_of, financial)

    # ---- 内部 ----

    def _attach_basic(
        self,
        daily: pd.DataFrame,
        symbols: list[str],
        start: date,
        end: date,
        columns: list[str],
    ) -> pd.DataFrame:
        """并入 daily_basic 列（与 ResearchService 同一装配逻辑，保证 v2 §25 一致性）。"""
        if self._basic_repo is None:
            raise ValueError(
                f"选股条件/因子需要每日指标列 {columns}（daily_basic），"
                "但未注入 DailyBasicRepository。请检查 API 的依赖装配。"
            )
        basic = load_basic_df(self._basic_repo, symbols, start, end, columns)
        if basic.empty:
            raise ValueError(
                f"daily_basic 表在 {start}~{end} 无数据，无法计算需要 {columns} 的因子/条件。"
                "请先运行：python -m app.cli.sync daily_basic --start 20200101"
            )
        return merge_basic_into_daily(daily, basic)

    def _run(
        self,
        query: SelectionQuery,
        daily: pd.DataFrame,
        stocks: list,
        as_of: date,
        financial: dict[str, FinancialIndicator],
    ) -> SelectionResult:
        if query.method == "score":
            result = run_score_selection(daily, query, as_of)
        else:
            result = run_condition_selection(daily, stocks, query, as_of, financial)
        # 名称只在业务层回填：引擎（quant/selection.py）保持纯符号计算，
        # 而 `stocks` 是本用例已经装配好的股票池，天然带 name，无需再查库/join。
        return fill_candidate_names(result, stocks)

    @staticmethod
    def _uses_fundamental(query: SelectionQuery) -> bool:
        for c in query.conditions:
            if c.field.startswith(_FUNDAMENTAL_PREFIX) or (
                c.ref is not None and c.ref.startswith(_FUNDAMENTAL_PREFIX)
            ):
                return True
        return False

    def _load_financial(
        self, symbols: list[str], as_of: date
    ) -> dict[str, FinancialIndicator]:
        """按 announce_date <= as_of 批量取财务，每 symbol 保留最新一版。"""
        if self._financial_repo is None:
            raise ValueError("condition 引用了 fundamental.* 字段，但未注入 FinancialRepository")
        getter = getattr(self._financial_repo, "list_announced_many", None)
        if getter is not None:
            rows = list(getter(symbols, as_of))
        else:  # 回退逐只
            rows = []
            for sym in symbols:
                rows.extend(self._financial_repo.list_announced(sym, as_of))
        by_symbol: dict[str, FinancialIndicator] = {}
        for row in rows:
            cur = by_symbol.get(row.symbol)
            if cur is None or (row.announce_date, row.report_date) > (
                cur.announce_date,
                cur.report_date,
            ):
                by_symbol[row.symbol] = row
        return by_symbol