feat(backend): 字段库（condition_field）+ 因子参数化（模板/受控参数）+ 单位换算底座

字段库（本次新增的表与接口）： - `condition_field` 表 + `/api/condition-fields`：中文名/说明可编辑、可停用； `kind`/单位阶梯/`base_unit` 由代码注册表收敛（改类型 422，伪字段 422，越界单位 422），停用的字段不再进条件下拉，但既有策略仍按名字解析。 - 说明书里的数值条件按字段注册表补**基准单位**后缀（字段间比较不加，不猜单位）。因子参数化（键即身份，冻结口径）： - 模板 + 参数注册表（`quant/factors.py`）：`ParamSpec`（类型/范围/枚举/默认值/说明）+ `FactorTemplate`（公式/依赖列/参数）；规范键把**全部**参数写进名字，如 `momentum(window=90,direction=lower_is_better)`，所以改参数 = 新建一个身份，旧因子/既有策略/已归档实验都不变义；`momentum(window=90)`（缺参数）明确拒绝 —— 缺项要靠模板默认值补齐，而默认值是可改的代码细节，一旦改动会追溯性改义。 - 参数只在受控范围内取值（窗口 2~500、方向二选一），越界/未知模板/多给参数一律 422 并列出允许范围，不静默截断、不悄悄取默认值；内置实例的启用开关由代码决定（422）。 - `/api/factors` 暴露 `template`/`params`/`param_specs`/`label`/`source`/`enabled`/ `resolvable`；新增 `/api/factors/templates`、`POST /api/factors`、`PATCH /api/factors`； `get_factor = resolve_factor` 兼容全部旧调用点，参数化键也是一等条件字段。 - 迁移链：c5d6（存量策略陈旧说明重算）→ d6e7（condition_field）→ a7c1 （factor_definition.enabled + name varchar(128)）。测试：新增 test_condition_fields.py / test_factor_params.py；全量 pytest 500 passed。
2026-10-01 16:33:32 +08:00
parent 40bd603b44
commit 2e90f3eeac
39 changed files with 3280 additions and 244 deletions
@@ -0,0 +1,102 @@
+"""字段库 Repository 的 SQLAlchemy 实现（2026-10）。"""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from app.domain.entities.condition_field import ConditionField
+from app.infrastructure.persistence.sqlalchemy.models.condition_field import ConditionFieldModel
+
+
+def _to_entity(row: ConditionFieldModel) -> ConditionField:
+    return ConditionField(
+        name=row.name,
+        label=row.label,
+        description=row.description,
+        kind=row.kind,
+        group_name=row.group_name,
+        unit=row.unit,
+        source=row.source,
+        enabled=row.enabled,
+        sort_order=row.sort_order,
+        created_at=row.created_at,
+        updated_at=row.updated_at,
+    )
+
+
+class SqlAlchemyConditionFieldRepository:
+    def __init__(self, session: Session) -> None:
+        self._session = session
+
+    def list(self) -> list[ConditionField]:
+        rows = self._session.scalars(
+            select(ConditionFieldModel).order_by(
+                ConditionFieldModel.sort_order, ConditionFieldModel.name
+            )
+        ).all()
+        return [_to_entity(r) for r in rows]
+
+    def get(self, name: str) -> ConditionField | None:
+        row = self._session.get(ConditionFieldModel, name)
+        return _to_entity(row) if row else None
+
+    def insert_missing(self, items: list[ConditionField]) -> int:
+        if not items:
+            return 0
+        existing = set(
+            self._session.scalars(
+                select(ConditionFieldModel.name).where(
+                    ConditionFieldModel.name.in_([i.name for i in items])
+                )
+            )
+        )
+        now = datetime.now()
+        added = 0
+        for item in items:
+            if item.name in existing:
+                continue  # 只补不删、不覆盖用户改过的文案
+            self._session.add(
+                ConditionFieldModel(
+                    name=item.name,
+                    label=item.label,
+                    description=item.description,
+                    kind=item.kind,
+                    group_name=item.group_name,
+                    unit=item.unit,
+                    source=item.source,
+                    enabled=item.enabled,
+                    sort_order=item.sort_order,
+                    created_at=now,
+                    updated_at=now,
+                )
+            )
+            added += 1
+        return added
+
+    def save(self, item: ConditionField) -> ConditionField:
+        now = datetime.now()
+        row = self._session.get(ConditionFieldModel, item.name)
+        if row is None:
+            row = ConditionFieldModel(name=item.name, created_at=now, updated_at=now)
+            self._session.add(row)
+        row.label = item.label
+        row.description = item.description
+        row.kind = item.kind
+        row.group_name = item.group_name
+        row.unit = item.unit
+        row.source = item.source
+        row.enabled = item.enabled
+        row.sort_order = item.sort_order
+        row.updated_at = now
+        self._session.flush()
+        return _to_entity(row)
+
+    def delete(self, name: str) -> bool:
+        row = self._session.get(ConditionFieldModel, name)
+        if row is None:
+            return False
+        self._session.delete(row)
+        return True
@@ -1,4 +1,8 @@
-"""因子目录 Repository 的 SQLAlchemy 实现（M7.1）。"""
+"""因子目录 Repository 的 SQLAlchemy 实现（M7.1；2026-10 加 enabled）。
+
+只写**真列**：实体上还有 template/params/label/param_specs 等由名字解析出来的投影字段，
+它们不是列 —— 若照 model_dump 全量 setattr，会出现「看着写进去了、其实没落库」的假象。
+"""

 from __future__ import annotations

@@ -9,7 +13,23 @@ from sqlalchemy import select
 from sqlalchemy.orm import Session

 from app.domain.entities.factor import FactorDefinition
-from app.infrastructure.persistence.sqlalchemy.models.factor import FactorDefinitionModel
+from app.infrastructure.persistence.sqlalchemy.models.factor import (
+    FactorDefinitionModel,
+)
+
+# 真正落库的列（其余实体字段是解析投影）
+_STORED_COLUMNS = (
+    "name",
+    "description",
+    "formula",
+    "brief",
+    "frequency",
+    "lookback",
+    "direction",
+    "requires",
+    "version",
+    "enabled",
+)


 def _to_entity(row: FactorDefinitionModel) -> FactorDefinition:
@@ -23,6 +43,7 @@ def _to_entity(row: FactorDefinitionModel) -> FactorDefinition:
        direction=row.direction,
        requires=json.loads(row.requires_json or "[]"),
        version=row.version,
+        enabled=bool(row.enabled),
        created_at=row.created_at,
    )

@@ -57,11 +78,13 @@ class SqlAlchemyFactorRepository:
                        direction=d.direction,
                        requires_json=json.dumps(d.requires),
                        version=d.version,
+                        enabled=d.enabled,
                        created_at=now,
                    )
                )
            else:
-                for k, v in d.model_dump(exclude={"created_at"}).items():
+                for k in _STORED_COLUMNS:
+                    v = getattr(d, k)
                    if k == "requires":
                        v = json.dumps(v)
                    setattr(row, k, v)