"""因子目录领域实体（M7.1：因子元数据 DB 化，v2 §11；2026-10 参数化）。

DB 是因子目录的契约源：**哪些因子存在**（含用户从模板派生的参数化实例）入库；
**能不能算**仍由代码注册表（quant/factors.py）唯一决定 —— 登记但解析不出来的因子
在 score/condition 里引用时抛 FactorError（不假装支持）。

参数化的读法：参数化实例的名字本身就是身份（`momentum(window=90,direction=...…)`），
所以 template / params / param_specs / label / source / resolvable 都是**由名字解析出来的
投影**，不落库。落库的只有 `enabled`（是否出现在下拉里）—— 这是人做的配置，
不是引擎事实。好处：参数不可能出现「表里一套、键里一套」的分裂。
"""

from __future__ import annotations

from datetime import datetime
from typing import Any

from pydantic import BaseModel, Field


class FactorParam(BaseModel):
    """一个可编辑参数的约束（与 quant/factors.ParamSpec 对齐，供界面渲染表单）。"""

    name: str
    label: str = ""
    kind: str = "int"  # "int" | "enum"
    default: Any = None
    minimum: int | None = None
    maximum: int | None = None
    choices: list[str] = Field(default_factory=list)
    note: str = ""

    @classmethod
    def from_spec(cls, spec) -> FactorParam:
        return cls(
            name=spec.name,
            label=spec.label,
            kind=spec.kind,
            default=spec.default,
            minimum=spec.minimum,
            maximum=spec.maximum,
            choices=list(spec.choices),
            note=spec.note,
        )


class FactorDefinition(BaseModel):
    name: str = Field(min_length=1, max_length=128)
    description: str = ""
    formula: str = ""
    brief: str = ""
    frequency: str = "daily"
    lookback: int = 20
    direction: str = Field(default="higher_is_better", pattern="^(higher_is_better|lower_is_better)$")
    requires: list[str] = Field(default_factory=list)
    version: str = "1"
    created_at: datetime | None = None
    # ---- 参数化（落库的只有 enabled；其余由 name 解析投影而来）----
    enabled: bool = True
    template: str = ""  # 模板名，如 "momentum"
    params: dict[str, Any] = Field(default_factory=dict)  # 冻结的参数取值
    param_specs: list[FactorParam] = Field(default_factory=list)  # 可编辑参数与约束
    label: str = ""  # 中文显示名（含参数）
    source: str = "builtin"  # builtin（代码注册表实例）| custom（目录里的参数化实例）
    resolvable: bool = True  # False = 登记了但引擎算不出来（历史手工登记行）

    @classmethod
    def from_registry_def(cls, d) -> FactorDefinition:
        """由 quant/factors.FactorDef（dataclass）构造目录实体（seed 用）。"""
        return cls.from_factor_def(d, enabled=True)

    @classmethod
    def from_factor_def(cls, d, *, enabled: bool = True) -> FactorDefinition:
        """由因子实例（内置或参数化）构造目录实体（seed / 新建用）。"""
        return cls(
            name=d.name,
            description=d.description,
            formula=d.formula,
            brief=d.brief,
            frequency=d.frequency,
            lookback=d.lookback,
            direction=d.direction,
            requires=list(d.requires),
            enabled=enabled,
            template=d.template,
            params=dict(d.params),
            param_specs=[FactorParam.from_spec(s) for s in d.param_specs],
            label=d.label,
            source=d.source,
            resolvable=True,
        )