qlib/backend/app/quant/condition_fields.py

"""条件字段注册表 —— 「字段库」的唯一事实来源（2026-10）。

要解决的问题
------------
策略库的「过滤条件」此前是**手填字段名**的输入框：用户必须知道 dv_ratio /
static.industry / fundamental.roe 这类内部标识，既看不到含义，写错了也不报错 ——
引擎对未知字段求值一律返回 None，条件**永远不通过**，策略会安静地选出 0 只股票。
这正是 AGENT.md 禁止的「静默失败 / 假装支持」。

本模块的职责
------------
把**引擎真正支持的字段域**集中声明一次（中文名 + 含义 + 单位 + 分组 + 类型 + 排序），
供三方共用：

1. ``/api/condition-fields`` 据此 seed 目录、据此校验用户新增的自定义字段；
2. 前端据此渲染分组下拉、含义提示、并按类型收窄可选比较符；
3. :func:`is_supported_field` 直接查 ``Stock`` / ``FinancialIndicator`` 的字段定义与
   因子注册表（``quant.factors``），**不另写一套近似规则** —— 避免注册表与引擎漂移。

诚实性约束（AGENT.md §24）
--------------------------
只登记真能算的字段。日期字段（如 ``static.list_date``）无法比较大小，:func:`reason_unsupported`
会明确拒绝并说明理由，而不是放行让用户建出一条「永远选不出股票」的条件。
单位一律照抄数据源落库口径（见 ``data_sources/tushare.py`` 的换算注释），不凭印象写。
"""

from __future__ import annotations

from dataclasses import dataclass

from app.domain.entities.condition_field import OPS_BY_KIND
from app.domain.entities.market import (
    DAILY_BAR_NUMERIC_FIELDS,
    DAILY_BASIC_NUMERIC_FIELDS,
    FinancialIndicator,
    Stock,
)
from app.quant.factors import FactorError, get_factor, list_factors, resolve_factor

# ---------- 分组（下拉的 optgroup 顺序即此顺序） ----------

GROUP_STOCK = "股票基础"
GROUP_QUOTE = "行情"
GROUP_TECH = "技术指标"
GROUP_DAILY = "每日指标"
GROUP_FUNDAMENTAL = "财务指标"
GROUP_FACTOR = "因子"

GROUP_ORDER: tuple[str, ...] = (
    GROUP_STOCK,
    GROUP_QUOTE,
    GROUP_TECH,
    GROUP_DAILY,
    GROUP_FUNDAMENTAL,
    GROUP_FACTOR,
)

# 比较符规则（哪种类型能比大小）定义在领域实体 domain/entities/condition_field.py，
# 此处转发 —— 保证「字段库 API 返回的 ops」与「注册表里 FieldDef.ops」出自同一处。

# ---------- 单位阶梯（2026-10） ----------
#
# 单位分两层，避免「改个显示单位把历史策略的数值偷偷换义」：
#   · **基准单位**（FieldDef.unit）：引擎存储与比较用的单位，写死在数据源落库口径里，
#     不可改。归档里的 ConditionSpec 存的永远是基准单位值 —— 复现不受界面设置影响。
#   · **界面单位**（本阶梯里的备选项）：只在「输入/显示」这一层做换算，factor 表示
#     「该单位 → 基准单位的系数」（即提交前 ×factor，回显时 ÷factor）。
# 所以用户在字段库把总市值选成「亿元」，输入 5 会存成 50000（万元）——引擎比较的仍是
# 基准单位，而界面上看到的始终是 5 亿元。改单位不会让任何历史策略变义。
#
# 只登记换算无歧义、且实际会用到的单位：金额（元/万元/亿元）、股数（股/手/万手）、
# 股本（万股/亿股）。百分数（%）与倍数（倍）不提供备选 —— 换成小数只会制造误读。

U_MONEY_YUAN: tuple[tuple[str, float], ...] = (("元", 1.0), ("万元", 1e4), ("亿元", 1e8))
U_MONEY_WAN: tuple[tuple[str, float], ...] = (("万元", 1.0), ("亿元", 1e4))
U_SHARE_GU: tuple[tuple[str, float], ...] = (("股", 1.0), ("手", 100.0), ("万手", 1e6))
U_SHARE_WAN: tuple[tuple[str, float], ...] = (("万股", 1.0), ("亿股", 1e4))

# 哪些字段提供备选界面单位（键 = 引擎字段名；不在表里的字段只能用基准单位）
_UNIT_LADDERS: dict[str, tuple[tuple[str, float], ...]] = {
    # 行情原列：volume 入库为股（源为手 ×100），amount 入库为元（源为千元 ×1000）
    "volume": U_SHARE_GU,
    "amount": U_MONEY_YUAN,
    # 每日指标：市值为万元，股本为万股
    "total_mv": U_MONEY_WAN,
    "circ_mv": U_MONEY_WAN,
    "total_share": U_SHARE_WAN,
    "float_share": U_SHARE_WAN,
    "free_share": U_SHARE_WAN,
    # 财务指标：金额入库为元
    "fundamental.net_profit": U_MONEY_YUAN,
    "fundamental.total_revenue": U_MONEY_YUAN,
}


@dataclass(frozen=True)
class FieldDef:
    """一个条件字段的登记项（引擎真能算的字段）。"""

    name: str  # 引擎字段名（写进 condition.field）
    label: str  # 中文名（下拉里给人看的）
    description: str  # 含义 / 口径（含单位），必须可核对
    kind: str  # num | str
    group_name: str
    unit: str = ""  # **基准单位**（引擎存储/比较用），不可由界面更改
    curated: bool = True  # True=默认进字段库；False=仅登记为「可新增」（少用字段）
    units: tuple[tuple[str, float], ...] = ()  # 可选界面单位；(单位, →基准单位系数)，首项须是基准单位

    @property
    def ops(self) -> tuple[str, ...]:
        return OPS_BY_KIND.get(self.kind, ())

    @property
    def unit_options(self) -> tuple[tuple[str, float], ...]:
        """可选界面单位；未登记阶梯的字段只有基准单位一项（界面不给选择）。"""
        return self.units or ((self.unit, 1.0),)


# ---------- 股票基础（static.*）：来自 Stock 实体，只有字符串字段可比较 ----------

# (attr, 中文名, 含义, curated)
_STATIC_FIELDS: tuple[tuple[str, str, str, bool], ...] = (
    ("industry", "所属行业", "股票基础信息里的行业名称（字符串），如「银行」「白酒」。等值用「=」，多值用「属于」。", True),
    ("market", "上市板块", "主板 / 创业板 / 科创板 / 北交所（字符串）。", True),
    ("area", "注册地域", "公司注册地省份或地区（字符串），如「广东」「北京」。", True),
    ("exchange", "交易所", "SH 上交所 / SZ 深交所 / BJ 北交所（字符串）。", False),
    ("status", "上市状态", "L 上市 / D 退市 / P 暂停上市（字符串）。研究池已默认剔除退市股。", False),
    ("name", "股票名称", "证券简称（字符串）。一般用于核对，不建议拿来做条件。", False),
    ("symbol", "股票代码", "Tushare 风格代码，如 600519.SH（字符串）。多值用「属于」。", False),
)

# ---------- 行情原列（open/high/low/close/volume/amount） ----------
# 换算口径见 data_sources/tushare.py: volume=vol(手)*100 → 股；amount=amount(千元)*1000 → 元。

_BAR_FIELDS: tuple[tuple[str, str, str, str, bool], ...] = (
    ("close", "收盘价", "当日收盘价（元）。复权口径由公共配置的 price_adjustment 决定（默认 hfq）。", "元", True),
    ("open", "开盘价", "当日开盘价（元），复权口径同上。", "元", True),
    ("high", "最高价", "当日最高价（元），复权口径同上。", "元", True),
    ("low", "最低价", "当日最低价（元），复权口径同上。", "元", True),
    ("volume", "成交量", "当日成交股数（股）。数据源原始单位为「手」，入库时已 ×100 换算。", "股", True),
    ("amount", "成交额", "当日成交金额（元）。数据源原始单位为「千元」，入库时已 ×1000 换算。", "元", True),
)

# ---------- 技术派生（滚动窗口计算，非行情原列） ----------

_TECH_FIELDS: tuple[tuple[str, str, str, str, bool], ...] = (
    ("ma20", "20 日均线", "收盘价的 20 个交易日简单移动平均（元），在选股日当日取值。", "元", True),
    ("ma60", "60 日均线", "收盘价的 60 个交易日简单移动平均（元），在选股日当日取值。", "元", True),
)

# ---------- 每日指标（daily_basic） ----------
# 单位照抄 data_sources/tushare.py: 百分数/倍数为原样，股本为万股，市值为万元。

_DAILY_FIELDS: tuple[tuple[str, str, str, str, bool], ...] = (
    ("dv_ratio", "股息率", "近 12 个月现金分红 / 总市值 × 100（%），逐日时点值 —— 即因子 dividend_yield 的口径。", "%", True),
    ("dv_ttm", "股息率 TTM", "近 12 个月滚动现金分红 / 总市值 × 100（%），即因子 dividend_yield_ttm 的口径。", "%", True),
    ("pe", "市盈率 PE", "总市值 / 最新年报净利润（倍，静态口径）。", "倍", True),
    ("pe_ttm", "市盈率 PE(TTM)", "总市值 / 最近 12 个月净利润（倍）。", "倍", True),
    ("pb", "市净率 PB", "总市值 / 最新报告期净资产（倍）。", "倍", True),
    ("turnover_rate", "换手率", "当日成交股数 / 流通股本 × 100（%）。", "%", True),
    ("volume_ratio", "量比", "当日成交量 / 过去 5 日平均成交量（倍）。", "倍", True),
    ("total_mv", "总市值", "总股本 × 当日收盘价（万元）。", "万元", True),
    ("circ_mv", "流通市值", "流通股本 × 当日收盘价（万元）。", "万元", True),
    ("ps", "市销率 PS", "总市值 / 最新年报营业收入（倍）。", "倍", False),
    ("ps_ttm", "市销率 PS(TTM)", "总市值 / 最近 12 个月营业收入（倍）。", "倍", False),
    ("total_share", "总股本", "总股本（万股）。", "万股", False),
    ("float_share", "流通股本", "流通股本（万股）。", "万股", False),
    ("free_share", "自由流通股本", "自由流通股本（万股）。", "万股", False),
)

# ---------- 财务指标（fundamental.*） ----------
# 可见性口径：只取 announce_date <= 选股日的最新已公告值（防未来函数，见 selection.run_condition_selection）。

_FUNDAMENTAL_FIELDS: tuple[tuple[str, str, str, str, bool], ...] = (
    ("roe", "净资产收益率 ROE", "最新已公告报告期的净资产收益率（%）。", "%", True),
    ("eps", "每股收益 EPS", "最新已公告报告期的每股收益（元）。", "元", True),
    ("gross_margin", "毛利率", "最新已公告报告期的毛利率（%）。", "%", True),
    ("net_profit", "归母净利润", "最新已公告报告期的归母净利润（元）。", "元", False),
    ("total_revenue", "营业总收入", "最新已公告报告期的营业总收入（元）。注意：目前只有新浪兜底源提供该字段，多数行可能为空 —— 缺失时条件视为不通过。", "元", False),
)

# static.* 里明确不支持的字段（存在但不可比较）
_STATIC_UNSUPPORTED: dict[str, str] = {
    "list_date": "上市日期是日期，不是可比较的数值/字符串；请改用股票池的「上市天数」设置",
    "delist_date": "退市日期是日期，不是可比较的数值/字符串",
}


def _defs() -> list[FieldDef]:
    """构造全部内置字段定义（每次调用重新构造，保证与代码注册表实时一致）。"""
    out: list[FieldDef] = []
    for attr, label, desc, curated in _STATIC_FIELDS:
        out.append(
            FieldDef(
                name=f"static.{attr}",
                label=label,
                description=desc,
                kind="str",
                group_name=GROUP_STOCK,
                curated=curated,
            )
        )
    for name, label, desc, unit, curated in _BAR_FIELDS:
        out.append(
            FieldDef(
                name, label, desc, "num", GROUP_QUOTE, unit, curated,
                _UNIT_LADDERS.get(name, ()),
            )
        )
    for name, label, desc, unit, curated in _TECH_FIELDS:
        out.append(
            FieldDef(name, label, desc, "num", GROUP_TECH, unit, curated, _UNIT_LADDERS.get(name, ()))
        )
    for name, label, desc, unit, curated in _DAILY_FIELDS:
        out.append(
            FieldDef(name, label, desc, "num", GROUP_DAILY, unit, curated, _UNIT_LADDERS.get(name, ()))
        )
    for name, label, desc, unit, curated in _FUNDAMENTAL_FIELDS:
        full = f"fundamental.{name}"
        out.append(
            FieldDef(full, label, desc, "num", GROUP_FUNDAMENTAL, unit, curated, _UNIT_LADDERS.get(full, ()))
        )
    for d in list_factors():
        # 因子既能当「打分因子」也能当「过滤条件」：这里复用因子注册表的元数据，
        # 不另写描述，避免两处文案漂移。因子的 description 里已写明公式与口径；
        # 标签用中文名（含参数），如「动量（窗口 60，越高越好）」——
        # 参数化实例不在这里（它们在 /factors 目录里，条件下拉按名并入）。
        out.append(
            FieldDef(
                name=d.name,
                label=f"{d.display}（因子）",
                description=d.description + (f" 用法：{d.brief}" if d.brief else ""),
                kind="num",
                group_name=GROUP_FACTOR,
                curated=True,
            )
        )
    return out


def builtin_fields() -> list[FieldDef]:
    """全部引擎支持的字段（含 curated=False 的「可新增但不默认展示」项）。

    名字唯一性由因子名与各分组前缀保证；一旦重复说明注册表写错，直接抛错而非静默覆盖。
    单位阶梯同样自检：首项必须是基准单位且系数为 1.0，系数必须为正 —— 写错了会让
    「界面显示 5 亿元、引擎按 5 万元比」这种错静默溜进生产。
    """
    defs = _defs()
    names = [d.name for d in defs]
    dup = {n for n in names if names.count(n) > 1}
    if dup:
        raise ValueError(f"条件字段注册表存在重名：{sorted(dup)}")
    for d in defs:
        if not d.units:
            continue
        base, factor = d.units[0]
        if base != d.unit or factor != 1.0:
            raise ValueError(
                f"字段 {d.name} 的单位阶梯首项必须是基准单位 {d.unit!r}（系数 1.0），实际 {d.units[0]!r}"
            )
        if any(f <= 0 for _, f in d.units):
            raise ValueError(f"字段 {d.name} 的单位换算系数必须为正：{d.units}")
        if len({u for u, _ in d.units}) != len(d.units):
            raise ValueError(f"字段 {d.name} 的单位阶梯有重复单位：{d.units}")
    return defs


def curated_fields() -> list[FieldDef]:
    """默认进「字段库」的字段（下拉里开箱可见的那批）。"""
    return [d for d in builtin_fields() if d.curated]


def get_field(name: str) -> FieldDef | None:
    """按字段名取定义：注册表字段，或**参数化因子键**（如 momentum(window=90,direction=…)）。

    为什么参数化因子也要能取到：它是引擎真认的条件字段（`momentum_60 > 0` 一直合法），
    而字段库/说明书的单位后缀、类型判断都走这里。取不到会让人误以为「引擎不支持」，
    甚至让「把参数化因子加进字段库」这一步半路 assert 崩掉（500 而不是 422）。
    """
    for d in builtin_fields():
        if d.name == name:
            return d
    return _factor_field(name)


def _factor_field(name: str) -> FieldDef | None:
    """参数化因子键 → 字段定义（因子是无量纲量，不带单位）。"""
    try:
        defn, _fn = resolve_factor(name)
    except FactorError:
        return None
    if defn.name in {d.name for d in builtin_fields()}:
        return None  # 注册表字段已在上一步返回；这里只处理新增的参数化实例
    return FieldDef(
        name=defn.name,
        label=f"{defn.display}（因子）",
        description=defn.description + (f" 用法：{defn.brief}" if defn.brief else ""),
        kind="num",
        group_name=GROUP_FACTOR,
        curated=False,  # 不自动进字段库：目录在 /factors 管，条件里按名并进来
    )


def _stock_attrs() -> set[str]:
    return set(Stock.model_fields)


def _fundamental_attrs() -> set[str]:
    """FinancialIndicator 里可比较的数值字段（排除 symbol/报告期/来源等元数据）。"""
    skip = {"symbol", "report_date", "announce_date", "source"}
    return {n for n in FinancialIndicator.model_fields if n not in skip}


def reason_unsupported(name: str) -> str:
    """字段不可用的理由（用于 422 文案；可用字段返回空串）。"""
    if not name or not name.strip():
        return "字段名为空"
    if name in DAILY_BAR_NUMERIC_FIELDS:
        return ""
    if name in ("ma20", "ma60"):
        return ""
    if name in DAILY_BASIC_NUMERIC_FIELDS:
        return ""
    if name.startswith("static."):
        attr = name[len("static.") :]
        if attr in _STATIC_UNSUPPORTED:
            return f"{name} 不可用作条件：{_STATIC_UNSUPPORTED[attr]}"
        if attr in _stock_attrs():
            return ""
        return f"{name} 不存在：股票基础信息里没有 {attr} 字段"
    if name.startswith("fundamental."):
        attr = name[len("fundamental.") :]
        if attr in _fundamental_attrs():
            return ""
        return f"{name} 不存在：财务指标里没有 {attr} 字段"
    try:
        get_factor(name)
    except FactorError:
        return (
            f"{name} 不是引擎支持的字段。可用：行情列（{', '.join(DAILY_BAR_NUMERIC_FIELDS)}）、"
            "ma20/ma60、每日指标列、static.<股票基础字段>、fundamental.<财务字段>、"
            "已注册因子名，或参数化因子键（如 momentum(window=90,direction=higher_is_better)）"
        )
    return ""


def is_supported_field(name: str) -> bool:
    """引擎是否真能算这个字段（False = 条件永远不通过，必须拒绝）。"""
    return reason_unsupported(name) == ""


def available_fields(existing: set[str]) -> list[FieldDef]:
    """引擎支持但**尚未进目录**的字段（用户「新增字段」时可选项）。

    只从注册表里挑，用户因此不可能加进一个引擎算不出来的字段（§24 不假装支持）。
    """
    return [d for d in builtin_fields() if not d.curated and d.name not in existing]


# ---------- 单位换算（界面单位 ⇄ 基准单位） ----------


def unit_options(name: str) -> list[tuple[str, float]]:
    """该字段可选的界面单位（首项为基准单位，系数 = 该单位 → 基准单位）。字段不存在 → 空列表。

    **换算在界面层做**（前端按系数换算输入/回显），存储与引擎一律用基准单位：
    这样归档里的 ConditionSpec 永远不随界面设置改变含义。
    """
    d = get_field(name)
    return list(d.unit_options) if d else []


def unit_allowed(name: str, unit: str) -> bool:
    """该单位是否在字段允许的阶梯里（API 据此 422 拒绝自由文本单位）。"""
    return unit in {u for u, _ in unit_options(name)}