simon/qlib
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
字段库（本次新增的表与接口）：
- `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。
This commit is contained in:
Simon
2026-10-01 16:33:32 +08:00
parent 40bd603b44
commit 2e90f3eeac
39 changed files with 3280 additions and 244 deletions
Download Patch File Download Diff File Expand all files Collapse all files
backend/app/infrastructure/persistence/sqlalchemy/models/__init__.py
+6 -3
View File
@@ -4,13 +4,16 @@
模型统一继承 infra.persistence.sqlalchemy.base.Base。
"""
from app.infrastructure.persistence.sqlalchemy.models.composite import ( # noqa: F401
FactorCompositeModel,
)
from app.infrastructure.persistence.sqlalchemy.models.combo import ( # noqa: F401
BacktestComboModel,
GlobalConfigModel,
)
from app.infrastructure.persistence.sqlalchemy.models.composite import ( # noqa: F401
FactorCompositeModel,
)
from app.infrastructure.persistence.sqlalchemy.models.condition_field import ( # noqa: F401
ConditionFieldModel,
)
from app.infrastructure.persistence.sqlalchemy.models.factor import ( # noqa: F401
FactorDefinitionModel,
)
backend/app/infrastructure/persistence/sqlalchemy/models/condition_field.py
+31
View File
@@ -0,0 +1,31 @@
"""字段库表（2026-10）。
condition_field：过滤条件字段的目录契约源（name 主键幂等）。
内置字段由 quant/condition_fields.py 的注册表在 API 首次读取时 seed（只补不删），
自定义字段与用户改过的文案都落在这张表里。
"""
from __future__ import annotations
from datetime import datetime
from sqlalchemy import Boolean, DateTime, Integer, String
from sqlalchemy.orm import Mapped, mapped_column
from app.infrastructure.persistence.sqlalchemy.base import Base
class ConditionFieldModel(Base):
__tablename__ = "condition_field"
name: Mapped[str] = mapped_column(String(64), primary_key=True)
label: Mapped[str] = mapped_column(String(64), default="")
description: Mapped[str] = mapped_column(String(500), default="")
kind: Mapped[str] = mapped_column(String(8), default="num")
group_name: Mapped[str] = mapped_column(String(32), default="行情")
unit: Mapped[str] = mapped_column(String(16), default="")
source: Mapped[str] = mapped_column(String(8), default="builtin")
enabled: Mapped[bool] = mapped_column(Boolean, default=True)
sort_order: Mapped[int] = mapped_column(Integer, default=100)
created_at: Mapped[datetime] = mapped_column(DateTime)
updated_at: Mapped[datetime] = mapped_column(DateTime)
backend/app/infrastructure/persistence/sqlalchemy/models/factor.py
+9 -4
View File
@@ -1,13 +1,16 @@
"""因子目录表（M7.1）。
"""因子目录表（M7.1；2026-10 支持参数化实例）。
factor_definition：因子元数据契约源（name 主键幂等）；requires 以 JSON 存。
factor_definition：因子名（主键，参数化实例的参数就写在名字里）→ 元数据；requires 以 JSON 存。
`enabled` 是唯一由人配置的字段（是否出现在因子下拉里）；内置实例的开关注由代码注册表
收敛（见 application/services/factor_catalog.py），停用只影响「能不能被选中」，
不影响已引用它的策略/归档解析 —— 历史不能被开关改义。
"""
from __future__ import annotations
from datetime import datetime
from sqlalchemy import DateTime, Integer, String, Text
from sqlalchemy import Boolean, DateTime, Integer, String, Text
from sqlalchemy.orm import Mapped, mapped_column
from app.infrastructure.persistence.sqlalchemy.base import Base
@@ -16,7 +19,8 @@ from app.infrastructure.persistence.sqlalchemy.base import Base
class FactorDefinitionModel(Base):
__tablename__ = "factor_definition"
name: Mapped[str] = mapped_column(String(64), primary_key=True)
# 128：参数化实例的名字把参数写全（如 momentum(window=90,direction=lower_is_better)）
name: Mapped[str] = mapped_column(String(128), primary_key=True)
description: Mapped[str] = mapped_column(String(500), default="")
formula: Mapped[str] = mapped_column(String(500), default="")
brief: Mapped[str] = mapped_column(String(500), default="")
@@ -25,4 +29,5 @@ class FactorDefinitionModel(Base):
direction: Mapped[str] = mapped_column(String(32), default="higher_is_better")
requires_json: Mapped[str] = mapped_column(Text, default="[]")
version: Mapped[str] = mapped_column(String(16), default="1")
enabled: Mapped[bool] = mapped_column(Boolean, default=True, server_default="1")
created_at: Mapped[datetime] = mapped_column(DateTime)
backend/app/infrastructure/persistence/sqlalchemy/models/strategy.py
+2 -1
View File
@@ -16,7 +16,8 @@ class StrategyModel(Base):
id: Mapped[str] = mapped_column(String(32), primary_key=True)
name: Mapped[str] = mapped_column(String(64), unique=True)
description: Mapped[str] = mapped_column(String(300), default="")
spec_type: Mapped[str] = mapped_column(String(16), default="backtest")
# 2026-09 重构后策略库只存选股策略，新行一律 selection（历史行的 backtest 由数据迁移收敛）
spec_type: Mapped[str] = mapped_column(String(16), default="selection")
config_json: Mapped[str] = mapped_column(Text)
version: Mapped[str] = mapped_column(String(16), default="1")
created_at: Mapped[datetime] = mapped_column(DateTime)
backend/app/infrastructure/persistence/sqlalchemy/repositories/condition_field_impl.py
+102
View File
@@ -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
backend/app/infrastructure/persistence/sqlalchemy/repositories/factor_impl.py
+26 -3
View File
@@ -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)