qlib/backend/app/domain/entities/research.py

"""研究领域对象：Research Specification、标准化研究结果。

原则（AGENT.md §16/§21/§24、ARCHITECTURE §14）：
- 前端 / Agent / 后端统一经 Research Specification 描述任务，禁止直接拼引擎配置
- 回测结果一律标准化为 BacktestResult；未建模的成本/市场约束显式列在
  unimplemented，禁止默认「无成本 / 永远可成交」假设
"""

from __future__ import annotations

from datetime import date, datetime

from pydantic import BaseModel, Field, field_validator, model_validator

# ---------- Research Specification ----------


class UniverseSpec(BaseModel):
    """股票池口径。MVP：市场 + 过滤条件；指数成分等 Phase 3 扩展。

    symbols 白名单：非空时仅这些股票参与（再叠加其余过滤）；供自选池/测试使用。
    market 目前为预留字段（stock.market 存储主板/创业板/科创板等中文枚举，过滤未启用）。
    """

    market: str = Field(default="CN_A", description="CN_A / CN_B / ...（预留）")
    exclude_st: bool = True
    exclude_suspended: bool = True
    min_listing_days: int = Field(default=250, ge=0, description="上市至少 N 个自然日")
    index_code: str | None = Field(
        default=None, description="指数成分过滤（如 000300.SH）：按 as_of 当日历史成分（v3 §9）"
    )
    symbols: list[str] = Field(
        default_factory=list,
        description="白名单（可选）：非空时仅这些 symbol 参与选股/回测",
    )


class FactorSpec(BaseModel):
    """引用一个已注册因子并给定权重。"""

    name: str
    weight: float = Field(default=1.0, gt=0)


class ConditionSpec(BaseModel):
    """结构化选股条件（回测与选股共用）。

    字段域：
    - static.*：股票基础字段（industry / market / area / exchange / status…）
    - 行情/技术字段：close / ma20 / ma60 / volume 及全部已注册因子名（momentum_60 等），
      以及每日指标列（dv_ratio / dv_ttm / pe / pb / total_mv …）
    - fundamental.*：财务字段（eps / roe / total_revenue / net_profit / gross_margin），
      仅取 announce_date <= as_of 的最新已公告值（防未来函数）

    右操作数取 value（字面量）或 ref（另一字段名），二者二选一。

    定义位置说明：本模型被 ResearchSpec（回测）与 SelectionQuery（选股）共用，
    故落在 research.py（被 selection.py 依赖的低层模块），selection.py 再 re-export，
    避免循环导入。
    """

    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 SelectionSpec(BaseModel):
    """选股方式（两级截断）。

    口径（用户案例「选 n 只 → 持仓前 x 只」）：
    - `top_n` = n：**候选池**大小。universe ∩ conditions 过滤后，按复合因子分降序取前 n
      只 → 这就是「择股条件选出来的股数」（写入 selection_history）。
    - `hold_top_x` = x：**实际持仓数**，取候选池前 x 只等权。x 必须 ≤ n；
      另受「池内实际可买股票数」约束（过滤/缺数据会让实际池子小于 n）。
      None → 等于 top_n（此时与旧行为一致：选出多少就持多少）。

    `allow_substitute` 与 `defer_buy` 决定「买不进」时的处理（两者互斥，只能选一个）：
    - `allow_substitute=True`（**默认**，保持历史语义不变）：从 n 名**之外**继续往下找
      可买标的补足 x 只 —— 引擎既有行为，见 v3 §20.3 的 Signal↔Fill 测试。
    - `defer_buy=True`（本项目「只买选出来的前 x 只」口径，推荐显式开启）：
      **不替补**，把这只股票的买单**顺延到之后第一个可成交的交易日**（涨停/停牌解除后
      按当日收盘价买入）；到下一次调仓仍未成交则作废，未投入资金留作现金。
    - 两者都 False：意图被拒后直接放弃，资金留现金（不替补也不顺延）。

    默认值刻意保持「向后兼容」：既有 Strategy / Experiment 的语义不因本次扩展而静默改变
    （AGENT.md §35）。高股息案例在前端与 spec 中显式设置 defer_buy=True。
    """

    top_n: int = Field(default=30, ge=1, le=1000, description="n：候选池大小")
    hold_top_x: int | None = Field(
        default=None, ge=1, le=1000, description="x：实际持仓数；None → = top_n"
    )
    allow_substitute: bool = Field(
        default=True,
        description="True（默认，历史语义）：从 n 名之外替补补足；False：不引入计划外标的",
    )
    defer_buy: bool = Field(
        default=False,
        description="True：买不进（涨停/停牌）时顺延到之后首个可成交日的收盘买入",
    )

    @model_validator(mode="after")
    def _check_x_le_n(self) -> SelectionSpec:
        if self.hold_top_x is not None and self.hold_top_x > self.top_n:
            raise ValueError(
                f"hold_top_x（持仓 x={self.hold_top_x}）不能大于 top_n（候选池 n={self.top_n}）"
            )
        if self.allow_substitute and self.defer_buy:
            raise ValueError(
                "allow_substitute=True（往下替补）与 defer_buy=True（顺延买入）语义互斥，只能选一个"
            )
        return self

    @property
    def x(self) -> int:
        """实际持仓目标数（未显式给 x 时等于 n）。"""
        return self.hold_top_x if self.hold_top_x is not None else self.top_n


class PortfolioSpec(BaseModel):
    """组合构建（v2 §16）。MVP：等权；单股/行业上限等约束字段预留，
    未建模约束在回测结果 unimplemented 中如实标注（禁止假装支持）。
    """

    weighting: str = Field(default="equal", pattern="^(equal)$")
    max_position_pct: float | None = Field(
        default=None, gt=0, le=1, description="单股最大权重（预留，未建模）"
    )
    max_industry_weight_pct: float | None = Field(
        default=None, gt=0, le=1, description="行业最大权重（预留，未建模）"
    )


class CostSpec(BaseModel):
    """交易成本模型。

    买：commission（≥ min_commission）+ slippage
    卖：commission（≥ min_commission）+ stamp_tax + slippage

    `min_commission` 为**单笔最低佣金**（A 股常见 5 元）。默认 0.0 = 不启用，
    以保持既有回测数值不变（AGENT.md §35）；高股息等实盘贴近场景建议显式设 5.0。
    注意：最低佣金对**小额单**影响显著，x 越多、单笔越小，成本占比越高。
    """

    commission_rate: float = Field(default=0.0003, ge=0, le=0.01)
    stamp_tax_rate: float = Field(default=0.0005, ge=0, le=0.01)
    slippage_rate: float = Field(default=0.001, ge=0, le=0.05)
    min_commission: float = Field(
        default=0.0, ge=0, le=100.0, description="单笔最低佣金（元）；0 = 不启用"
    )
    benchmark: str = Field(default="000300.SH", description="对照基准指数代码")


class ResearchSpec(BaseModel):
    """一次研究的完整描述。type 决定执行路径。"""

    type: str = Field(default="backtest", pattern="^(factor_test|backtest)$")
    universe: UniverseSpec = UniverseSpec()
    price_adjustment: str = Field(
        default="none", pattern="^(none|qfq|hfq)$",
        description=(
            "研究行情口径：none 不复权（默认）/ qfq 前复权 / hfq 后复权。"
            "qfq/hfq 基于 adjust_factor 折算（v3 §20.5）；结果与 config_snapshot 中显式记录。"
        ),
    )
    factors: list[FactorSpec] = Field(min_length=1)
    conditions: list[ConditionSpec] = Field(
        default_factory=list,
        description=(
            "选股过滤条件（AND，可选）：universe 之后、因子排序之前执行。"
            "字段域同 SelectionQuery.conditions（static.* / 行情列 / 已注册因子 / "
            "fundamental.*），回测与 /api/selections 共用同一求值器（v2 §25 一致性）。"
        ),
    )
    selection: SelectionSpec = SelectionSpec()
    rebalance: str = Field(default="monthly", pattern="^(weekly|monthly)$")
    selection_interval_months: int | None = Field(
        default=None, ge=1, le=60,
        description=(
            "m：择股间隔（月）。None → 每次调仓都重新择股（等价于 rebalance 频率）。"
            "择股日 = 起始月锚定，月序号 % m == 0 的月份的首个交易日。"
        ),
    )
    rebalance_interval_months: int | None = Field(
        default=None, ge=1, le=60,
        description=(
            "y：调仓间隔（月）。None → 等于 selection_interval_months（未给则按 rebalance 频率）。"
            "y < m 时池子在下一次择股前保持不变（结果中会标注池子陈旧）。"
        ),
    )
    period: tuple[date, date]
    costs: CostSpec = CostSpec()
    portfolio: PortfolioSpec = PortfolioSpec()
    initial_capital: float = Field(default=1_000_000.0, gt=0)

    @field_validator("period")
    @classmethod
    def _period_ordered(cls, period: tuple[date, date]) -> tuple[date, date]:
        if period[0] >= period[1]:
            raise ValueError("period 必须满足 start < end")
        return period

    @model_validator(mode="after")
    def _no_duplicate_factors(self) -> ResearchSpec:
        names = [f.name for f in self.factors]
        if len(set(names)) != len(names):
            raise ValueError("factors 存在重复因子名")
        return self

    @model_validator(mode="after")
    def _check_intervals(self) -> ResearchSpec:
        m = self.selection_interval_months
        y = self.rebalance_interval_months
        # 未给 m 却给了 y：语义不完整（y 无锚点可依）→ 明确拒绝而非猜
        if m is None and y is not None and y != 1:
            raise ValueError(
                "只给了 rebalance_interval_months(y) 而没给 selection_interval_months(m)："
                "请同时给出 m，否则无法确定择股日集合"
            )
        if m is not None and y is not None and y < m and y != 1:
            # 允许但不静默：池子会在多个调仓日复用（陈旧），交由结果 unimplemented 标注
            return self
        return self

    @property
    def effective_selection_months(self) -> int | None:
        """实际择股间隔（月）；None 表示「每次调仓都择股」。"""
        return self.selection_interval_months

    @property
    def effective_rebalance_months(self) -> int | None:
        """实际调仓间隔（月）；None 表示按 rebalance 频率（周/月）。"""
        if self.rebalance_interval_months is not None:
            return self.rebalance_interval_months
        return self.selection_interval_months


# ---------- 回测结果 ----------


class CurvePoint(BaseModel):
    date: date
    value: float


class MonthlyReturn(BaseModel):
    year: int
    month: int
    return_pct: float  # 百分数，如 3.2 表示 +3.2%


class YearlyReturn(BaseModel):
    year: int
    return_pct: float


class BacktestSummary(BaseModel):
    start: date
    end: date
    initial_capital: float
    final_equity: float
    total_return_pct: float
    annual_return_pct: float
    sharpe: float
    max_drawdown_pct: float
    volatility_pct: float
    win_rate_pct: float
    total_trades: int
    avg_turnover_pct: float
    benchmark_return_pct: float | None = None


class Trade(BaseModel):
    entry_date: date
    exit_date: date
    symbol: str
    name: str | None = Field(default=None, description="股票名称（展示用）")
    entry_price: float
    exit_price: float
    return_pct: float


class Position(BaseModel):
    date: date
    symbol: str
    name: str | None = Field(default=None, description="股票名称（展示用）")
    weight: float


class RankedPick(BaseModel):
    """调仓日选股意图候选（与 select(as_of) 同源；v3 §22.3 selection_history）。"""

    date: date
    symbol: str
    name: str | None = Field(default=None, description="股票名称（展示用）")
    rank: int
    score: float


class ActionRecord(BaseModel):
    """一次交易意图（Signal）及其成交结果（Fill）—— v3 §20.3 Signal↔Fill 区分。

    signal=BUY/SELL（策略意图）；filled=是否实际成交；reject_reason 给出未成交原因
    （涨停/跌停/无价/现金不足等）。fills = [a for a in signal_history if a.filled]。

    `name` 为展示增强字段：由服务层按股票池统一回填（未命中则为 None），
    引擎自身不感知名称 —— 引擎只处理 symbol，保持纯行情计算职责。
    """

    date: date
    symbol: str
    name: str | None = Field(default=None, description="股票名称（展示用）")
    signal: str = Field(pattern="^(BUY|SELL)$")
    filled: bool
    reject_reason: str | None = None
    price: float | None = Field(default=None, description="成交价（fill）或意图参考价")


class SymbolCurve(BaseModel):
    """个股收益率趋势曲线 + 该股买卖点标注（回测结果可视化用）。

    `points[].value` 语义：该股**持仓期间**的累计收益率（%，以建仓日收盘为 0% 基准，
    按日复利）。只在该股被持有的交易日落点（未持有期间不落点，以压缩结果体积）；
    建仓当日会补一个基准点，保证买卖点标注总能在曲线上取到数值。多段持仓以累计值
    连乘衔接，读图时以 marks 中的 BUY/SELL 区分各段持仓区间。

    `marks` 为该股实际成交（BUY/SELL fill）的日期与价格，与 `signal_history`
    中 filled=True 的记录一致（v3 §20.3 的成交口径）。
    """

    symbol: str
    name: str | None = Field(default=None, description="股票名称（展示用）")
    points: list[CurvePoint] = Field(default_factory=list)
    marks: list[ActionRecord] = Field(default_factory=list)
    final_return_pct: float = Field(
        default=0.0, description="该股持仓期累计收益率（%，多段持仓连乘）"
    )


class BacktestResult(BaseModel):
    """标准化回测结果（ARCHITECTURE §14）。前端只依赖该结构。"""

    summary: BacktestSummary
    equity_curve: list[CurvePoint]
    drawdown: list[CurvePoint]
    monthly_returns: list[MonthlyReturn]
    yearly_returns: list[YearlyReturn]
    positions: list[Position]
    trades: list[Trade]
    selection_history: list[RankedPick] = Field(
        default_factory=list, description="各调仓日选股意图候选（同 select(as_of)）"
    )
    signal_history: list[ActionRecord] = Field(
        default_factory=list, description="交易意图与是否成交（v3 §20.3）"
    )
    fills: list[ActionRecord] = Field(
        default_factory=list, description="实际成交（signal_history 中 filled=True 的子集）"
    )
    symbol_curves: list[SymbolCurve] = Field(
        default_factory=list,
        description="个股收益率曲线 + 买卖点标注（按期末收益绝对值降序，体积可控）",
    )
    turnover_pct: float
    unimplemented: list[str] = Field(
        default_factory=list,
        description="本结果中未建模的约束（AGENT §24：必须显式标注，禁止假装支持）",
    )
    config_snapshot: dict = Field(default_factory=dict, description="复现用完整配置快照")
    archive_meta: dict = Field(
        default_factory=dict,
        description=(
            "归档元数据（由 experiment_archive 在落库时写入）：curves_stored / "
            "curves_total / truncated / budget_chars / budget_bytes / result_chars / "
            "result_bytes。用于说明归档是否因体积预算被裁剪（AGENT §24 不静默）"
        ),
    )


SymbolCurve.model_rebuild()


# ---------- 因子测试结果 ----------


class QuantileReturn(BaseModel):
    """分层收益：按因子值升序分 N 层后各层等权组合的区间收益。"""

    quantile: int
    return_pct: float


class FactorTestReport(BaseModel):
    factor_name: str
    ic_mean: float
    icir: float
    rank_ic_mean: float
    positive_ratio_pct: float
    quantile_returns: list[QuantileReturn]
    spread_quantile: int | None = Field(
        default=None, description="分层价差 = 最高层收益 - 最低层收益（若多头/空头语义适用）"
    )
    sample_days: int
    unimplemented: list[str] = Field(default_factory=list)
    config_snapshot: dict = Field(default_factory=dict)


# ---------- 因子相关性 / 暴露分析（C1，v3 §12） ----------


class FactorCorrelationReport(BaseModel):
    """多因子两两相关（横截面相关逐日均值；v3 §12 冗余剔除前置）。"""

    factors: list[str]
    corr_matrix: dict[str, dict[str, float]] = Field(
        default_factory=dict, description="{f1: {f2: spearman 相关系数}}（对角线=1）"
    )
    sample_days: int = 0
    sample_min_symbols: int = 0
    unimplemented: list[str] = Field(default_factory=list)
    config_snapshot: dict = Field(default_factory=dict)


# ---------- 异步 Job 与 Experiment（Phase 4） ----------


class JobStatus(str):
    """统一状态机（AGENT.md §20）：queued→running→(success|failed|cancelled)。"""

    QUEUED = "queued"
    RUNNING = "running"
    SUCCESS = "success"
    FAILED = "failed"
    CANCELLED = "cancelled"


class JobRecord(BaseModel):
    """一次异步研究任务。spec/result 以 JSON 文本存储（保持 Schema 演进自由）。"""

    id: str
    kind: str  # factor_test | backtest
    status: str = JobStatus.QUEUED
    stage: str | None = None
    spec_json: str
    error: str | None = None
    result_json: str | None = None
    experiment_id: str | None = None
    created_at: datetime | None = None
    started_at: datetime | None = None
    finished_at: datetime | None = None


class ExperimentRecord(BaseModel):
    """一次研究的可复现存档（AGENT.md §21）。"""

    id: str
    kind: str  # factor_test | backtest
    spec_json: str
    result_json: str
    summary_text: str | None = None  # 便于列表展示的摘要（如 total_return_pct）
    code_version: str | None = None  # git commit / 代码指纹
    data_version: str | None = None
    job_id: str | None = None
    created_at: datetime | None = None


class ExperimentSummary(BaseModel):
    """归档列表项（**不含 result_json**）。

    列表接口一次可能返回上百条归档，而 `result_json` 是 MEDIUMTEXT（完整存档后
    单条可达数 MB）：为避免把上百 MB 拉进内存，仓储的列表查询只取元数据列，
    `result_bytes` 由 SQL 的字符长度函数（MySQL CHAR_LENGTH / SQLite length）
    在库侧算出，不取回大字段本身。
    """

    id: str
    kind: str
    spec_json: str
    summary_text: str | None = None
    code_version: str | None = None
    data_version: str | None = None
    job_id: str | None = None
    created_at: datetime | None = None
    result_bytes: int = 0  # 归档 JSON 的字符数（SQL 侧计算，不拉大字段）